Documentation

This page is organized so you can scan the left rail, search for a topic, and jump straight to the part you need.

1. Editor guide to learn the workspace and panel layout.
2. Workflow and files to understand project structure and asset flow.
3. Viewport and play mode to get comfortable moving around scenes.
4. Sterren FS basics to start scripting.
5. Build and test when you are ready to compile locally.

The Sterren editor is a dockable ImGui application for building scenes, previewing assets, and running the game runtime.

Main panels

• Project Browser — browse project files, create folders, scripts, materials, and scenes.
• Hierarchy — the entity tree for the open scene.
• Inspector — edit transforms and components.
• Viewport — the live 3D editing surface with play controls.
• Script Editor — analyze and edit .fs scripts.
• Console — filter info, warning, and error output.

Expected project layout

Assets/
Assets/Scenes/
Assets/Scripts/
Build/

Assets/ holds the project content, Assets/Scenes/ stores scene files, Assets/Scripts/ stores .fs scripts, and Build/ is the recommended location for generated output.

• Orbit — right-drag, or Option/Alt + left-drag on trackpads.
• Pan — Shift + right-drag, or Shift + middle-drag.
• Dolly or zoom — Ctrl/Cmd + right-drag, or the mouse wheel.
• Press Play in the Viewport or Game panel to enter runtime; use Stop to leave.

Sterren FS is the engine's Lua-based scripting format. Files use the .fs extension.

local script = Behaviour.define({
  props = { moveSpeed = 4.0 },
  state = { velocityY = 0.0 },
})

function script:update(dt)
  if Input.Held("MoveForward") then
    self.xform.pz = self.xform.pz - self.props.moveSpeed * dt
  end
end

return script

Lifecycle hooks

• start() runs once after a script is loaded.
• update(dt) runs every frame.
• fixedUpdate(dt) runs on the fixed 60 Hz step.
• collision(otherEntity, contact) runs on physics collisions.

Export fields

The editor reads -- @export ... comments and turns them into Inspector controls.

-- @export <type> <name> <default>

Supported export types include:

• float, int, bool, string, color, vec3, and enum.
• entityref for entity references.

-- @export float moveSpeed 4.0
-- @export int lives 3
-- @export bool enabled true
-- @export string displayName "Robot"
-- @export color tint 1.0 1.0 1.0 1.0
-- @export vec3 offset 0.0 1.0 0.0
-- @export enum cameraMode "FirstPerson;ThirdPerson" 0
-- @export entityref target "" ""

• enum stores a quoted list of options separated by semicolons and a default index.
• entityref stores an entity reference and can carry an optional filter string.
• Exported values are preserved when the editor reparses the same script.

Built-in modules

The framework bootstrap creates and normalizes these namespaces before scripts run:

• Sterren.World
• Sterren.Entity
• Sterren.Query
• Sterren.Input
• Sterren.Physics
• Sterren.Time
• Sterren.Events
• Sterren.Audio
• Sterren.Debug
• Sterren.Math
• Sterren.Assets
• Sterren.Scenes
• Sterren.Net
• Sterren.Replay
• Sterren.Profiler
• Sterren.Jobs
• Sterren.Random
• Sterren.Services

Common helpers

• Sterren.Time.now()
• Sterren.Input.Held, Down, and Released
• Sterren.World.spawnPrefab, spawn, destroy, and DestroyEntity
• Sterren.Query.FindEntity, FindEntityByName, FindEntityByTag, and FindEntitiesInRange
• Sterren.Physics.Raycast, sphereCast, boxCast, capsuleCast, overlapSphere, and overlapBox
• Sterren.Assets.loadAsync
• Sterren.Scenes.load, loadAsync, loadAdditive, unload, and setActive
• Sterren.Audio.PlayEntity, StopEntity, PauseEntity, ResumeEntity, PlayOneShot, and volume controls
• Sterren.Debug.log, warn, and error
• Vec2, Vec3, Vec4, Quat, and Color

Descriptor and schema helpers

• Behaviour.define, System.define, Service.define, Asset.define, Query.define, and Test.define
• Prop.* schema helpers for inspector-exposed fields including bool, int, float, string, vec2, vec3, vec4, quat, color, enum, flags, entityref, componentref, assetref, prefabref, sceneref, materialref, audioref, animationref, inputAction, layer, layerMask, tag, curve, gradient, bounds, rect, variant, and uiref, plus group, struct, list, and map.
• State.* schema helpers for runtime state including bool, int, float, string, vec2, vec3, vec4, quat, color, entity, table, list, map, and variant.
• Signal.define and Validation.ok, Validation.warn, Validation.error.

Runtime instance helpers

• self.entity:id(), name(), and hasTag(tag)
• self:emit(signalName, ...), self:on(...), and self:send(methodName, ...)
• self:task(name, callback) and task helpers such as nextFrame(), fixedUpdate(), waitSeconds(seconds), untilCondition(predicate), and cancel()
• self:service(name), self:getState(path), self:setState(path, value), and self:isAlive()
• The runtime keeps the entity proxy and self.xform access available, which is why sample scripts can move entities directly from Lua.

Hot reload and diagnostics

• The runtime keeps per-entity script instances stable so exported values and state can survive hot reload when the descriptor still matches.
• The Script Editor warns about long lines, unmatched brackets, debug prints, invalid @export declarations, and missing script descriptors.
• When a script fails, the error is forwarded back into the editor console.

cmake -S "/path/to/forge3d" -B /tmp/sterren-build -G Ninja \
  -DCMAKE_TOOLCHAIN_FILE="/path/to/forge3d/vcpkg/scripts/buildsystems/vcpkg.cmake" \
  -DCMAKE_BUILD_TYPE=Debug

cmake --build /tmp/sterren-build --target forge_editor
ctest --test-dir /tmp/sterren-build --output-on-failure