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 毎にシリアライズコストが掛かるため、描画に不要なロジック用フィールドは含めないでください。

デバッグ & 運用

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 ドキュメント内の該当章も更新してください。

ガイド on Codigrowa Docs