# 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)**（快速开始 / 打包为桌面软件）。

## 文档地图

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