别再让AI手搓3D引擎：GameBlocks把游戏系统拆成74块

只靠提示词让智能体写 3D 游戏，最先坏掉的常不是画面，而是方向：前后轴颠倒、相机与角色不同步、碰撞坐标和屏幕所见不一致。GameBlocks 不让 Agent 重推空间数学，而是给它可阅读、复制、改造的实现。

~~这不是“装完就能做游戏”的引擎，也不是 npm 组件库~~，而是面向 Codex、Claude Code 的本地 Skill，加上 74 个浏览器 3D 游戏 ES Module。仓库以 16 个可玩 Demo 展示射击、飞行、竞速、塔防、解谜等用途。

项目提供了什么

项目把“有状态的游戏世界”拆为七层，并明确采用右手坐标系。

1. Math：统一空间语义。WorldBasis 是坐标真相源，可配置 right/up/forward 的世界轴和正负方向，负责控制信号、平面投影、航向/罗盘角、姿态 frame 与距离。ScalarUtils 提供钳制、插值和帧率无关平滑；Vector3Utils 安全归一化；确定性 PRNG 可复现；Clock 支持系统或手动时间。

2. Actor Motion：把输入变成运动意图。 角色基类统一速度、朝向、冲刺、蹲伏、跳跃、重力、落地与“计划/提交”；四个适配器处理世界目标、世界四向、角色相对移动和鼠标视角。车辆既有贴合地形的 ArcadeCar，也有 Rapier 轮式物理链路：控制器生成油门、倒车、制动、手刹、转向、Boost 意图，批处理器同步刚体/车轮，配置器按 WorldBasis 生成底盘与轮轴，漂移插件根据横向滑移改变抓地、转向和偏航。另有六轴载具、固定翼、蛇形移动、平板倾斜和三种模型控制器。

3. Behavior：可组合的 AI 驾驶与战斗。 网格规划器支持阻塞格、边界或环绕地图，并能求路径和可达区域；路径导航器把位置与路点变成速度/方向意图；进度跟踪器负责到点切换并计算弯角；WaypointDriver 再把弯角、车速、目标方向转换成转向、油门、倒车、刹车、Boost。NearbyAvoidanceSteering 在保持原始行进意图的同时避让邻近 Agent。CombatBehaviorDirector 为每个敌人保存记忆，在 idle、patrol、chase、attack、dead 间转换。

4. Gameplay：规则状态机而非画面脚本。CombatPlay 维护队伍、生命、护甲、死亡、胜者和重置；FlightPlay 判断地形撞击和完成状态；RaceCheckpointLapPlay 管倒计时、检查点、圈数、名次、完赛顺序与事件；SnakePlay 处理撞墙、自撞、互撞、道具和死亡原因；WaveSpawnDirector 按波次、权重和解锁规则提高出生压力。武器系统统一枪械/导弹切换、弹药、冷却、过热、锁定状态和开火决策；AimResolver 从屏幕 NDC 或显式射线得到命中点、目标和发射方向；ProjectileManager 托管存活弹体并汇总命中事件。

5. Camera 与 UI。 相机基类统一位置/旋转平滑、坐标基准和高度来源；四种具体 Rig 分别是固定世界偏移跟随、随目标姿态追尾、第一人称锁定、临时自由观察并自动回中。UI 层包含 DOM HUD 数据绑定、世界坐标到小地图投影、航向相对雷达、赛道小地图、完整飞行座舱 HUD、通知队列/过期消息流、可观察 UI 状态快照，以及容错的 localStorage JSON 设置。

6. World：场景、碰撞和生命周期。 Arena 生成地板、墙、柱、坡道，支持阻挡查询、出生采样和 Rapier Collider；NaturalEnvironment 组合程序化地形、树石草与碰撞；RaceTrack 压平道路并生成检查点、护栏、出生姿态；BoardEnvironment 负责格子/世界坐标互转。三类 TerrainSampler 统一暴露 heightAt/normalAt/colorAt/sample；MeshFactory 生成顶点色网格和匹配 trimesh；SpawnAreaSampler 支持矩形、圆、多边形、线段走廊允许/排除区；WorldBounds 建立边墙。

7. Object、Factory 与 Effects。 Pickup 负责动画和收集；Projectile 支持直线/追踪、命中、过期；FPS ViewModel 处理移动、姿态、瞄准和后坐力；HealthBar 是世界空间血条。工厂生成飞机、汽车、三类补给、弹体、植物和岩石。喷焰、点击标记、轮胎痕、对象池化武器特效补齐反馈；disposeObject3D 递归释放 geometry/material。

架构里最值得抄的不是类，而是数据流

GameBlocks 的核心模式是 input → planMovement → resolver → commitMovement → model/camera/UI。控制器先计算“想移动多少”，不直接假定它真的移动；多个角色把 intent 排入 KinematicBatchResolver，由 Rapier 角色控制器统一处理自动踏阶、坡度、贴地、碰撞过滤和 grounded 查询，再把 resolved movement 提交回权威状态。动态车辆则由另一批处理器统一 step 物理世界并回读底盘、车轮、线速度与角速度。

这解决了常见的“三份真相”：逻辑位置、物理刚体、Three.js 模型各自更新。模型、Camera 和 HUD 只读提交后的状态；插件则可在 plan/commit 两端介入。

安装：真正要装的是 Skill

Codex 的官方流程如下；Claude Code 只需把目标目录改为 ~/.claude/skills/gameblocks。

git clone https://github.com/xt4d/GameBlocks.git
cd GameBlocks
mkdir -p ~/.codex/skills/gameblocks
cp -R gameblocks/. ~/.codex/skills/gameblocks/

可选重启 Codex，然后输入 /gameblocks 或 $gameblocks；Claude Code 使用 /gameblocks。任务命中“浏览器 3D 游戏”描述时也可自动加载。

“从源码安装”没有编译步骤：仓库没有 package.json、发布包、构建脚本或 CLI，源码就是原生 ES Module。目标项目需自行提供 Three.js 0.161.0 与 Rapier3D compat 0.14.0；使用 bundler 时还要让 from 'three' 正常解析。

最高效的使用方式

不要把 74 个文件整包塞进项目。先固定 WorldBasis，再读 summary.md，按玩法挑最短闭环，并保持相对目录结构复制，防止内部 import 失效。

●第三人称角色：角色控制器 + KinematicBatchResolver + Pose/PositionFollowCameraRig。

●FPS：MouseLookCharacter + FirstPersonCamera + AimResolver + 武器/弹体系统 + FpsWeaponViewModel。

●赛车：ArcadeCar 快速出原型；需要轮胎悬挂与漂移，再换 DynamicCar 全链路；加赛道、路点驾驶、圈赛状态和 RaceMinimap。

●飞行：AirplaneMotion/Model + FlightPlay + FlightHud + JetFlame；需要导弹再接武器和弹体模块。

●棋盘/贪吃蛇：BoardEnvironment + GridPathPlanner 或 SnakeMotion/SnakePlay，不必引入 Rapier。

每帧顺序保持固定：采集输入；由控制器计划 intent；批量碰撞/物理解析；提交状态；最后更新模型、相机、HUD 与特效。适配优先改参数和边界，不要随手重写坐标公式。完成后按 Skill 要求建立 gameblocks_usage.md，记录用了哪些模块、原样复用还是改造、关键变化和集成位置——这既是给下一轮 Agent 的上下文，也是防止升级时丢失本地修改的清单。

适用边界

它适合快速构造浏览器端、单机、状态驱动的 3D 原型，也适合当作空间数学和玩法系统的参考实现；它没有编辑器、资产管线、网络同步、存档框架、音频系统、ECS、统一入口、自动依赖安装和仓库内测试。16 个 Demo 是外部 Vercel 成品链接，示例工程源码不在本仓库。项目处于极早期，接口兼容性也未作承诺。

MIT 许可证允许使用、复制、修改、合并、发布、分发、再许可和销售，但须保留版权与许可声明，软件按“原样”提供、无担保。

GameBlocks 最有价值的地方，不是替开发者隐藏复杂度，而是把最容易被 Agent 写错的复杂度变成了可检查的代码：一个坐标基准、一条权威状态链、一组可以按需拆走的积木。