テーマ
エンジン概要
@uzuhq/engine-2d は Vibe Coding を前提とした AI ファーストな Canvas ベースの 2D ゲームエンジンです。Claude Code などの AI アシスタントがドキュメントを参照しながらゲームを実装できるよう、シンプルで宣言的な API を提供します。レスポンシブな画面サイズ対応と高 DPI ディスプレイへの自動対応を備えており、UZU PlayScreen SDK と組み合わせてマルチプレイゲームを構築できます。
エンジンの役割
エンジンは描画とゲームオブジェクトの管理に特化しています。通信やサウンドなど、SDK が既に提供している機能はエンジンでは扱いません。
| 機能 | 担当 |
|---|---|
| ノード（ゲームオブジェクト）の管理 | エンジン |
| アニメーション・画面効果 | エンジン |
| 衝突判定・物理演算 | エンジン |
| カメラ・タイルマップ | エンジン |
| サウンド（SE・BGM） | SDK (@uzuhq/code-sdk) |
| マルチプレイ（通信） | SDK (@uzuhq/code-sdk) |
エンジンの初期化
createEngine() で Canvas 要素を渡してエンジンを作成します。
typescript
import { createEngine } from '@uzuhq/engine-2d';
const engine = createEngine({
canvas: document.getElementById('canvas') as HTMLCanvasElement,
background: '#1a1a2e',
assets: {
images: { player: '/sprites/player.png' },
},
});
await engine.ready; // アセットロード完了を待つ設定オプション
| プロパティ | 型 | デフォルト | 説明 |
|---|---|---|---|
canvas | HTMLCanvasElement | 必須 | 描画先の canvas 要素 |
width | number | canvas.width | デザイン幅（固定サイズモード用） |
height | number | canvas.height | デザイン高さ（固定サイズモード用） |
background | string | '#000' | 背景色 |
assets.images | Record<string, string> | — | 初期ロードする画像 {キー: URL} |
画面サイズとレスポンシブ対応
エンジンはデフォルトでレスポンシブモードで動作します。端末によって画面サイズが変わるため、座標のハードコードは禁止です。必ず engine.width / engine.height を使ってください。
レスポンシブモード（デフォルト）
縦画面の場合、幅は固定値 390 になり、高さは端末の画面比率によって 640〜844 の範囲で変動します。
typescript
// デフォルト: 縦画面
createEngine({ canvas });
// 明示的に縦画面を指定
createEngine({ canvas, orientation: 'portrait', baseSize: 390, maxLength: 844 });
// 横画面
createEngine({ canvas, orientation: 'landscape', baseSize: 390, maxLength: 844 });| 設定 | 型 | デフォルト | 説明 |
|---|---|---|---|
orientation | 'portrait' | 'landscape' | 'portrait' | 画面の向き |
baseSize | number | 390 | 固定軸のサイズ（縦画面=幅、横画面=高さ） |
maxLength | number | 844 | 可変軸の上限 |
固定サイズモード
レスポンシブが不要な場合や、既存ゲームの互換性を保つ場合に使います。
typescript
createEngine({ canvas, width: 600, height: 600 });レイアウトの指針
| 要素の配置 | コード例 |
|---|---|
| 上端に固定（スコアなど） | y: 20 |
| 下端に固定（ボタンなど） | y: engine.height - 80 |
| 画面中央 | x: engine.width / 2, y: engine.height / 2 |
| 全幅のボタン | x: 30, width: engine.width - 60 |
| 画面外から登場させる | y: engine.height + 50（下端外） |
数値のハードコードに注意
画面サイズは端末によって異なります。以下のような書き方は避けてください。
typescript
// NG
const centerX = 195;
const groundY = 784;
// OK
const centerX = engine.width / 2;
const groundY = engine.height - 60;