Struct Ctx 

pub struct Ctx<'a> {
    pub entity: Entity,
    pub scene: &'a mut Scene,
    pub input: &'a Input,
    pub time: Time,
    /* private fields */
}

What a script sees each call.

Fields

entity: Entity

Entity owning this script slot; it may become stale if a script despawns it.

scene: &'a mut Scene

Mutable host scene. Register custom storages only in permanent host code.

input: &'a Input

Frame snapshot and shared shell requests.

time: Time

Scaled callback time.

Implementations

impl Ctx<'_>

pub fn ui(&self) -> &Canvas

The screen interface of this frame (see crate::canvas).

pub fn ui_width(&self) -> f32

Width of the virtual interface screen (its height is always 720).

pub fn storage(&self) -> Storage

The game’s data folder: saves, settings and files.

pub fn save_game( &self, slot: &str, title: &str, data: &Value, ) -> Result<(), String>

Writes a save slot (title is shown in load menus; the scene is recorded too).

pub fn load_game(&self, slot: &str) -> Option<Value>

Reads a save slot.

pub fn save_slots(&self) -> Vec<SaveInfo>

Every save, newest first.

pub fn has_save(&self, slot: &str) -> bool

Whether a slot exists.

pub fn setting_f32(&self, key: &str, default: f32) -> f32

A persistent setting (kept across runs), or default.

pub fn setting_bool(&self, key: &str, default: bool) -> bool

A persistent on/off setting, or default.

pub fn setting_text(&self, key: &str, default: &str) -> String

A persistent text setting, or default.

pub fn set_setting(&self, key: &str, value: Value)

Stores a persistent setting.

pub fn active_camera(&self) -> Option<Entity>

The camera the game looks through.

pub fn set_active_camera(&mut self, camera: Entity) -> bool

Looks through another camera from the next frame on (security monitors, cut-scenes…).

pub fn set_active_camera_named(&mut self, name: &str) -> bool

Switches to the camera named name.

pub fn add_camera_effect( &mut self, camera: Entity, shader: &str, params: [f32; 4], ) -> Option<usize>

Adds a camera shader (fn effect) to a camera; returns its index.

pub fn set_camera_effect( &mut self, camera: Entity, index: usize, enabled: bool, params: [f32; 4], )

Changes the numbers of a camera shader (fade a VHS, pulse damage…).

pub fn set_camera_fov(&mut self, camera: Entity, fov: f32)

Field of view of a camera in degrees (zoom, sprint effect).

pub fn camera_position(&self) -> Option<Vec3>

World position of the active camera.

pub fn camera_forward(&self) -> Option<Vec3>

Direction the active camera looks along.

pub fn place_camera(&mut self, camera: Entity, position: Vec3, target: Vec3)

Places a camera and points it at a target (cut-scenes).

pub fn set_reverb(&mut self, amount: f32, room_ms: f32)

Room echo for sounds started from now on: amount 0..1, room_ms first reflection delay (20 small room .. 120 hall). Call when the player enters a space.

pub fn set_volumes(&mut self, master: f32, music: f32, effects: f32)

Volumes of the mix: everything, music, other sounds (0..1, kept up to 2).

pub fn quit_game(&self)

Closes the game (in the editor it stops Play).

pub fn set_fullscreen(&self, on: bool)

Switches the window to fullscreen or back.

impl Ctx<'_>

pub fn dt(&self) -> f32

Callback delta in seconds; fixed callbacks receive the configured fixed interval.

pub fn elapsed(&self) -> f32

Scaled gameplay seconds since runtime creation.

pub fn frame(&self) -> u64

Frames simulated so far (a counter, handy for “every N frames”).

pub fn fps(&self) -> f32

Frames per second implied by this callback’s dt (0 when dt is 0).

pub fn every(&self, seconds: f32) -> bool

True once every seconds of game time (use inside update).

pub fn time_of_day(&self) -> f32

Current in-game hour, 0..24.

pub fn set_time_of_day(&mut self, hour: f32)

Jumps to an hour of the day (wraps into 0..24) and switches the procedural sky on.

pub fn set_day_speed(&mut self, hours_per_second: f32)

Game hours that pass per real second (0 freezes the sun).

pub fn sky(&mut self) -> &mut SkySettings

The whole sky configuration for fine control: clouds, stars, haze, aurora, moon.

pub fn set_clouds(&mut self, amount: f32)

0 = clear sky, 1 = overcast.

pub fn is_night(&self) -> bool

Whether it is night (sun below the horizon, roughly 20:00-05:00).

pub fn post(&mut self) -> &mut PostSettings

Screen effects for fine control: ctx.post().bloom = 0.8; ctx.post().motion_blur = 0.5;.

pub fn shadows(&mut self) -> &mut ShadowSettings

Sun shadow settings: ctx.shadows().softness = 2.0;.

pub fn post_preset(&mut self, name: &str)

Applies a ready-made look: “cinematic”, “dreamy”, “crisp”, “retro” or anything else for none.

pub fn set_exposure(&mut self, exposure: f32)

Exposure multiplier (brightness) of the picture.

pub fn add_post_effect(&mut self, shader: &str) -> usize

Adds a custom full-screen shader to the camera (a WGSL file with fn effect(..)) and returns its index.

pub fn set_post_effect_params(&mut self, index: usize, params: [f32; 4])

Sets the four numbers a custom effect receives as params.

pub fn enable_post_effect(&mut self, index: usize, on: bool)

Switches a custom effect on or off.

pub fn clear_post_effects(&mut self)

Removes every custom camera effect.

pub fn play_sound(&mut self, clip: &str, volume: f32) -> SoundId

Plays a clip (path inside assets/) in 2D, e.g. ctx.play_sound("sounds/click.wav", 1.0).

pub fn play_music(&mut self, clip: &str, volume: f32) -> SoundId

Plays a looping 2D clip (music). Keep the id to stop it with Self::stop_sound.

pub fn play_sound_at( &mut self, clip: &str, volume: f32, position: Vec3, ) -> SoundId

Plays a clip at a world position (distance falloff and left/right stereo).

pub fn play_sound_panned( &mut self, clip: &str, volume: f32, pan: f32, ) -> SoundId

Plays a clip with stereo position pan (-1 left .. 1 right).

pub fn play_sound_pitched( &mut self, clip: &str, volume: f32, pitch: f32, ) -> SoundId

Plays a clip with a pitch / speed multiplier.

pub fn stop_sound(&mut self, id: SoundId)

Stops a sound started earlier.

pub fn set_sound_volume(&mut self, id: SoundId, volume: f32)

Changes the volume of a running sound.

pub fn stop_all_sounds(&mut self)

Stops every sound.

pub fn set_master_volume(&mut self, volume: f32)

Master volume for the whole game, 0..1.

pub fn world(&mut self) -> &mut World

Mutable host world; its built-in component storages already exist.

pub fn log(&mut self, msg: impl Into<String>)

Appends a message to the host log shown in the editor/player.

pub fn get<T: EcsComponent>(&self) -> Option<&T>

Borrows this entity’s component; returns None when missing or despawned.

pub fn get_mut<T: EcsComponent>(&mut self) -> Option<&mut T>

Mutably borrows this entity’s component, if present.

pub fn get_of<T: EcsComponent>(&self, e: Entity) -> Option<&T>

Borrows another living entity’s component, if present.

pub fn get_mut_of<T: EcsComponent>(&mut self, e: Entity) -> Option<&mut T>

Mutably borrows another living entity’s component, if present.

pub fn transform(&self) -> &Transform

This entity’s transform (panics only if a script removed it; the editor does not allow that).

pub fn transform_mut(&mut self) -> &mut Transform

Mutable local pose.

Panics

Panics when this entity has no Transform, including after self-despawn.

pub fn world_position(&self) -> Vec3

Current world position computed from the hierarchy, including pending local edits.

pub fn set_color(&mut self, e: Entity, rgba: [f32; 4])

Sets the material colour of an entity (linear-ish sRGB, 0..1).

pub fn set_texture(&mut self, e: Entity, texture: &str)

Sets a texture by asset path or by a procedural key (NoiseTexture::key()).

pub fn set_shape(&mut self, e: Entity, shape: Shape)

Replaces the mesh with a parametric shape (the mesh is rebuilt when parameters change).

pub fn children(&self, e: Entity) -> Vec<Entity>

Direct non-transient children in entity index order.

pub fn find(&self, name: &str) -> Option<Entity>

First exact entity-name match; names are not unique identifiers.

pub fn find_all(&self, name: &str) -> Vec<Entity>

Every entity with this exact name.

pub fn find_with<T: EcsComponent>(&self) -> Vec<Entity>

Entities that have component T.

pub fn var(&self, entity: Entity, script: &str, name: &str) -> Option<Value>

Reads a public variable (a field listed in the script’s fields()) of a script on any entity, e.g. ctx.var(door, "DoorLogic", "locked"). Returns JSON: numbers, bools, strings, arrays.

pub fn set_var( &mut self, entity: Entity, script: &str, name: &str, value: Value, ) -> bool

Changes a public variable of a script on any entity; the script sees it before its next callback. Returns false when the entity has no such script.

pub fn var_f32(&self, entity: Entity, script: &str, name: &str) -> Option<f32>

Number variable of another script, see Ctx::var.

pub fn var_bool(&self, entity: Entity, script: &str, name: &str) -> Option<bool>

Boolean variable of another script, see Ctx::var.

pub fn spawn(&mut self, name: &str) -> Entity

Creates a named entity with an identity local transform.

pub fn spawn_primitive( &mut self, name: &str, primitive: &str, position: Vec3, ) -> Entity

Creates a visible primitive at a world-space position with no collider/body. Supported primitive names are listed in crate::mesh::PRIMITIVES.

pub fn despawn(&mut self, e: Entity)

Destroys an entity and its subtree. Physics objects are removed on the next fixed step.

pub fn add_impulse(&mut self, impulse: Vec3)

Accumulates a world-space impulse for this body to consume on the next physics step. Does nothing when no RigidBody is attached.

pub fn set_velocity(&mut self, v: Vec3)

Requests a world-space linear velocity in metres/second for the next fixed step.

pub fn set_angular_velocity_of(&mut self, e: Entity, w: Vec3)

Sets the spin of a rigid body (any entity); Vec3::ZERO stops it rotating.

pub fn set_velocity_of(&mut self, e: Entity, v: Vec3)

Sets the linear velocity of any rigid body.

pub fn velocity(&self) -> Vec3

Last simulated linear velocity, or zero when no body is attached.

pub fn raycast( &self, origin: Vec3, dir: Vec3, max_distance: f32, ) -> Option<RayHit>

First solid collider hit by the ray; this entity’s own collider and triggers are ignored.

pub fn raycast_filtered( &self, origin: Vec3, direction: Vec3, max_distance: f32, options: QueryOptions, ) -> Option<RayHit>

Ray query with layer/sensor filters; defaults to excluding this script’s body. An explicit options.exclude overrides that default owner exclusion.

pub fn overlap_sphere_filtered( &self, center: Vec3, radius: f32, options: QueryOptions, ) -> Vec<Entity>

Sphere query under explicit layer/sensor/exclusion filters. No implicit owner exclusion.

pub fn overlap_sphere(&self, center: Vec3, radius: f32) -> Vec<Entity>

Collider entities overlapping a world-space sphere in the last physics state. Includes triggers and this entity; results are sorted and deduplicated.

pub fn touching(&self, entity: Entity) -> Vec<Entity>

Active solid contacts and sensor overlaps for a collider entity.

pub fn is_alive(&self, entity: Entity) -> bool

Whether an entity handle still refers to a living object in this scene.

pub fn world_matrix_of(&self, entity: Entity) -> Mat4

Current world matrix, evaluated directly from local transforms.

pub fn set_parent(&mut self, entity: Entity, parent: Option<Entity>) -> bool

Reparents while preserving world pose when representable as TRS.

pub fn set_parent_local( &mut self, entity: Entity, parent: Option<Entity>, ) -> bool

Reparents while preserving local pose; rejects stale handles and cycles.

pub fn insert<T: EcsComponent>(&mut self, entity: Entity, component: T)

Adds a component of a host-registered type to a living entity.

Panics

Panics for unregistered or conflicting component types; scripts use built-ins only.

pub fn remove<T: EcsComponent>(&mut self, entity: Entity) -> Option<T>

Removes a component, returning its former value if present.

pub fn has<T: EcsComponent>(&self) -> bool

Whether this entity currently has a component.

pub fn attach_script(&mut self, entity: Entity, name: &str) -> bool

Adds a named script slot. The runtime creates its instance at the next sync. Returns false for a stale entity; duplicate names in different slots are allowed.

pub fn detach_script(&mut self, entity: Entity, name: &str) -> usize

Removes every slot with this script name. Returns the number removed.

pub fn tagged(&self, tag: &str) -> Vec<Entity>

Snapshot of all living entities with an exact tag, in index order.

pub fn has_tag(&self, entity: Entity, tag: &str) -> bool

Whether an entity contains this exact group label.

pub fn add_tag(&mut self, entity: Entity, tag: &str) -> bool

Adds a group label, creating Tags if needed. Invalid/duplicate labels or stale entities return false.

pub fn remove_tag(&mut self, entity: Entity, tag: &str) -> bool

Removes a label without removing other tags; returns whether it existed.

pub fn despawn_after(&mut self, entity: Entity, seconds: f32) -> bool

Schedules/replaces subtree expiration after non-negative simulation seconds. Zero expires after update callbacks in the current/next accepted frame. Invalid durations or stale entities return false without changing components.

pub fn set_visible(&mut self, entity: Entity, visible: bool) -> bool

Sets inherited mesh visibility without changing scripts, lights or physics. Returns false for a stale entity.

pub fn is_visible(&self, entity: Entity) -> bool

Effective mesh visibility, including hidden ancestors.

pub fn move_to( &mut self, entity: Entity, target: Vec3, seconds: f32, ease: Ease, ) -> bool

Starts/replaces a parent-local position tween from the current pose. Returns false for invalid targets/durations, stale entities or missing transforms.

pub fn teleport_of( &mut self, entity: Entity, position: Vec3, reset_velocity: bool, ) -> bool

Moves an entity to a world-space point and queues physical teleportation. With reset_velocity, pending impulses and both velocities are cleared. For a dynamic body the final pose is integrated on the next fixed step; non-physical entities move immediately. Invalid/singular requests do nothing.

pub fn teleport(&mut self, position: Vec3, reset_velocity: bool) -> bool

Teleports this script’s entity, optionally resetting its motion.

pub fn emit( &mut self, channel: &str, payload: Value, ) -> Result<u64, SignalError>

Broadcasts JSON data on a channel for delivery before the next frame’s callbacks. Sending is bounded and returns an explicit error rather than silently dropping data.

pub fn send_to( &mut self, target: Entity, channel: &str, payload: Value, ) -> Result<u64, SignalError>

Sends a directed message to a living entity for the next simulation frame.

pub fn signals(&self, channel: &str) -> Vec<Signal>

Clones the current channel messages addressed to this entity or broadcast. Owned snapshots let callbacks mutate the scene while handling messages. Reading does not consume signals; use update for one-shot processing.

pub fn key_down(&self, k: Key) -> bool

Whether the physical key is held this frame.

pub fn key_pressed(&self, k: Key) -> bool

Whether the physical key went down in this frame snapshot.

pub fn key_released(&self, key: Key) -> bool

Whether the physical key went up in this frame snapshot.

pub fn mouse_down(&self, b: MouseButton) -> bool

Whether a physical pointer button is held.

pub fn mouse_pressed(&self, button: MouseButton) -> bool

Whether a physical pointer button went down this frame.

pub fn mouse_released(&self, button: MouseButton) -> bool

Whether a physical pointer button went up this frame.

pub fn lock_cursor(&self, lock: bool)

Hides the cursor and keeps it centred while true; input.mouse_delta then is the look movement.

pub fn load_scene(&self, path: &str)

Switches to another scene once this frame ends, e.g. ctx.load_scene("scenes/level2.scene.json"). Objects and scripts of the current scene go away; the new scene starts with fresh scripts.

pub fn add_scene(&self, path: &str)

Adds every object of another scene to this one once this frame ends (a level piece, a shared menu…). Its scripts start on the next frame; the scene settings stay as they are.

pub fn reload_scene(&self)

Starts the running scene again from its file once this frame ends (restart a level).

pub fn scene_path(&self) -> String

Asset path of the running scene, e.g. scenes/main.scene.json (empty if unknown).

pub fn hud_prompt(&self, text: &str)

Shows the interaction hint on screen for this frame (“Press E to open”).

pub fn hud_message(&self, text: &str, seconds: f32)

Displays a transient message for finite non-negative simulation seconds.

pub fn hud_objective(&self, text: &str)

Replaces persistent HUD objective text; empty clears it.

pub fn hud_crosshair(&self, on: bool)

Requests that the hosting shell show/hide the crosshair.

pub fn action_down(&self, name: &str) -> bool

Named input actions from Project Settings > Input.

pub fn action_pressed(&self, name: &str) -> bool

Whether any bound input went down this frame; missing actions return false.

pub fn action_released(&self, name: &str) -> bool

Whether the last held input bound to this action was released.

pub fn action_vector( &self, left: &str, right: &str, down: &str, up: &str, ) -> Vec2

Unit-length two-dimensional movement from four named actions.

pub fn action_axis(&self, negative: &str, positive: &str) -> f32

Digital axis: positive minus negative action, in [-1, 1].

pub fn rebind(&self, name: &str, inputs: &[&str])

Changes an action’s bindings while the game runs, e.g. ctx.rebind("Jump", &["Space", "W"]).

impl Ctx<'_>

pub fn position(&self) -> Vec3

World position of this entity (alias of Ctx::world_position).

pub fn position_of(&self, entity: Entity) -> Option<Vec3>

World position of another entity, None when it is dead or has no Transform.

pub fn set_position(&mut self, position: Vec3) -> bool

Moves this entity to a world position immediately (no physics teleport; see Ctx::teleport).

pub fn translate(&mut self, delta: Vec3)

Adds delta to the local position (parent space axes).

pub fn translate_local(&mut self, delta: Vec3)

Moves along the entity’s own axes: translate_local(Vec3::NEG_Z * 2.0) goes 2 m forward.

pub fn rotate(&mut self, degrees: Vec3)

Adds Euler degrees (pitch, yaw, roll) to the local rotation.

pub fn forward(&self) -> Vec3

Facing direction (local -Z in parent space).

pub fn right(&self) -> Vec3

Right direction (local +X in parent space).

pub fn up(&self) -> Vec3

Up direction (local +Y in parent space).

pub fn distance_to(&self, entity: Entity) -> Option<f32>

Straight-line distance to another entity, None when it cannot be measured.

pub fn direction_to(&self, target: Vec3) -> Vec3

Unit vector from this entity to a world point, zero when they coincide.

pub fn look_at(&mut self, target: Vec3)

Turns the entity (yaw and pitch, no roll) so that its forward axis points at a world point. Assumes the parent is not rotated. Does nothing when the point is at the entity.

pub fn look_at_flat(&mut self, target: Vec3)

Like Ctx::look_at but ignores height: only the yaw changes (characters, turrets).

pub fn move_towards(&mut self, target: Vec3, speed: f32) -> bool

Walks towards a world point at speed metres per second (uses the callback dt). Returns true once the point is reached. Moves the transform directly, so use it for kinematic objects; dynamic bodies should use add_impulse or set_velocity.

pub fn nearest_tagged(&self, tag: &str) -> Option<(Entity, f32)>

The closest entity carrying tag (other than this one) and its distance.

pub fn despawn_self(&mut self)

Removes this entity (and its children) from the scene.

pub fn random(&self) -> f32

A random number in 0.0..1.0. Every call advances a shared stream, so values differ per call. For a repeatable sequence keep a crate::random::Rng in your script instead.

pub fn random_range(&self, min: f32, max: f32) -> f32

A random number in min..max.

pub fn chance(&self, p: f32) -> bool

True with probability p (0..1) on each call.

impl Ctx<'_>

Hierarchy, tags and shared variables.

pub fn parent(&self) -> Option<Entity>

The parent of this entity, if it has a living one.

pub fn parent_of(&self, entity: Entity) -> Option<Entity>

The parent of any entity.

pub fn root(&self) -> Entity

The top-most ancestor (the entity itself when it has no parent).

pub fn descendants(&self, entity: Entity) -> Vec<Entity>

Every entity below entity: children, grandchildren and so on.

pub fn find_child(&self, name: &str) -> Option<Entity>

The first descendant of this entity with the given name.

pub fn tagged_within(&self, tag: &str, center: Vec3, radius: f32) -> Vec<Entity>

Entities carrying tag within radius metres of a world point, nearest first.

pub fn tags_of(&self, entity: Entity) -> Vec<String>

All tags of an entity.

pub fn play_animation(&mut self, entity: Entity, clip: &str) -> bool

Plays an animation clip on an object (cross-fading from the current one); adds an crate::skeletal::Animator when the object has none. The model must have a skeleton: clips from its file, or the procedural humanoid ones (Idle, Walk, Run, Talk, Wave, Sit, Wipe, Look). Returns false for a stale entity.

pub fn set_animation_speed(&mut self, entity: Entity, speed: f32)

Playback speed of an object’s animation (1 = as authored). Use it to match a walk cycle to the speed the object really moves at.

pub fn ragdoll(&mut self, entity: Entity, impulse: Vec3) -> bool

Makes an animated humanoid go limp: its body becomes physics capsules joined at the joints, starting in the current pose and pushed by impulse (newton-seconds, world space). Adds a crate::ragdoll::Ragdoll when there is none. Returns false for a stale entity.

pub fn stop_ragdoll(&mut self, entity: Entity)

Ends a ragdoll: the bodies are removed and the clip animates the character again.

pub fn look_at_point(&mut self, entity: Entity, point: Option<Vec3>)

Turns an animated humanoid’s head (and chest) towards a world point, or lets go with None. Adds a crate::ik::CharacterIk when there is none.

pub fn animation_clips(&self, entity: Entity) -> Vec<String>

The clips an animated object’s model offers (empty until its first frame was skinned).

pub fn set_global(&mut self, key: &str, value: Value)

Stores a value that every script can read with Ctx::global. Lives until the game stops.

pub fn global(&self, key: &str) -> Option<&Value>

A shared value, if it was set.

pub fn global_f32(&self, key: &str, default: f32) -> f32

A shared number (integers are converted), or default.

pub fn global_bool(&self, key: &str, default: bool) -> bool

A shared flag, or default.

pub fn add_global(&mut self, key: &str, delta: f32) -> f32

Adds to a shared number (starting from 0) and returns the new value: ctx.add_global("score", 10.0).

impl Ctx<'_>

Vertex access and deformation (see crate::mesh_deform).

pub fn make_editable(&mut self, entity: Entity) -> bool

Makes the entity’s built-in primitive mesh (primitive:sphere…) editable so its vertices can be changed from scripts. Returns true when the entity is editable afterwards.

pub fn editable(&mut self, entity: Entity) -> Option<&mut EditableMesh>

The editable mesh of an entity, for deformation: ctx.editable(e)?.twist(Vec3::Y, 30.0).

impl Ctx<'_>

Logging for debugging: everything lands in the editor Console (warnings yellow, errors red).

pub fn warn(&mut self, message: impl Into<String>)

A yellow warning line: ctx.warn("health is below zero").

pub fn error(&mut self, message: impl Into<String>)

A red error line. The script keeps running; use it for conditions that should never happen.

pub fn watch(&mut self, name: &str, value: impl Debug)

Logs name = value using Debug: ctx.watch("velocity", ctx.velocity()).

pub fn watch_every(&mut self, seconds: f32, name: &str, value: impl Debug)

Like Ctx::watch but at most once per seconds, so it can sit in update without flooding the Console.