nEngine

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

图形化编辑器本身也是可分发桌面应用（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() 释放事件处理器引用，无残留事件泄漏。