Scripting the GAM200 engine

How scripting works

You write components as JSON files and systems as C# scripts. The editor turns the JSON into C# types, wires your systems into the engine and recompiles every time you save. You never write or see that plumbing.

Project layout

Everything lives in your project folder (the one with the .astge file), never in the engine folder.

MyGame/
  MyGame.astge          project file: open this in the editor
  Scenes/               *.scene.json, made in the editor
  Prototypes/           *.proto.json, reusable entities ("prefabs")
  Components/           *.json, your components
  Scripts/              *.cs, your systems (shipped with the game)
  Editor/               *.cs, your editor tools (editor only)
  Animations/           *.anim.json animation clips
  Assets/ ...           art and audio, any folder names you like
  Resources/            files you only load by name from code (always exported)
  StreamingAssets/      data files read with Assets.ReadText (always exported)
  ProjectSettings/      Build.json (Build window settings)
  Library/              editor cache and editor save data   (do not commit)
  Builds/               exported games                      (do not commit)

The frame, in order

Knowing the order explains most "why didn't this happen yet" questions.

1. Input and events. SDL events are polled, then queued events are delivered (scene loads, spawns, your events).
2. FixedUpdate. 0 to 5 steps at 60 Hz. Physics runs here.
3. Update. Systems in phase order PreUpdate → Update → PostUpdate, lower Order first. Commands are flushed between phases.
4. Animation, then LateUpdate (camera, UI, hierarchy).
5. Frame end. Commands flushed, events delivered again, timers fire, Session.FrameEnd runs, debug lines and UI are sent.
6. Audio and render. Queued sounds start, then the frame is drawn.

Your first component and system

This walkthrough makes a sprite spin, with a speed you can change in the Inspector. It touches every part of the workflow.

1. Define the data

Create Components/Spinner.json (or Scripts › New Component). Pick an id of 1000 or more that nobody else uses.

{
  "name": "Spinner",
  "id": 1200,
  "fields": [
    { "name": "Speed",   "type": "float", "default": 90, "tooltip": "Degrees per second" },
    { "name": "Enabled", "type": "bool",  "default": true }
  ]
}

2. Write the behaviour

Create Scripts/SpinnerSystem.cs. The SpinnerCollection parameter tells the engine which entities this system runs over.

using Engine.Core;
using GeneratedECS;
using static GeneratedECS.GeneratedECSRegistry;

namespace Game;

[ECSSystem(6200)]                                   // unique system id
public static class SpinnerSystem {
    public static void Update(float dt, SpinnerCollection spinners) {
        for (int i = 0; i < spinners.Length; i++) {
            var s = spinners[i];
            if (!s.Enabled) continue;
            if (Transform.TryGet(s.EntityId, out var t))
                t.Rotation += s.Speed * dt;          // writes straight into the entity
        }
    }
}

3. Use it

1. Save both files. The editor compiles automatically; errors appear in the Console with file and line.
2. Select an entity with a Sprite, click Add Component and pick Spinner.
3. Press Play. Change Speed in the Inspector while it runs.
4. Press Stop. Play-mode changes are discarded; save the scene (Ctrl+S) for changes made while stopped.

Everyday workflow

IntelliSense is missing my component

Generated types such as EnemyCollection come from the component JSON. If your IDE doesn't know them yet, save and let the editor compile once, then reload the project in the IDE. After changing the generator itself, restart Visual Studio, which caches it.

GameScripts.csproj and git

The editor writes GameScripts.csproj into the project folder whenever it opens the project. It is only for your IDE (the editor compiles scripts itself) and it is committed with the project. The engine build folder is written relative to the project, so everyone with the same folder layout gets the same file, whichever drive or folder the repository is in:

<EcsEngineExeDir>$([System.IO.Path]::GetFullPath('$(MSBuildProjectDirectory)\..\..\local_desktop_build\Debug'))</EcsEngineExeDir>
<EcsEngineSourceDir>$(EcsEngineExeDir)\ScriptEngine</EcsEngineSourceDir>
<EcsToolsDir>$(EcsEngineExeDir)\Tools</EcsToolsDir>

It still changes when you open the project with a Release editor (Release instead of Debug in that path) or keep the project somewhere else relative to the build folder. Either version works for anyone who has that build folder, so the team commits the Debug one and discards the other change. Don’t edit the file by hand: the editor rewrites it.

Writing a component

A component is plain data. One JSON file per component, anywhere under a Components/ folder.

{
  "name": "Enemy",
  "id": 1100,
  "trackChanges": false,
  "fields": [
    { "name": "Health", "type": "float", "default": 100, "range": [0, 100], "tooltip": "Hit points" },
    { "name": "Alive",  "type": "bool",  "default": true },
    { "name": "Home",   "type": "Vec2",  "default": "0, 0" },
    { "name": "Tint",   "type": "Color", "default": "#FF8800" },
    { "name": "State",  "type": "enum",  "values": ["Idle", "Chase", "Attack"], "default": "Idle" },
    { "name": "Target", "type": "Entity", "header": "AI" },
    { "name": "Icon",   "type": "Texture" },
    { "name": "Hit",    "type": "Audio" },
    { "name": "Name",   "type": "string" },
    { "name": "Loot",   "type": "List<string>" }
  ]
}

Top-level keys

Field types

Aliases also accepted: Sprite/Image (Texture), Anim/AnimationClip, Sound/AudioClip.

Per-field keys

Mistakes

Bad JSON, an unknown type, a duplicate field, or two components with the same id or name are compile errors that name the file (GEN001–GEN004). The bad component is left out; everything else still compiles.

Using components from C#

Every component JSON produces a struct in GeneratedECS.GeneratedECSRegistry, which the using static at the top of every script brings into scope. The struct is a view: it holds a pointer to the entity's data, so setting a property writes straight into the engine. Copying it into a local variable does not copy the data.

// from anywhere: systems, event handlers, timers, UI callbacks
if (Enemy.TryGet(entity, out var en)) en.Health -= 10;   // safe: checks first
var t = Transform.Get(entity);                             // throws if missing
bool armed = Weapon.Has(entity);
foreach (var e in Enemy.All()) Debug.Log(e.Health);        // every Enemy in the world

// asset fields: path string, or the fast int id
var sprite = Sprite.Get(entity);
sprite.Texture = "Assets/Images/Boss.png";
if (sprite.TextureId == other.TextureId) { /* same image */ }

// enum fields use the generated enum
if (en.State == EnemyState.Chase) { /* ... */ }

Adding and removing

public static void Update(EnemyCollection enemies, Commands cmd) {
    for (int i = 0; i < enemies.Length; i++) {
        var e = enemies[i];
        if (e.Health <= 0 && !Burning.Has(e.EntityId)) {
            var b = Burning_Defaults();           // raw struct with the JSON defaults
            b.Duration = 3f;
            cmd.Add(e.EntityId, Burning.TypeId, in b);
        }
    }
}

Built-in components

The engine's own components (ids 100–127) work exactly like yours. Their fields are listed in the component reference.

Writing a system

A system is a static class marked [ECSSystem(id)] with any of six lifecycle methods. Write only the ones you need.

using Engine.Core;
using GeneratedECS;
using static GeneratedECS.GeneratedECSRegistry;

namespace Game;

[ECSSystem(6000)]
public static class EnemySystem {
    public static void OnStart() {
        Physics.OnTriggerEnter(Scenes.Find("Goal"), c => Scenes.Load("Level2"));
    }

    public static void Update(float dt, EnemyCollection enemies, Commands cmd) {
        for (int i = 0; i < enemies.Length; i++) {
            var e = enemies[i];
            if (e.Health <= 0) { cmd.Destroy(e.EntityId); continue; }
            if (e.State == EnemyState.Chase && World.IsAlive(e.Target)) { /* move towards it */ }
        }
    }
}

Lifecycle methods

Parameters

Every method takes 0–3 parameters, matched by type in any order:

• float: delta time (same as Time.DeltaTime).
• One XCollection or one Query<A, B>: the entities this system runs over. Use the same one in every method of the system.
• Commands: deferred structural changes.

A system without a collection still runs once per frame. Use it for global logic (input, spawning waves, HUD).

Phases and order

[ECSSystem(6010, Phase = SystemPhase.PreUpdate, Order = 10)]
public static class ReadInputSystem { /* ... */ }

Phases run PreUpdate → Update (default) → PostUpdate. Inside a phase, lower Order runs first (default 0, negatives allowed).

So gameplay in Update sees last frame's physics result, and moves you make in Update are applied to children and the camera the same frame.

Several components: Query

When a system needs entities that have two or more components, take a Query instead of a collection.

[ECSSystem(6020)]
[Without(typeof(Frozen))]                         // optional: skip entities that have Frozen
public static class MoveSystem {
    public static void Update(float dt, Query<Velocity, Transform> q) {
        foreach (var row in q) {
            var (v, t) = row;                         // or: var (entity, v, t) = row;
            t.PosX += v.X * dt;
            t.PosY += v.Y * dt;
        }
    }
}

• Up to 4 components. The first is iterated; entities missing any other are skipped, so put the rarest first.
• Query<A> yields A directly.
• [Without(...)] applies to the system's Query parameters only.
• Same rules as collections: the views write through; structural changes go through Commands.

Change tracking

Set "trackChanges": true in a component's JSON, then skip entities that didn't change since this system last ran:

public static void Update(HealthBarCollection bars) {
    for (int i = 0; i < bars.Length; i++) {
        if (!bars.Changed(i)) continue;            // only bars added or modified since last time
        Redraw(bars[i]);
    }
}

Untracked components report every slot as changed. For a Query, q.Changed(row.Index) covers the first component.

Entities, handles and structural changes

An entity id is a ulong handle: slot index plus a generation. When an entity dies its slot's generation changes, so an old handle you kept (a target, a follow) never reaches a different entity that reused the slot. World.IsAlive(id) just returns false.

ulong target = enemy.Target;
if (World.IsAlive(target) && Transform.TryGet(target, out var tt)) { /* chase */ }

Structural changes

Creating or destroying entities and adding or removing components can move component memory. Inside a system loop, do them through something deferred:

Event handlers, timers, physics and UI callbacks all run at the end of the frame, outside any loop, where anything is allowed.

Events

Events pass messages between systems without direct references. They go through the same queue C++ uses, so C++ and C# can talk both ways.

1. Declare a struct with a unique id. Only unmanaged fields: numbers, bools, ulong entities, Vec2, nested blittable structs. No strings or lists.
2. Subscribe in OnStart. Subscriptions are cleared when Play stops, so you never get duplicates.
3. Publish from anywhere. Delivery happens at the next dispatch (start of the frame or after LateUpdate).

[ECSEvent(9001)]
public struct DamageEvent { public ulong Target; public int Amount; }

[ECSSystem(6100)]
public static class HealthSystem {
    public static void OnStart() {
        Events.Subscribe<DamageEvent>(e => {
            if (Health.TryGet(e.Target, out var h)) h.Value -= e.Amount;
        });
    }
}

// somewhere else:
Events.Publish(new DamageEvent { Target = enemy, Amount = 5 });

Keep the subscription to stop early: var sub = Events.Subscribe<T>(...); sub.Dispose();

Engine events you can subscribe to

Global state: Resources

For data that belongs to no entity (score, wave number, settings), use a plain class through Resources. Don't use static fields for per-entity state: put that in components.

public class GameState { public int Score; public int Wave = 1; public bool GameOver; }

Resources.Get<GameState>().Score += 10;          // created on first use

[PersistentResource]                              // survives Play/Stop (e.g. options)
public class Options { public float MusicVolume = 0.8f; }

Resources reset when Play stops, so every Play starts clean, unless marked [PersistentResource].

Scenes and prototypes

A prototype (.proto.json) is a reusable entity with its children, like a Unity prefab. Create one from the Project panel and edit it like a small scene.

Scenes.Load("Level2");                        // Scenes/Level2.scene.json, at the next frame boundary
Scenes.Reload();
ulong boss = Scenes.Find("Boss");            // by editor name, 0 if none

// spawn: safe anywhere, appears next frame boundary
Scenes.Spawn("Prototypes/Bullet", pos, bullet => {
    var rb = Rigidbody.Get(bullet);
    rb.Velocity = dir * 600f;
});

// immediate: only outside system loops
ulong e = Scenes.Instantiate("Prototypes/Pickup", 100, 50);

Scenes.DontDestroyOnLoad(player);            // survives scene changes
Scenes.Loaded += name => Debug.Log("loaded " + name);

Names are flexible: "Level2", "Scenes/Level2" and the full file name all work, and a bare prototype name is found anywhere in the project.

Parent and child

Nest entities in the Hierarchy panel, or at runtime:

Hierarchy.SetParent(sword, player);                 // keepWorld: true by default
Hierarchy.ClearParent(sword);
if (Hierarchy.TryGetParent(sword, out var owner)) { }

• Transform is always world space. Move a parent by its Transform and children follow.
• Move a child relative to its parent with its Parent.LocalX/LocalY/LocalRotation/LocalScaleX/LocalScaleY.
• Destroying a parent destroys its children. Call ClearParent first to keep them.
• The first SetParent on an entity adds a component immediately: call it from OnStart or a callback, not while looping over that entity.

Time, timers and cooldowns

Time.TimeScale = 0.5f;                        // slow motion; 0 = paused game
float real = Time.UnscaledDeltaTime;          // for menus while paused

Timers.After(2f, () => Debug.Log("2 seconds later"));
var spawner = Timers.Every(0.5f, SpawnEnemy);           // until cancelled
Timers.Every(1f, Tick, count: 3);                       // exactly 3 times
Timers.After(1f, Explode, owner: bomb);                 // skipped if bomb died first
Timers.DestroyAfter(bullet, 2f);
spawner.Cancel();

// a field in your system class:  static Cooldown s_dash = new Cooldown(1.5f);
if (Input.KeyPressed(Key.Space) && s_dash.TryUse()) Dash();
UIDraw.Rect(10, 40, 100 * s_dash.Progress, 6, Color.Cyan);  // cooldown bar

Timers use game time (TimeScale applies) unless unscaled: true. They fire at the end of the frame and are cleared when Play stops. For a per-entity cooldown store the time in a component: if (Timers.Now >= w.NextShot) { w.NextShot = Timers.Now + w.FireRate; Shoot(); }

Input

Vec2 move = Input.MoveVector;                         // WASD / arrows, length <= 1
float h = Input.Axis(Key.A, Key.D);
if (Input.KeyPressed(Key.Space)) Jump();
if (Input.KeyDown(Key.LeftShift)) speed *= 2;

var p = Input.Pointer;                                // mouse-left or first finger
if (p.Pressed && !UI.PointerOverUI) Shoot(Camera.MouseWorld);

for (int i = 0; i < Input.TouchCount; i++) {
    var t = Input.GetTouch(i);
    if (t.WasPressed) Debug.Log($"finger {t.Id} at {t.X},{t.Y}");
}
if (Input.KeyPressed(Key.Back)) OpenPauseMenu();     // Android back

• Read input in Update. Pressed and Released last exactly one frame.
• Coordinates are screen pixels, origin top-left, y down. For the world position use Camera.MouseWorld.
• In the editor the Game panel must be focused or hovered, and positions are relative to it.
• Input.Pointer works on both desktop and phones; prefer it for taps and clicks.

Physics

1. Add a Collider (Box or Circle). Size 1,1 or Radius 0.5 covers the sprite quad.
2. Add a Rigidbody to things that move. A Collider without a Rigidbody is a static wall.
3. Tick IsTrigger for areas that detect overlaps but never push (pickups, goals).
4. React in code with the callbacks below.

public static void OnStart() {
    ulong player = Tags.Find("Player");
    Physics.OnCollisionEnter(player, c => {
        if (Tags.Has(c.Other, "Enemy")) Events.Publish(new DamageEvent { Target = player, Amount = 1 });
    });
    foreach (var coin in Tags.FindAll("Coin"))
        Physics.OnTriggerEnter(coin, c => {
            if (!Tags.Has(c.Other, "Player")) return;
            Resources.Get<GameState>().Score++;
            World.Destroy(c.Entity);
        });

    Physics.NameLayer(3, "Enemy");
    Physics.SetLayerCollision(3, 3, false);        // enemies pass through each other
    Physics.Gravity = new Vec2(0, -980);           // platformer: also set GravityScale 1 on bodies
}

// queries
if (Physics.Raycast(origin, dir, 500f, out var hit)) DebugDraw.Line(origin, hit.Point, Color.Red);
var near = Physics.OverlapCircle(pos, 120f, Physics.Mask("Enemy"));
Physics.AddImpulse(e, new Vec2(0, 400));

• Rigidbody GravityScale defaults to 0 (top-down). Set it to 1 for platformers.
• Put Rigidbodies on root entities; a child's Transform is rewritten from its parent.
• Rotation is not simulated. Colliders follow the Transform rotation for overlap tests.
• Physics.DebugDraw = true outlines every collider.

Camera

Camera.Follow(player, speed: 6f);              // 0 = locked on
Camera.Zoom = 2f;
Camera.Shake(8f, 0.3f);
Camera.SetBounds(new Vec2(-2000, -1000), new Vec2(2000, 1000));
Vec2 world = Camera.MouseWorld;
Vec2 screen = Camera.WorldToScreen(enemyPos);  // e.g. a UI marker above an enemy

Add an entity with a Camera2D component to set the camera up in the editor (the Game view shows it even when stopped). These functions then write into that component. Without one, they drive a default camera.

Animation

Make a clip

1. Select a sprite-sheet image in the Project panel.
2. Set Columns and Rows (saved in the image's .meta), then click Create Animation Clip.
3. Pick frames, fps and loop in the Inspector; the preview plays live.

{ "texture": "Assets/Images/Hero.png", "columns": 8, "rows": 4,
  "frames": [8, 9, 10, 11], "fps": 12, "loop": true }

Play it

Animator.Play(e, "Run");                         // by name or path; adds an Animator if missing
Animator.Play(e, "Attack", restart: true);
if (!Animator.IsPlaying(e, "Attack")) Animator.Play(e, "Idle");
Animator.OnFinished(e, clip => Animator.Play(e, "Idle"));   // non-looping clips

Audio

Each sound is an int handle to a native audio component. Create it once, then play it as often as you like.

static int s_jump, s_music;

public static void OnStart() {
    s_jump  = Audio.Create("Assets/Audio/sfx/jump.wav");                  // SFX group by default
    s_music = Audio.Create("Assets/Audio/theme.ogg", AudioGroup.BGM, 0.6f);
    Audio.Play(s_music);
}

public static void Update() {
    if (Input.KeyPressed(Key.Space)) Audio.Play(s_jump);
    if (Input.KeyPressed(Key.M)) {
        if (Audio.GetState(s_music).IsPaused) Audio.Resume(s_music); else Audio.Pause(s_music);
    }
}

From a component field of type Audio: Audio.Create(c.HitId).

Canvas UI

Build it in the editor

1. Entity › UI › Canvas. Elements live under a Canvas and are laid out in reference pixels (default 1280×720), scaled to the screen.
2. Add children: Panel, Image, Text, Button, Input Field, Toggle, Slider.
3. Position with UIRect, which works like Unity's RectTransform: equal AnchorMin/AnchorMax pins to a point of the parent, different anchors stretch.
4. Give buttons an Action name to hook them up by name from code.

The Game view draws the UI even when stopped, so you can lay it out without pressing Play.

Hook it up

public static void OnStart() {
    UI.OnClick(UI.Find("PlayButton"), () => Scenes.Load("Level1"));
    UI.OnClick("Quit", Application.Quit);                       // UIButton.Action == "Quit"
    UI.OnValueChanged(UI.Find("Volume"), v => SaveData.SetFloat("volume", v));
    UI.OnSubmit(UI.Find("NameField"), text => SaveData.SetString("name", text));
}

public static void Update() {
    UI.SetText(UI.Find("Score"), "Score: " + Resources.Get<GameState>().Score);
    if (UI.PointerOverUI) return;                               // click was on the UI
}

Canvas modes

Drawing a HUD in code

UIDraw draws in screen pixels from any system, without entities. Good for quick HUDs and debug overlays.

[ECSSystem(6300)]
public static class HudSystem {
    public static void Update() {
        var gs = Resources.Get<GameState>();
        float hp01 = 0.7f;                                        // your health, 0..1
        float s = UIDraw.ScreenHeight / 720f;                     // scale with the window
        UIDraw.Rect(16 * s, 16 * s, 200 * s, 16 * s, new Color(0, 0, 0, 0.5f));
        UIDraw.Rect(16 * s, 16 * s, 200 * s * hp01, 16 * s, Color.Red);
        UIDraw.Text("Score " + gs.Score, 16 * s, 40 * s, 24 * s, Color.White);
        UIDraw.Text("PAUSED", 0, 0, UIDraw.ScreenWidth, UIDraw.ScreenHeight, 64 * s,
                    Color.White, TextAlign.Center, TextVAlign.Middle);
    }
}

Assets and files

string json = Assets.ReadText("StreamingAssets/waves.json");     // null if missing
byte[] raw = Assets.ReadBytes("Resources/map.bin");
string path = Assets.Find("Run");                                 // "Animations/Run.anim.json"
var size = Assets.TextureSize("Assets/Images/hero.png");

• Paths are relative to the project folder and work the same in the editor, a desktop export and on Android.
• Files you only load by name from code belong in Resources/ or StreamingAssets/, which are always exported.
• Changing a file on disk reloads it in the running editor.

Image settings (.meta)

Select an image in the Project panel to set its sprite-sheet grid, filter (nearest for pixel art) and 9-slice border. They're saved next to it:

{ "columns": 6, "rows": 1, "filter": "nearest", "border": [8, 8, 8, 8] }

Save data

SaveData.SetInt("coins", coins);
SaveData.SetString("lastLevel", Scenes.Current);
SaveData.SetObject("settings", mySettings);       // any plain class
SaveData.Save();                                  // also automatic on Stop / Quit

int coins = SaveData.GetInt("coins", 0);
var s = SaveData.GetObject("settings", new Settings());
SaveData.Slot = "slot2";                          // switch save slot

Logging and debug drawing

Debug.Log("spawned " + n);
Debug.LogWarning("low hp");
Debug.LogError("save corrupt");                  // kept in release, written to log.txt
Debug.LogException(ex);
Debug.Assert(hp >= 0, "negative hp");

DebugDraw.Circle(pos, attackRange, Color.Red);   // this frame
DebugDraw.Line(a, b, Color.Yellow, duration: 2f);
DebugDraw.Box(center, new Vec2(64, 32), Color.Green, angle: rot);
Physics.DebugDraw = true;                        // every collider

Finding problems

• Double-click a Console line to open the file at that line.
• Console › Error Pause pauses Play on the first exception.
• The editor also writes everything to Editor.log in its app-data folder (useful after a crash).
• Every run of the editor and of the development game also writes logs/<executable>.log in its working directory (exported games don't): every C++ and C# line with time and frame number, including start-up before the editor UI exists. See Running headless for the options.
• On Android, use Build › Logcat; your messages appear with the SDL/APP tag.
• Slow frame or a freeze? Open the Watchdog panel: it shows which system took the time, and a hang report names the system the game is stuck in.

Profiler and the Watchdog panel

Every ECS system is timed automatically, per phase, with the names the generator registered. You don't add anything to get the systems table. For your own code, time a block or record a value:

// or: using var _ = Profiler.Scope("Pathfinding");  (ends at the end of the block)
using (Profiler.Scope("Pathfinding")) {
    FindPath(start, goal);
}
Profiler.Counter("Enemies alive", enemies.Length);       // one value per frame, graphed
Profiler.Mark("Boss spawned");                           // event list + trace marker

double ms = Profiler.Stat("system_ms:EnemySystem");      // any profiler value by name (NaN if unknown)

The Watchdog panel

View › Watchdog, Ctrl+Shift+W, or click the FPS counter in the toolbar. It docks next to the Console.

The header has Record trace (open the file in ui.perfetto.dev for a timeline of every frame, system and scope) and Save report (text report in <Project>/Profiler/).

Turning it off

Collecting costs a little per system and per C++ allocation, which shows when you mass-spawn thousands of entities. Preferences › Debug › Profiler (also a combo in the Watchdog header) decides when it runs:

The hang watchdog and crash reports stay on in every mode; they cost nothing per frame.

Debug console commands

One set of commands works everywhere: the Watchdog Console tab, a terminal (headless runs), test scripts and code. help lists them all, including the ones scripts added.

Your own commands

[ECSSystem(6400)]
public static class CheatSystem {
    public static void OnCreate() {
        DebugConsole.Register("heal", "heal <amount>", "heal the player", args => {
            var hp = Health.Get(Scenes.Find("Player"));
            hp.Value += int.Parse(args[1]);              // args[0] is the command name
            return "player hp " + hp.Value;               // shown in the console; throw to report a failure
        });
    }
}

string table = DebugConsole.Execute("systems max");      // run any command from code

Commands from game scripts are removed automatically when the scripts reload, so registering in OnCreate never duplicates them.

Testing at a glance

The engine has four kinds of tests. One command builds everything and runs all of them, the same way on your machine and on a build server, and exits non-zero when anything fails.

The two commands

From a clean checkout (CMake 3.16+, a C++20 compiler, Python 3.9+, the .NET SDK):

python Tests/ci.py            # build Debug + Release (+ ASan on Linux/macOS), run every test
python Tests/ci.py --quick    # Debug only: unit tests + leak self-check, about a minute after a build

See Build and test everything for the options and where the results go.

Which kind of test should I write?

Running headless

Any build of the game or the editor runs without a window. That is how tests run on a build server, but it is also the quickest way to profile a scene. The engine runs normally: the scene loads, systems tick, audio plays (silently if there is no sound device), and the profiler records.

# the start scene for 10 seconds: a summary line every second, a full report at the end
GAM200_Game --project MyGame/MyGame.astge --headless --seconds 10

# 600 frames with a Chrome trace and a report file
GAM200_Game --project MyGame/MyGame.astge --headless --frames 600 --trace trace.json --report report.txt

# pure simulation: no drawing, every frame advances exactly 1/60 s (repeatable results)
GAM200_Game --project MyGame/MyGame.astge --headless --no-render --fixed-dt 0.0166667 --frames 3600

# the editor executable without a window behaves like the game (no editor UI)
GAM200_Editor --project MyGame/MyGame.astge --headless --test Tests/smoke.gtest

The executables are in local_desktop_build/<Config>/ after setup_build, or build/ci-<config>/<Config>/ after Tests/ci.py. --project picks the game; without it the engine also accepts a bare *.astge argument or the GAM_PROJECT environment variable.

What you see

First a start-up table: how long each step took (SDL, window and GL, C# runtime, assets, renderer, audio, OnCreate). Then a summary line every second, with the three most expensive systems at the end:

[prof] fps  60.0 | ms avg  2.41 p99  4.80 max  6.12 | cpu  38% | rss 212.4MB | ent 214 | top EnemySystem 0.42ms, PhysicsSystem 0.31ms

When the run ends, a full report: frame-time percentiles, the systems and timers tables, memory, leak trends, hitches, hangs and test results.

Options

The most useful ones. GAM200_Game --debug-help prints all of them; the same list can also be set once in the GAM_DEBUG_ARGS environment variable (the command line wins).

Where it can run

Logs

Every run writes its log to the terminal and to logs/<executable name>.log in the working directory (for example logs/GAM200_Editor.log), rewritten on each start. It holds every line of the process: C++ LOGI / LOGE, std::cout, C# Debug.Log and the debugger's own lines, with time and frame number. The first line of the main loop says where the file is. --log-file path chooses another file, --no-log-file turns it off. On Android the log is logcat.

Exported games never write it, stripped or not: the game doesn't create logs/ in a player's install folder. --log-file still works there when a tester asks for it, and errors from scripts still go to log.txt in the save folder (Debug.LogError).

When start-up fails

EngineCore::TryInitialize returns false when the engine cannot run, and says why in one sentence. Instead of an empty window you get that sentence in the log and, in a windowed run, an error dialog naming the log file. The process exits with code 1.

Exit codes

Engine test cases

Test cases given with --test run one after another while the real scene plays, so they see the real systems, physics, audio and profiler. When the last one finishes the engine quits; the exit code is the number of failures.

GAM200_Game --project MyGame/MyGame.astge --headless --test Tests/smoke.gtest --junit results.xml --hang-abort 30
GAM200_Game --headless --test-dir Tests --junit results.xml       # every test file in a folder, sorted
Tests/run_tests.sh [game executable] [project.astge]             # run_tests.bat on Windows: the team's standard set

Test scripts (.gtest)

One command per line; # starts a comment. Any console command works, plus these:

A script stops at its first failure. An unknown command is skipped with a warning; --strict-scripts makes it a failure.

# Smoke test: the start scene runs for a while without errors, hangs or a collapsing frame rate.
name    Smoke: start scene runs cleanly
timeout 60

profile reset                  # any console command works in a script
wait 120                       # frames; "wait 2s" = seconds
expect frame        >= 120
expect fps_avg      >  20      # <  <=  >  >=  ==  !=
expect hangs        == 0
assert_no_errors               # no error logged since the test started (C++ or C#)

mark "smoke: half way"
wait 2s
expect frame_ms_p99 <  100
expect rss_mb       <  2048

name    Systems: toggle + timings
wait 30
systems                         # prints the systems table into the log
expect systems_run >= 1
system EnemySystem off          # the game keeps running without it
wait 30
system EnemySystem on
pause
step 10                         # exactly 10 frames, then paused again
resume
trace start systems_trace.json  # 60 frames of timeline for ui.perfetto.dev
wait 60
trace stop
assert_no_errors

Stat names

The same names work in expect, Profiler.Stat, TestAssert.Stat and native modules' api->Stat.

A launcher that is also a test

Lines starting with #gam: (shell) or REM gam: (batch) are comments to the shell and test commands to the engine. Tests/run_tests.sh passes itself to --test this way, so the launcher checks that it works too.

#!/bin/sh
# Lines starting with "#gam:" are comments to the shell, test commands to the engine.
#gam: name  Shell-launched smoke test
#gam: wait 60
#gam: expect fps_avg > 20
#gam: assert_no_errors
exec "$GAME" --headless --test "$0" ...

C# tests

Put tests in a class library that references EngineScripts.dll and pass the built .dll to --test. Static [EngineTest] methods run first, then every IEngineTest class runs frame by frame until all report done.

public static class QuickChecks {
    [EngineTest] public static void PlayerExists() => TestAssert.True(Scenes.Find("Player") != 0, "no Player");
}

public sealed class BoxFalls : IEngineTest {                // runs across frames
    ulong _box; float _y0, _t;
    public void Start() { _box = Scenes.Find("Box"); _y0 = Transform.Get(_box).PosY; }
    public bool Update(float dt) {                          // true = finished
        if ((_t += dt) < 1f) return false;
        TestAssert.True(Transform.Get(_box).PosY < _y0, "box did not fall");
        return true;
    }
}

Native test modules

A small shared library that only needs Src/Engine/Debug/GamTestApi.h. Every *.cpp in Tests/native/ becomes one module (cmake -S Tests/native -B build/native && cmake --build build/native; ci.py does this for you), and run_tests picks up whatever is in Tests/native/build/. Keep CMake’s own files under build/ (git-ignored): only the finished modules go to Tests/native/build/.

#include "GamTestApi.h"

static int s_frames = 0;
extern "C" GAM_TEST_EXPORT const char* GamTest_Name(void) { return "Frame pacing"; }

extern "C" GAM_TEST_EXPORT int GamTest_Init(const GamTestApi* api) {
    GAM_CHECK(api, api->GetNative("Time.GetState") != nullptr);   // any ENGINE_NATIVE, same table as C#
    GAM_CHECK(api, api->Execute("profile reset") == 0);           // any console command
    return 0;                                                      // 0 = ok
}

extern "C" GAM_TEST_EXPORT int GamTest_Update(const GamTestApi* api, float dt) {
    if (++s_frames < 120) return 0;                                // 0 = keep going
    GAM_CHECK(api, api->Stat("fps_avg") > 20.0);
    return 1;                                                      // 1 = done (failed if a check failed)
}

Results

--junit file.xml writes JUnit XML that any CI server can show. Tests/run_tests.* writes JUnit, the text and JSON reports, a trace and the log to test-results/ (or the folder in GAM_TEST_OUT). The exit codes are in Running headless.

Unit tests

GAM200_UnitTests tests the engine's core C++ with nothing else running: no window, no OpenGL, no C# runtime, and it does not even link EngineCore. It builds in seconds, runs in about 50 ms, and names the exact case that broke.

Running them

cmake --build build --target GAM200_UnitTests      # seconds: it does not need EngineCore or C#
build/Debug/GAM200_UnitTests                         # everything
build/Debug/GAM200_UnitTests Registry View           # only cases whose name contains "Registry" or "View"
build/Debug/GAM200_UnitTests --list                  # names only
build/Debug/GAM200_UnitTests --junit unit.xml        # JUnit XML for CI
ctest -C Debug --test-dir build                      # the same through CTest

Running 47 unit test case(s) with per-test leak checking
[ RUN      ] SparseSet: remove keeps every other key mapped to its own value
[       OK ] SparseSet: remove keeps every other key mapped to its own value (0.00 ms)
[ RUN      ] Registry: destroyed ids are recycled and handles to the old entity go stale
[  FAILED  ] Registry: destroyed ids are recycled and handles to the old entity go stale (1.23 ms)
    RegistryTests.cpp:63: newHandle != handle  (4294967297 != 4294967297)
...
46 of 47 unit test case(s) passed in 41.2 ms -- 1 FAILED

Exit code: the number of failed cases (0 = all passed). Some cases test error paths on purpose, so lines such as [C++ ECS] Error: AddComponentRaw on dead entity 5 in the output are expected; only [ FAILED ] means something broke.

Writing a test

Add a .cpp file to Tests/unit/ (or a case to an existing one) and re-run CMake. Every .cpp in the folder is part of the executable.

#include "UnitTest.h"
#include "ECSRegistry.h"
#include <memory>

namespace { struct Health { int hp = 0; }; }             // test-only component

TEST_CASE("Registry: removing a component keeps the others") {
    auto reg = std::make_unique<ECS::Registry>();         // ~4 MB: keep it off the stack
    const ECS::EntityID a = reg->createEntity(), b = reg->createEntity();
    reg->addComponent(a, Health{ 10 });
    reg->addComponent(b, Health{ 20 });

    reg->removeComponent<Health>(a);

    CHECK(!reg->hasComponent<Health>(a));
    REQUIRE(reg->hasComponent<Health>(b));                 // stops here if false: the next line would crash
    CHECK_EQ(reg->getComponent<Health>(b)->hp, 20);
}

Code that calls the engine

The ECS calls two engine services: ScriptEngineHost::GetExports() (so C# can free a component's strings and lists) and the profiler's Begin/EndSystem. In the unit tests they are small doubles in Tests/unit/EngineSeams.cpp that a test can observe or fill in:

namespace {
    int g_released = 0;
    void CDECL_CONV OnReleased(uint64_t, uint32_t, void*) { ++g_released; }
    // puts the null exports table back even if a REQUIRE leaves the test early
    struct ExportsGuard { ExportsGuard() { TestSeams::ResetExports(); } ~ExportsGuard() { TestSeams::ResetExports(); } };
}

TEST_CASE("Registry: destroying an entity lets C# release its component") {
    ExportsGuard guard;
    ScriptEngineHost::GetExports().OnEntityComponentDestroyed = &OnReleased;   // what C# would install
    // ... create an entity with a managed component, destroy it ...
    CHECK_EQ(g_released, 1);
}

TestSeams::Profiler() counts system dispatches the same way. If the ECS starts calling another engine function, the unit test link fails with an undefined symbol: add a double for it to EngineSeams.cpp.

Leak checking

Every unit test case is also a leak check: whatever a test allocates must be freed by the time it returns, or the case fails with LEAK: n block(s) .... A leak fails the run exactly like a wrong value.

Proof that it works

Tests/unit/LeakCheckSelfTest.cpp holds two hidden cases that leak on purpose. Tests/ci.py runs them every time and only passes when the leak checker fails that run, so a broken leak checker can never go unnoticed.

$ build/Debug/GAM200_UnitTests --run-hidden leak-demo
[  FAILED  ] leak-demo: a test case that forgets to delete one block (0.00 ms)
    LEAK: 1 block(s) allocated with new in this test case were never deleted
[  FAILED  ] leak-demo: a container that is never destroyed (0.00 ms)
    LEAK: 2 block(s) allocated with new in this test case were never deleted
0 of 2 unit test case(s) passed -- 2 FAILED                     (exit code 2)

Finding a leak

1. Run only the failing case: GAM200_UnitTests "name of the case".
2. On Windows, run the Debug build. The CRT debug heap dump above the failure lists each leaked block as {1234} normal block at .... Run the same case under the Visual Studio debugger with --break-alloc 1234: it stops on the line that made that allocation.
3. On Linux, build the sanitizer configuration and run it. LeakSanitizer prints the stack of each leaked allocation.

cmake -S . -B build/asan -G Ninja -DCMAKE_BUILD_TYPE=Debug -DGAM_SANITIZE=address,undefined
cmake --build build/asan --target GAM200_UnitTests
LSAN_OPTIONS=suppressions=Tests/sanitizers/lsan.supp build/asan/Debug/GAM200_UnitTests

==10727==ERROR: LeakSanitizer: detected memory leaks
Direct leak of 64 byte(s) in 1 object(s) allocated from:
    #0 0x7f... in malloc
    #1 0x55... in CountedAlloc Tests/unit/UnitTestMain.cpp:37
    #2 0x55... in operator new[](unsigned long) Tests/unit/UnitTestMain.cpp:65
    #3 0x55... in LeakOneBlock Tests/unit/LeakCheckSelfTest.cpp:15      <- the line that leaked
SUMMARY: AddressSanitizer: 488 byte(s) leaked in 3 allocation(s).

The whole engine

The unit tests cover the core logic. For a run of the whole game, configure with -DGAM_SANITIZE=address,undefined (Linux / macOS) and run it headless; Tests/sanitizers/lsan.supp silences leaks that belong to third-party libraries (SDL, FMOD, the .NET runtime, Mesa), never engine code. The engine's own report also prints after shutdown: N more native allocations alive. That number includes statics and caches, so compare it between runs rather than expecting 0.

Build and test everything (ci.py)

Tests/ci.py builds every configuration and runs every test without asking anything, so a build server can run the exact command you run. It exits with 0 only when every step passed and 1 otherwise.

python Tests/ci.py                         # everything
python Tests/ci.py --quick                 # Debug only: unit tests + leak self-check
python Tests/ci.py --configs debug asan    # pick configurations
python Tests/ci.py --mutation-check        # also prove the tests catch deliberate bugs
python Tests/ci.py --list                  # print the plan, run nothing

Configurations

The default is all three (Windows: debug and release; there the CRT debug heap does the leak checking). Each configuration builds into build/ci-<name>/, so they never overwrite each other or your own build folder.

Options

How the engine tests get your scripts

A game runs the project’s compiled scripts from CSharpRuntime/Game/GameScripts.dll next to the executable, and only an editor writes that file. A fresh build folder such as build/ci-debug has never had an editor open a project, so a game started from it knows no components and runs no systems (unknown component 'Transform' skipped, systems_run stays 0).

So for every engine configuration, ci.py first exports the project with that configuration’s editor, exactly like File › Build (GAM200_Editor --build), into build/ci-<config>/export/<Project>/, and runs the engine tests on the exported game from its own folder, the way a player starts it. The tests then check the project’s own scripts, compiled the way a player gets them.

• Your project is left as it was. Opening a project makes the editor rewrite ProjectSettings/Build.json, GameScripts.csproj and .gitignore; ci.py puts all three back byte for byte afterwards, also when the export fails, and warns if anything else in the project changed.
• Strip Debugger / Profiler turns tests off in an exported game, so the test export always has it off (and keeps the console window). The summary says when your Build Settings had it on. Your real exports are not affected.
• The export runs headless (GAM200_Editor --headless --build): no window, no display, no OpenGL, so it works the same on a Linux build server. An editor built before headless export existed is detected within a second; ci.py then exports with an editor window instead (xvfb-run on Linux).
• Logs: test-results/<config>/export.log (what the editor printed) and export-editor.log (its full log).

Testing a project that lives somewhere else

python Tests/ci.py --project "D:/My Games/BossRush"                 # the project folder
python Tests/ci.py --project "D:/My Games/BossRush/BossRush.astge"   # or its .astge file

# PowerShell: the same project for every run in this window
$env:GAM_PROJECT = "D:/My Games/BossRush"
python Tests/ci.py

Put paths with spaces in quotes. A wrong path, or a folder without a *.astge, stops ci.py straight away instead of running without a project.

Running it on Windows

You need Python 3.9+, CMake, Visual Studio with Desktop development with C++, and the .NET SDK, all on PATH. A normal PowerShell or Command Prompt in the repository root is enough: CMake finds Visual Studio itself.

python Tests\ci.py --quick          # Debug unit tests + leak self-check
python Tests\ci.py                  # Debug + Release, headless engine tests included
echo $LASTEXITCODE                  # PowerShell (cmd: echo %ERRORLEVEL%): 0 = everything passed

Results

==========================================================================================
  PASS  debug: configure                               4.1 s
  PASS  debug: build everything                       96.3 s
  PASS  debug: unit tests                              0.2 s  47 of 47 unit test case(s) passed in 41.2 ms
  PASS  debug: leak checker self-check                 0.1 s  deliberate leak was reported and failed the run as expected
  PASS  debug: native test modules                     2.0 s
  FAIL  debug: engine tests (headless)                64.8 s  1 of 4 test case(s) failed
  ...
==========================================================================================
[ci] 11/12 steps passed in 412 s. Logs and JUnit XML: test-results                (exit code 1)

test-results/
  summary.json                 every step: config, name, ok, seconds, detail
  debug/
    configure.log  build.log
    unit-tests.log  unit-junit.xml
    leak-selfcheck.log
    native-configure.log  native-build.log
    export.log  export-editor.log  the project export (editor --build)
    engine-tests.log
    engine/                    junit.xml  report.txt  report.json  trace.json  engine.log  (crash / hang dumps)
  release/  ...
  asan/     ...
  debug/mutations/             one build + test log per deliberate bug (--mutation-check)

build/ci-<config>/             build output, git-ignored (Windows: a <Config> folder with GAM200_Game.exe, CSharpRuntime, ...)
build/ci-<config>/native/      CMake files of the native test modules
build/ci-<config>/export/      the exported game the engine tests run
Tests/native/build/            the native test modules themselves (run_tests loads them from here)

Proving the tests catch regressions

--mutation-check breaks the engine on purpose, one bug at a time, from Tests/unit/mutations.json. For each one it patches the source, rebuilds the unit tests, and requires the run to fail. A bug that survives means no test protects that behaviour yet. The real source is always restored, including after Ctrl+C or a killed run.

{
  "name": "SparseSet::remove forgets to re-point the element it moved",
  "file": "Src/ECS/SparseSet.h",
  "find": "sparse[backEntityID] = di;",
  "replace": "/* mutation: moved element keeps its old index */"
}

find must appear exactly once in file. When someone edits that line, the entry fails with a clear message: update it to match.

Keep it out of git

Everything a run creates is ignored by the repository’s .gitignore: build/, test-results/, logs/, *.dmp and the *.ci-mutation-backup files an interrupted --mutation-check can leave. If git lists files from a test run, the .gitignore is out of date: don’t commit them.

On a build server

Install the same tools, check out the repository, run python Tests/ci.py, and keep test-results/ as the build's artifacts (the *junit*.xml files are what most CI servers display). Nothing else is needed: no editor, no display, no prompts. On a Linux server add Mesa for rendering, or the engine tests run without drawing.

Editor tools

Put scripts in <Project>/Editor/. They compile with your scripts, only in the editor, reload on save, and are never shipped. Draw with Dear ImGui through Engine.UI.ImGui.

using System.Linq;
using Engine.Core;
using Engine.Editor;
using Engine.UI;
using GeneratedECS;

[EditorWindow("Tools/Level Stats")]
public class LevelStats : EditorWindow {
    public override void OnGUI() {
        ImGui.Text($"Entities: {Selection.All.Count()}");
        if (ImGui.Button("Select player"))
            Selection.Select(Selection.Find(n => n.Name == "Player"));
    }
}

public static class MyMenus {
    [MenuItem("Tools/Create Spawn Point")]
    static void CreateSpawn() => Selection.CreateEntity("SpawnPoint");
}

[CustomInspector(typeof(GeneratedECSRegistry.Enemy))]
public class EnemyInspector : ComponentInspector {
    public override bool OnInspectorGUI() {
        bool changed = DrawDefault();                       // the normal fields
        if (ImGui.Button("Full health")) { SetFloat("Health", 100); changed = true; }
        return changed;                                     // true = undoable edit
    }
}

A tool that throws is logged with its file and line, and the editor's UI state is repaired.

Exporting

File › Build Settings (Ctrl+Shift+B): product name, company, version, icon, start scene, window size, fullscreen, vsync, platform, output folder, and the two strip options below.

What goes into a build

• The start scene and every scene, with everything they reference.
• Every .anim.json clip and its texture.
• Files named as a path in a script string, e.g. Audio.Create("Assets/Audio/jump.wav").
• Everything under Resources/ and StreamingAssets/.
• With Include All Assets ticked: every project file.

Release builds

Both are off by default. Tick both for a fully quiet release. Engine options such as --headless and --frames keep working.

Android checklist

• Press Logcat in the Build window before starting the game to see its log.
• Folder names that differ only in capitalisation from the engine's (Audio vs audio) are handled; file names must match exactly.
• Audio .ogg files must be Vorbis.
• Large GIFs are shrunk to fit phone memory (manifest key animatedTextureBudgetMB).

Command line

GAM200_Editor --project MyGame/MyGame.astge --build Linux [--output dir]              # opens the editor, exports, closes
GAM200_Editor --project MyGame/MyGame.astge --build Linux [--output dir] --headless   # no window: build servers / CI

Both use the project’s Build Settings, with the target and output folder from the command line. With --headless the editor UI never starts and the export runs on its own (HeadlessBuild.cs), so no display or OpenGL is needed. The exit code is 0 when the export succeeded and 1 when it failed; the reason is in the [Build] lines of the log.

Ids and rules of thumb

Id ranges

Ask before taking a range: two components or systems with the same id are a compile error.

Rules of thumb

• Data in components, behaviour in systems. No static fields for per-entity state.
• Subscribe to events and callbacks in OnStart.
• Use Entity fields, not names, for links that must survive saving.
• Structural changes inside loops go through Commands, AddDeferred or Scenes.Spawn.
• Commit Scenes/ Prototypes/ Components/ Scripts/ Editor/ ProjectSettings/ and your art. Ignore Library/ Builds/ obj/ bin/.
• Never put test content in the engine folder.

Troubleshooting

API reference

Every public member scripts can use, grouped by area. Signatures are taken from the engine source. Namespaces: Engine.Core for the runtime, GeneratedECS for generated components, Engine.Editor and Engine.UI for editor tools.

Built-in components

Fields of the engine's own components, as defined in EngineComponents/*.json. Use them from C# exactly like your own: Transform.Get(e).PosX, Sprite.TryGet(e, out var s).