Runtime Docs

Scripts Runtime API

Purpose

Runtime script helpers access typed self state, dynamic vars, and dynamic method calls across script boundaries.

Scripts Runtime API explains behavior, constraints, and practical usage so implementation decisions stay consistent across scripts and scenes.

Jump to Docs

Statetyped script data Methodscallable behavior

API Source

Functions

with_state!with_state_mut!get_var!set_var!call_method!query_first!

Enums

// not documented yet for this module

Constants

dynamic dispatch crosses Variant boundary

Types

RuntimeWindowVariantScriptMemberIDNodeIDScriptContext

Usage Pattern

let enemy = query_first!(ctx.run, all(name["Enemy1"])).unwrap();set_var!(ctx.run, enemy, var!("alerted"), variant!(true));call_method!(ctx.run, enemy, func!("take_damage"), params![10_i32]);

API Breakdown

with_state!

with_state!(ctx.run, StateType, node_id, |state| -> V { ... }) -> V

Params

StateType: struct marked #[State] in script code

node_id: NodeID for script instance owner node

closure receives &StateType for typed read access

Returns

closure return V; if missing/mismatch, runtime returns V::default()

Fail Modes

node missing or no script state of StateType => default return

invalid StateType (no matching script state) => default return

Example

let hp = with_state!(ctx.run, EnemyState, enemy_id, |state| state.health);

Use with_state! for safe typed local reads without leaking runtime borrows across systems.

with_state_mut!

with_state_mut!(ctx.run, StateType, node_id, |state| -> V { ... }) -> Option<V>

Params

StateType: #[State] struct bound to script

node_id: NodeID for target script instance

closure receives &mut StateType for typed mutation

Returns

Some(V) on successful mutable access, None on invalid node/type mismatch

Fail Modes

invalid NodeID or missing script state => None

StateType mismatch => None

Example

let _ = with_state_mut!(ctx.run, EnemyState, enemy_id, |state| {    state.alerted = true;});

Use with_state_mut! for deterministic per-instance state updates with borrow scope ending at closure exit.

get_var! / set_var!

get_var!(ctx.run, node_id, member) -> Variantset_var!(ctx.run, node_id, member, value) -> ()

Params

member accepts var!("name"), ScriptMemberID, Member, &str, String, Cow<str>

value should use variant!(...) for stable conversion

Returns

get_var! returns Variant; set_var! updates dynamic script var store

Fail Modes

missing variable key resolves to default/empty Variant value

set value may be ignored if node/script binding invalid

Example

set_var!(ctx.run, enemy_id, var!("alert_level"), variant!(2_i32));let alert = get_var!(ctx.run, enemy_id, var!("alert_level"));

Use var access for per-instance scene-injected values and dynamic runtime data that should not be hardcoded in shared behavior.

call_method!

call_method!(ctx.run, node_id, method, params) -> Variant

Params

method accepts method!("..."), func!("..."), ScriptMemberID, Member, &str, String

params usually from params![...] Variant list

Returns

Variant return from called method

Fail Modes

target node missing/method missing => default Variant result

param type mismatch at dynamic boundary => fallback/default behavior by callee

Example

let result = call_method!(ctx.run, enemy_id, func!("take_damage"), params![10_i32]);

Use call_method! for cross-node script orchestration when compile-time direct references are not available.

Key Details

with_state! and with_state_mut! provide typed state access.

get_var! and set_var! use dynamic Variant member ids.

call_method! dispatches by method id/name.

Query or traversal usually supplies target NodeID values.