Quick reference

Tide on one page: a complete game, the rules most games rely on, and links to each topic's full reference. It covers the common path; follow the links when a task needs more. It's also the page to give an AI agent: Using Tide with AI explains how.

Find the project and version

A Tide game is a folder of .tide files, including its subfolders. Declarations are visible across files without imports. An ordinary new game needs no project generator, CMake project or C host: create a folder and a game.tide. Optional packages are listed in tide.packages; authored scenes and prefabs also use .tprefab files. Every .tide file under the folder is compiled, except in hidden folders, whose names start with a dot: tide build writes to .build/, and scratch or probe copies of the game belong in a hidden folder or outside the game folder.

Inspect the existing game and its instructions before changing it. Run tide version to identify the installed compiler and tide help build or tide help run for its actual CLI. These docs describe the website's source revision, which can be newer than an installed release. Prefer documentation supplied with the project's pinned toolchain when available. On a mismatch, report the versions and use compiler diagnostics to check the relevant feature; do not silently upgrade the user's installation.

A complete game

Save the following as game.tide in an otherwise empty game folder. It is the same source used by Your first game: a bouncing ball and a WASD-controlled player for each joining player. The built-in host starts the match and joins a player even in single-player.

tide
component Body
{
    [Position] float2 position;
    float2 velocity;
    float radius = 20;
}

component Ball { }

input Controls
{
    float2 move;

    Sample(Devices devices)
    {
        var keys = devices.keyboard;
        if (keys.d.pressed) move.x += 1;
        if (keys.a.pressed) move.x -= 1;
        if (keys.w.pressed) move.y += 1;
        if (keys.s.pressed) move.y -= 1;
    }
}

scene Main { }

event(Spawned) Setup(with Main)
{
    Spawn(Body { velocity = float2(160, 120) }, Ball);
}

event(PlayerJoined joined) AddPlayer()
{
    Spawn(Body { radius = 16 }, Owner { player = joined.player });
}

system Steer(Controls input, mut Body body, with Owner)
{
    body.velocity = Math.Normalize(input.move) * 250;
}

system Move(mut Body body, Time time)
{
    body.position += body.velocity * time.dt;
}

system Bounce(mut Body body, with Ball)
{
    if (Math.Abs(body.position.x) > 160) body.velocity.x = -body.velocity.x;
    if (Math.Abs(body.position.y) > 160) body.velocity.y = -body.velocity.y;
}

view DrawBalls(Body body, with Ball)
{
    Draw.Circle(body.position, body.radius, Color.red);
}

view DrawPlayers(Body body, Owner owner, Session session)
{
    var color = owner.player == session.player ? Color.yellow : Color.gray;
    Draw.Circle(body.position, body.radius, color);
}

Build with tide build. For a human's interactive session, tide run --stats watches files and reloads when they change. Automated checks (a script, CI or an AI agent) use a bounded hidden run instead, as shown below.

The model

  • Components hold each entity's data. A component with no fields is a tag. Singletons hold one value per world; declare one with singleton Score { int value; } and request it as a parameter.
  • Systems run each fixed tick for every entity matching their component parameters. mut Body body writes data, Body body reads it, and with Ball or without Ball filters without reading data. Repeat the modifier for each filter: with Ball, without Frozen. A system with only singleton/input parameters runs once per tick. Use this for its current entity, not an invented entity parameter.
  • Views run each rendered frame, in declaration order, and later views draw on top. They read the presented match and draw; they can change local state, but cannot change match state. Time is a singleton: a system takes a Time time parameter and moves by time.dt, the fixed tick interval. Views animate local effects by Frame.dt, the frame interval. Frame and Screen are not parameters: views read Frame.dt, Screen.width and Screen.height directly. Views explains interpolation and drawing order.
  • Events notify code inside the game. scene Main; is the initial scene; event(Spawned) Setup(with Main) initializes it once. event(PlayerJoined joined) ... initializes a joining player's entities. Events explains handlers and their data parameters.
  • Every game is a networked match, including single-player. Keep gameplay state in match components and singletons. Menus, camera preferences and presentation-only effects belong in local singleton, local fields or local entities. Local state explains their lifetimes and access.

Systems declare access so the compiler can schedule them. Component filters create no data dependency. Conflicting systems follow deterministic declaration order unless explicit ordering changes it; put a system that sets velocity before one that integrates it. See Systems and The schedule.

Syntax that matters

Values are read-only unless declared mut, including locals. var value = ...; infers a read-only type; use mut var value = ...; for an accumulator that changes. A for (var i = 0; i < n; i++) loop permits its step to change i; changing it inside the body requires mut var. Fields are writable through a mutable component or singleton binding. Pass singletons explicitly through helper parameters instead of looking them up by type.

Construct components with Body { radius = 12 }, without new. Fields not specified use defaults or zero. float2(x, y) constructs a vector; arithmetic is component-wise, and ==/!= compare two vectors whole, giving one bool (if (cell == target)), so no Same(a, b) helper is needed. Math supplies deterministic operations such as Math.Normalize, Math.Length, Math.Clamp and Math.Sin. Angles are radians; 90deg is a radians literal. String interpolation is $"Score: {score.value}". Fixed tables of plain values (no text) are constants: const float[3] SPEEDS = [1, 2.5, 4]; or const List<int> QUAD = [0, 1, 2, 0, 2, 3];, up to 4096 values written out, read as SPEEDS[int(kind)] anywhere, GPU code included; Kind.Values() is every member of an enum, for foreach, and two values of one enum order with <. Read Basics, Functions, Math and Text and lists for signatures, collections and copy/borrow rules.

Spawn(Body { position = at }, Ball) returns an Entity handle. entity.Add(Component { ... }), entity.Remove(Component) and entity.Destroy() record structural changes. Those changes apply at the end of the tick, not immediately: a spawned entity cannot be queried yet, and recording a destroy does not remove a row from a running query. Guard against counting the same pending removal twice. Entity changes in local code apply to local entities at the local frame boundary. See Entities.

For a second set of entities, declare a query parameter:

tide
system CountBalls(query (with Ball) balls, mut Score score)
{
    mut var count = 0;
    foreach (var ball in balls) count += 1;
    score.value = count;
}

This fragment assumes the Ball tag and Score singleton above. Query bindings are read-only match data; a row exposes its bound values and .entity. An ordinary explicit World world parameter supports handle lookups, for example world.Get<Body>(entity) (a copy) and world.Has<Body>(entity). A mut World world parameter permits world.Set<Body>(entity, replacement), and changing another entity's component in place with world.Edit<Body>(entity, body) { body.velocity.y = 5; }: in the block, body is that entity's component, put back when the block ends, even on return or continue; an entity without one skips the block. Prefer Edit to a Get, a change and a Set. Look up the query and World rules before building cross-entity changes; do not invent world.Entities, GetComponent or writable query bindings.

Input and submitted actions

Use a declared input for per-tick controls, as in the complete game. Sample(Devices devices) reads this machine's devices; gameplay systems receive the input of the entity's Owner. Owner.player is a PlayerID. The input sampler starts from field defaults each tick. Keys are named as in Unity's Input System: a, space, r, leftArrow, upArrow, digit1, leftShift.

Input carries whether keys are held: a late player's input is guessed by repeating it, and a repeated "just pressed" would press twice. In Sample, record .pressed, not a key's .down. Match code gets one-shot edges from the input's own bool fields, which have .down and .up:

tide
input Controls
{
    bool restart;
    Sample(Devices devices) { restart = devices.keyboard.space.pressed; }
}

system Restart(Controls input, mut Score score, with Owner)
{
    if (input.restart.down) score.value = 0;
}

A view can read local devices, including .down edges, but its device reads cannot directly alter the match: a view turns a press into a command, below. See Input.

Use typed commands for submitted actions from local UI. A minimal entity-targeted action is:

tide
component Ready { bool value; }
command SetReady { bool value; }

view ReadyButton(Ready ready, with ownership)
{
    if (GUILayout.Button(ready.value ? "Unready" : "Ready"))
        this.Send(SetReady { value = !ready.value });
}

command(SetReady action) ApplyReady(mut Ready ready, with ownership)
{
    ready.value = action.value;
}

Spawn Ready alongside each player's Owner to use this fragment. In a command handler, with ownership runs it only for an entity the command's sender owns (without ownership, only for others'); a handler without it names the sender, command(SetReady action, PlayerID sender), and checks it, such as if (sender != owner.player) return;. The connection supplies the sender; never trust a sender ID in the payload. Validate ownership and game rules before writing state. Handlers return void, with ordinary guard clauses. They have no acceptance method or transaction. A global command uses Send(...); an entity-targeted command uses entity.Send(...). See Commands and GUI.

Initialize multiplayer entities in PlayerJoined, and clean up their entities/state in PlayerLeft when the game needs it. Treat PlayerID as an opaque identity, not a display index: retain joined.player or read an entity's Owner.player; do not assume the players are PlayerID(1) and PlayerID(2). When the game needs ordered seats (left and right paddle, wallet slots), assign them in the PlayerJoined handler from a singleton, such as mut Seats seats holding each seat's PlayerID, and free them in PlayerLeft. Do not count the entities spawned for earlier players instead: spawns apply at the end of the tick, and two players can join in the same tick. with ownership selects this machine's entities in local code, and the command sender's in a command handler; match systems use with Owner. Write separate filters as with Wallet, with ownership.

All machines in a match must execute identical simulation rules. Read Matches before implementing room setup, admission or migration. Optional Rooms supplies a Play/Host/Join menu; it is not automatically included in a new folder.

Draw and validate

The default 2D view uses world coordinates centered on the window, with Y up and one world unit per pixel. Draw.SetScreen() changes subsequent drawing to logical pixels from the top left, with X right and Y down, the same coordinates as GUI rectangles and script mouse x y. It also affects later views in that frame until another camera is selected; Draw.Screen() { ... } limits the change to a block. For a grid whose row 0 is at the top, screen Y increases with the row. Draw.Circle(position, radius, color) and Draw.Rect(center, size, color) use the shape's center; a GUI Rect(x, y, width, height) uses its top-left corner. Draw.Text(text, position, size, color) accepts an Anchor to align text.

There is no window-size setting: players resize the window, which opens at 960×540 on desktop. For a game designed at a fixed size such as 640×360, draw the play area in world units and set the camera in the first view, so it scales with the window: Draw.SetCamera(float2(0, 0), 180) shows 360 units of height (its size is half the visible height), and Math.Max(180, 320 * Screen.height / Screen.width) instead also keeps all 640 units of width visible. The camera stays for later views in that frame.

Device pointer positions use bottom-left, Y-up coordinates even when drawing in screen mode; use Screen.Flip(devices.pointer.position) before screen-space hit tests. Read Views and drawing, Cameras and GUI for signatures and layout. Do not assume the default world camera and GUI use the same axes. For 3D, read Drawing in 3D before choosing meshes, depth or lighting.

Compile early, then check behavior. These are game commands; building the engine repository is a different workflow.

sh
tide version
tide build
tide build --web

For automated native runs, set TIDE_HIDDEN=1 in that shell before running the game. PowerShell:

powershell
$env:TIDE_HIDDEN = '1'
tide run --frames 120 --capture smoke.png --stats

POSIX:

sh
TIDE_HIDDEN=1 tide run --frames 120 --capture smoke.png --stats

This finishes after 120 frames and captures the final picture. Add --size 640 360 to test a particular logical window size; use Screen.width and Screen.height for responsive layout. For dynamic play in the same session, use tide run --interactive play.txt: send capture menu.png, inspect it, queue future-frame input lines, then send step 30 and wait for tide: interactive ready <frame> (protocol). To press a GUI widget, send controls to list the widgets with their labels and positions, then click "Play" or click <number>, rather than estimating pixels from the picture. Open the PNG and inspect it; a successful build alone does not establish that the game draws or behaves correctly. If inspection is inconclusive, take a later capture or check simulation values with Debug.Log/Debug.Assert before concluding the game is blank or broken. For input, use tide run --script smoke.txt --frames 180 --capture smoke.png --stats, with a script such as:

1 key d down
60 key d up
120 capture after-move.png
150 quit

Script times are frames, and lines go in frame order; key actions use down/up, or neither for a one-frame tap. A capture path in a script is relative to the script's folder. --players 2 runs two game processes in one match over a simulated network on this machine, with player 2 after a frame number to target the second player; each capture name gains the player's number, after-move-1.png and after-move-2.png. 300 player 2 leave, drop, sleep and rejoin test what happens when a player goes and comes back. --latency 80, --jitter 10 and --loss 5 put every joining player that far from the match's server (--latency 2:120 for one player), and the run still repeats exactly. It does not exercise real network transports. Read CLI capture and scripts for the supported actions, output naming and exit codes. A web build still needs a browser test; native captures do not verify WebGPU. Launch automated Chrome/Edge with --mute-audio and a bounded test, not an unbounded tide run --web.

For numerical behavior, supplement pictures with Debug.Log of state changes or Debug.Assert of invariants. A multiplayer money transfer can assert that balances never go negative and that the pool plus all balances stays constant; a collector can log cell and score after each move. With several players, a client runs a tick again after a wrong guess about another player's input, and logs in it print again: include time.tick in the line. Check the actual log as well as the captures. A failed or unclear image inspection is not evidence of a replication bug.

For performance work, capture a representative scripted run in an optimized build:

sh
tide run --release --script play.txt --frames 360 --profile profile.json --profile-warmup 60

For GPU bottlenecks, inspect gpu_passes.rows: target, pass order, shader membership and mean/p95/max GPU time. Check missing-sample counters; a mixed pass's time cannot be assigned to one shader. See the GPU pass reference.

This native desktop report is written when the run ends, independently of the panels; it measures frames after warmup and includes source locations and engine draw counters. Read actual CPU work and GPU availability, not the hidden run's fixed-step FPS. Follow expensive views into their draw diagnostics: many frustum tests with few rejections are a candidate for investigation, not proof that culling is redundant. Compare one change at a time using the same script, seed, resolution, saves and build mode, and inspect captures and relevant simulation checks before claiming an improvement. CPU, concurrent worker and asynchronous GPU intervals overlap. See Profile captures for the report's measurement meanings and limits.

Fix diagnostics using the current compiler and relevant reference rather than guessing APIs. Report the builds, behavior checks and platforms actually tested. If a tool or backend is unavailable, say which check remains unverified.

References on demand

The documentation index links to clean Markdown pages. The optional full documentation download is for offline searching, not required reading on every task. The language spec separates decided behavior from provisional implementation and open proposals; an open design is not an available API.

Use Assets for imports, Packages for optional dependencies and their pinned documentation, Determinism for simulation constraints, and Visibility for secrets and recipient state. Keep gameplay state deterministic and use Tide's math/random APIs; C reached through extern is trusted and can violate those guarantees.