ルーム定義リファレンス

stateMachine のルームでは、GS2-StateMachine に登録したルール（GSL）をルーム内で実行し、共有オブジェクトの生成・更新、操作の検証、時間経過の処理を行います。このページは、そのルールを書くための仕様をまとめます。

ルールは C# で書いて GSL を生成するのが基本です。C# の記述形式（状態の record、Step など）は StateMachine と共通なので、C# 定義リファレンスもあわせて参照してください。手順を通して試すにはチュートリアルを参照してください。

ルールの全体像

ルームの状態と共有オブジェクトは、ルームが動いている間だけ保持されます。ルームが終わると失われ、永続保存されません。

C# での書き方

ルールのクラスには、次の 3 種類のメソッドを書きます。

Start では、共有オブジェクトの種類を定義して初期のオブジェクトを生成し、Step.WaitFor(nameof(Interact), state).Or(nameof(Timer)) で入力を待ちます。Interact と Timer は、処理の後に Step.Stay(state) で同じ入力を待ち続けます。

プレイヤーが送れる操作は Interact だけです。操作の種類は method の値で振り分けます。C# に public メソッドを追加しても、クライアントから呼べるようにはなりません。

生成の設定では hostProfile に RealtimeRoomV1 を指定します。このプロファイルでは、GameRewards（報酬）と GameRandom（乱数）は使えません。

Room API

C# からは Room.*、GSL の Lua からは同じ名前の room.* を呼びます。値はすべて int32 です。

オブジェクトの種類を定義する

ルームの初期化中（Start から最初の入力待ちまで）だけ呼べます。

オブジェクトを生成し、値を読み書きする

field には、同期スキーマの enum の値（EnemyFields.Health など）か、RoomFields.PositionX などの標準フィールドを指定します。ルールの中で読み書きした値は、同じ入力の処理の中ですぐに Get に反映されます。

位置の値は、刻み幅で割った整数です。標準の刻み幅（0.01）では、50 が Unity の 0.5 にあたります。

時間経過で処理する

予約は 1 つのオブジェクトにつき 1 つで、同じオブジェクトに After を呼ぶと予約を置き換えます。一定間隔で繰り返す処理は、Timer の中で次の After を予約します。敵の行動間隔、扉が閉じるまでの時間、復活までの待ち時間などに使います。

タイマーはルーム内で約 50 ミリ秒ごとに処理されます。Unity の描画フレームとは同期せず、正確な時刻での実行を保証するものではありません。発火したタイマーは、ルールが拒否・失敗しても消費されます。

一定間隔でシミュレーションする（ティック）

初期化で DefineTickRate を呼ぶと、ルームは毎秒決まった回数 Tick(state, int tick) を実行します。プレイヤーキャラクターの移動などを、サーバーが入力から計算する場合に使います。クライアントは位置を書き込めないので、移動速度の改ざんや壁抜けを防げます。

// 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);
}

• Tick の引数名は tick（1 から始まるティック番号）で固定です。DefineTickRate を使う定義に Tick がないとコンパイルエラーになります。
• Tick を受け付けている入力待ちの間だけ実行されます。Interact や Timer と同時に待つこともできます（.Or(nameof(Interact))）。シミュレーションを続けたいすべての入力待ちに Tick を含めてください。含まない間もティック番号は進みます。
• Tick がエラーになったティックは何も変更されず、次のティックは通常どおり実行されます。
• DefineSimulatedPrefab の種類は、プレイヤーオブジェクトと同じようにクライアントが生成し、そのプレイヤーが所有します。クライアントが生成できるのは種類ごとに 1 つまでで、要求から使われるのは位置と回転だけです（ほかのフィールドは 0 から始まります）。値を書けるのも削除できるのもルールだけで、所有者の書き込みと削除は拒否されます。所有者の退出で削除されます。
• Input・DefineHitbox・DefineRelevance・Raycast・Overlap を使う定義に DefineTickRate がないと、コンパイルエラーになります。
• プレイヤーは「どのティックに使う入力か」を付けて入力を送ります。そのティックの入力が届いていなければ、直前の入力が使われます。
• ティックで変更した値は、定期送信（UDP を使えるときは UDP）でクライアントへ届きます。
• 処理が遅れたときは、1 回に最大 3 ティックまでまとめて実行し、残りは飛ばします。
• ルールの計算は整数だけです。位置は刻み幅で割った整数（標準では 0.01 単位）で扱います。

撃った側の画面どおりに当てる（ラグ補償）

プレイヤーの画面に映るほかのキャラクターは、通信の遅れと補間のぶんだけ少し過去の位置です。そのまま判定すると、画面では当たっていたのに外れます。クライアントは入力ごとに「そのとき画面がどれだけ遅れていたか」を送るので、ルームは撃ったプレイヤーが見ていた位置で判定できます。

public static Step Start() {
    Room.DefineTickRate(30);
    Room.DefineSimulatedPrefab<Character>();
    Room.DefineHitbox<Character>(50);   // 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);
}

• 当たり判定は位置のフィールド（0〜2 番。標準の Position）を中心にした球です。2D のゲームでは Z を 0 にすれば円として扱えます。
• shooterId が Simulated オブジェクトなら、ほかのオブジェクトはその所有者が現在のティックの入力を送ったときに見ていた位置まで戻して判定します。ティックの間は補間します。戻せるのは最大 500 ミリ秒です。shooterId 自身は判定の対象になりません。
• shooterId には存在するオブジェクトを指定します（0 は指定できません）。
• 撃つ位置と向きは、引数の値がそのまま使われます。撃つ側の現在位置を渡してください（撃つ側の位置は所有者のクライアントが予測しているので、画面と一致します）。
• [Predict] の処理からは呼べません。クライアントではエフェクトだけを先に表示し、ダメージはルームの結果が届いてから反映してください。

遠くのオブジェクトの更新を間引く

人数の多いルームでは、全員の位置を全員へ毎ティック送ると通信量が大きくなります。DefineRelevance を宣言すると、その種類のオブジェクトの更新は、受け取るプレイヤーのキャラクターから遠いほど少ない頻度で届きます。

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

• 距離は、そのプレイヤーが所有する Simulated オブジェクトのうち最も近いものから、位置のフィールド（0〜2 番）で測ります。自分のキャラクターは毎ティック届きます。
• 間引いた間に変わった値は、次に送るときに最新の値で届きます。表示は補間されるので、遠くのキャラクターも滑らかに動きます。
• Simulated オブジェクトを持たないプレイヤー（観戦など）には毎ティック送ります。
• 1 秒ごとの送り直しと、RPC などの直前に送る値は間引きません。
• 例: 64 人が 20 m 四方に散らばり全員が動く場合（distance 300）、更新の通信量はおよそ 3 分の 1 になります。

クライアントで先に動かす（予測）

1 体を動かす処理を private の補助関数に分け、[Predict(typeof(スキーマ))] を付けると、所有者のクライアントもその処理を実行して、自分のキャラクターを入力した瞬間に動かせます。

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);
}

• 対象の補助関数は private static void 名前(int objectId) か (int objectId, int tick) の形にします。[Predict] は 1 つのスキーマにつき 1 つです。ルームでは Tick から通常どおり呼び出されます。
• コンパイラは、この補助関数と、そこから呼んでいる補助関数を、Unity 用の C#（unity/<ルールクラス名>Prediction.cs）としても出力します。値の計算はルームと同じ整数演算になります。
• 予測する処理で使えるのは、int と bool の値、System.Math.Min と Max、ルールクラスの補助関数、Room.Get・Set・Input・ObjectCount・ObjectAt・SpawnOwned・Despawn です。計算はすべて int か bool で行います（スキーマのフィールドは名前で指定し、enum へのキャストはできません）。それ以外（float、静的フィールド、状態 state の読み取りなど）を使うとコンパイルエラーになります。
• 予測する処理の中で SpawnOwned を呼ぶと（弾の発射など）、撃ったプレイヤーの画面には弾がすぐに表示されます（予測スポーン）。ルームが生成した弾が届くと、表示中の同じオブジェクトにそのまま引き継がれます。ルームが生成しなかった場合は消えます。弾を正しく対応付けるため、SpawnOwned は予測する処理の中だけで呼び、当たり判定はルームだけで行う処理に分けてください。
• クライアントでは、ほかのプレイヤーの入力は 0 として、ほかのオブジェクトの値はルームから届いた最新の値として計算します。キャラクター同士がぶつかる場合などは予測が外れることがありますが、ルームの結果で補正されます。

操作したユーザーを調べる

Start と Timer には操作したプレイヤーがいないので、SenderUserId() は空文字、SenderConnectionId() は 0 を返します。タイマーの処理で「誰が始めた操作か」が必要なら、Interact の処理で状態 record に保存しておきます。

プレイヤーごとの所有物や順番を管理するときは、再接続しても変わらない SenderUserId() を使ってください。

同期スキーマ

共有オブジェクトの同期する値は、RoomSchema 属性を付けた enum で宣言します。この宣言から、ルールの定義と Unity の同期スキーマ（.realtimeschema）の両方が生成されます。

[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,
}

上の例で、Progress に 125 を Set すると、Unity では 1.25f として受け取ります。bool には 0 か 1 を設定します。

フィールド番号は通信上の識別子です。リリースした後に番号を変えたり、並び替えで番号がずれたりしないようにしてください。

入力 1 回の処理と取り消し

1 回の入力（Interact または Timer）で行った変更は、まとめて確定するか、まとめて取り消します。

Step.Ignore の理由の値は、操作したクライアントの CommandCompleted にそのまま届きます。値 1〜7 はシステムの結果コード（MissingObject など）と同じ番号なので、理由には 1000 以上の値を使ってください。クライアントが受け取る結果の一覧は Unity クライアントを参照してください。

Step.End はルールの実行を終えるだけで、共有オブジェクトの削除やルームの終了は行いません。

生成と登録

生成物は次のとおりです。

ルームは割り当てられたときに、ルールを一度だけ読み込みます。バージョンを省略した場合はその時点で最新のルールを、指定した場合はそのバージョンを読み込みます。保存先にルールが 1 件も登録されていない場合や、読み込みや初期化に失敗した場合、ルームは使われません。動いているルームは最後まで同じバージョンを使い、新しいルールは、その後に割り当てられるルームから使われます。

ルール（GSL）と同期スキーマは、同じ C# 定義から同時に生成したものを組み合わせて配布してください。

上限値

使えない機能

ルームのルールは、ルーム内で完結する処理だけを実行します。次の機能は使えません。

• GameRewards（報酬の付与）、GameRandom（乱数）
• GSL の Script（GS2-Script の呼び出し）
• 外部の API、ファイル、ネットワークへのアクセス
• Unity API や任意の .NET ライブラリ

ルールで使える C# の構文は C# 定義リファレンスを参照してください。

GSL を直接書く場合

C# を使わずに GSL を直接書くこともできます。GSL の基本の書式は GSL フォーマットを参照してください。ルームで実行する GSL には、次の決まりがあります。

• 状態変数は map run と map execution の 2 つです。

• 入力を待つ WaitTask で受け取るイベントは、次のシグネチャにします。

  イベント	パラメーター
  Interact	int revision, int objectId, int method
  Timer	int revision, int objectId, int eventId
  Tick	int revision, int tick

• Task の Payload に書いた Lua から、room.Spawn などの Room API を呼びます。

• Script による GS2-Script の呼び出しは使えません。