Skip to content

runtime_api.md

Latest commit

 

History

History
66 lines (53 loc) · 3.54 KB

runtime_api.md

File metadata and controls

66 lines (53 loc) · 3.54 KB
Raw

Runtime API

Page Map

Header Link
Purpose Purpose
Use Cases Use Cases
Runtime Modules Runtime Modules
Example Example

Purpose

ctx.run is the window a script uses to act on the live game world. It is where gameplay code reads the frame clock, moves and spawns nodes, loads the next level, plays animations and sound, runs physics queries, and fires the signals that let systems talk to each other. If a script needs to change something that is happening right now in the running game, it happens through ctx.run.

Resources you load ahead of time (textures, meshes, audio clips) live under ctx.res; live player input lives under ctx.ipt. ctx.run is the runtime side: the state that changes every frame.

Use Cases

  • Frame-rate-independent movement and cooldowns: read the frame delta with delta_time!(ctx.run) and drive one-shot delays with timer_start! (see Time).
  • Move and pose the world: reposition a character with set_global_pos_3d!(ctx.run, id, pos), aim a turret with look_at_3d!, or spawn a pickup with spawn! (see Nodes).
  • Level flow: swap the active level with scene_load!(ctx.run, "res://levels/boss.pscene") or warm the next area with scene_preload! (see Scenes).
  • Cross-system messaging: announce signal_emit!(ctx.run, signal!("boss_defeated"), params![]) and let unlocks, music, and UI react (see Signals).
  • Character control and hit detection: slide a player with physics_move_and_slide_3d! and shoot a line-of-sight ray with ctx.run.Physics().raycast_3d(...) (see Physics).
  • Playback and feedback: trigger a jump clip with anim_player_play!, or attach a footstep sound to the player with audio_play_attached! (see Animations, Audio).

Decision Guide

Use ctx.run for live world state and operations: nodes, scripts, scenes, time, physics, signals, and window control. Use ctx.res for asset/resource ownership and ctx.ipt for current input. Runtime access is callback-scoped; do not retain it in state. End each node/state borrow before starting another runtime operation.

Runtime Modules

Module Page Ctx
Animations animations ctx.run.AnimPlayer() / ctx.run.AnimTree()
Audio audio ctx.run.Audio()
Helpers helpers helper macros
Mesh Query mesh_query ctx.run.MeshQuery()
Navmesh navmesh ctx.run.NavMesh()
Node Query node_query ctx.run.NodeQuery()
Nodes nodes ctx.run.Nodes()
Physics physics ctx.run.Physics()
Scenes scenes ctx.run.Scene()
Scripts scripts ctx.run.Scripts()
Signals signals ctx.run.Signals()
Time time ctx.run.Time()
Window window ctx.run.Window()

Example

lifecycle!({
    fn on_update(&self, ctx: &mut ScriptContext<'_, API>) {
        let dt = delta_time!(ctx.run);
        if dt > 0.0 {
            window_set_title!(ctx.run, "Perro");
        }
    }
});