Functions

Overview

Functions in BattleScript allow you to group code into reusable blocks. They can accept parameters, return values, and be called from other parts of your script.

Function Declaration

Functions are declared with a return type followed by function name, and parameters:

int add(int a, int b) => {
    return a + b;
}

void greet(string name) => {
    std::console.log("Hello, " + name + "!");
}

Functions can also have default parameter values:

int multiply(int a, int b = 2) => {
    return a * b;
}

// This will return 10 (5 * 2)
int result = multiply(5);

Return Values

Functions can return values using the return keyword:

bool isEven(int num) => {
    if (num % 2 == 0) {
        return true;
    }
    
    return false;
}

string getPlayerStatus(int health) => {
    if (health <= 0) {
        return "Eliminated";
    } else if (health < 30) {
        return "Critical";
    } else {
        return "Healthy";
    }
}

Calling Functions

Functions are called using their name followed by parentheses and any arguments:

// Call a function and store the result
int sum = add(5, 3);

// Call a function without storing the result
greet("Player1");

// Call a function with a variable as an argument
string playerName = "Player2";
greet(playerName);

Error Handling with catch

BattleScript provides the catch keyword for handling errors that may occur during function calls. When a function call results in an error, the catch block allows you to inspect and handle the error.

The catch keyword inspects the value of the specified identifier(s). If any is found to be an error, the catch block executes. The optional as clause assigns the error value to a variable for inspection.

int r = std::math.randomInt(0, 255);
int g = std::math.randomInt(0, 255);
int b = std::math.randomInt(0, 255);
catch r {
	// An error occurred, inspect 'r' to see what it is
}
catch r as err {
	// An error occurred in 'r', inspect 'err' to see what it is
}
catch r, g, b as err {
	// An error occurred in either 'r', 'g', or 'b', inspect 'err' to see what it is
}

In the examples above:

• The first catch block executes if r contains an error, allowing you to inspect r directly.
• The second catch block executes if r contains an error, and assigns the error to err for inspection.
• The third catch block executes if any of r, g, or b contain an error, assigning the error to err.

The as identifier is optional and allows you to access the specific error value within the catch block.

Function Scope

Variables declared inside a function are only accessible within that function:

void exampleScope() => {
    string localVar = "I'm local to this function";
    std::console.log(localVar);  // Works fine
}

exampleScope();
// std::console.log(localVar);  // Error: localVar is not defined

Modifiers and Parameters

Functions can be marked with modifiers and support advanced parameter patterns:

• pure - Marks a function as having no side effects for optimization.
• native - Declares a function implemented by the runtime or device firmware (not in BattleScript). A native declaration has no body and ends with a semicolon.
• Default parameters - Assign a default with = in the parameter list (shown above).
• Rest parameters - Capture remaining args with the type first, then ...name, e.g. any ...args.
• Namespaced function identifiers - Library functions are called with a namespace like std::console.log() or battlecore::player.takeDamage().

// A pure function with a body
pure int sum (int a, int b) => {
	return a + b;
}

// A native declaration: no body, ends with a semicolon.
// The runtime/firmware provides the implementation.
native void logAll (any ...args);

// Calling them
std::console.log("Sum:", sum(2, 3));