throw

throw

Category

Error Handling

Arity

Unary — throw <value>.

throw <any>

Description

Throws an error with the given value. If inside a try block, execution jumps to the corresponding catch block with the thrown value available as _exception. If not inside a try block, the fiber terminates with an error.

How It Works

The compiler emits a throw opcode. The VM unwinds the execution stack to the nearest enclosing try/catch. If no try block is found, the fiber is terminated and the error propagates to the fiber's ScriptHandle.

The caught error is an SqError object with properties:

• .message — the thrown value as string
• .file — source file
• .line — line number
• .col — column number

Usage

Basic throw and catch

try {
    if (_hp <= 0) then { throw "Unit is dead"; };
    doWork();
} catch (_error) {
    systemChat f"Error: {_error}";
};

Throw with structured data

try {
    if (_index < 0) then { throw ["out_of_range", _index]; };
} catch (_err) {
    _err params ["_code", "_detail"];
    systemChat f"Error {_code}: {_detail}";
};

Validation guard

_validatePositive = {
    params ["_val", "_name"];
    if (_val < 0) then {
        throw f"{_name} must be positive, got {_val}";
    };
};

try {
    [_hp, "HP"] call _validatePositive;
    [_armor, "Armor"] call _validatePositive;
} catch (_error) {
    systemChat f"Validation failed: {_error}";
};

Uncaught throw (fiber error)

_handle = spawn {
    throw "Something went wrong";
    systemChat "Never reached";
};
// The handle resolves with an error — await will return nil

Thread Safety

Throwing unwinds the current fiber only. Other fibers are unaffected. The SqError object is owned by the catching fiber.

See Also

• try/catch — error handling construct