Perro Engine

Purpose

Lifecycle hooks are engine entry points for script instances. They receive one ScriptContext that bundles runtime/resource/input windows and active node id.

Script Lifecycle explains behavior, constraints, and practical usage so implementation decisions stay consistent across scripts and scenes.

Jump to Docs

Scriptsfull script shape Methodscall reusable behavior

API Source

Functions

on_initon_all_initon_updateon_fixed_updateon_removal

Enums

// not documented yet for this module

Constants

hooks return ()

Types

ScriptContextNodeID

Usage Pattern

lifecycle!({    fn on_update(&self, ctx) {        let dt = delta_time!(ctx.run);        self.tick(ctx, dt);    }});

API Breakdown

lifecycle! hook shape

lifecycle!({    fn on_init(&self, ctx: &mut ScriptContext<'_, RT, RS, IP>) {}    fn on_all_init(&self, ctx: &mut ScriptContext<'_, RT, RS, IP>) {}    fn on_update(&self, ctx: &mut ScriptContext<'_, RT, RS, IP>) {}    fn on_fixed_update(&self, ctx: &mut ScriptContext<'_, RT, RS, IP>) {}    fn on_removal(&self, ctx: &mut ScriptContext<'_, RT, RS, IP>) {}});

Params

ctx: ScriptContext with runtime window at ctx.run

ctx.res: read-only ResourceWindow for asset loading + resource controls

ctx.ipt: read-only InputWindow for key/mouse/gamepad/joycon/player state

ctx.id: NodeID for current scene node holding this script instance

Returns

hooks return ()

Fail Modes

RuntimeWindow mutable borrow rules apply; nested mutable runtime closure calls in one scope fail borrow checks

state/node/script helpers inside hook may return None/default on invalid NodeID or type mismatch

Example

fn on_update(&self, ctx: &mut ScriptContext<'_, RT, RS, IP>) {    let speed = if key_down!(ctx.ipt, KeyCode::ShiftLeft) { 440.0 } else { 220.0 };    let dt = delta_time!(ctx.run);    let _ = with_base_node_mut!(ctx.run, Node2D, ctx.id, |node| {        node.position.x += speed * dt;    });}

Use lifecycle hooks for engine-driven script entry. Cache any value from ctx.run before entering a with_node/with_state closure.

Key Details

on_init runs when the script instance initializes.

on_all_init runs after all scripts initialize for that frame.

on_update runs each frame.

on_fixed_update runs on the fixed update step.

on_removal runs before script or node removal.