Basics
Tide is a language of its own. Its basics are the familiar kind, braces and semicolons, so if you've programmed before, most of this page will read as you expect. It covers what's the same everywhere in the language: values, variables and control flow. What's special to Tide starts with components and entities.
Style
- Types, systems and methods use PascalCase:
Transform,MovePlayer,Spawn(...). - Fields, parameters and locals use camelCase:
trs.position, nottrs.Position. So do public properties, even static ones:Color.red,quaternion.identity. - True constants use FULL_CASE:
Math.PI,Math.TAU. - Names are ASCII. Other characters go in comments, text and character literals. Save source files as UTF-8. Names starting with
tide_are the engine's, for the C it generates. - Braces go on lines of their own, and so does an
elseafter a block. A block that fits on one line can stay there:scene Main { },if (dead) { return; }.
The editors' formatter lays code out this way (see Editors).
Compiler diagnostics name the source file, line and column. Start with the first error and read its following notes: they can show the required syntax, a supported alternative or the declaration involved. For an invalid number, check its base, digit separators and suffix; for an out-of-range literal, use the range or alternative the note describes. A var declaration needs a value to infer its type; write an explicit type when assigning it later.
Types
| Type | What it holds |
|---|---|
bool |
true or false |
byte |
An unsigned 8-bit integer, from 0 to 255; binary file contents use List<byte> |
int |
A 32-bit integer |
long |
A 64-bit integer, for what outgrows an int: scores, money, tick counts over months |
float |
A 32-bit float |
double |
A 64-bit float, for values needing more precision |
double2, double3, double4, float2, float3, float4, int2, int3, int4 |
Vectors (see Math) |
quaternion, float2x2, float3x3, float4x4, double2x2, double3x3, double4x4 |
Rotations and matrices (see Math) |
Color |
A color, with r, g, b and a from 0 to 1 (see Views) |
Rect |
A rectangle on the screen: x, y, width and height (see GUI) |
string |
Text (see Text and lists) |
char |
One character of text, like 'a' (see Characters) |
List<T> |
A list of values (see Text and lists) |
T[N], like int[32] or string[3] |
A fixed number of values, stored side by side (see Arrays) |
Map<K, V>, Set<K> |
Values by key, and keys each once, in the order they were added (see Text and lists) |
Grid2<T>, Grid3<T> |
Cells at int2 or int3 positions, in fields (see Grids) |
Entity |
A handle to an entity (see Components and entities) |
LocalEntity |
A handle to one of this machine's own entities (see Local state) |
PlayerID |
A player (see Input) |
T?, like int? |
A value or nothing (see Errors) |
The engine has enums of its own too, on the pages they belong to: Anchor (GUI), Filter (Meshes and textures), SessionState, DisconnectReason and Prediction (Matches).
Everything is a value: assigning copies it, and nothing is shared, text and lists included. That's what keeps the whole world plain data, which the engine copies to take snapshots.
The type arguments in List<T>, Map<K, V> and the other containers pick what they hold. Containers can nest, such as Map<string, List<int>>. Functions can be generic too, T Max<T>(T a, T b); structs can't be yet, so a struct names the concrete types it uses.
Give a concrete type another name with a type alias, declared at namespace scope: using Points = List<float3>;. Points is the same type as List<float3>, with the same behavior and restrictions. Aliases don't declare type parameters of their own.
Numbers
bytestores one byte. It converts toint,longandfloatby itself, and arithmetic promotes it toint. Integer constants from 0 to 255 fit a byte:byte value = 255; List<byte> bytes = [0, 128, 255];. Other numbers needbyte(x), which keeps their low 8 bits; a float first converts withint(x). Compound assignments and++/--wrap back into the byte range.1.5is afloat, and thefsuffix is optional. The zero before the point can be left out:.5fis0.5. Anintconverts tofloatby itself, never the other way:int(x)truncates toward zero.1.25d,.5Dand1e100daredoubleliterals. Unsuffixed decimals remain floats, even indouble value = 1.25;: usedwhen the literal needs double precision.byte,char,int,longandfloatwiden todoubleimplicitly. Int and float vectors widen to the matching double vector. A long can round when converted to double, whose integer precision is 53 bits.- Double arithmetic and mixed float/double arithmetic give doubles. Narrowing is explicit:
float(value),float3(position),int(value)orlong(value). Integer conversions truncate, saturate at the destination's range and map NaN to zero. Double to float rounds to the nearest float, overflowing to a signed infinity. - A decimal number ending in lowercase
degis afloatin radians:180deg,.5deg,1e2deg,1_8_0degand-90deg. The compiler converts the number from degrees once; use it anywhere a float is accepted, such asquaternion.Euler(0, 180deg, 0). - An
intconverts tolongby itself too, and the two mix:total + 1is alongwhentotalis. Alongand afloatdon't: writefloat(x)orlong(x)to say which way the value goes, andint(x)to cut alongdown to its low 32 bits.5Lis alongliteral, and so is any integer literal past theintrange. - Integers can be written in decimal (
255), hex (0xFF) or binary (0b1010), and_separates digits:1_000_000. - Integer arithmetic wraps on overflow, and dividing by zero gives 0. No input can crash the simulation.
- Bitwise operators
& | ^ ~ << >>work onintandlong.>>keeps the sign, and a shift uses its count's low 5 bits, or 6 for along:1 << 33is2.
Variables
Everything is read-only unless it's mut, locals included:
var speed = player.speed * 2; // read-only, type inferred
mut var total = 0.0; // mutable, type inferred
float limit = 10; // read-only, explicit type
mut float scale = 1; // mutable, explicit typeA local with an explicit type can be assigned later:
Animation current;
switch (zombie.state)
{
case ZombieState.Run: current = movementAnims.rootRun; break;
case ZombieState.Jump: current = movementAnims.rootJump; break;
default: current = movementAnims.rootRun; break;
}Every path that reaches a read must assign the local first. Without mut, each path initializes it once; choosing its first value in different branches needs no mut. Declare mut Animation current; if the code changes it again. A read-only local declared inside a loop can be initialized once each iteration; one declared outside can't be repeatedly initialized by the loop.
var and mut var need an initializer to infer their type. A local can't reuse the name of another local or parameter in scope.
A local that's never read is a warning. It's usually a value worked out and then forgotten:
var move = Math.Normalize(float3(input.horizontal, 0, input.vertical));
var fwd = Math.Mul(player.rotation, move); // Warning: local 'fwd' is never used
player.position += move * 5 * time.dt; // ...this meant fwdA local that's only ever assigned counts as never read. The warning says what to do: use the local or remove it, and when its value is a call that does something, like var enemy = Spawn(Enemy);, keep the call as a statement, Spawn(Enemy);. The editors offer both as quick fixes.
The names a loop needs don't count: foreach (var touch in touches) count += 1; is fine without reading touch.
Constants
const declares a value that code reads by name. Constants go at the top level of a file:
const int MAX_HEALTH = 100;
const float REGEN_PER_SECOND = MAX_HEALTH / 20.0;
component Health
{
float value = MAX_HEALTH;
}
system Regenerate(mut Health health, Time time)
{
health.value = Math.Min(health.value + REGEN_PER_SECOND * time.dt, MAX_HEALTH);
}- The type is written out. The value is worked out from literals, other constants, constructors,
Mathand operators, like a field's default. It can't read fields, singletons orTime, nor an asset, which only a field's default names. - A constant whose value calls a function is made by build code as the game builds:
const List<float> CURVE = Curve(64);. - Constants are named in FULL_CASE.
- A constant is the same on every machine. Any code can read one: systems, views, handlers, functions and other constants. Reading one never makes a system wait for another.
- They work anywhere a constant value is needed: field defaults,
[Clamp]bounds,caselabels and the values of enum members. In the last two, int constants and operators on them work:case MAX_LEVEL + 1:. - A constant can be a number, vector, matrix, quaternion,
bool,Color,Rect,PlayerID, text, struct or enum, or a table of plain values: an array or a list written out (below), which holds no text. It can't be an entity, a map or a set. - A constant in a namespace belongs to it: code outside writes
Combat.CRIT_MULTIPLIER(see Namespaces and files). - Changing a constant under
tide runreloads the game and keeps the match where it is.
Tables
An array or a list can be a constant, written out: a table of values every machine has the same.
enum TreeKind { Pine, Oak, Birch }
const float[3] HEIGHTS = [6, 4.5, 3]; // One per TreeKind, by int(kind)
const List<int> QUAD = [0, 1, 2, 0, 2, 3]; // A quad's two triangles
const int2[4] NEIGHBORS = [int2(1, 0), int2(0, 1), int2(-1, 0), int2(0, -1)];
const TreeKind[3] PLANTED = [.Birch, .Pine, .Oak];
float HeightOf(TreeKind kind) { return HEIGHTS[int(kind)]; }- What a table holds is plain values: numbers, bools, chars, vectors, matrices, quaternions, colors, rects, enums, arrays, and structs of those. Text (in a struct too), lists inside a table, entities and resources are errors; for text, a switch expression on the index picks one.
- An array constant has exactly as many values as its type says. A list constant is written out (
[...],[]too) or names another list constant written out, and holds 4096 values at the most, all of its elements' lengths together, as an array does. A longer one, or one that code works out, is made by build code,const List<int> SQUARES = Squares(16);; another constant can't name that one, which code and field defaults read instead. HEIGHTS[i]reads an element by anint,HEIGHTS[int(kind)]by an enum's number, and gives the element type's zero past either end, as any array or list does;.countis how many it has.foreachgoes through one, and a list constant goes wherever aList<T>is read:Draw.Mesh(corners, QUAD), a function's parameter,QUAD.Contains(2), or copied into a field, which then has a list of its own.- Its elements are worked out while compiling, so an element read with a constant index is a constant too, of a table written out, another table constant,
TreeKind.Values()and an element of a table (GRID[1][2]):const int THIRD = QUAD[2];, acase, an array's length (int[QUAD.count] seen;), a setting (maxRewind = WINDOWS[1];). A character of text isn't one:NAME[0]is read in code. - Nothing can change one:
QUAD[0] = 1andQUAD.Add(4)are errors. Copy it into amut varto change the copy. - They're no part of the match: reading one makes no system wait, and costs what reading the element costs. Frags and verts read them too, by index,
.countandforeach. TreeKind.Values()is one already: every member of an enum, asTreeKind[3](Every member).
Settings
settings sets the engine's settings for the game. It goes at the top level of any of the game's files:
settings
{
title = "Asteroids";
tickRate = 30;
}| Setting | What it is | Without it |
|---|---|---|
title |
The window's title | The game's folder's name |
startScene |
The prefab or scene declaration the program starts in, such as Levels.Start |
Main |
tickRate |
How many times a second the match ticks, from 1 to 1000: Time.dt is 1 / tickRate, and code reads the rate as Time.tickRate |
60 |
maxPlayers |
How many players a match takes, from 1 to 65536. Builds with different values can't play together (see Matches) | 16 |
hostMigration |
When the machine running a room's match goes, another player's takes it over (see Host migration) | false |
prediction |
How clients keep up with the match: Prediction.Rollback runs ahead with no input delay and runs ticks again when a guess was wrong; Prediction.Delay delays inputs instead and runs every tick once (see Input delay) |
Prediction.Rollback |
predictionRange |
With Prediction.Rollback: how far from its player's own entities a client predicts, in world units. Farther entities stay as the server confirmed them, and tick once (see Predicting what's near) |
Everything is predicted |
appId |
The app's ID on phones, like com.studio.game: what Android and iOS, and their app stores, know it by (see Android) |
dev.tide.<the game's name>, to test with |
version |
The version people see, like 1.2.0: one to three numbers between dots. Each build's version code, which app stores order updates by, goes up by itself |
1.0 |
stats |
Shows the stats in the window's bottom right corner: the frame rate, and at a click on it or F8, the rest (see The tide command). It's in what tide build makes too, so take it out before players get the game, unless the frame rate is theirs to see |
false |
debugViews |
The engine's debug views are on: F7 shows the profiler, which says where a frame's time and a tick's go. --debug-views turns them on too, whatever this says |
false |
ticksAlongsideViews |
On the machine that runs the match, a tick runs on the job threads while the frame draws, so a frame with a tick takes the longer of the two, not both. What's drawn is one frame older for it; input reaches the match as soon as before. A game's C that both the match's code and its views call is then called from two threads at once. --ticks-alongside turns it on too, whatever this says |
false |
- Settings are set without a type.
startScenenames a prefab or scene declaration, without quotation marks; other settings take constant expressions, which can name constants. A game's own values go in constants, not settings. - A game can have several
settingsblocks, in any of its files, so a setting can be written beside the code it's about: each block sets what the others don't. A setting that's set twice, in one block or in two, is an error that says where the other one is. - The editors complete the names of the settings the game doesn't set yet, and show what each one does.
- Settings are part of the build. The machine that runs a match decides its tick rate, and every player ticks at that rate. Under
tide run, a newtickRatetakes effect when a match starts. --titlegoes over thetitlesetting (see The tide command).- Startup uses
--scenefirst, thenstartScene, thenMain(see Matches).
Logging and asserting
Debug.Log(text) prints a line: to the terminal under tide run, to the browser's console on the web, to the system's log on Android. On desktop and Android it also goes into the game's Player.log, which a player can send you (see Logs and crashes). Debug.Assert(condition), or Debug.Assert(condition, text), stops the program when the condition is false and says where, with the source line and the text. Both go anywhere: systems, views, handlers, functions.
Standalone release builds keep assertions and messages you wrote, but replace the source path with an ID and omit the copied source line. Keep the build's private game.names map to resolve reported source IDs and line numbers.
system Fall(Time time, mut Body body)
{
body.velocity.y -= 9.8 * time.dt;
Debug.Assert(body.velocity.y > -1000, $"{body.velocity.y} is too fast to be right");
if (time.tick % 60 == 0) Debug.Log($"tick {time.tick}: {body.position}");
}Neither changes the match, so the simulation stays the same on every machine with or without them. A client runs a tick again when a guess about another player's input was wrong (see Networking), and a log in it prints again: prefix what you log of the match with Time.tick to tell the runs apart. tide run --stats, or the stats setting, shows the three systems that took longest in the last tick, beside the frame rate, and the profiler shows where the rest of a tick and a frame go (see Debug views).
Default values
default is the default value of the type where it goes, so the type doesn't have to be spelled out:
Draw.Circle(default, 5, Color.yellow); // At float2(0, 0)
float2 center = default;
if (target == default) { return; } // The null entityIt's the value a field of that type starts at: zero for numbers, vectors, matrices and colors, false, empty text, an empty list, the null entity, no player, and for a struct or component, its fields' defaults, as Stats { } makes them.
Its type comes from where it goes: a typed local, an assignment, an argument, a return, a field's value, or the other side of ==, != or ?:. var x = default; says no type, so it's an error. default is only ever compared, never added or multiplied.
Operators
From the ones that bind tightest to the loosest:
-x,!x,~x,tryandawaitvalue switch { ... }*,/,%+,-<<,>><,<=,>,>=,is==,!=&^|&&||??cond ? a : b
Operators on one line group from the left: a - b - c is (a - b) - c. ?? and ?: group from the right: a ?? b ?? 0 is a ?? (b ?? 0).
The arithmetic and bitwise operators have compound assignments: +=, <<= and the rest. i++, i--, ++i and --i are the same as i += 1 and i -= 1. Inside an expression they're a value too: ++i is i after it changed and i++ what it was before, so (++count % 2 == 0) ? a : b counts and picks in one line. In a frag or a vert, the statement they're in reads the variable nowhere else, and they don't go on a side of ?: or after && or ||: the compiler says so, and what to write instead.
??, is, ! after a value and try unwrap what a function that can fail gives, and T? values (see Errors).
Expressions run left to right: operands, arguments and field values in the order they're written, on every platform. That's part of what makes every machine spawn the same entities with the same IDs, and it holds for calls that change what they're given too: in Pack(Next(counter), Next(counter)) the first Next runs first, and in Pack(counter.n, Next(counter)) counter.n is read before Next changes it (see Functions).
So what happens in order, Spawn, Scene.Load and the GUI's widgets, can't go where it would only run sometimes, or again and again: on the right of && or ||, in a side of ?:, or in a loop's condition or a for's step. Spawn into a local first, or use if and else.
Control flow
Tide has if and else, switch, and the loops for, foreach and while, with break, continue and return.
for (var i = 0; i < 10; i++)
{
if (i == 3) continue;
total += i;
}
foreach (var score in scores)
{
best = Math.Max(best, score);
}
while (fuel > 0)
{
fuel -= burn;
}A for loop's variable is read-only in its body unless it's declared mut var; the loop's step can change it either way. foreach goes through a list in order, and each element is a read-only copy; foreach (int score in scores) names their type. foreach and parallel go through a grid's cells too (see Grids), and foreach through a text's characters (see Characters). There's no do ... while yet.
Enums and switch
An enum is a set of named values, and switch picks code by a value:
enum Phase
{
Warmup,
Playing = 5,
Over,
}
system Advance(mut Match match)
{
switch (match.phase)
{
case Phase.Warmup:
match.phase = Phase.Playing;
break;
case Phase.Playing:
case Phase.Over:
break;
}
}- A member without a value is one more than the one before it, and the first is 0. A value is an int, which can come from constants:
Playing = FIRST_LEVEL + 1. It can read any member of another enum, wherever that enum is declared, and the members before it in its own; one at or after it, or two enums worked out from each other, is an error. - Write a member with its enum,
Phase.Playing, or use.Playingwhen the expected enum type is clear:match.phase = .Playing;. Typed declarations, field defaults, function arguments and returns, container elements andcase .Warmup:inside an enum switch supply that type. Comparisons can use it too:match.phase == .Playing. A typed conditional can use shorthand in both branches:Phase next = ready ? .Playing : .Warmup;. - Without an expected enum type, keep the qualified spelling:
var phase = Phase.Playing;. If overloads could take different enums, qualify the argument; the compiler does not pick an enum by searching for its member name. ==and!=compare two values of the same enum, and<,<=,>and>=put two in order by their numbers:Phase.Warmup < Phase.Playingbecause 0 is less than 5. The order is the numbers', not where members are written; shorthand works here too,match.phase >= .Playing. An enum doesn't compare with a number or another enum:int(phase) < 3compares numbers.- An enum and its number convert both ways, written out:
int(phase)gives a value's number, andPhase(5)the value with that number.Combat.Stance(2)does it for an enum in a namespace. See From a number below. - Write conversions as
int(phase), not(int)phase. The compiler explains the replacement when it encounters a parenthesized cast. Phase.Count()is the number of declared members, as a compile-timeint. ThePhaseabove has three members despite its numeric gaps. Members sharing the same numeric value each count. The call takes no arguments; a member you declare namedCountremainsPhase.Count.- An enum takes four bytes, like an int.
enum Voxel : byte { ... }takes one, for members from 0 to 255, and: ushorttwo, for 0 to 65535: worth it where there are a lot of them, like a grid's cells. switchworks on ints, longs, chars and enums. A case is an int (or a long, for a long), a char like'a', an enum's member, or a constant. Every section ends withbreakorreturn, so none runs into the next.
Switch expressions
A switch expression chooses a value, so it can initialize a local directly:
Animation current = zombie.state switch
{
ZombieState.Run => movementAnims.rootRun,
ZombieState.Jump => movementAnims.rootJump,
_ => movementAnims.rootRun,
};The selector is evaluated once, and only the selected arm's value runs. Labels are constants of the same kinds a statement switch accepts. Each label appears once; the final _ arm handles every other value and is required, including for enums, which can hold unnamed numbers. A trailing comma is allowed.
The arm values must have compatible types. A typed destination supplies the type of default, null, list literals and enum shorthand such as .Jump; otherwise the other arms supply it. An enum selector also supplies the type for shorthand labels such as .Run. Each arm has its own scope for locals declared with out. Patterns and guards aren't supported yet.
switch binds tighter than arithmetic: (a + b) switch { ... } switches on the sum. It works in functions, tasks and GPU code as well as systems, subject to the types those places support.
From a number
Phase(number) is the enum's value with that number, the other way from int(phase):
enum Card { Vitality, RapidFire, Scatter, Ricochet }
const int CARDS = Card.Count();
// One of the cards, picked by a hash: the same on every machine
Card Offer(int round, int slot)
{
return Card(Math.Hash(int2(round, slot)) % CARDS);
}- It takes an
int(or abyte). Afloator alonggoes throughint(...)first,Phase(int(x)), and so does another enum's value. The compiler says which when it's something else. - A number none of the members has is kept as it is: with the
Phaseat the top of this section,Phase(3)is aPhasewhose number is 3. It equals no member, aswitchon it runs itsdefault, and text shows3. So bound the number first when it comes from somewhere that can be wrong, as the% CARDSdoes, or handle the rest in adefault. - An enum stored as a
byteor aushortkeeps the number's low 8 or 16 bits, asbyte(x)does:Voxel(300)isVoxel(44). - With a constant number it's a constant, so it works in a
const, a field's default and acase.
For consecutive values starting at zero, advance and wrap with %:
enum Direction { North, East, South, West }
Direction Next(Direction direction)
{
return Direction((int(direction) + 1) % Direction.Count());
}This assumes the starting value is a declared member. Member count is not a numeric range: this formula does not cycle through enums with gaps, negative values or duplicate numeric values. Count() works in shaders and constant expressions too.
Every member
Phase.Values() is every declared member once, in the order they're declared, as an array of Phase.Count() of them, so it goes through any enum, gaps and all:
enum TreeKind { Pine, Oak = 4, Birch }
foreach (var kind in TreeKind.Values()) // Pine, Oak, Birch
{
Plant(kind);
}
TreeKind second = TreeKind.Values()[1]; // Oak- It's an array,
TreeKind[3]here: index it, read its.count, keep it in a field (TreeKind[3] kinds = TreeKind.Values();) or a constant. It's made while compiling, so it costs nothing, and works in match code, views, workers, frags and verts alike. - A member declared with another's number is there at its own place: in
enum Size { Small = 1, Little = 1, Big },Size.Values()isSmall, Little, Big, whose first two are one value. Go throughCount()places, asCount()counts both. - It takes no arguments, and belongs to the enum: a value's
kind.Values()is an error that namesTreeKind.Values(). A member you declare namedValuesstaysPhase.Values.
Comments and attributes
Comments are // and /* */.
Attributes, in square brackets, are only metadata: when a system runs, or the bounds of an input's field, never what code does. The engine can enforce what one declares, as it clamps an input's field to its [Clamp].
[After(Gravity)]
system Move(mut Body body) { ... }