Component Reference

A component is a plain Zig struct that opts into editor discovery. There is no base class to inherit and no registration boilerplate — a single marker is enough.

Marking a struct as a component

pub const Health = struct {
    pub const is_component = true;

    max: f32 = 100.0,
    current: f32 = 100.0,
};
  • pub const is_component = true; marks the struct for discovery. Set it to false to temporarily opt out without deleting the struct.
  • The editor parses real Zig source (not a regex), so the marker works regardless of formatting, comments, or conditional compilation.
  • The struct must be pub and its name must start with a capital letter.
  • Component type names must be unique across the project. Duplicates are reported and the second definition is ignored.

User scripts live in your project's assets/ folder. After adding or editing a script, click Refresh in the Asset Browser to re-scan.

Supported field types

Public fields with a default value become editable controls in the Inspector.

Type Inspector control
f32 number field
i32 integer field
bool checkbox
engine.Vec3 three-axis vector field
engine.GameObjectRef drop target — drag an object from the Hierarchy
engine.ComponentRef drop target — reference another component
engine.AssetRef drop target — reference an asset

Fields prefixed with _ (e.g. _timer) are treated as private runtime state and are not shown in the Inspector.

Lifecycle hooks

All hooks are optional — implement only the ones you need.

Hook Called when
awake(self) or awake(self, frame: engine.Frame) Object is first loaded
enable(self) or enable(self, frame: engine.Frame) Object becomes active
start(self) or start(self, frame: engine.Frame) Scene starts running
update(self, frame: engine.Frame) Every frame (preferred)
update(self, time: engine.Time) Every frame (legacy)
disable(self) or disable(self, frame: engine.Frame) Object becomes inactive
destroy(self) or destroy(self, frame: engine.Frame) Object is destroyed

The engine.Frame context bundles everything a script needs: frame.time, frame.input, frame.transform, frame.objects, and frame.services. See the Input System page for a full field reference.

engine.Time

Field Type Meaning
.delta f32 seconds since the last frame
.elapsed f32 total seconds since the scene started
.frame u64 frame counter

Built-in components

Built-in components ship with the engine and require no script. Add them via Add Component ▾ in the Inspector. Authoring your own built-in is a contributor task — see Install & Build from Source.

Next steps

← All docs Edit on GitLab