内容
<div align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/brand/readme-banner-dark.svg">
<img src="assets/brand/readme-banner-light.svg" alt="hearth" width="480">
</picture>
**一款为人类和编码代理共同打造游戏而设计的 2D 游戏引擎和编辑器。**
[官网](https://hearth-engine.vercel.app) · [下载](https://github.com/echoo19/hearth/releases/latest) · [快速入门](docs/quickstart.md) · [文档](#documentation)
[](https://github.com/echoo19/hearth/actions/workflows/ci.yml)
[](https://github.com/echoo19/hearth/releases/latest)
[](LICENSE)
</div>
---
Hearth 是一款真正的游戏引擎，而非 AI 游戏生成器。人类可以使用正常的视觉编辑器，而编码代理（Claude Code、Codex 等任何 MCP 客户端）可以获得整个编辑器界面作为结构化、验证的、具有权限检查的操作，基于 CLI 和 MCP 服务器。引擎内部不运行任何 AI，不需要 API 密钥或云账户，项目存储为本地磁盘上的文件夹，包含可读的 JSON 文件、脚本和资产。
```
人类 ──▶ 编辑器 UI ──┐
├──▶ 共享命令系统 ──▶ 项目文件
代理 ──▶ CLI / MCP ──┘ （验证 · 执行 · 差异） 场景 · 脚本 · 资产
```
两类用户都使用相同的 51 条引擎命令：`createEntity`、`setComponentProperty`、`runPlaytest`、`getDiff` 等。代理可以构建关卡、连接输入、编写行为脚本、导入和裁剪艺术资源、运行无头测试，并提供结构差异供审查，所有操作无需猜测文件格式。你始终保持控制：权限模式控制代理可以触及的内容，每个会话都可以快照、差异对比和回滚。
## 引擎内容
**运行时.** 一个固定时间步长、确定性的 2D 运行时：精灵和精灵图集、图块地图（带有自动生成的碰撞器）、文本、2D 灯光、多边线、确定性粒子、精灵动画、游戏手柄输入（带有模拟虚拟轴）、相机效果（震动/闪烁/渐变/缩放冲击）和屏幕空间游戏 UI（带有布局容器、滑块、切换按钮和焦点导航）。物理引擎涵盖质量、恢复系数、摩擦力、命名碰撞层、单向平台和盒子/圆形/凸多边形碰撞器。音频包括音效、程序合成和一个在场景切换时保持活跃的流媒体音乐通道。相同的运行时在编辑器预览、Node.js 无头环境和导出的游戏中运行。
**脚本支持.** 默认使用 Lua（沙盒环境、种子确定性），同时支持 JavaScript，两者都针对相同的 `ctx` API：定时器、缓动函数、种子随机数生成器、发布/订阅事件、数学助手、网格寻路、相机控制和效果、UI 焦点、存档数据和场景切换，用于构建自己的菜单。`hearth inspect api` 打印整个接口。
**编辑器.** 一个可停靠的工作区，包含场景视图、层次结构、基于模式的检查器（每个固定选择字段的下拉菜单）、资产浏览器（带有精灵图集裁剪和预览）、实时游戏预览、控制台、输入设置面板（按键捕获、游戏手柄绑定）、撤销/重做（带有历史面板）和代理会话的差异/审查面板。在开发过程中在浏览器中运行，或作为一个打包的桌面应用程序（Electron）与本地文件夹对话框一起运行。
**代理工具.** `hearth` CLI 命令行工具包装了所有带有 `--json` 信封的命令，包括 `undo`/`redo`/`history`。MCP 服务器公开了 48 个类型化的工具，每个工具都有会话权限模式。Playtests 脚本输入（包括游戏手柄轴和指针拖动）并断言游戏状态、事件、粒子、音频、相机效果和 UI 焦点，完全无头且 CI 友好。`hearth screenshot` 通过无头 Chromium 渲染真实帧，让代理可以查看自己的作品。
**导出.** `hearth export web` 生成一个静态、自包含的构建（一个文件夹、一个 HTML 文件或一个 zip 文件，用于 itch.io），直接启动到你的第一个场景。没有引擎启动画面，没有品牌标识，Hearth 的任何 UI 元素都不会出现在你的游戏中。
**程序占位符.** 代理可以通过命令创建确定性 SVG 精灵和 WAV 音效，因此游戏在没有任何真实资产的情况下是可玩和可闻的。真实的艺术资源、音效、音乐和字体通过相同的资产管道导入：导入、探测、裁剪、动画。
## 状态
Hearth 当前版本为 **v0.7.0**，是一个开发者预览版。完整的循环功能已经实现：项目模型、编辑器、运行时预览、CLI、MCP、无头测试、差异审查和网页导出。此版本新增了磁盘备份的撤销/重做、游戏手柄输入（带有模拟虚拟轴）、确定性相机效果和第二代 UI 小部件（布局容器、滑块、切换按钮、焦点导航），并在早期版本的基础上增加了资产管道、物理引擎 v2、寻路、2D 灯光和粒子、Lua 脚本支持。[路线图](docs/roadmap.md) 列出了仍需实现的功能，包括预制资产、批量资产导入和桌面应用的签名。
## 安装
**桌面应用.** 从 [最新版本](https://github.com/echoo19/hearth/releases/latest) 下载：macOS (`Hearth-mac-arm64.dmg` / `Hearth-mac-x64.dmg`)、Windows (`Hearth-win-x64.exe`)、Linux (`Hearth-linux-x86_64.AppImage` / `Hearth-linux-amd64.deb`)。在 macOS 上，首次启动时需要右键单击 → 打开；如果 macOS 提示应用已损坏，请运行 `xattr -cr /Applications/Hearth.app`（预览版本为临时签名，暂未获得官方认证）。
**代理工具，无需安装.** CLI 和 MCP 服务器也作为单个文件发布，仅需 Node.js 20+：
```bash
curl -LO https://github.com/echoo19/hearth/releases/latest/download/hearth-cli.mjs
curl -LO https://github.com/echoo19/hearth/releases/latest/download/hearth-mcp.mjs
node hearth-cli.mjs --help
claude mcp add hearth -- node $PWD/hearth-mcp.mjs --project <your game>
```
这两个文件也包含在桌面应用中，编辑器的代理设置面板显示了它们的确切路径。
## 从源码快速开始
需要 Node.js 20+。
```bash
git clone https://github.com/echoo19/hearth.git && cd hearth
npm install
npm run build:packages # core → runtime → playtest → cli → mcp-server
npm test # 完整测试套件，无头环境
npm run dev # 编辑器启动，地址：http://localhost:5173
```
在启动器中打开一个示例项目（试试 **Mini Platformer**），按下 **Play**。使用箭头键或 WASD 移动，按 Space 跳跃。对于桌面应用，运行 `npm run app` 启动应用，`npm run app:dist` 打包一个真正的安装程序；详见 [docs/desktop-app.md](docs/desktop-app.md)。
## 尝试代理循环
这是代理的工作流程，也适合手动操作：
```bash
alias hearth="node $PWD/packages/cli/dist/main.js"
cd packages/examples/mini-platformer
hearth snapshot # 快照，用于审查
hearth inspect scene "Level 1" --json # 查看内容
hearth create entity "Level 1" Gem \
--position 620,300 --tags coin \
--components '{"SpriteRenderer":{"shape":"diamond","color":"#9b59b6","width":20,"height":20},"Collider":{"shape":"circle","radius":12,"isTrigger":true}}'
hearth attach script "Level 1" Gem scripts/coin-pickup.js
hearth validate --json # 模式 + 引用检查
hearth test # 无头测试
hearth diff # 更改内容，人类可读
hearth revert --confirm # 撤销整个会话
```
连接 Claude Code：
```bash
claude mcp add hearth -- node $PWD/packages/mcp-server/dist/main.js \
--project $PWD/packages/examples/mini-platformer
```
然后要求它调用 `get_agent_instructions`。权限模式从 `--mode read-only` 开始，最高到 `--mode all`，控制代理可以执行的操作；详见 [docs/mcp.md](docs/mcp.md)。
## 示例
`packages/examples` 中有八个示例项目，每个项目都是通过命令系统生成的，并被 CI 中的测试覆盖。它们涵盖了从迷你平台游戏到纯 Lua 示范的各种示例：**Ember Trail**（场景切换、定时器、保存的最佳分数）、**Glow Caves**（灯光和粒子在火炬照亮的洞穴中）、**Bounce Patrol**（物理层和寻路巡逻）、**Sky Courier**（切片像素艺术精灵图集、流媒体 chiptune 音乐和导入的字体）和 **Drift Cellar**（模拟游戏手柄移动、相机震动/闪烁/渐变和焦点可导航的暂停菜单，带有滑块和切换按钮）。它们也作为参考项目：文档中描述的每个功能都可以在其中一个示例中找到。
## 文档
| | |
| --- | --- |
| [快速入门](docs/quickstart.md) | 安装 → 十分钟内创建首个游戏 |
| [桌面应用](docs/desktop-app.md) | Electron 打包，原生文件夹对话框 |
| [CLI 指南](docs/cli.md) | 每个命令，以及 JSON 信封 |
| [MCP 指南](docs/mcp.md) | 连接代理，权限模式 |
| [代理工作流](docs/agents.md) | 代理如何操作，为什么 |
| [架构](docs/architecture.md) | 包，命令系统，数据流 |
| [项目格式](docs/project-format.md) | 每个文件，每个模式 |
| [组件](docs/components.md) | 所有 17 种组件类型及其默认值 |
| [资产](docs/assets.md) | 导入，精灵图集，动画，音乐，字体 |
| [脚本支持](docs/scripting.md) | Lua 和 JS，完整的 `ctx` API |
| [输入](docs/input.md) | 操作，键盘，游戏手柄，虚拟轴 |
| [UI](docs/ui.md) | 小部件，布局，焦点导航 |
| [网页导出](docs/export.md) | 静态构建，单文件，itch.io |
| [路线图](docs/roadmap.md) | 下一步是什么，诚实地列出遗漏的功能 |
| [贡献](CONTRIBUTING.md) | 开发设置和 AI 贡献政策 |
## 设计原则
1. **引擎无需 AI 支持.** 代理是首要的客户端，但引擎的任何部分都不依赖于它们。
2. **统一的命令系统.** 如果不是已注册的命令，UI 和代理都无法执行，因此功能保持可读和可审计。
3. **人类始终保持控制.** 权限模式控制代理可以触及的内容，快照和结构差异使每个代理会话都可审查和回滚，并且测试使“有效”可检查。
4. **本地优先，可读的文件.** 项目是可差异对比的 JSON 文件，可以在任何地方打开的艺术资源，以及纯 Lua 或 JavaScript 脚本。
## 许可证
[MIT](LICENSE)。依赖项均为开源友好型：zod、commander、PixiJS、React、wasmoon 和 MCP SDK。
