内容
# Studio Foundation
**一款基于人工智能的开源游戏开发工具包 — 采用Godot 4.7.1 WebGPU浏览器后端，真正实现3D渲染。**
官方 [Godot](https://github.com/godotengine/godot) 是基础，并保持为上游。在其之上是一个WebGPU导出路径，以有序的、SHA-256锁定的补丁系列方式维护，以及MCP服务器、代理工作流和资产管道，使整个过程可由AI助手驱动。WebGL 2仍然是支持的备用方案。
### ▶ [在线试玩 — 在浏览器中运行的Godot游戏，基于WebGPU](https://lxsolutions.github.io/studio-foundation/)
无需安装，无需插件。需要支持WebGPU的浏览器（Chrome/Edge 113+，Safari 26+，Windows上的Firefox）；页面会在您点击之前告诉您是否符合要求。首次加载大约需要15-30秒，取决于您的连接速度 — 大部分时间用于下载约46 MB的引擎，而不是编译着色器（管道在大约2秒内构建）。之后会缓存。详情：[webgpu-performance.md](docs/architecture/webgpu-performance.md)。
[](https://lxsolutions.github.io/studio-foundation/)
***The Chariot Club*** *— 一个真正的游戏，而不是测试场景：一个罗马圆形剧场，带有拥挤的看台、战车队伍和实时阴影，通过WebGPU由Godot 4.7.1渲染。在NVIDIA Tesla P40上以60帧锁定，约490-630次绘制调用和~23M个图元/帧，**0 `GPUValidationError`***。发布的演示是从同一个GPU的公共URL重新渲染的，作为最终检查。
> **您可以重建所有内容：** 所有内容。引擎和补丁系列都是校验和锁定的，两个演示都在这个仓库中 — 下面最小的场景和The Chariot Club本身在[`games/chariot/`](games/chariot)中。请注意，游戏发布时为了使演示可复制和审计，而不是重新许可：根据[`games/LICENSE`](games/LICENSE)，没有自己的LICENSE的游戏目录保留所有权利。Foundation本身（`engine/`、`tools/`、`shared/`等）仍然在仓库根目录的LICENSE下。
<details>
<summary>还发布了一个~100行的最小场景，用于从头开始重现渲染路径</summary>
[](https://lxsolutions.github.io/studio-foundation/showcase/index.html)
[`webgpu_showcase.gd`](templates/godot-game/project/scenes/webgpu_showcase.gd) 构建了六个PBR网格、定向光源和实时阴影映射，完全在代码中，没有外部资产 — 59-60帧/秒，36次绘制/帧，0 `GPUValidationError`。它的存在是为了在没有游戏内容的情况下可以重现渲染路径。在线演示：[`/showcase/`](https://lxsolutions.github.io/studio-foundation/showcase/index.html)。
</details>
## 我们的方向：基于人工智能的开源游戏开发
Godot不接受AI生成的代码贡献，并已声明不打算在引擎中添加AI功能。这是一个刻意的选择 — 而这就留下了一个空白。Studio Foundation的目标是**使用AI构建游戏**，在公开的环境中，不作为附加功能。
WebGPU后端证明了这个模型是可行的：一个AI辅助功能，社区已经期盼多年，以透明的补丁系列在官方Godot（MIT）上进行，并在一款真正的GPU硬件上进行验证。如果它再优秀不过，Godot的政策也不会改变，因此它在这里继续发展。
## 快速开始
`just doctor` 会报告所需的先决条件。快速的仓库检查需要Python 3.11；Godot和引擎工具链仅在它们的套件中需要。
```sh
git clone https://github.com/lxsolutions/studio-foundation.git
cd studio-foundation
just doctor
just bootstrap
just test
```
如果没有`just`，请在Windows上运行`powershell scripts/bootstrap.ps1`或在Linux、macOS或WSL2上运行`sh scripts/bootstrap.sh`。
### 在不构建WebGPU后端的情况下使用它
已发布预构建的Web导出模板，因此您可以尝试WebGPU 3D而无需进行多小时的引擎构建：
**[下载模板](https://github.com/lxsolutions/studio-foundation/releases/tag/godot-4.7.1-webgpu-p0014)** （官方Godot 4.7.1 + 补丁系列0001-0014，单线程，因此导出在普通静态主机上运行，无需COOP/COEP标头）。将`web`预设的`custom_template/release`和`custom_template/debug`指向它们，然后使用`just export-browser-webgpu`导出 — 此步骤应用WebGPU交接，官方编辑器无法发出，如果跳过它，将生成一个无法启动的构建。两个文件都在发行说明中列出了SHA-256。
### 自己构建WebGPU路径
```sh
just engine-versions # 显示固定的提交和补丁系列
just engine-fetch # 克隆官方Godot，验证并应用补丁
just engine-build # 构建WebGPU导出模板
just engine-validate
just export-browser-webgpu
```
管道故意拆分，以便每个阶段都可以独立检查：
```text
官方Godot提交 -> 验证的补丁系列 -> 发布 + 调试WebGPU模板
-> Godot导出 -> 浏览器运行时探针 -> 直观证据
```
`engine-build` 需要 [engine-lock.toml](engine/engine-lock.toml) 中固定的Emscripten版本。完整过程：[WebGPU运行手册](docs/runbooks/godot-webgpu-update.md)。
## 什么是可验证的
| 功能 | 此仓库中的证据 |
|---|---|
| 官方引擎基础 | Godot 4.7.1稳定版由[engine-lock.toml](engine/engine-lock.toml)中的完整提交固定 |
| WebGPU源代码 | [engine/patches/](engine/patches/)中的有序补丁系列，每个补丁在应用前都经过SHA-256校验。`just engine-verify-patches`重新检查整个系列 — 校验和、顺序和磁盘上没有解锁的内容 — 无需工具链。 |
| WebGPU工具链 | 确切的Emdawn源代码和Dawn命名空间反向移植独立版本控制并校验和锁定在[engine/toolchain/](engine/toolchain/)下 |
| 源代码准备 | `engine-fetch`仅克隆官方Godot并创建可处理的修补工作树 |
| 导出模板 | 接受的存档由文件名、字节数和SHA-256在[engine-lock.toml](engine/engine-lock.toml)中记录 |
| 运行时验证 | 浏览器烟雾测试观察引擎的适配器、设备和WebGPU画布请求，并拒绝任何WebGL上下文请求 |
| 3D着色器转换 | 在NVIDIA Tesla P40上在浏览器中验证。补丁0009-0012修复了四个不同的转换崩溃；运行时专门的场景着色器在没有崩溃的情况下转换。 |
| WebGPU着色器覆盖率 | 205个着色器模块中的199个转换为空有效的WGSL，**0个GLSL编译失败**，在引擎的实际目标环境（Vulkan 1.1 / SPIR-V 1.3 — 之前测量的工具链无法重现引擎；参见补丁0016）。**这6个剩余的失败不会阻止Forward+下的WebGPU：** 两个是Forward Mobile的子通道色调映射，一个是FSR的16位变体（驱动程序报告没有half-float，因此引擎选择备用，它转换），两个是WebGPU不选择的subgroup变体，一个是编辑器调试 gizmo。 |
| 渲染上限 | 每个WebGPU导出都运行**Forward Mobile**，它在项目设置中硬禁用SSAO、SSIL、SSR、SDFGI、VoxelGI和体积雾。补丁0015和0017解锁**Forward+**（集群）— 需要这些效果的渲染器和更好的架构选择，因为Mobile的一个不可转换的着色器也是引擎中唯一使用subpass的着色器。每个Forward+需要的着色器都已转换；**尚未硬件验证**，因此`mobile`仍是默认导出。 |
| 3D渲染（带光和阴影） | **在NVIDIA Tesla P40上在浏览器中验证**。补丁0013-0014修复了每个阶段的采样器可见性和深度纹理采样器类型。一个最小的PBR + 阴影场景以59-60帧/秒 / 36次绘制/帧渲染，一个完整的游戏（The Chariot Club）在~490-630次绘制和~23M个图元/帧下保持60帧锁定 — 两者都有0 `GPUValidationError`。 |
| 备用 | 相同的模板项目有一个官方的WebGL 2导出预设 |
| 模板行为 | 无头GDScript测试涵盖共享插件和中性启动项目 |
| 可选服务 | Rust和Nakama组件独立测试，不需要客户端使用 |
确切的测试计数、工件状态和未验证区域在[验证报告](BOOTSTRAP_REPORT.md)中。
## 状态和诚实的限制
WebGPU支持处于**测试**阶段。
有效且在真实GPU硬件上验证的内容：引擎启动WebGPU后端（Forward Mobile），转换运行时专门的3D场景着色器，并渲染带有0个验证错误的光照3D几何图形。2D/UI渲染并与WebGL基准线以1.2%的视觉差异进行对比。
还未实现的内容：几个后处理效果（色调映射变体、SSR、TAA、SDFGI/体素GI调试视图）仍然会**优雅地**失败着色器转换 — 它们被跳过而不是崩溃，因此3D渲染不会出现问题。要看到一个可见的帧已经经过了十四次补丁修复着色器转换和绑定描述问题；每个问题都在[engine/patches/README.md](engine/patches/README.md)中记录了它解决的确切缺陷。
Godot自己的WebGPU支持也在上游单独开发中。这个项目不是该努力的竞争对手 — 它是一个可维护的、可重现的路径，适用于今天的Godot 4.7.1，并且在上游准备就绪时保持为补丁系列，以便可以将其撤回。
发布的演示下载约45 MB的引擎（12 MB压缩）后才可以绘制。测量的分解以及为什么大部分是Godot而不是WebGPU堆栈，请参见[WebGPU有效载荷和启动](docs/architecture/webgpu-payload-and-startup.md)。
尚未声明：Safari/iOS行为和原生Android/iOS设备运行。完整列表在[BOOTSTRAP_REPORT.md](BOOTSTRAP_REPORT.md)中；正在进行的工程日志在[docs/architecture/webgpu-runtime-status.md](docs/architecture/webgpu-runtime-status.md)中。
在[docs/architecture/webgpu-performance.md](docs/architecture/webgpu-performance.md)中测量了WebGPU-vs-WebGL 2性能（相同场景，相同GPU）和每个游戏渲染验证。
## 包含的组件
- 中立的Godot 4.7.1项目模板和可重用的`studio_core`插件。
- 带有官方WebGL 2备用的WebGPU导出工具。
- 浏览器烟雾、截图、视觉回归、基准测试和发布检查。
- MCP服务器和代理工作流文档。
- Blender到glTF验证和导出工具。
- 可选的Rust API/会话脚手架和PostgreSQL开发设置。
- 可选的Nakama适配器，无需定义游戏机制即可转发不透明的应用程序有效负载。
可选的后端是脚手架，而不是必需的架构。 使用中的游戏拥有其内容、规则、模式、身份策略、持久性语义和部署。
## 仓库布局
| 路径 | 目的 |
|---|---|
| `engine/` | 官方Godot固定、WebGPU补丁、构建命令和工件记录 |
| `templates/godot-game/` | 机械中立的Godot客户端和可选服务器模板 |
| `shared/godot-addons/studio_core/` | 可重用的Godot服务和平台接口 |
| `services/` | 可选的Rust协议、会话、API和持久性脚手架 |
| `infra/` | 可选的本地PostgreSQL、Nakama和跟踪服务 |
| `tools/` | 引擎、资产、导出、浏览器、发布、MCP和存储库工具 |
| `tests/` | 跨语言、浏览器、集成、性能和视觉检查 |
| `docs/` | 决策、架构说明和操作手册 |
## 常用命令
| 命令 | 目的 |
|---|---|
| `just test` / `just lint` | 运行快速测试和代码检查套件 |
| `just test-godot` / `test-rust` / `test-python` | 运行一个实现套件 |
| `just NAME=my_game DISPLAY_NAME="My Game" new-game` | 生成一个中立的Godot项目 |
| `just export-browser-webgl [GAME]` | 使用官方WebGL 2模板导出 |
| `just export-browser-webgpu [GAME]` | 使用本地构建的WebGPU模板导出 |
| `just run-browser-smoke` | 检查浏览器启动、控制台输出、画布和渲染器 |
| `just ci-local` | 运行完整的本地验收套件 |
运行`just`列出所有支持的命令。
## 源代码和归属
官方Godot是唯一的活跃引擎上游。WebGPU后端具有MIT许可的历史血统，来自`dwalter/godotwebgpu`；Studio Foundation维护当前的Godot 4.7.1补丁系列、构建工具和验证表面在这个仓库中。 lineage仓库永远不会被构建克隆。
参见[NOTICE.md](NOTICE.md)和[WebGPU集成来源](docs/architecture/webgpu-integration.md)，获取确切的源边界和提交固定。
## 贡献和许可证
Material引擎更改需要测试、更新的证据和相关的ADR。贡献者工作流程在[WORKING_AGREEMENTS.md](docs/agents/WORKING_AGREEMENTS.md)中。安全范围和私人报告说明在[SECURITY.md](SECURITY.md)中。
Foundation代码、工具、模板、文档和基础设施在MIT和CC BY 4.0下双重许可；参见[LICENSE](LICENSE)。第三方归属在[NOTICE.md](NOTICE.md)和[dependency-licenses.md](docs/architecture/dependency-licenses.md)中。
