ゲーム構築
プレイ可能で正しいブラウザゲームを構築します — 静的なスクリーンショットではありません。ゲームとは、<canvas>(またはR3Fの場合は<Canvas>)とDOMオーバーレイUIを持つReactルートに過ぎません。オーバーレイ(スタート画面、HUD、メニュー)のスタイリングは**design-ui**スキルに任せ、このスキルはゲームプレイループとワールドを担当します。
コントロール / A/D反転: WASD、ステアリング、フライト入力を書く前に、**.grok/skills/controls/SKILL.md**を開いてください。このファイルや単一ジャンルのプレイブックだけを読むと、車両/フライトのデモでA/Dが反転して出荷されることがよくあります。
適用範囲 — シングルプレイヤー、ボット、または小規模P2P協力:
- デフォルトではシングルプレイヤーまたはシングルプレイヤー + AI/ボットを出荷します。
- 2〜8人の協力プレイ / カジュアルリアルタイム(共有カーソル、パーティーゲーム、友人同士のカジュアルアクション)はサポートされています —
multiplayer-p2pスキル(WebRTCメッシュ、/api/rtcでシグナリング)を使用してください。最初にその信頼モデルを読んでください。 - P2Pが現在サポートされている唯一のマルチプレイヤー方式です。接続できないソケットを中途半端に構築しないでください。
リファレンス(オンデマンドでロード):
controlsスキル(../controls/) — 移動/操縦/フライトに必須: プレイヤーから見たA/D、反転操縦アンチパターン、フライト補助翼、必須の自己テスト +window.__controlsTest。車両/飛行機では必須です。references/threejs-foundational.md— 詳細な3D/ループ/パフォーマンスリファレンス。3Dの場合はこちらを読んでください。references/3d-libs.md— three.js + @react-three/fiber + drei + rapierの使用方法。threejsスキル(../threejs/) — 公式の完全なThree.js + TSL APIダンプ(llms-full.txt)。高度なマテリアル/シェーダー/WebGPU/ローダーに使用します。単純な2Dキャンバスゲームには使用しません。references/babylon.md— Babylon.js、バッテリー同梱の3Dエンジンの代替。references/phaser.md— Phaser 3、2Dゲームのデフォルトエンジン。references/ecs-architecture.md— 大規模ゲーム向けエンティティ・コンポーネント・システム構造。references/genres/*.md— ジャンル別プレイブック(FPS、platformer-2d、racing-kart、puzzle-match3-tetris、voxel-minecraft、endless-runner、topdown-twin-stick、tower-defense、board-card-chess)。ジャルファイルは**controls**の代わりにはなりません。references/game-feel-juice.md、input.md、audio.md、collision-physics.md、save-persistence.md、procedural-generation.md、ai-pathfinding.md。game-asset-core(+game-animation-frames/game-tilesets/game-character-consistency/game-ui-icons) — スプライト、シート、タイル、UIを生成する際の、エンジン対応2Dアートのデフォルト設定と検証(§6参照)。
構築する特定のジャンル/トピックのリファレンスを選択してください。このファイルはループ/ワールドのためのユニバーサルコアです。入力符号 → controls。 2Dゲームアート → game-asset-core。
1. ゲームループとタイミング(最も重要な正確性の問題)
- エンジンのRAFループ(
renderer.setAnimationLoop、R3FのuseFrame、または2DキャンバスのrequestAnimationFrame)でループを駆動します。ゲームタイミングに決してsetInterval/setTimeout/Date.now()を使用しないでください。 - すべての移動/アニメーションをデルタタイム(秒)でスケーリングし、速度をフレームレート非依存(60Hz vs 144Hz)にします。デルタはフレームごとに1回計算し、再利用します。
- three.js:
THREE.Timerを使用します(Clockは使用しないでください —Clock.getDelta()は同じフレーム内で2回目に呼び出すと〜0を返し、古典的なフリーズバグの原因になります)。
- three.js:
- デルタをキャップします(
min(delta, 0.1))。バックグラウンドタブでオブジェクトが瞬間移動するのを防ぎます。 - 物理/ゲームプレイには固定タイムステップ: デルタを蓄積し、ディスプレイレートでレンダリングしながら、シミュレーションを固定レート(例:1/60)でステップ実行します — トンネリングと非決定性を防ぎます。
2. コントロール(controlsスキルに委任)
WASD / 操縦 / フライトコードを実装する前に、.grok/skills/controls/SKILL.mdを開いてください。 そのスキルが以下の真実の情報源です:
- プレイヤーから見える A = 左 / D = 右(チェイスカメラ、前進中)
- なぜ
KeyA → steer−+yaw += steer * +rateが反転するのか(最も一般的なバグ) - 車両 vs FPS(ストレイフ ≠ 操縦)、固定翼補助翼、ヘリ/ドローンの注意点
- 必須の自己テスト +
window.__controlsTestプローブ
genres/racing-kart.mdを操縦符号の唯一の場所として扱わないでください — 飛行機、ジェットスキー、メカはそれを開くことはありません。
簡単なリマインダー(詳細はcontrols内):
// 車両のヨー本体(チェイスカメラ): Aはこの基底でヨーを増加させる必要があります
forward = (-sin(yaw), 0, -cos(yaw))
// KeyA → steer = +1; yaw += steer * turnRate * speedFactor * dt
// 間違い(反転して出荷): KeyA → steer = -1; yaw += steer * turnRate * dt
- ポインターロック: マウスルックのみ — WASDは自分で実装。クリックしてプレイするオーバーレイ。ロック時に解除。
- キーの押下状態とdtを追跡。
references/input.mdを介してデバイスを統合。 - 完了:
controlsスキルのチェックリストを実行。スクリーンショットのみでは車両/飛行機には不十分です。
3. 3D座標系とワールドオブジェクト(「横向き/後ろ向き」バグ)
- three.jsは右手系、+Y上: +X右、+Y上、+Zビューア方向。メッシュは+Zを向き、カメラは−Zを見ます(古典的な「カメラが後ろ向き」の落とし穴)。
Cone/Cylinderのようなプリミティブはデフォルトで**+Y**を指します → 先端を前方に合わせるために回転します(geo.rotateX(Math.PI/2))。- メッシュを
forwardに向ける(メッシュは**+Zを向く): 最も簡単な正しい方法はmesh.lookAt(mesh.position.clone().add(forward))です。手動で基底を構築するには、+Z列をforwardに設定し、それが適切な右手回転(det = +1)を維持するようにx軸を選択します:xAxis = normalize(cross(up, forward))、次にmakeBasis(xAxis, up, forward)。 これはcross(up, forward)であることに注意してください — §2の移動用right = cross(forward, up)とは異なります。メッシュはカメラの−Zではなく+Zをターゲットにするため、x軸の符号が反転し、xAxis × up = forwardとなります。フレームは右手系を維持します(ミラーリングなし)。メッシュにmakeBasis(xAxis, up, -forward)を使用しないでください** — それは−forward(カメラの慣例)をターゲットにするため、メッシュが後ろ向きになります。 - カメラを
forwardに沿って向ける(カメラは**−Z**を見る): +Z列を-forwardに設定 —xAxis = normalize(cross(forward, up))、次にmakeBasis(xAxis, up, -forward)(または単にcamera.lookAt(target))。 - 一貫したワールド
upを維持してオブジェクトを直立させます。平らなプリミティブだけを回転させて立てます。 - glTFインポートの向きを検証。
AxesHelper/ArrowHelperでデバッグ。直立自己テスト: キャラクターが地面に立っており、横たわったり沈み込んだりしていないことを確認。
4. カメラは移動と一致する必要があります
- 専用の**
moveForward/moveRight**を移動用に保持し、一度計算してカメラコードで決して変更しないでください(共有テンポラリベクトルをエイリアスするとカメラと移動が不一致になります — 実際の再現バグです)。 - 三人称追従:
desired = playerPos + up*height + moveForward*(-followDist)。カメラをそれに向かってlerpします(指数ベースのスムージング、デルタスケールを使用)、lookAt(player)。 - レイヤー分離デバッグ順序: (1) キーが登録される → (2) 移動符号が正しい → (3) カメラが一致する。この順序で修正します。
5. パフォーマンス
- 描画呼び出しを最小化(
renderer.info.render.calls、目標<100): マテリアルを共有、InstancedMesh/BatchedMeshを繰り返しオブジェクトに、アトラスを使用。 - GPUリソースを自分で破棄(
geometry/material/texture.dispose())レベルチェンジ時 — three.jsはそれらをGCしません。弾丸/敵/パーティクルをプールします。 - フレームごとのアロケーションなし(テンポラリベクトルを再利用)。テクスチャを圧縮。距離に応じてLOD。
6. アセット(生成写真の罠を避ける)
- インタラクティブな3D要素(武器ビューモデル、キャラクター、小道具、発射物) → 3Dジオメトリ / glTFから構築し、生成画像からは構築しません。手に持った銃の写真のようにリアルなJPGをFPSビューモデルとして使用すると、見た目がおかしく、アニメーションできず、(JPGにはアルファがないため)黒い箱としてレンダリングされます。実際の3Dビューモデルをオーバーレイレンダーレイヤーとしてカメラにペアレントします。
- 画像生成はフラットな2Dアセットのみに予約します(テクスチャ、空/メニュー背景、2Dスプライト、UIアート)。生成された写真を3Dメッシュ、ビューモデル、またはキャラクターの代わりとして決して使用しないでください — これらは3Dジオメトリ / glTFで構築してください。キャンバス/テクスチャに描画される画像には
crossOrigin="anonymous"を設定します。**imagine-grok-build**スキル(2Dのみ — 画像ツールは実際の3Dを生成できません)を参照してください。 - エンジン対応ゲームアートの原則 → デフォルト設定 + ブラインド検証 + リトライの規律については**
game-asset-core(../game-asset-core/)を開き、次に対応する専門家:game-animation-frames(ループ/モーション則)、game-tilesets、game-character-consistency、game-ui-icons。これらはQC/原則**であり、エクスポートパイプラインではありません。実際のアートが期待される場合に棒人間のプレースホルダーを出荷しないでください。 - 2Dゲームスプライト / アニメーションシート →
generate2dsprite(.grok/skills/generate2dsprite/SKILL.md)を実行: 純色の**#FF00FFマゼンタimagine_text_to_imageシート + クロマ後処理スクリプト(プロセッサにはマゼンタが必要です)。透明なPNG/GIFをCanvas/Phaserに配線します。該当する場合はgame-asset-core**(+ アニメーション/キャラクター専門家)を適用します。 - 2Dマップ / レベル / プロップパック →
generate2dmap(.grok/skills/generate2dmap/SKILL.md)を開きます。プレイ可能なマップには、基礎のみのベース + 別個のプロップ/衝突判定を推奨します。ブラウザデフォルト:raw_canvas/ Phaser。タイル可能な地面/壁 → 2×2シームチェックには**game-tilesets**も。 - オプションの高密度移動 →
video2dsprite(Grokimagine_image_to_video+ サンドボックススクリプト; マゼンタベース)を実行。鮮明なプロダクションヒーローにはgenerate2dspriteを推奨します。ループ/反転テスト則には**game-animation-framesを使用。このサンドボックスでは、アドホックなffmpegのみの収穫よりもvideo2dsprite**を推奨します。
7. オーディオ、セーブ、フィール
- オーディオ: 最初のユーザージェスチャー(タップして開始)で
AudioContextのロックを解除しないと、iOSでは無音になります。visibilitychangeで再開します。(references/audio.md) - セーブ:
localStorage/IndexedDBをversionフィールド+マイグレーションとともに使用。 - フィール: 画面シェイク、ヒットストップ、イーズドトゥイーン、パーティクル — 低コストで知覚品質が大幅に向上。プレゼンテーションとシミュレーションは分離してください。
8. モバイル
- キャンバスのバッファサイズとCSSサイズを区別。
devicePixelRatioを尊重。 touch-action: none、レターボックスフィットでベース解像度に合わせ、向きを処理。- タッチコントロール(バーチャルジョイスティック + アクションボタン)、44px以上のターゲット。
スタック / エンジンの選択
- 3D → three.js、理想的には**@react-three/fiber + drei**(Reactアプリに適合。dreiはポインターロック/コントロール/ローダーを提供)+ @react-three/rapier(物理/キャラクターコントローラー用)。
references/3d-libs.mdを参照。 - 2D → ネイティブCanvas 2Dはスネーク/テトリス/フラッピー/プラットフォーマーに十分。Phaserはジャンルが必要な場合にのみ使用。
- これらのゲーム依存関係はプリインストールされていません —
npm installしてください(そしてVercelビルドが持つようにpackage.jsonに確実に含めてください)。
完了基準(「完了」と見なす前に)
- コンソールエラーなしで読み込まれ、可視のゲームプレイがある(空のキャンバスではない)。
controlsスキルの自己テスト合格(チェイスカメラから前進中にA = 左 / D = 右。反転している場合は1つの符号を反転)。スクリーンショットのみではない。- 3D直立 & カメラ一致自己テスト合格(§3、§4)。
- タッチコントロールでモバイルビューポートで動作。
- 本番ビルド(
npm run build)が開発時だけでなくビルド出力をレンダリング。 - 共有 / Xカード: **
og**スキルを開く — カスタムpublic/og.jpgおよびsrc/lib/og/site.json内の"type": "x:game"。Xはog:type="x:game"を使用してアンファールをゲームカードとして表示します。これにはtwitter:cardや独自のx:typeを使用しないでください。browser-smoke/brand-checkは、キャンバスアプリがsite.jsonフィールドを省略した場合に警告します。