Module components

Expand description

The runtime component vocabulary (Camera3D, Room, DirectionalLight, Transform, …): every type a World holds, each addable with add_component.

A type an application authors but a world never stores – a Texture, a Prefab, a MainMenu – belongs to the cook namespace instead. Where a name is in both, the authoring form is cook::X and the runtime form components::X; glob this module and path-qualify cook, since the twinned names are ambiguous under two globs.

Structs§

Animation: A skeletal animation clip that animates one SkinnedMesh.
AnimationBlendPoint: One member of a 1D blendspace: a clip pinned at a parameter value.
AnimationCondition: One transition condition, parameter <op> value. All of a transition’s conditions must pass for it to fire.
AnimationGraph: An animation state machine for one SkinnedMesh.
AnimationIkChain: One two-bone IK chain, pinning the chain’s end joint (typically a foot) to the ground the physics scene finds beneath it.
AnimationParam: A named float parameter driving a graph’s transitions. Gameplay systems (or the anim-param debug command) write parameter values at runtime; transitions compare against them. Flag-like parameters use 0 and 1.
AnimationParams: Runtime-only parameter block for one animation graph target.
AnimationState: One state of the graph: while active it plays either a single Animation clip or a blend (a blendspace mixing several clips by parameter value). Exactly one of the two must be set.
AnimationTrack: An animation channel: a time-ordered list of keyframes for one joint.
AnimationTransition: One directed transition between two states.
AppConfig: Runtime half of the AppConfig asset: where the application keeps what it writes, and its process resource budgets.
AudioCommand: Runtime-only event sent by GraphicsSystem when a volume setting changes, read by AudioSystem from its Events<AudioCommand> queue.
AudioCue: Plays audio when a Screen is shown.
AudioEmitter: A point source of sound in the world.
AudioOcclusionProbe: Runtime-only occlusion probe for a positional audio emitter.
Behavior: A unit of world logic: an event source, the entities it runs against, its state, the world it reads, and the nodes it runs.
BehaviorLocal: A per-entity state slot declared by a Behavior. The declared value fixes both the slot’s type and its starting value.
BehaviorQuery: A world read declared by a Behavior, resolved once per tick into the entities carrying every named component.
BlockType: Describes one entry in a VoxelChunk palette.
BodyDynamics: Dynamic-body parameters attached to an entity with a Collider.
Camera3D: Declares the 3D camera. One per scene.
CameraController: First-person / fly-through controller settings carried on a Camera3D.
CameraProbe: Runtime-only occlusion probe for the third-person follow camera.
CharacterRig: Runtime-only link between a skinned mesh and its character capsule.
CharacterShape: Shape sliders and joint proportions applied to one SkinnedMesh.
Children: The entities that name this entity as their Parent.
Collider: Collision volume attached to an entity, in local space scaled by the entity’s transform.
ContactEvent: Runtime-only event published by the physics system when two bodies collide hard enough to pass the world’s contact impulse threshold. a is always a simulated prop entity; b is the other side’s entity, or None when the other body has no entity (terrain, the floor slab, a character capsule). normal points from a’s surface toward b; impulse is the contact’s total impulse magnitude (mass times velocity change). World authors never declare this type directly.
ControlsCommand: Runtime-only event sent by GraphicsSystem when a live camera setting changes, read by Camera3DSystem from its Events<ControlsCommand> queue.
DebugHud: Requests the developer debug HUD: a set of TextLabel chips with diagnostic readouts, anchored to the top-right of the window and toggled with F1 (hidden by default).
Decal: A projected texture stamped onto whatever scene geometry sits inside the decal’s oriented box.
DespawnRequest: Runtime-only event requesting that an authored placement be removed from the world at runtime. A named target needs no live Entity handle; an entity-addressed one reaches placements that never had a name. GraphicsSystem reads these from its Events<DespawnRequest> queue each step, resolves the target to its entity, hides that entity’s GPU draw slots, and despawns it and its descendants. World authors never declare this type directly.
DirectionalLight: An infinitely distant directional light (sun, moon, or sky fill).
EngineDefaults: Opts a world out of individual engine-injected defaults.
File: References a source file by path.
FollowController: Third-person follow settings carried on a CameraController.
FpsCounter: Requests a frames-per-second counter; optionally writes it to a TextLabel.
FrameInput: Per-frame keyboard and mouse input state.
GamepadMap: The canonical action -> gamepad button map. Persisted in the engine’s controls settings and applied by the input sampling; carried live to consumers via ControlsCommand on a rebind. Each field is #[serde(default)] so adding an action in a future build never invalidates an existing settings file.
GlassPanel: A flat translucent panel of coloured glass. A fixed-orientation rectangular quad that refracts and tints the scene behind it and brightens the grazing-angle rim with a Fresnel highlight.
GlobalTransform: Composed world matrix for an entity, after parent transforms are applied.
GraphicsConfig: Rendering settings for the world: frame pacing, shadows, and clear colour. One per world. The GPU backend is chosen by the engine for the platform and is not user-configurable.
GroundProbe: One downward ground probe: a ray and, once physics has answered it, the hit it found.
GroundProbes: Runtime-only ground-probe exchange for one animated character.
Held: Marks an entity currently being carried by the player.
Hidden: Runtime-only tag: this entity’s draw slots are switched off by a hide action (VisibilityRequest). The entity keeps simulating; scene-driven visibility switches leave tagged entities dark, and a show request removes the tag and relights the slots. Never authored directly.
HitRegion: A responsive invisible rectangular region in screen space.
InstanceTransform: Per-instance transform within an InstancedProp.
InstancedProp: A single mesh + material drawn at many world-space transforms.
InteractEvent: Runtime-only event published by the camera controller when the interact key fires on an Interactable entity: target is the entity’s declared name. BehaviorSystem reads these from its Events<InteractEvent> queue each step (one tick after the press, since the controller runs later in the schedule). World authors never declare this type directly.
Interactable: Marks an entity the player can interact with (press the interact key while close and facing it to trigger its behavior).
JointProportion: One joint’s proportion change.
KeyBinding: Maps a keyboard key to an action string.
Keyframe: One keyframe in an animation track: a joint pose sampled at time seconds. The pose fields (translation, rotation_deg, scale) are given directly on the keyframe, each defaulting to the identity transform when omitted.
LabelBox: A label’s measured extent, used by LayoutContainer::layout to place it. w/h are the full background-box size in pixels (the text extent grown by pad on every side). pad is the horizontal inset from the box’s left edge to the text origin. top_inset is the vertical inset from the box’s top edge down to the text origin (the label’s y); it is distinct from pad because the box hugs the visible glyphs, which sit below the text origin.
LabelPlacement: The resolved top-left text origin for one label.
LayoutContainer: Positions a set of TextLabels as a stack of rows, so a HUD does not have to hand-place every chip. Each row lays its labels out left to right; rows stack top to bottom. The container owns the labels’ on-screen position: the labels keep their own styling (font, colour, background, padding) but their x/y are overwritten each frame.
LayoutRow: One horizontal row of labels inside a LayoutContainer.
Lifetime: Runtime-only countdown on an entity: seconds remaining before it is automatically removed. A spawn carries it onto short-lived instances (projectiles, debris, timed effects); the graphics step decrements it each frame and despawns the entity (and its descendants) when it reaches zero, reclaiming the GPU draw slots for reuse. World authors never declare this type directly; it is set at spawn time.
LoadingOverlay: Requests the scene-loading overlay: a full-window backdrop with a progress bar, shown while a scene jump waits for its streamed content and faded out once the destination scene is fully resident.
MeshRenderer: Single-mesh render description for an entity: which mesh, material, and optional legacy texture to draw, plus an optional view-distance cutoff.
Model: An ordered list of sub-meshes, each with its own material.
ModelRenderer: Multi-mesh render description for an entity: a Model whose sub-meshes all share this entity’s transform, each with its own material.
MorphKey: One morph-weight keyframe of an Animation: per-target weights at one sample time.
Parent: The entity whose world transform this entity inherits.
ParticleEmitter: A billboard particle emitter.
PhysicsConfig: Configures the world’s physics floor / terrain.
PhysicsJoint: A physics constraint connecting two Props that own a collider.
Pickup: Marks an entity the player can pick up and carry with the interact key.
PlayCue: Runtime-only event asking the audio system to play a clip: the direct equivalent of an AudioCue firing, for systems that trigger audio from their own state (the story system plays page music and one-shots this way). World authors never declare this type directly.
PointLight: A spherical point light with quadratic distance attenuation.
PostProcessConfig: Tunables for the post-process stack. One per world; the first declared instance wins. With no PostProcessConfig present, the defaults below are used.
ProceduralMesh: Geometry built by a named generator at compile time. Use for standard shapes.
Prop: A scene object: places geometry at a world-space transform.
PropBody: Makes a companion Prop a dynamic physics body.
PropCollider: Collision volume attached to a Prop.
PropInstance: Marks an entity that was authored as a Prop.
RectAreaLight: A rectangular area light: a glowing panel that lights the scene from its whole surface rather than from a single point.
ReflectionProbe: A localized reflection probe. The renderer captures the surrounding scene into a cubemap from position and uses it for the specular reflection on glossy surfaces within the influence box (position plus or minus half_extents). The box is also the parallax-correction volume, so a reflection stays anchored to the surrounding geometry as the camera moves.
RenderHandle: The backend draw-object slot(s) an entity occupies.
ReparentRequest: Runtime-only event requesting that an authored placement be re-parented at runtime: child is moved under parent, or detached to a root when parent is None. GraphicsSystem reads these from its Events<ReparentRequest> queue each step, resolves the nameto their entities, re-points the child’s Parent edge, and recomposes world matrices. World authors never declare this type directly.
ResolvedSliders: Morph weights resolved from a shape’s sliders against a mesh’s morph-target names, plus the slider names that matched nothing.
RigidBody: Gives a player Camera3D gravity, jumping, and a grounded character body.
Room: A self-contained room (floor, ceiling, four walls), with optional texturing.
RootMotionEvent: Per-frame character displacement extracted from root-motion clips.
Scene: A named group of world content.
SceneCommand: Runtime-only event sent by UiInputSystem when a scene-jump HitRegion fires. GraphicsSystem reads these from its Events<SceneCommand> queue each step and applies the scene jump. World authors never declare this type directly.
SceneMember: The Scene an entity belongs to, for per-scene show/hide.
Screen: A named full-screen layer of UI drawn over the world: a pause menu, a settings page, a console, a score overlay.
ScreenShown: Runtime-only event sent by UiInputSystem whenever a screen reaches the top of the stack: the initial screen at world start, a screen:show / screen:push / screen:toggle navigation, or a pop revealing the screen beneath. Read by AudioSystem to fire AudioCues. World authors never declare this type directly.
ScrollGroup: A collapsible group of rows inside a ScrollPanel.
ScrollPanel: Runtime model that makes a band of UI rows scrollable and (optionally) collapsible.
ScrollRow: One row inside a ScrollPanel: the elements that move together, the row’s height, and the collapsible group it belongs to.
SdfVolume: A raymarched signed-distance-field volume. It occupies a world-space bounding box; a user-authored fragment shader sphere-traces an SDF inside the box, composites correctly with the surrounding scene through the depth buffer, and shades hits with the engine’s lighting helpers.
SettingCommand: Runtime-only event sent by UiInputSystem when a “setting:*” action fires. GraphicsSystem reads these each step: it applies the change to the named setting (cycling it or setting it from a fraction), updates the value_label text, and (when persist is set) writes the new value to the settings store. World authors never declare this type directly.
Shader: Replaces how surfaces are shaded, and optionally how vertices are placed, with functions of your own. Written in Slang, one source for every backend.
ShaderPrograms: The compiled payload a Shader carries in the blob: the authored files and every program the cook compiled from them. Written by the cook, decoded once by the renderer at load.
ShapeSlider: One named shape value in [-1, 1].
SkeletonPose: Runtime-only link between a skinned mesh and its animation state.
SkyRotation: Turns the whole celestial sphere: the sky, the image-based lighting it casts, every DirectionalLight, and any Prop hung on it.
SpawnRequest: Runtime-only event requesting that a copy of an existing placement be created in the world at runtime. The symmetric counterpart to DespawnRequest.
Spawner: Periodically instantiates copies of an existing placement at this entity’s position.
SpotLight: A cone-shaped local light: a point light restricted to the cone around direction, with a soft edge between inner_angle and outer_angle.
Sprite: Screen-space 2D rectangle drawn as a UI overlay each frame.
StatHud: Requests the default on-screen stats HUD. Drives a set of TextLabel chips with live engine stats, refreshed on a fixed interval.
Story: A compiled branching story graph, played at runtime by the story system.
StoryChoice: One option in a StoryNode’s choice menu.
StoryCondition: A condition on a StoryChoice.
StoryGate: One conditional jump in a Story’s script.
StoryImage: One placed stage image: which Texture to sample and where it sits on the reference canvas.
StoryNode: One jump target in a Story: a run of pages optionally ending in a choice menu.
StoryOp: One variable operation in a Story’s script. All story state is named integer variables, starting at 0 each playthrough: a plain flag is a variable set to 1 and cleared to 0.
StoryPage: One click-through page of a StoryNode.
StoryReload: Runtime event carrying a freshly re-compiled Story graph. The story system swaps its graph for the new one in place, keeping the current position (matched by node slug) and raised flags, so edits to a story’s source land in the running game. A plain event, not a declarable asset.
StoryScaffold: The stage scaffolding a Story’s build expansion generated: the Screens, Sprites, and TextLabels the story system mutates page by page.
StorySpeaker: A resolved speaker attribution on a StoryPage.
StoryStage: The stage dressing current at a page or choice menu: the backdrop and the character portraits standing on stage.
StreamingConfig: Enables and tunes asset streaming.
SubMeshRef: One geometric part of a Model, referencing a mesh and its surface material.
TextInput: An editable single-line text field drawn as a UI overlay.
TextLabel: Screen-space text drawn as a UI overlay on top of the 3D scene each frame.
Transform: World-space placement of an entity: translation, rotation, and scale.
TriggerVolume: An invisible sensor region that reports when something enters or leaves it.
VariableDecl: One variable declared by the world’s Variables. The declared value fixes both the variable’s type and the value it holds at world start.
Variables: The world’s shared variables: the state Behaviors read with var and write with set, and the state a save node persists.
VisibilityRequest: Runtime-only event requesting that an entity (and its descendants) be hidden or shown without despawning it. SpawnSystem drains these each step, toggling the subtree’s Hidden tags and its draw slots’ visibility. World authors never declare this type directly.
VolumeEvent: Runtime-only event published by the physics system when something crossing a TriggerVolume boundary passes the volume’s detects filter. entered is true on the way in and false on the way out. BehaviorSystem reads these from its Events<VolumeEvent> queue each step (one tick after the crossing, since physics runs later in the schedule). World authors never declare this type directly.
VolumetricFog: Environmental volumetric fog: a single lit medium that wraps the scene, thicker near the ground and thinning with height, with extra glow around the sun.
VoxelChunk: A voxel grid that compiles into a single mesh.
VoxelWorld: An infinite, procedurally generated voxel world.
WaterSurface: A translucent animated water surface.
WaterWave: One wave in a water surface’s motion. A surface sums up to four of these to displace its flat grid. Each wave travels horizontally along direction, rising and falling with amplitude peak height, wavelength distance between crests, and speed metres per second. steepness in [0, 1] pinches the crests and broadens the troughs (choppier water).
Window: Declares the application window.

Enums§

AaMode: Anti-aliasing mode for PostProcessConfig.aa_mode. Off runs no edge smoothing; Fxaa (default) applies the composite’s single-frame edge filter, which is nearly free; Taa adds a temporal pass that jitters the projection and reprojects detail across frames for the cleanest edges, at the cost of a velocity pre-pass and a per-frame history buffer.
AnimationBlend: A blendspace: several clips mixed continuously by parameter value instead of one clip per state. kind selects the shape.
AudioBus: A mix bus grouping related sounds under one user volume.
AudioTarget: The output stage an AudioCommand addresses: the master mix or one of the three buses under it.
BehaviorExpr: A value expression in a Behavior.
BehaviorLiteral: A typed literal in a Behavior.
BehaviorNode: One node run by a firing Behavior.
BehaviorSource: The event that fires a Behavior.
CueKind: How an AudioCue plays its clip.
EntityTarget: How a runtime request addresses the entity it acts on. Authored placements are named, so a producer holding no live handle addresses them by asset name and the applying system resolves it. Logic that already holds an entity – one it spawned, one a query yielded – addresses it directly, which is the only way to reach an entity that never had a name.
FileKind: The category of file content, inferred from the extension when not supplied.
FollowDrive: How a followed character converts movement input into displacement.
GamepadAction: A rebindable gamepad action. Movement and look come from the sticks (with the d-pad as a digital movement fallback), so only the button-driven actions are rebindable; pause (Start) carries menu semantics and stays fixed, like Escape on the keyboard.
GamepadButton: A canonical, vendor-neutral gamepad button.
IndirectLighting: Indirect-diffuse lighting source for PostProcessConfig.indirect_lighting. Ibl is the image-based-lighting-only ambient term the renderer has always used; Ssgi layers a screen-space global-illumination bounce on top.
InputKey: A canonical, backend-agnostic keyboard key.
Justify: Horizontal placement of a row’s labels within the container’s content width (the width of the widest row). Ignored when a row is as wide as the content.
NavDirection: A directional UI-navigation pulse, carried by FrameInput::nav for one frame.
PhysicsJointKind: The constraint shape a PhysicsJoint declares.
ReflectionBlurResolution: Internal render resolution of the roughness-aware reflection blur (only meaningful when ssr or ray_traced_reflections is on). The blur is the expensive multi-tap part of the reflection composite and is low-frequency (a widening glossy cone), so running it at a fraction of the pixels and bilinearly upsampling is visually free. half (the default) blurs at a quarter of the pixels; full keeps it at native resolution; quarter is the cheapest. Mirrors stay sharp regardless: the composite lerps in the full-resolution reflection for low roughness.
Rolloff: How an AudioEmitter’s volume falls with distance.
ScreenCommand: Runtime-only event sent by UiInputSystem when a screen:* action fires. UiInputSystem reads these from its Events<ScreenCommand> queue on the next step and applies the stack transition. World authors never declare this type directly.
ScreenInput: How a Screen treats input while it is active.
SettingOp: What a “setting:*” action does to its value: cycle one step (for a stepper row), jump to an absolute option index (for a dropdown pick), set an absolute position in [0, 1] (for a slider row’s drag), or bind a key (for a key-rebind row).
ShaderStage: One of the two files a Shader declares.
ShadowUpdate: How often each cascaded-shadow-map slice is re-rendered. The shadow pass re-rasterizes all scene geometry into every cascade, so it is one of the heavier passes; updating distant cascades less often cuts that cost.
SpriteFit: How a screen-owned overlay element (a Sprite, TextLabel, or HitRegion) maps from the 1280x720 reference canvas to the live window when their aspect ratios differ.
SsgiResolution: Internal render resolution of the SSGI gather pass (only meaningful when indirect_lighting is ssgi). The gather is the expensive part (a hemisphere ray-march per pixel), and its composite is a depth-aware bilateral filter that upsamples a lower-resolution gather back to full resolution at little visible cost. half (the default) gathers at a quarter of the pixels for a large saving; full keeps the gather at native resolution; quarter is the cheapest, for low-end GPUs or debugging.
StoryCommand: Runtime-only event sent by UiInputSystem when a story:* action fires (a stage click, a Space press, a choice button, a Start / Restart button). The story system reads these and moves through the story graph. World authors never declare this type directly.
StoryCompareOp: A comparison operator in a Story condition. An unset variable reads as 0, so a plain flag test is Ne 0 and its negation Eq 0.
StoryPlayback: The Story playback command a Behavior node sends.
TextAlign: Horizontal alignment of a TextLabel relative to its x.
TriggerFilter: What a TriggerVolume senses.
UpscaleQuality: Render-scale preset for PostProcessConfig.temporal_upscaling. The ratio applies to both axes (input pixel count = output * ratio per axis), so Quality renders at 4/9 of the output pixel count, Performance at 1/4, and UltraPerformance at 1/9.
UpscalerBackend: Upscaler backend selector for PostProcessConfig.temporal_upscaling. Auto resolves at runtime to the best available (DLSS, then XeSS, then FSR3); the explicit variants request a specific backend and fall back when it is unavailable. DLSS (NVIDIA NGX) and XeSS (Intel) are DirectX-only; Metal uses MetalFX and Vulkan has no upscaler yet, so both treat any value as their native path.
WindowMode: How the application window is presented.