构建游戏
构建一个可玩、正确的浏览器游戏——不是静态截图。游戏只是React路由中的一个<canvas>(或R3F的<Canvas>)加上DOM叠加UI。使用**design-ui**技能设计叠加界面(开始界面、HUD、菜单);本技能负责游戏循环和世界。
控制 / 反转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 Canvas游戏。references/babylon.md——Babylon.js,功能完备的3D引擎替代品。references/phaser.md——Phaser 3,默认的2D游戏引擎。references/ecs-architecture.md——适用于大型游戏的实体组件系统结构。references/genres/*.md——各类别剧本(FPS、2D平台跳跃、赛车卡丁车、益智三消俄罗斯方块、体素我的世界、无尽跑酷、俯视角双摇杆、塔防、棋盘卡牌象棋)。类型文件不能替代**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. 游戏循环与计时(#1正确性问题)
- 使用引擎的RAF循环驱动循环(
renderer.setAnimationLoop、R3F的useFrame或2D Canvas的requestAnimationFrame)。绝对不要使用setInterval/setTimeout/Date.now()进行游戏计时。 - 根据增量时间(秒)缩放所有移动/动画,使速度与帧率无关(60Hz与144Hz)。每帧计算一次增量并重复使用。
- three.js:使用
THREE.Timer(而非Clock——在同一个帧内第二次调用Clock.getDelta()会返回约0,这是一个经典的冻结bug)。
- three.js:使用
- 限制增量上限(
min(delta, 0.1)),防止后台标签页导致物体瞬移。 - 物理/游戏逻辑使用固定时间步长: 累积增量并以固定速率(例如1/60)步进模拟,同时以显示速率渲染——防止隧穿和非确定性。
2. 控制(委托给controls技能)
在实现任何WASD/转向/飞行代码之前,请打开**.grok/skills/controls/SKILL.md**。该技能是以下内容的唯一权威来源:
- 玩家可感知的A = 左 / D = 右(追逐摄像机,向前移动时)
- 为什么**
KeyA → steer−+yaw += steer * +rate会反转**(最常见的bug) - 车辆与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方向与世界对象(“侧向/反向”bug)
- 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,并选择保持其为正确右手旋转的X轴(det = +1):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**用于移动,只计算一次,不被摄像机代码修改(别名共享临时向量会导致摄像机与移动不一致——这是一个真实的复现bug)。 - 第三人称跟随:
desired = playerPos + up*height + moveForward*(-followDist);将摄像机向目标插值(使用基于指数的平滑,按增量缩放),lookAt(player)。 - 分层隔离调试顺序:(1) 按键注册 → (2) 移动方向正确 → (3) 摄像机一致。按此顺序修复。
5. 性能
- 最小化绘制调用(
renderer.info.render.calls,目标<100):共享材质,对重复对象使用InstancedMesh/BatchedMesh,图集。 - 自行释放GPU资源(
geometry/material/texture.dispose()),在关卡切换时执行——three.js不会自动垃圾回收它们。对象池化子弹/敌人/粒子。 - 无每帧分配(复用临时向量)。压缩纹理;距离使用LOD。
6. 资源(避免生成照片陷阱)
- 交互式3D元素(武器视图模型、角色、道具、投射物)→ 使用3D几何体/glTF构建,而非生成的图像。一个平面的照片级JPG枪械手部图用作FPS视图模型会看起来很奇怪,无法动画化,并且(JPG没有Alpha通道)会渲染成一个黑框。将真实的3D视图模型作为叠加渲染层挂载到摄像机。
- 保留图像生成仅用于平面2D资源(纹理、天空/菜单背景、2D精灵、UI美术)。绝对不要使用生成的图片作为3D网格、视图模型或角色替代品——使用3D几何体/glTF构建它们。
在绘制到Canvas/纹理的图像上设置
crossOrigin="anonymous"。 请参考**imagine-grok-build**技能(仅2D——图像工具无法生成真正的3D)。 - 引擎就绪的游戏美术规范 → 打开**
game-asset-core(../game-asset-core/)获取默认值 + 盲验 + 重试规则,然后是对应的专家:game-animation-frames(循环/运动法则)、game-tilesets、game-character-consistency、game-ui-icons。这些是质量控制/规范**,而非导出管线。当期望真实美术时,不要发布火柴人占位符。 - 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。可平铺的地面/墙壁 → 同时也需要game-tilesets**进行2×2接缝检查。 - 可选的更密集运动 → 运行**
video2dsprite(Grokimagine_image_to_video+ 沙箱脚本;洋红色基础)。对于清晰的生产主角,优先使用generate2dsprite。使用game-animation-frames进行循环/翻转测试法则;在此沙箱中,优先使用video2dsprite**而非临时仅ffmpeg采集。
7. 音频、保存、手感
- 音频:在首次用户手势(点击开始)时解锁
AudioContext,否则iOS无声;在visibilitychange时重新恢复。(references/audio.md) - 保存:使用带有
version字段 + 迁移的localStorage/IndexedDB。 - 手感:屏幕震动、打击停顿、缓动补间、粒子——成本低,感知质量提升大。保持表现层与模拟层分离。
8. 移动端
- 区分Canvas缓冲区大小与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足以应对贪吃蛇/俄罗斯方块/Flappy Bird/平台跳跃;仅在类型需要时使用Phaser。
- 这些游戏依赖未预装——请
npm install它们(并确保它们出现在package.json中,以便Vercel构建能获取它们)。
完成标准(在“完成”之前)
- 无控制台错误加载;可见的游戏玩法(非空白画布)。
controls技能自检通过(在向前移动时,从追逐摄像机视角看A = 左 / D = 右;如果反转则翻转一个符号)。非仅截图。- 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。当Canvas应用省略site.json字段时,browser-smoke/brand-check会发出警告。