sapdon 3.2.2 → 3.3.3

package/doc/user/config/mod-info.md

@@ -0,0 +1,33 @@
+# mod.info 配置参考
+
+`mod.info` 位于项目根目录，定义模组的元数据，用于生成 manifest.json。
+
+## 格式
+
+```json
+{
+  "name": "hello_sapdon",
+  "description": "我的第一个 Sapdon 模组",
+  "author": "YourName",
+  "version": "1.0.0",
+  "min_engine_version": "1.19.50"
+}
+```
+
+## 字段说明
+
+| 字段 | 说明 | 必填 |
+|------|------|------|
+| `name` | 模组名称，会被用作 `manifest.json` 中的名字和包目录名 | 是 |
+| `description` | 模组描述 | 是 |
+| `author` | 作者名 | 是 |
+| `version` | 版本号，格式 `major.minor.patch` | 是 |
+| `min_engine_version` | 最低游戏引擎版本 | 是 |
+
+### version 格式
+
+版本号必须是三位数字，用 `.` 分隔，如 `1.0.0`、`2.3.1`。
+
+### min_engine_version
+
+指定支持的最低 Minecraft 版本。例如 `1.19.50` 表示需要 1.19.50 及以上版本。

package/doc/user/faq.md

@@ -0,0 +1,160 @@
+# 常见问题 (FAQ)
+
+## 1. 如何更新框架版本？
+
+全局更新 sapdon CLI 和核心库：
+
+```bash
+npm update -g sapdon
+```
+
+如果使用的是本地项目依赖，请在项目目录中执行：
+
+```bash
+npm update sapdon
+```
+
+---
+
+## 2. 如何添加依赖？
+
+在项目根目录的 `build.config` 文件中配置 `dependencies` 字段：
+
+```json
+{
+  "dependencies": [
+    {
+      "module_name": "@minecraft/server",
+      "version": "1.8.0"
+    },
+    {
+      "module_name": "@minecraft/server-ui",
+      "version": "1.3.0"
+    }
+  ]
+}
+```
+
+构建时框架会自动将依赖注入到行为包的 `manifest.json` 中。
+
+---
+
+## 3. 构建输出在哪？
+
+执行 `sapdon build <项目名>` 后，构建产物会输出到项目根目录的 `dev/` 文件夹中。该目录包含完整的资源包和行为包结构，可直接用于开发测试。
+
+---
+
+## 4. 如何同步到 Minecraft？
+
+框架支持自动同步功能。构建完成后，产物会自动复制到 Minecraft 开发包目录（`com.mojang` 开发包文件夹）。前提是已正确配置开发包路径。
+
+如果自动复制失败，可以手动将 `dev/` 目录下的资源包和行为包复制到 Minecraft 的开发包目录。
+
+---
+
+## 5. 如何切换 release/beta 版本？
+
+在 `build.config` 中设置 `versionType` 字段：
+
+```json
+{
+  "versionType": "release"
+}
+```
+
+可选值：
+
+| 值 | 说明 |
+|-----|------|
+| `"release"` | 正式版 |
+| `"beta"` | beta 测试版 |
+
+切换后会影响生成的 `manifest.json` 中的 `header.name` 后缀和 `min_engine_version` 等配置。
+
+---
+
+## 6. 如何覆盖 Minecraft 路径？
+
+通过设置环境变量来指定 Minecraft 开发包目录：
+
+| 环境变量 | 说明 |
+|----------|------|
+| `MC_PATH` | 正式版 Minecraft 开发包路径 |
+| `MC_BETA_PATH` | Beta 版 Minecraft 开发包路径 |
+
+示例（Windows PowerShell）：
+
+```powershell
+$env:MC_PATH = "C:\Users\<用户名>\AppData\Local\Packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\games\com.mojang"
+```
+
+设置后，构建完成的包会自动同步到指定路径。
+
+---
+
+## 7. 构建报错 "tsc-alias not found"？
+
+确保已安装项目依赖：
+
+```bash
+npm install
+```
+
+如果使用了全局安装方式，可能需要重新安装：
+
+```bash
+npm install -g sapdon
+```
+
+此错误通常是因为依赖未正确安装或 node_modules 目录不完整导致的。
+
+---
+
+## 8. 为什么实体/物品 JSON 没有生成？
+
+常见原因：
+
+1. **未调用 `registry.submit()`** — 在完成所有注册后必须显式调用 `registry.submit()` 来提交数据。
+   ```javascript
+   import { registry } from "@sapdon/core";
+   registry.submit();
+   ```
+
+2. **`dataList` 为空** — 检查注册的模块是否正确调用了注册 API，确认数据是否已推入 `dataList`。
+
+3. **注册时机不对** — 确保 `registry.submit()` 在所有 API 注册调用之后执行。
+
+---
+
+## 9. 热更新不生效？
+
+检查 `build.config` 中是否启用了热更新：
+
+```json
+{
+  "useHMR": true
+}
+```
+
+确保 `useHMR` 设置为 `true`。如果已启用但仍不生效，请检查：
+
+- Minecraft 是否正在运行并加载了开发包
+- 网络连接是否正常（HMR 通过 WebSocket 通信）
+- 修改的文件是否在框架的监听范围内
+
+---
+
+## 10. 如何手动运行 sapdon lib？
+
+在项目目录下直接执行：
+
+```bash
+sapdon lib
+```
+
+该命令会手动运行 Sapdon 的核心库逻辑，通常用于调试或在某些自动化流程中单独触发库的处理流程。
+
+---
+
+> 如有其他问题，请加入官方 QQ 群：`810904181`

package/doc/user/quick-start.md

@@ -0,0 +1,108 @@
+# 快速入门
+
+## 环境要求
+
+- Node.js 16+
+- npm（随 Node.js 安装）
+- Visual Studio Code（推荐）
+
+## 安装 CLI
+
+```bash
+npm install -g sapdon
+```
+
+## 创建项目
+
+```bash
+sapdon create hello_sapdon
+```
+
+按提示填写项目信息：
+
+```
+✔ Project Name: hello_sapdon
+✔ Project Description: 我的第一个模组
+✔ Author Name: YourName
+✔ Project Version: 1.0.0
+✔ Minimum Engine Version: 1.19.50
+✔ Language:(js/ts) ts
+```
+
+## 项目结构
+
+```
+hello_sapdon/
+├── main.ts              # 构建入口——定义物品、实体等
+├── build.config         # 构建配置文件
+├── mod.info             # 模组元数据
+├── tsconfig.json        # TypeScript 配置
+├── pack_icon.png        # 模组图标
+├── res/                 # 资源文件（纹理、模型、音效）
+└── scripts/
+    └── main.ts          # Script API 入口（游戏内逻辑）
+```
+
+## 编写代码
+
+打开 `main.ts`，编写以下代码：
+
+```typescript
+import { ItemAPI, registry, ItemComponent } from '@sapdon/core'
+
+// 创建一个基础物品
+const item = ItemAPI.createItem(
+  'hello_sapdon:my_item',
+  'items',
+  'masterball'
+)
+item.addComponent(ItemComponent.setDisplayName('我的物品'))
+
+// 提交所有注册数据
+registry.submit()
+```
+
+## 构建项目
+
+```bash
+cd hello_sapdon
+sapdon build .
+```
+
+### 构建模式
+
+`build.config` 中的 `buildMode` 控制构建行为：
+
+| 模式 | 行为 |
+|------|------|
+| `development`（默认） | 运行 `main.ts` → 根据代码生成所有 JSON → 打包脚本 → 同步到 Minecraft |
+| `production` | 跳过 `main.ts`，直接同步已有 `dev/` 目录到 Minecraft（适合直接编辑 JSON 测试） |
+
+```bash
+# 使用 sapdon pack 以 production 模式构建（不启动热更新）
+sapdon pack
+```
+
+## 构建输出
+
+构建完成后，`dev/` 目录下生成：
+
+```
+dev/
+├── hello_sapdon_BP/          # 行为包
+│   ├── manifest.json
+│   ├── items/my_item.json
+│   └── scripts/index.js
+└── hello_sapdon_RP/          # 资源包
+    ├── manifest.json
+    └── textures/item_texture.json
+```
+
+同时自动同步到 Minecraft 开发包目录，启动游戏即可看到你的模组。
+
+## 下一步
+
+- [物品教程](./tutorials/item.md) — 学习创建各类物品
+- [实体教程](./tutorials/entity.md) — 学习创建实体
+- [方块教程](./tutorials/block.md) — 学习创建方块
+- [API 参考](./api/item.md) — 完整的 API 文档