ランタイム on Codigrowa Docs

アーキテクチャ概観

Mon, 01 Jan 0001 00:00:00 +0000

Codigrowa のゲームエンジンは GameLoop → Scheduler → World → Entity → Renderer という鎖で構成されています。Expo（React Native）上では requestAnimationFrame を起点に時間が進み、React 側のコンポーネントは Game.onRender() から受け取るスナップショットだけで描画を完結させます。

useGameLoop (engine/hooks/useGameLoop.ts)
 │
 ▼
┌──────────────┐
│ Game │ ← ランタイム中枢
│ • Scheduler │ ← 関数単位 tick
│ • World │ ← Entity 単位 tick
└──────────────┘
 │
 ▼
Canvas Renderer (components/game-canvas.tsx)

データフロー#

useGameLoop が requestAnimationFrame から dt（秒）を算出し Game.update(dt) を連続呼び出し。
Game.update はまず Scheduler.update(dt) を処理し、待機中のコールバックを実行。
続いて World.process(dt) が全 Entity の process() を tick に合わせて回す。
Game.notifyRender() が World からのスナップショットをまとめ、onRender 購読者（HUD や Skia Canvas）へ配布。

描画層は GameRenderPayload を受け取るだけで済むため、World/Entity の内部状態を UI から直接 mutate しません。これにより、レンダリングとロジックの責務分離とデバッグ容易性を両立しています。

Game クラス

Mon, 01 Jan 0001 00:00:00 +0000

engine/Game.ts はランタイムの司令塔です。World と Scheduler を束ね、1 tick ごとに状態更新と描画用スナップショット生成を行います。

ライフサイクル API#

メソッド	用途
`start({ reset?: boolean })`	GameLoop 起動。`reset` で `elapsed` / `tick` を初期化し即スナップショット配布。
`pause()` / `resume()`	`update()` の実行を一時停止／再開。Zustand ストアから UI でトグル。
`stop()`	ループ停止 + Scheduler タスク破棄。
`update(dt: number)`	`Scheduler.update(dt)` → `World.process(dt)` → `notifyRender()` の順で実行。

useGameLoop から渡される dt（秒）だけを頼りに Game は決定的に進行します。React 側で Game や World を直接触る場合は、状態破壊を避けるためなるべく API 経由（addEntity, wait など）で操作してください。

World / Scheduler 依存差し替え#

コンストラクタでは new Game({ world, scheduler }) としてテスト用のモックを注入できます。既存インスタンスを入れ替える場合は setWorld() / setScheduler() を利用します。

World & Entity

Mon, 01 Jan 0001 00:00:00 +0000

engine/World.ts と engine/entities/Entity.ts はエンジンの心臓部です。World が Entity を束ね、Entity は tickRate ごとに _process() を実行します。

World の責務#

addEntity(entity) / removeEntity(id) / clear() で登録を管理。
process(dt) で全 Entity の process(dt) を呼び出し。
getSnapshots() が描画層へ渡す EntitySnapshot[] を生成。

World は順序保証のため Map を使っています。Entity 追加時に _onEnterWorld() が走り、_ready() が 1 度だけ実行されます。除去時は _onExitWorld() で _ready() の再実行を許可します。

Entity 抽象クラス#

abstract class Entity<TSnapshot extends EntitySnapshot> {
 tickRate: number; // デフォルト 1/60 秒
 private tickTimer = 0; // 経過時間累積

 process(dt: number) {
 this.tickTimer += dt;
 while (this.tickTimer >= this.tickRate) {
 this.tickTimer -= this.tickRate;
 this._process(this.tickRate);
 }
 }

 protected abstract _process(elapsed: number): void;
 abstract getSnapshot(): TSnapshot;
}

tickRate と決定性#

tickRate は Entity ごとの更新周期です。World は dt をそのまま流すのではなく、tickTimer に蓄積した上で tickRate を超えた回数だけ _process() を実行します。これにより、RAF のフレームレートが揺らいでもロジックは固定周期で進行します。

Scheduler

Mon, 01 Jan 0001 00:00:00 +0000

engine/Scheduler.ts は時間ベースの関数実行を担当します。GameLoop の dt を受け取り、内部に積んだタスクの remaining 時間を減算し、0 を下回ったタイミングで実行します。

タスクモデル#

type SchedulerTask = {
 id: string;
 callback: () => void;
 remaining: number;
 interval: number;
 repeat: boolean;
};

wait(delay, callback) は一度だけ実行するタスクを登録。
schedule(callback, interval, { repeat }) はデフォルトで繰り返し（repeat: true）。
cancel(id) / clear() で後始末。

Game.update が Scheduler を World より先に呼び出すため、タスク内で Entity の状態を変更しても同じ tick 内で描画に反映されます。

使い所#

HUD へ定期的にログを出す（components/game-canvas.tsx 内参照）。
Cutscene のように「数秒待ってから次アクション」を表現する。
Entity 内から this.game.wait() を呼びたい場合は依存注入で Game インスタンスを受け取り、_ready() でタスク登録・ _onExitWorld() で cancelTask() する。

エラーハンドリング#

タスク実行中に例外が起こっても Scheduler 自身は落ちません。console.warn() を出した上で、単発タスクは削除、繰り返しタスクは次のインターバルへ進みます。長時間走り続けるサービスを意識し、repeat タスクでは必ず cancel() のタイミングを決めておきましょう。

パフォーマンスのコツ#

タスク数は Map で管理しているため数百件程度までなら問題なし。大量登録が必要なら getTaskCount() を監視し、デバッグ HUD から過剰登録を検知する仕組みを追加すると安全です。
update(dt) はタスクが無い場合 O(1) で即 return するため、必要なタイミングでこまめに cancel() しておくと無駄なループを避けられます。

GameLoop と状態共有

Mon, 01 Jan 0001 00:00:00 +0000

React 側では engine/hooks/useGameLoop.ts と engine/stores/useGameStore.ts がゲームエンジンを UI に接続します。

useGameLoop フック#

useGameLoop((dt) => {
 game.update(dt);
}, isRunning && game.isRunning);

requestAnimationFrame の time から dt（秒）を算出。
isRunning が false のときは RAF を解除し、lastTimeRef をリセット。
ループ中に最新のコールバック参照を使うため useRef で callback を保持。

必要に応じて UI 側から任意の Game インスタンスを渡せます。Expo DevTools のホットリロードでも問題なく再初期化されるよう、useEffect のクリーンアップで cancelAnimationFrame を確実に呼んでいます。

Zustand ストア#

engine/stores/useGameStore.ts は Game を 1 つだけ生成し、UI からは start/pause/resume/stop をディスパッチできるようにしています。

setRenderPayload(payload) が Game.onRender から届いたデータを tick/elapsed/entities に反映。
toggleRunning() で UI トグルスイッチと同期。
ストアはクライアントサイドのみで使うため、サーバーレンダリングの心配は不要。

GameCanvas 以外の画面（HUD、デバッグパネル、外部ツール）でも同じストアを購読すれば、最新の World スナップショットを共有できます。