GameBlocks — 面向 AI 编程 Agent 的浏览器 3D 游戏开发 Skill 库

📝

GameBlocks 不是游戏引擎也不是 npm 库，而是一套本地 Skill + 74 个 ES Module，专为 Codex / Claude Code 等 AI 编程 Agent 设计，解决 AI 写 3D 游戏时方向轴颠倒、相机不同步、碰撞坐标不一致等经典痛点。

项目概览

项目	GameBlocks
GitHub	xt4d/GameBlocks
定位	本地 Skill + 74 个 ES Module，不是游戏引擎，不是 npm 库
目标用户	用 Codex / Claude Code 写 3D 游戏的开发者
运行环境	浏览器（Three.js 渲染）

解决的核心痛点

AI 编程 Agent 写 3D 游戏时，最常见的三类低级错误：

方向轴颠倒 — Agent 经常搞混 Y-up 和 Z-up，导致角色倒着走、天空在脚下
相机不同步 — 第三人称相机和目标角色各算各的，视角漂移
碰撞坐标不一致 — 物理引擎和渲染引擎坐标系对不上，穿模/幽灵碰撞

GameBlocks 的核心思路：给 Agent 一套统一的坐标真相源和分层模块，让 Agent 不用每次从零推导坐标系。

七层架构

GameBlocks 将 3D 游戏开发拆分为七层，每层是一组独立的 ES Module：

1. Math — 统一右手坐标系

WorldBasis 是坐标真相源，所有模块从这里取轴向定义
统一右手坐标系（Y-up），消除 Agent 的轴向混淆

2. Actor Motion — 输入→运动意图

将玩家输入（键盘/手柄/触屏）转换为运动意图向量
支持角色（Character）、车辆（Vehicle）、飞行器（Aircraft）三种运动模式

3. Behavior — AI 行为

AI 驾驶、战斗决策、路径规划
基于行为树/状态机的 NPC 逻辑

4. Gameplay — 规则状态机

内置多种游戏模式的状态机模板：战斗、竞速、贪吃蛇等
管理游戏生命周期（开始→进行→结束→计分）

5. Camera & UI — 相机与界面

相机绑定策略（第一人称、第三人称、俯视、轨道）
HUD 元素与游戏状态的同步

6. World — 场景管理

场景图组织、地形生成、光照配置
对象生命周期管理（生成/销毁/池化）

7. Physics — 物理碰撞

碰撞检测与响应
与 Math 层坐标系严格对齐

为什么不是 npm 库？

GameBlocks 的设计哲学是 Skill 而非依赖：

传统 npm 库：npm install → 引入 → 调用 API。Agent 需要理解 API 文档，容易用错
GameBlocks Skill：文件直接在项目目录里，Agent 可以读源码、改源码、理解上下文。每个模块都是可读的 ES Module，Agent 可以直接看到坐标系定义、运动公式、状态机转换

这与 Claude Code / Codex 的 Skill 系统天然契合——Skill 就是给 Agent 看的结构化知识 + 可执行代码。

74 个 ES Module

项目包含 74 个独立的 ES Module，覆盖：

向量/矩阵/四元数运算
角色控制器（走/跑/跳/爬）
车辆物理（悬挂/转向/漂移）
飞行器动力学
第三人称相机（碰撞回避/平滑跟随）
路径查找（A*/导航网格）
战斗系统（命中检测/伤害计算）
游戏状态机模板
HUD 组件
场景管理器
对象池
粒子效果
音频管理

每个模块都是独立的 .js 文件，Agent 可以按需引用，不需要理解整个框架。

使用方式

# 克隆到项目目录
git clone https://github.com/xt4d/GameBlocks.git

# 在 Claude Code / Codex 中作为 Skill 加载
# Agent 会自动读取 WorldBasis 获取坐标系定义
# 然后按层引用所需模块

与 Three.js 的关系

GameBlocks 基于 Three.js 渲染，但不是 Three.js 的封装层。它更像是一组经过验证的 3D 游戏开发模式，以 ES Module 形式组织，让 AI Agent 可以直接引用和修改。

总结

GameBlocks 填补了一个独特的生态位：给 AI 编程 Agent 用的 3D 游戏开发参考库。它不试图成为 Unity 或 Godot，而是成为 Agent 的「3D 游戏开发直觉」——通过统一的坐标系、分层的模块、可读的源码，让 Agent 写出方向正确、相机同步、碰撞一致的 3D 游戏代码。

对于用 AI 写浏览器 3D 游戏的开发者，这是一个值得关注的项目。

本文基于项目 GitHub 仓库及介绍文章整理。原文来源：微信公众号文章。