Ludra 0.91：用 JSON 搭 3D 游戏，让 AI 测试与截图

Ludra 的 3D 游戏引擎

Ludra v0.91.0 把 Three.js 画面与 Rapier 3D 物理接入同一条 AI 开发流程：写场景、跑模拟、做断言、看截图，再交给人试玩。它提供自己的游戏引擎与命令行工具，适合从小型原型评估这套方法。

Sky Islands 浮岛关卡，官方 3D 模板局部 · Ludra 官方仓库

JSON 场景如何接上 3D 世界

Ludra（ersingvn/ludra）是一套面向 AI 智能体的游戏引擎。场景文件列出实体与组件，脚本补充自定义玩法；CLI 负责创建、检查和运行项目，AI 助手负责理解需求、修改这些文件。它本身不提供聊天模型。

v0.91.0 把这条流程扩展到 3D。Three.js 负责画面，Rapier 3D 负责物理；两者是底层依赖，主项目仍是 Ludra。3D 场景以米为单位，Y 轴向上，角色可走斜坡、推箱子、搭乘移动平台。

• mesh 定义外形、PBR 材质与纹理，light 负责灯光和阴影，camera3d 提供跟随、环绕、第一人称与固定视角。
• 角色、机关、检查点和终点进入同一套模拟；TypeScript 脚本还能使用力、冲量与射线查询。
• 渲染钩子可以调用 Three.js 做几何体、着色器和后处理，但不能修改游戏模拟状态。

2D 仍可使用原有平台跳跃、俯视角和打砖块模板，或选择 Rapier 物理。下面是官方 2D 物理示例，与开头的 3D 浮岛属于不同场景。

箱子、坡面与物理机关，官方 2D 示例局部 · Ludra 官方仓库

从官方 CLI 创建第一个项目

按官方文档整理，未进行本机实测。环境要求为 Node.js 22.18 或更新版本；需要输出真实画面时，机器还要有 Chrome、Edge 或 Chromium。AI 助手另行准备，命令行路径也可手动操作。

项目与安装说明在同一仓库。微信外链可能无法直接打开，可复制下面的完整地址到浏览器；packages/cli/README.md 提供 CLI 入门说明。

https://github.com/ersingvn/ludra

https://github.com/ersingvn/ludra/tree/v0.91.0/packages/cli

• 在终端运行下面的官方创建命令，生成 my-game 目录。3d 模板是 Sky Islands：收集水晶、乘木筏并抵达传送门的浮岛关卡。

npx @ludra/cli new my-game --template 3d

• 进入新目录。以后让 AI 围绕这里的场景、脚本与测试修改游戏，保留项目文件即可继续迭代。

cd my-game

本文对应 0.91.0 资料，创建命令未锁定包版本；后续执行可能取得更新版本。CLI 的 npm 包名是 @ludra/cli，不要省成 npx ludra，后者指向无关包。

使用 Claude Code 的读者也可按仓库 Quick start 安装官方插件。插件提供工作流指导，底层仍由同一套 CLI 创建、检查和测试项目，不是另一套游戏引擎。

把检查、测试与画面一起交给 AI

在 my-game 目录先检查场景和素材，再运行项目自带测试。check 会返回错误位置与修复提示；test 执行 tests 目录中的输入脚本和断言。两者回答的问题不同，创建目录成功不能代替测试通过。

npx @ludra/cli check
npx @ludra/cli test

测试可以检查 won、deaths、score 和事件次数，也能检查某个时刻角色的位置或是否落地。官方 Sky Islands 模板自带 10 项测试；这是上游提供的基线，新增机关和胜负条件仍需补相应断言。

把“能运行”扩展到“画面正确”，还需要 play 的真实截图。官方 play 命令支持 --screenshot 选项，可指定时间点；输出是 PNG 文件。AI 应打开图片检查角色、平台和遮挡关系，再决定如何改场景。

移动平台上的角色，官方 2D 截图示例局部 · Ludra 官方仓库

review 还会检查未测试的机制、默认 HUD、缺少反馈等问题。它能提出修改线索，最终手感与视觉效果仍要在浏览器试玩中判断。运行下面的命令后，可用键盘体验同一项目，开发服务支持热重载。

npx @ludra/cli dev

模拟采用固定步进，渲染只读取状态，有助于让脚本测试与浏览器画面对应。测试的覆盖面由断言决定：一条通关路线通过，并不代表所有跳跃路线和边界情况都已检查。

早期版本的适用范围与许可

Ludra 仍是早期项目。v0.91.0 于北京时间 10 月 26 日 02:23 发布，当前 3D 重点是基本几何体、物理角色、光照与相机，适合评估 AI 如何在文本场景里修改和验证小型原型。

glTF/GLB 模型、骨骼动画及更多程序化地形列在 v0.92 路线图中；单文件网页构建、触摸和手柄控制列在 v0.93 计划中。当前教程止于本地浏览器试玩，不把这些规划写成已交付能力。

对已有 Unity 或 Godot 项目的团队，这里值得参考的是场景文件、输入脚本、断言与截图如何配合。Ludra 使用自己的场景与组件结构，本篇没有把现有引擎工程迁入它的路径。

仓库采用 MIT 许可证；复制或分发软件及文档的实质部分时，需要保留版权和许可声明。项目图片、字体、模型以及外部依赖仍需按各自来源核对授权，MIT 不代替第三方素材许可。

从一个模板和一条可重复的测试路线开始，能较快看清工具是否符合自己的原型需求；确定采用后，再扩充机制测试、画面检查和人工试玩范围。