# nEngine

**nEngine** 是一个**俯视角 2D 种田游戏的引擎**（top-down 2D farming game engine），而不是一个可玩的游戏。TypeScript + PixiJS 的 monorepo（pnpm workspaces），围绕三大不可妥协支柱：**MCP-first 接口**、**引擎级 Mod 支持**、**强制数据驱动内容**。

核心价值：**可控性**（外部工具 / AI Agent 通过 MCP 完整操控）、**可扩展性**（Mod 通过类型化钩子注入玩法）、**内容即数据**（游戏 = YAML 数据文件，引擎逻辑不硬编码内容）。

## 三种运行方式

1. **浏览器游玩（开发模式）**：`pnpm dev` → 打开 `http://localhost:5173/apps/dev/?contentDir=examples/sample-game/content&modsDir=examples/sample-game/mods`
2. **MCP 调试（headless 核心 + stdio）**：`pnpm -r build` → `node apps/mcp-server/dist/index.js --content-dir examples/sample-game/content --mods-dir examples/sample-game/mods`，用任意 MCP 客户端连接
3. **打包发布**：`nengine-pack` 把内容编译成自包含静态网站 / Electron 桌面应用（安装器）：`NODE_OPTIONS=--use-system-ca pnpm pack:example:full`

（进阶：headless 核心 + `--ws-port` WebSocket 视口同步，浏览器只渲染快照。）

## 安装与打包桌面软件

下载/安装本引擎、以及如何把游戏打包为桌面软件（AppImage 等）的完整步骤，见 **[`docs/engine-guide-zh.md` §4](docs/engine-guide-zh.md)**（快速开始 / 打包为桌面软件）。

**图形化编辑器本身也是可分发桌面应用**（D41 F4，nEngine Editor）：`NODE_OPTIONS=--use-system-ca pnpm --filter @nengine/editor dist` → `apps/editor/dist-app/nEngine Editor-*.AppImage`；`ELECTRON_DISABLE_SANDBOX=1 DISPLAY=:1` 启动，也支持 `--mcp-stdio --dir <project>` 作为无头 MCP 服务器。详见 `docs/editor.md`（Distribution (F4) 一节）。

## 文档地图

| 路径 | 用途 |
|---|---|
| `docs/decisions.md` | 全部架构决策（D1–D39），**WHY 的事实来源** |
| `docs/architecture.md` | 顶层架构、包边界、目录布局 |
| `docs/mcp.md` | **MCP-first 接口规格**（23 命名空间 / 132 工具 / 36 资源 / 17 prompt） |
| `docs/api.md` | 引擎 API 参考（活的 API 文档） |
| `docs/boundaries.md` | 引擎/游戏边界（三判据） |
| `docs/engine-guide-zh.md` | 中文引擎指南：安装、游玩、制作游戏、打包发布 |
| `docs/editor.md` | **编辑器架构（D40）**：编辑器设计、IPC、E1–E7/F1–F4 进度、Distribution (F4) |
| `AGENTS.md` | 项目规则 + 当前状态摘要 |
| `examples/sample-game/README.md` | 示例游戏 Pinefield Valley 的完整游玩/驱动/打包说明 |

## 新功能亮点（v0.1 Latest）

- **物品合成系统 (Crafting)**：通过 `recipes/` 定义合成配方（物品 + 数量 → 产出），玩家在游戏中或通过 MCP `craft.do_craft` 执行合成；新增命名空间 `craft.*`（authoring 工具 + list/get/do_craft/validate）。
- **节日模板 (Festival Templates)**：春夏秋冬四季节日状态机（`festival-spring/summer/autumn/winter`），自动切换 BGM、发放节日奖励物品（樱花瓣/烟花券/丰收符咒/雪晶），示例游戏已启用。
- **BGM 音频系统**：`play-bgm` / `stop-bgm` 行为动作，支持循环 + 淡入淡出；`sound` 定义支持 `mode: "bgm"`；合成器 BGM 内建简单和弦循环，示例游戏有 5 首季节/胜利 BGM。
- **丰富物品 Schema**：新增 `rarity`（common/uncommon/rare/epic/legendary）、`durability`（工具耐久）、`description`、`effects`（食用加体力/金币）、`spriteRef`（图标）；物品类型扩展 7 种（tool/seed/material/consumable/decoration/good/crop）。
- **库存工具调用**：MCP 新增 `item.use`（消耗品）、`item.damage`（耐久损耗）。
- **打包跨平台兼容**：编辑器路径处理（content/outDir/modsDir）全面改为 `path.join/resolve`，在 Windows 正确构建 bundle.json 与 desktop shell。
- **内容热加载稳定性**：`ContentLoader.watch` 新增轮询兜底（250ms），fs.watch 信号不可靠的容器/沙箱环境照常热加载。
- **生命周期完备**：`engine.stop()` 清理 auto-tick 定时器、所有 event hooks、调用 `System.destroy()`（如有），`WorldEventBus.clear()` 释放事件处理器引用，无残留事件泄漏。