Room Definition Reference

In stateMachine rooms, the rules (GSL) registered with GS2-StateMachine run inside the room to create and update shared objects, validate operations, and handle the passage of time. This page summarizes the specifications for writing those rules.

The basic approach is to write rules in C# and generate GSL. The C# definition format (state records, Step, and so on) is shared with StateMachine, so also see the C# Definition Reference. To try the whole procedure, see the Tutorial.

Rules Overview

The room state and shared objects are kept only while the room is running. They are lost when the room ends and are not persisted.

Writing in C#

In the rules class, write the following three kinds of methods.

In Start, define the kinds of shared objects, spawn the initial objects, and wait for input with Step.WaitFor(nameof(Interact), state).Or(nameof(Timer)). After processing, Interact and Timer keep waiting for the same input with Step.Stay(state).

Interact is the only operation players can send. Distinguish kinds of operations by the value of method. Adding public methods in C# does not make them callable from clients.

In the generation settings, specify RealtimeRoomV1 for hostProfile. With this profile, GameRewards (rewards) and GameRandom (random numbers) are not available.

Room API

From C#, call Room.*; from Lua in GSL, call room.* with the same names. All values are int32.

Define Object Kinds

These can be called only during room initialization (from Start until the first wait for input).

Spawn Objects and Read and Write Values

For field, specify a sync schema enum value (such as EnemyFields.Health) or a standard field such as RoomFields.PositionX. Values read and written in the rules are reflected in Get immediately within the processing of the same input.

Position values are integers divided by the step size. With the default step size (0.01), 50 corresponds to 0.5 in Unity.

Handle the Passage of Time

Each object has one scheduled timer; calling After on the same object replaces it. For processing repeated at a fixed interval, schedule the next After inside Timer. Use it for enemy action intervals, the time until a door closes, the wait before reviving, and so on.

Timers are processed in the room about every 50 milliseconds. They are not synchronized with Unity’s rendering frames and are not guaranteed to run at an exact time. A fired timer is consumed even if the rules reject or fail.

Simulate at a Fixed Rate (Ticks)

When the initialization calls DefineTickRate, the room runs Tick(state, int tick) a fixed number of times per second. Use it when the server computes things such as player character movement from inputs. Clients cannot write positions, which prevents tampering with movement speed or walking through walls.

// Position is the standard XYZ (fields 0..2, 0.01 units); custom fields start at 6.
[RoomSchema(5, StandardFields = RoomSync.Position)]
public enum Character { Hits = 6 }

public static Step Start() {
    Room.DefineTickRate(30);
    Room.DefineSimulatedPrefab<Character>();
    return Step.WaitFor(nameof(Tick), new State(0));
}
public static Step Tick(State state, int tick) {
    int count = Room.ObjectCount<Character>();
    for (int i = 0; i < count; i++) {
        int id = Room.ObjectAt<Character>(i);
        int dx = System.Math.Max(-1, System.Math.Min(1, Room.Input(id, 0)));
        int dy = System.Math.Max(-1, System.Math.Min(1, Room.Input(id, 1)));
        Room.Set(id, RoomFields.PositionX, Room.Get(id, RoomFields.PositionX) + dx * 10);
        Room.Set(id, RoomFields.PositionY, Room.Get(id, RoomFields.PositionY) + dy * 10);
    }
    return Step.Stay(state);
}

• The parameter of Tick must be named tick (the tick number, starting at 1). A definition that uses DefineTickRate without Tick fails to compile.
• Tick runs only while the current input wait accepts it. You can wait for it together with Interact and Timer (.Or(nameof(Interact))). Include Tick in every wait the simulation should continue in; elsewhere the tick number still advances.
• A tick whose Tick fails changes nothing, and the next tick runs normally.
• Objects of a DefineSimulatedPrefab kind are spawned by clients like player objects and owned by that player. A client may spawn one object of each such kind, and only its position and rotation are taken from the request (other fields start at 0). Only the rules can write or remove them; the owner’s writes and removals are rejected. They are deleted when the owner leaves.
• A definition that uses Input, DefineHitbox, DefineRelevance, Raycast or Overlap without DefineTickRate fails to compile.
• Players send inputs tagged with the tick they are meant for. When a tick’s input has not arrived, the previous input is used.
• Values changed by ticks reach clients with the periodic updates (over UDP when available).
• When processing falls behind, the room runs at most 3 ticks at once and skips the rest.
• The rules compute with integers only. Positions are integers divided by the step size (0.01 by default).

Hit What the Shooter Saw (Lag Compensation)

Other characters on a player’s screen are slightly in the past, by the network delay and interpolation. Testing hits against their current positions misses shots that hit on screen. The client sends with every input how far behind its screen was, so the room can test hits at the positions the shooting player saw.

public static Step Start() {
    Room.DefineTickRate(30);
    Room.DefineSimulatedPrefab<Character>();
    Room.DefineHitbox<Character>(50);   // after DefineTickRate
    return Step.WaitFor(nameof(Tick), new State(0));
}
static void Fire(int id) {
    if (Room.Input(id, 2) == 0) return;
    int target = Room.Raycast<Character>(id,
        Room.Get(id, RoomFields.PositionX), Room.Get(id, RoomFields.PositionY), 0,
        Room.Input(id, 3), Room.Input(id, 4), 0, 2000);
    if (target != 0) Room.Set(target, Character.Hits, Room.Get(target, Character.Hits) + 1);
}

• A hitbox is a sphere centered on the position fields (0 to 2, the standard Position). In a 2D game, keep Z at 0 to treat it as a circle.
• When shooterId is a simulated object, other objects are moved back to where its owner saw them when sending the current tick’s input, interpolating between ticks, by at most 500 milliseconds. shooterId itself is never hit.
• shooterId must be an existing object (0 is not allowed).
• The origin and direction are used as given. Pass the shooter’s current position (its owner’s client predicts it, so it matches the screen).
• These cannot be called from [Predict] code. On the client, show only effects immediately and apply damage after the room’s result arrives.

Send Distant Objects Less Often

In a room with many players, sending everyone’s position to everyone every tick takes a lot of bandwidth. With DefineRelevance, updates of objects of that kind reach each player less often the farther they are from that player’s character.

Room.DefineRelevance<Character>(300);   // after DefineTickRate

• The distance is measured on the position fields (0 to 2) from the nearest simulated object the player owns. Your own character arrives every tick.
• Values changed in between arrive with their latest values the next time the object is sent. Display is interpolated, so distant characters still move smoothly.
• Players owning no simulated object (spectators, for example) receive every tick.
• The resend every second and values sent right before RPCs and similar commands are not thinned out.
• For example, with 64 players spread over 20 m square and all moving (distance 300), update traffic drops to about a third.

Move Objects on the Client First (Prediction)

Put the code that moves one object in a private helper and mark it with [Predict(typeof(Schema))]. The owner’s client then runs it too, so your own character moves the moment you press the input.

public static Step Tick(State state, int tick) {
    int count = Room.ObjectCount<Character>();
    for (int i = 0; i < count; i++)
        Move(Room.ObjectAt<Character>(i), tick);
    return Step.Stay(state);
}

[Predict(typeof(Character))]
static void Move(int id, int tick) {
    int dx = System.Math.Max(-1, System.Math.Min(1, Room.Input(id, 0)));
    Room.Set(id, RoomFields.PositionX, Room.Get(id, RoomFields.PositionX) + dx * 10);
}

• The helper must be private static void Name(int objectId) or (int objectId, int tick), one [Predict] per schema. In the room, Tick calls it as usual.
• The compiler also emits this helper and the helpers it calls as C# for Unity (unity/<RuleClass>Prediction.cs). Values are computed with the same integer arithmetic as the room.
• Predicted code can use int and bool values, System.Math.Min and Max, helpers of the rule class, and Room.Get, Set, Input, ObjectCount, ObjectAt, SpawnOwned and Despawn. All computation uses int or bool (schema fields by name; casts to the enum are not allowed). Anything else (float, static fields, reading the state and so on) is a compile error.
• Calling SpawnOwned in predicted code (launching a projectile, for example) shows the projectile on the shooter’s screen at once (predicted spawn). When the projectile spawned by the room arrives, it takes over the same object on screen; if the room did not spawn it, it disappears. To match projectiles correctly, call SpawnOwned only in predicted code and keep hit tests in code that only the room runs.
• On the client, other players’ inputs read as 0 and other objects have the latest values received from the room. Predictions can miss, for example when characters collide, and are corrected by the room’s results.

Find the User Who Operated

Start and Timer have no operating player, so SenderUserId() returns an empty string and SenderConnectionId() returns 0. If timer processing needs to know “who started the operation”, save it in the state record while processing Interact.

When managing per-player ownership or turn order, use SenderUserId(), which does not change on reconnection.

Sync Schema

Declare the synced values of shared objects with an enum that has the RoomSchema attribute. Both the rules definition and the Unity sync schema (.realtimeschema) are generated from this declaration.

[RoomSchema(7, StandardFields = RoomSync.Position)]
public enum EnemyFields
{
    Health = 6,
}

[RoomSchema(8)]
public enum SwitchFields
{
    [RoomField(typeof(bool))] IsOpen = 6,
    [RoomField(typeof(float), Precision = 0.01f)] Progress = 7,
}

In the example above, if you Set 125 to Progress, Unity receives 1.25f. Set 0 or 1 for a bool.

Field numbers are identifiers on the wire. After release, do not change them or let them shift by reordering.

Processing and Rollback per Input

Changes made by a single input (Interact or Timer) are committed together or rolled back together.

The reason value of Step.Ignore reaches the operating client’s CommandCompleted as is. Values 1 to 7 are the same numbers as system result codes (MissingObject, etc.), so use values of 1000 or more for reasons. For the list of results the client receives, see Unity Client.

Step.End only ends execution of the rules; it does not destroy shared objects or end the room.

Generation and Registration

The generated files are as follows.

A room loads the rules once when it is allocated. If the version is omitted, it loads the latest rules at that time; if specified, it loads that version. If no rules are registered in the storage namespace, or if loading or initialization fails, the room is not used. A running room uses the same version until it ends, and new rules are used by rooms allocated afterwards.

Distribute the rules (GSL) and the sync schema as a pair generated together from the same C# definition.

Limits

Unsupported Features

Room rules run only processing that is self-contained within the room. The following features are not available.

• GameRewards (granting rewards), GameRandom (random numbers)
• GSL Script (calling GS2-Script)
• Access to external APIs, files, or the network
• Unity APIs or arbitrary .NET libraries

For the C# syntax you can use in rules, see the C# Definition Reference.

Writing GSL Directly

You can also write GSL directly without C#. For the basic GSL syntax, see GSL Format. GSL that runs in a room follows these rules.

• The state variables are map run and map execution.

• Events received by a WaitTask that waits for input use the following signatures.

  Event	Parameters
  Interact	int revision, int objectId, int method
  Timer	int revision, int objectId, int eventId
  Tick	int revision, int tick

• Call Room APIs such as room.Spawn from the Lua written in a Task’s Payload.

• Calling GS2-Script via Script is not available.