Codigrowa Docs

Entity 実装ガイド

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

このガイドでは新しい Entity を engine/entities/ に追加し、Game へ組み込むまでの流れを説明します。

1. クラス定義#

engine/entities/MyEntity.ts を作成。
Entity を継承し、MyEntitySnapshot 型を定義。
コンストラクタで tickRate や初期座標を渡す。
_process(elapsed) に 1 tick 分のロジックを書く。

import { Entity, EntitySnapshot } from './Entity';

type MyEntitySnapshot = EntitySnapshot & { hp: number };

export class MyEntity extends Entity<MyEntitySnapshot> {
 private hp = 100;

 protected _process() {
 // 例: 徐々に減衰
 this.hp = Math.max(0, this.hp - 1);
 }

 getSnapshot() {
 const { x, y } = this.getPosition();
 return { id: this.id, x, y, hp: this.hp };
 }
}

2. World へ登録#

const entity = new MyEntity({ tickRate: 1 / 30, x: 50, y: 120 });
game.addEntity(entity);

Game.addEntity が World 経由で _ready() を一度だけ呼びます。
画面遷移やアンマウント時は game.removeEntity(entity.id) を必ず実行。

3. 描画スナップショットの更新#

Skia や React 側が必要とする最小情報だけを getSnapshot() に詰めます。大きなオブジェクトを渡すと render 毎にシリアライズコストが掛かるため、描画に不要なロジック用フィールドは含めないでください。

GameCanvas / Renderer

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

components/game-canvas.tsx は Game からのスナップショットを @shopify/react-native-skia で描画するデモ実装です。エンジンの状態を UI に届ける際のベストプラクティスをまとめます。

初期化フロー#

startGame({ reset: true }) を useEffect で 1 度だけ呼び、GameLoop を開始。
LinearMover のような Entity をインスタンス化して game.addEntity() で登録。
クリーンアップ時に game.removeEntity(entity.id) を忘れない。

レンダリング購読#

useEffect(() => {
 const unsubscribe = game.onRender((payload) => {
 renderPayloadRef.current = payload;
 setRenderPayload(payload); // HUD 用に tick / elapsed / entityCount だけ更新
 });
 return unsubscribe;
}, [game, setRenderPayload]);

GameCanvas は renderPayloadRef に最新スナップショットを保持しつつ、Zustand には HUD で必要な tick/elapsed/entityCount だけを流します。Skia の描画ノードは React ではなく「Entity ID → SharedValue ハンドル」へ直接書き込むため、Game の内部構造を UI から mutate する必要がありません。

Scheduler を使った HUD#

GameCanvas では game.schedule() と game.wait() を使い、定期ログと遅延ログを生成しています。setFunctionLogs で最新 4 件だけ表示する仕組みは、Scheduler の動作確認に最適です。

アーキテクチャ概観

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() を利用します。

デバッグ & 運用

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

エンジンを拡張する際に役立つ検証フローとチェックリストです。

1. ログと HUD#

Game.update は __DEV__ 時に dt をログ出力します。大量に出る場合は expo start --no-dev で実機挙動を確認。
Game.onRender から受け取る GameRenderPayload を HUD 表示し、elapsed / tick / entities.length をリアルタイムに監視。components/game-canvas.tsx の functionLogs 実装を流用できます。

2. テスト駆動のすすめ#

World と Entity は純粋な TypeScript クラスなので Jest で単体テスト可能。
Scheduler は update(dt) を段階的に呼び、task.callback が発火するかで検証できます。getTaskCount() を監視すればリーク検知が容易です。

3. 典型的なトラブルシュート#

症状	対処
Entity が停止する	`tickRate` が大きすぎて `_process` が呼ばれていない可能性。`__DEV__` ログで `dt` を確認。
Renderer に反映されない	`getSnapshot()` で必要なフィールドを返しているか確認。`GameCanvas` 側で型ガードを追加。
Scheduler タスクが残り続ける	`game.cancelTask(id)` を `useEffect` のクリーンアップで呼ぶ。
複数画面で Game を共有したい	`useGameStore` の `game` インスタンスをシングルトンとして取り回し、各画面で `onRender` を個別登録。

4. 将来の拡張ポイント#

docs/game_engine_develop_plan.md に記載されている Step #4 以降（タップ入力、Signal、Sprite 切替など）は現行アーキテクチャを前提としています。API 変更時は互換性を保つため、Hugo ドキュメント内の該当章も更新してください。

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 スナップショットを共有できます。