sapdon 3.2.2 → 3.4.0

package/doc/user/api/texture.md

@@ -0,0 +1,181 @@
+# 纹理系统 API 参考
+
+本文档涵盖 Sapdon 框架的纹理系统 API，包括物品纹理、方块纹理和翻书纹理（Flipbook Textures）。
+
+---
+
+## ItemTextureManager
+
+物品纹理管理器，用于注册和管理物品纹理。所有方法均为静态方法。
+
+### 方法
+
+#### `ItemTextureManager.registerTexture(name, path)`
+
+注册一个物品纹理。
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `name` | `string` | 纹理名称，如 `"masterball"` |
+| `path` | `string` | 纹理路径，如 `"textures/items/masterball"` |
+
+```javascript
+import { ItemTextureManager } from "@sapdon/core";
+
+ItemTextureManager.registerTexture("masterball", "textures/items/masterball");
+ItemTextureManager.registerTexture("ruby_sword", "textures/items/ruby_sword");
+```
+
+#### `ItemTextureManager.registerTextureData(name, data)`
+
+注册一个带有完整数据结构的物品纹理，允许传入包含 `textures` 字段的对象。
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `name` | `string` | 纹理名称 |
+| `data` | `object` | 纹理数据对象，至少包含 `{ textures: string \| string[] }` |
+
+```javascript
+ItemTextureManager.registerTextureData("ruby_ingot", {
+  textures: "textures/items/ruby_ingot"
+});
+```
+
+#### `ItemTextureManager.getItemTextures()`
+
+返回所有已注册的物品纹理的键值对对象。等价于 `Object.fromEntries(item_texture_sets)`。
+
+```javascript
+const textures = ItemTextureManager.getItemTextures();
+// 输出: { masterball: { textures: "textures/items/masterball" }, ... }
+```
+
+#### `ItemTextureManager.toObject()`
+
+与 `getItemTextures()` 行为相同，返回当前所有已注册纹理的纯对象表示。
+
+```javascript
+const obj = ItemTextureManager.toObject();
+```
+
+### 自动注册
+
+每次调用 `registerTexture` 或 `registerTextureData` 时，会自动调用 `GRegistry.register("item_texture", "resource", "textures/", this)`，将当前管理器注册到全局注册表中。当执行 `registry.submit()` 时，框架会调用 `toObject()` 获取最终数据并生成 JSON 文件。
+
+---
+
+## TerrainTextureManager
+
+方块纹理管理器，用于注册和管理方块（地形）纹理。API 与 `ItemTextureManager` 完全一致。
+
+### 方法
+
+#### `TerrainTextureManager.registerTexture(name, path)`
+
+注册一个方块纹理。
+
+```javascript
+import { TerrainTextureManager } from "@sapdon/core";
+
+TerrainTextureManager.registerTexture("ruby_block", "textures/blocks/ruby_block");
+TerrainTextureManager.registerTexture("ruby_ore", "textures/blocks/ruby_ore");
+```
+
+#### `TerrainTextureManager.registerTextureData(name, data)`
+
+注册一个带有完整数据结构的方块纹理。
+
+```javascript
+TerrainTextureManager.registerTextureData("sapdon_stone", {
+  textures: "textures/blocks/sapdon_stone"
+});
+```
+
+#### `TerrainTextureManager.getTerrainTextures()`
+
+返回所有已注册的方块纹理键值对对象。
+
+#### `TerrainTextureManager.toObject()`
+
+返回当前所有已注册方块纹理的纯对象表示。
+
+---
+
+## FlipbookTextures
+
+翻书纹理管理器，用于注册动画纹理（逐帧切换的纹理）。它是一个纯对象，不是类。
+
+### 方法
+
+#### `FlipbookTextures.registerFlipbookTexture(atlas_tile, texture, ticks_per_frame, options)`
+
+注册一个翻书纹理。
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `atlas_tile` | `string` | 对应的图块名称，与方块纹理名称对应 |
+| `texture` | `string` | 翻书纹理路径 |
+| `ticks_per_frame` | `number` | 每帧持续的 tick 数（20 ticks = 1 秒） |
+| `options` | `object` | 可选参数，会被合并到纹理对象中 |
+
+可选参数 `options` 包含的字段（对应 Minecraft 的 `flipbook_textures.json`）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `atlas_index` | `number` | 纹理图集中的索引 |
+| `atlas_tile_variant` | `number` | 图块变体 |
+| `replicate` | `number` | 复制次数 |
+| `blend_frames` | `boolean` | 是否混合帧过渡 |
+
+```javascript
+import { FlipbookTextures } from "@sapdon/core";
+
+FlipbookTextures.registerFlipbookTexture(
+  "sapdon_lamp",
+  "textures/blocks/sapdon_lamp_animated",
+  4,
+  { blend_frames: true }
+);
+```
+
+#### `FlipbookTextures.toObject()`
+
+返回翻书纹理数组。
+
+```javascript
+const flipbookData = FlipbookTextures.toObject();
+// 输出: [ { atlas_tile: "sapdon_lamp", flipbook_texture: "textures/blocks/sapdon_lamp_animated", ticks_per_frame: 4, blend_frames: true } ]
+```
+
+---
+
+## 与 GRegistry 的集成
+
+所有纹理管理器在调用注册方法时，会自动调用 `GRegistry.register()` 注册自身。构建时调用 `registry.submit()` 后，框架会遍历注册数据，调用每个管理器的 `toObject()` 方法获取最终 JSON 结构，然后写入对应的资源包文件。
+
+典型流程：
+
+```javascript
+import { ItemTextureManager, TerrainTextureManager, FlipbookTextures } from "@sapdon/core";
+import { registry } from "@sapdon/core";
+
+// 注册纹理
+ItemTextureManager.registerTexture("ruby_ingot", "textures/items/ruby_ingot");
+TerrainTextureManager.registerTexture("ruby_block", "textures/blocks/ruby_block");
+FlipbookTextures.registerFlipbookTexture("ruby_lamp", "textures/blocks/ruby_lamp_anim", 2);
+
+// 提交注册数据，触发 JSON 生成
+registry.submit();
+```
+
+---
+
+## 生成的 JSON 文件
+
+构建完成后，框架会根据注册数据自动生成以下文件到资源包目录：
+
+| 文件名 | 来源 | 示例 |
+|--------|------|------|
+| `textures/item_texture.json` | `ItemTextureManager` | `{ "resource_pack_name": "...", "texture_data": { "ruby_ingot": { "textures": "textures/items/ruby_ingot" } } }` |
+| `textures/terrain_texture.json` | `TerrainTextureManager` | `{ "resource_pack_name": "...", "texture_data": { "ruby_block": { "textures": "textures/blocks/ruby_block" } } }` |
+| `textures/flipbook_textures.json` | `FlipbookTextures` | `[ { "atlas_tile": "ruby_lamp", "flipbook_texture": "textures/blocks/ruby_lamp_anim", "ticks_per_frame": 2 } ]` |

package/doc/user/config/build-config.md

@@ -0,0 +1,83 @@
+# build.config 配置参考
+
+`build.config` 是项目的构建配置文件，位于项目根目录，支持 `//` 和 `/* */` 注释。
+
+## 完整字段
+
+```jsonc
+{
+  "formatVersion": 2,
+  "buildOptions": {
+    "useHMR": true,                       // 是否启用热更新
+    "buildMode": "dev",                   // "dev" | "prod" | "debug"
+    "buildEntry": "main.ts",              // Addon 构建入口文件
+    "useJs": false,                       // 是否使用 JavaScript
+    "scriptEntry": "scripts/main.ts",     // Script API 入口
+    "scriptOutput": "scripts/index.js",   // Script API 输出路径（相对于 buildDir）
+    "buildDir": "dev/",                   // 构建输出目录
+    "dependencies": [
+      {
+        "module_name": "@minecraft/server",
+        "version": "2.0.0"
+      }
+    ],
+    "resource": {
+      "path": "res/",                     // 资源文件目录
+      "resourceHints": true               // 是否生成资源提示文件
+    }
+  },
+  "versionType": "release"                // "release" | "beta"
+}
+```
+
+## 字段说明
+
+### formatVersion
+配置格式版本，当前为 `2`。v1 配置会在读取时自动迁移。
+
+### buildMode
+
+| 值 | 说明 |
+|----|------|
+| `dev` | **完整构建**：运行 `main.ts` → 根据代码生成所有 JSON → 打包脚本 → 同步到 Minecraft 目录。Script API 输出带 sourcemap，不压缩。 |
+| `prod` | **生产构建**：运行 `main.ts` → 生成 JSON → 打包脚本（terser 压缩混淆）→ 同步。不生成 sourcemap。 |
+| `debug` | **仅同步**：跳过 `main.ts` 执行和 JSON 生成，跳过脚本压缩，将已有 `dev/` 目录直接同步到 Minecraft 目录。适合直接编辑 JSON 文件测试时使用。 |
+
+### buildEntry
+构建入口文件路径（相对项目根目录）。文件中的 `registry.submit()` 会将注册数据提交到构建系统。
+
+### scriptEntry / scriptOutput
+- `scriptEntry` — Script API 源码入口，会打包为单个文件
+- `scriptOutput` — 打包后的输出路径，相对于 `buildDir/<name>_BP/`
+
+### buildDir
+构建输出目录，内容结构：
+
+```
+<buildDir>/
+├── <projectName>_BP/      # 行为包
+└── <projectName>_RP/      # 资源包
+```
+
+### dependencies
+manifest.json 中的依赖声明。常见模块：
+
+| 模块名 | 说明 |
+|--------|------|
+| `@minecraft/server` | 核心 Script API |
+| `@minecraft/server-ui` | 表单 UI API |
+| `@minecraft/server-net` | 网络 API |
+| `@minecraft/server-admin` | 管理 API |
+
+### resource
+- `path` — 资源文件夹路径，内容会复制到 RP 根目录
+- `resourceHints` — 设为 `true` 时生成 `res.hint.ts`，提供类型安全的资源引用
+
+### versionType
+
+| 值 | Minecraft 路径 |
+|----|---------------|
+| `release` | `%USERPROFILE%/AppData/Roaming/Minecraft Bedrock/...` |
+| `beta` | `%USERPROFILE%/AppData/Local/Packages/Microsoft.MinecraftWindowsBeta_.../LocalState/...` |
+
+可通过环境变量 `MC_PATH` 或 `MC_BETA_PATH` 覆盖。

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,122 @@
+# 快速入门
+
+## 环境要求
+
+- 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/
+    ├── index.ts         # 脚本入口——注册组件 + 游戏内逻辑
+    └── main.ts          # 游戏主类
+```
+
+## 编写代码
+
+打开 `main.ts`，编写以下代码：
+
+```typescript
+import { ItemAPI, ItemCategory, registry, ItemComponent } from '@sapdon/core'
+
+// 创建一个基础物品
+const item = ItemAPI.createItem(
+  'hello_sapdon:my_item',
+  ItemCategory.Items,
+  'masterball'
+)
+item.addComponent(ItemComponent.setDisplayName('我的物品'))
+
+// 提交所有注册数据
+registry.submit()
+```
+
+## 构建项目
+
+```bash
+cd hello_sapdon
+sapdon build .
+```
+
+### 构建模式
+
+`build.config` 中的 `buildMode` 控制构建行为：
+
+| 模式 | 行为 |
+|------|------|
+| `dev`（默认） | 运行 `main.ts` → 根据代码生成所有 JSON → 打包脚本（不压缩）→ 同步到 Minecraft |
+| `prod` | 运行 `main.ts` → 生成 JSON → 打包脚本（terser 压缩）→ 同步 |
+| `debug` | 跳过 `main.ts`，跳过压缩，直接同步已有 `dev/` 目录到 Minecraft（适合直接编辑 JSON 测试） |
+
+```bash
+# 使用 sapdon compile 以 production 模式构建（不启动热更新）
+sapdon compile
+```
+
+### 打包为 .mcaddon
+
+构建完成后，可将输出打包为 `.mcaddon` 文件，方便分发：
+
+```bash
+sapdon pack
+```
+
+输出文件：`dev/<项目名>.mcaddon`
+
+## 构建输出
+
+构建完成后，`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) — 学习创建方块
+- [指南书教程](./tutorials/neo-guidebook.md) — API 用法
+- [指南书实战经验](./tutorials/neo-guidebook-experience.md) — 接入流程与踩坑清单
+- [API 参考](./api/item.md) — 完整的 API 文档