はじめに

UZU Code SDK を使ってマルチプレイ対応の Web ゲームを作成する手順を説明します。

前提条件

ツール	バージョン
Node.js	20+
TypeScript	5.7+
Vite	6.0+

パッケージの取得

パッケージはすべて npm に公開されています。認証やレジストリ設定は不要です。

パッケージ	用途
@uzuhq/code-sdk	マルチプレイ通信・状態同期・サウンドなどのゲーム側 SDK
@uzuhq/code-cli	プロジェクト作成・ローカル開発サーバー・パブリッシュ CLI
@uzuhq/engine-2d	2D ゲーム用の Canvas ベースゲームエンジン (任意)

プロジェクトの作成

CLI コマンドでプロジェクトを生成します。

npx @uzuhq/code-cli create-2d-game my-game
cd my-game
npm install

生成されるファイル構成:

my-game/
├── manifest.json       # ゲームメタデータ
├── package.json        # npm 設定
├── tsconfig.json       # TypeScript 設定
├── vite.config.ts      # Vite 設定
├── index.html          # エントリー HTML
└── src/
    └── main.ts         # エントリーポイント

manifest.json

ゲームの ID や名前などのメタデータを定義します。詳細は manifest リファレンス を参照してください。

{
  "id": "my-game",
  "build": "npm run build",
  "output": "dist",
  "playerCount": 1
}

開発サーバーの起動

素の Vite で 1 player 用の生 debug をする場合:

npm run dev

ブラウザで http://localhost:5173 を開くと、 scenario の index.html がそのまま表示されます (SDK は !isHosted で早期 return するので run() / sync() / init() は何もしません)。

マルチプレイをローカルでシミュレート (uzu dev)

uzu dev は、 scenario の dev command を子 process で起動しつつ、 別 port で harness page (iframe grid + HUD + state inspector) と in-memory GameRoom / SyncRoom / RelayRoom (本番と同一 WS プロトコル) を serve するサブコマンドです。 scenario 側は run<S>({ logic, events }) を書くだけ で、 mount コード / import 文 を一切書かずに N 画面 P2P をローカルシミュレートできます。

create-2d-game の雛形には harness スクリプトが仕込んであるので、 scenario ディレクトリで:

pnpm run harness   # = uzu dev

素の 1 player debug は従来どおり pnpm run dev (= vite 単独)。

起動すると:

• 子 iframe には ?server=ws://localhost:<port>&roomId=<key>&seatId=dev_N&seats=<json>&revisionId=dev が付き、 SDK は既存 online mode で dev-server に接続します
• 親 frame (harness page) の window.__uzu_dev は dev-server の管理 channel と WebSocket で会話し、 setRawState / sendAction / pauseTick / stepTick / reset などを Playwright / E2E test から呼べます

manifest.json の dev フィールドで子 process 起動コマンドと ready 検出正規表現を上書きできます (省略時 default は pnpm run dev + vite の Local: http://localhost:5173/ 形式)。

{
  "id": "my-game",
  "playerCount": 2,
  "dev": {
    "command": "pnpm run dev",
    // capture group 1 が port もしくは full URL
    "readyPattern": "Local:\\s+http://[^\\s]+:(\\d+)",
  },
}

パブリッシュ

npx uzu publish

manifest.json を読み取り、ビルド → ZIP 化 → R2 アップロード → リビジョン登録まで自動で行います。--skip-build でビルドをスキップできます。

パッケージの役割

パッケージ	役割
@uzuhq/code-sdk	マルチプレイ通信・状態同期・ボイスチャット・サウンド再生 (runtime only、 DOM 非侵襲)
@uzuhq/engine-2d	Canvas 描画・アニメーション・入力・物理演算 (推奨ランタイム)
@uzuhq/code-cli	プロジェクト生成 (create-2d-game)、 開発 harness (uzu dev)、 パブリッシュ (uzu publish)

次のステップ

• API リファレンス — init / run / sync / firstFrameReady / gameReady 等
• 開発パターン — Relay / run() / sync() の使い分け
• 2D エンジン — ノード管理・アニメーション・入力・物理・UI ヘルパー
• SafeArea 対応 — ノッチ・UZU HUD を避けるレイアウト
• 認証要件 — publish 前に満たすべき MUST 要件