sapdon 3.2.2 → 3.3.3

package/doc/user/api/recipe.md

@@ -0,0 +1,427 @@
+# 配方系统 API 参考
+
+---
+
+## RecipeAPI
+
+工厂函数集合，用于创建各类配方并自动注册到游戏系统。
+
+```typescript
+import { RecipeAPI, registry } from '@sapdon/core'
+```
+
+所有注册器方法均返回配方实例，支持链式调用。完成后调用 `registry.submit()` 提交数据。
+
+---
+
+### registerSimpleFurnace
+
+快速创建熔炉配方（自动设置 `furnace` 标签）。
+
+```typescript
+RecipeAPI.registerSimpleFurnace(
+  identifier: string,
+  output: string,
+  input: string
+): AddonRecipeFurnace
+```
+
+**示例**
+
+```typescript
+RecipeAPI.registerSimpleFurnace('sapdon:smelt_ore', 'minecraft:iron_ingot', 'minecraft:iron_ore')
+```
+
+---
+
+### registerFurnace
+
+创建熔炉配方实例，返回 `AddonRecipeFurnace` 用于链式配置。
+
+```typescript
+RecipeAPI.registerFurnace(identifier: string): AddonRecipeFurnace
+```
+
+**示例**
+
+```typescript
+RecipeAPI.registerFurnace('sapdon:smelt_gold')
+  .input('minecraft:gold_ore', 0, 1)
+  .output('minecraft:gold_ingot')
+  .tags(['furnace'])
+```
+
+---
+
+### registerSimpleShaped
+
+快速创建有序工作台配方（自动设置 `crafting_table` 标签）。
+
+```typescript
+RecipeAPI.registerSimpleShaped(
+  identifier: string,
+  output: string,
+  pattern: string[],
+  key: Record<string, any>
+): AddonRecipeShaped
+```
+
+**示例**
+
+```typescript
+RecipeAPI.registerSimpleShaped(
+  'sapdon:sword',
+  'sapdon:sword',
+  [' X ', ' X ', ' Y '],
+  { X: { item: 'minecraft:iron_ingot' }, Y: { item: 'minecraft:stick' } }
+)
+```
+
+---
+
+### registerShaped
+
+创建有序配方实例，返回 `AddonRecipeShaped` 用于链式配置。
+
+```typescript
+RecipeAPI.registerShaped(identifier: string): AddonRecipeShaped
+```
+
+**示例**
+
+```typescript
+RecipeAPI.registerShaped('sapdon:armor')
+  .key({ X: { item: 'minecraft:diamond' } })
+  .pattern(['XXX', 'X X', '   '])
+  .output({ item: 'sapdon:armor', count: 1 })
+  .tags(['crafting_table'])
+```
+
+---
+
+### registerSimpleShapeless
+
+快速创建无序工作台配方（自动设置 `crafting_table` 标签）。
+
+```typescript
+RecipeAPI.registerSimpleShapeless(
+  identifier: string,
+  output: string,
+  ingredients: any[]
+): AddonRecipeShapeless
+```
+
+**示例**
+
+```typescript
+RecipeAPI.registerSimpleShapeless(
+  'sapdon:alloy',
+  'sapdon:alloy_ingot',
+  [{ item: 'minecraft:iron_ingot' }, { item: 'minecraft:gold_ingot' }]
+)
+```
+
+---
+
+### registerShapeless
+
+创建无序配方实例，返回 `AddonRecipeShapeless` 用于链式配置。
+
+```typescript
+RecipeAPI.registerShapeless(identifier: string): AddonRecipeShapeless
+```
+
+**示例**
+
+```typescript
+RecipeAPI.registerShapeless('sapdon:mixture')
+  .ingredients([{ item: 'minecraft:diamond' }, { item: 'minecraft:emerald' }])
+  .output({ item: 'sapdon:mixture', count: 2 })
+  .tags(['crafting_table'])
+```
+
+---
+
+## AddonRecipe 基类
+
+所有配方类型继承自 `AddonRecipe`。
+
+```typescript
+import { AddonRecipe } from '@sapdon/core'
+```
+
+### 方法
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `identifier(id: string)` | `this` | 设置配方标识符 |
+| `tags(tags: string[])` | `this` | 设置配方标签数组（覆盖） |
+| `getId(): string` | `string` | 获取配方标识符 |
+
+---
+
+## AddonRecipeShaped
+
+有序配方类，继承自 `AddonRecipe`。
+
+```typescript
+import { AddonRecipeShaped } from '@sapdon/core'
+```
+
+### 方法
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `assumeSymmetry(): void` | 无 | 启用对称假设，未定义键的字符自动视为相同 |
+| `key(key: Record<string, any>)` | `this` | 设置字符到物品的键映射 |
+| `pattern(pattern: string[])` | `this` | 设置 3 行图案数组 |
+| `priority(priority: number)` | `this` | 设置优先级（数值越小优先级越高） |
+| `output(item: string \| object)` | `this` | 设置输出，支持字符串或 `{ item, count }` |
+| `tags(tags: string[])` | `this` | 继承自 `AddonRecipe`，设置配方标签 |
+
+**示例**
+
+```typescript
+const recipe = new AddonRecipeShaped_1_20()
+recipe
+  .identifier('sapdon:example')
+  .key({ A: { item: 'minecraft:iron_ingot' } })
+  .pattern(['AAA', 'A A', 'AAA'])
+  .output({ item: 'sapdon:example', count: 8 })
+  .assumeSymmetry()
+  .tags(['crafting_table'])
+```
+
+### 版本化类
+
+| 类 | format_version |
+|------|------|
+| `AddonRecipeShaped_1_12` | `1.12` |
+| `AddonRecipeShaped_1_17` | `1.17` |
+| `AddonRecipeShaped_1_19` | `1.19` |
+| `AddonRecipeShaped_1_20` | `1.20` |
+
+---
+
+## AddonRecipeShapeless
+
+无序配方类，继承自 `AddonRecipe`。
+
+```typescript
+import { AddonRecipeShapeless } from '@sapdon/core'
+```
+
+### 方法
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `static create(ver, def)` | `AddonRecipeShapeless` | 静态工厂方法 |
+| `priority(priority: number)` | `this` | 设置优先级 |
+| `ingredients(ingredients: any[])` | `this` | 设置原料数组 |
+| `output(item: string \| object)` | `this` | 设置输出，支持字符串或 `{ item, count }` |
+| `tags(tags: string[])` | `this` | 继承自 `AddonRecipe`，设置配方标签 |
+
+**示例**
+
+```typescript
+const recipe = new AddonRecipeShapeless_1_17()
+recipe
+  .identifier('sapdon:example')
+  .ingredients([
+    { item: 'minecraft:iron_ingot' },
+    { tag: 'minecraft:planks' }
+  ])
+  .output({ item: 'sapdon:example', count: 4 })
+  .tags(['crafting_table'])
+```
+
+### 版本化类
+
+| 类 | format_version |
+|------|------|
+| `AddonRecipeShapeless_1_12` | `1.12` |
+| `AddonRecipeShapeless_1_17` | `1.17` |
+
+---
+
+## AddonRecipeFurnace
+
+熔炉配方类，继承自 `AddonRecipe`。
+
+```typescript
+import { AddonRecipeFurnace } from '@sapdon/core'
+```
+
+### 方法
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `static create(ver, def)` | `AddonRecipeFurnace` | 静态工厂方法 |
+| `input(item: string, data?, count?)` | `this` | 设置输入物品，可选副损伤值(data)和数量 |
+| `output(item: string)` | `this` | 设置输出物品 |
+| `tags(tags: string[])` | `this` | 继承自 `AddonRecipe`，设置配方标签 |
+
+**示例**
+
+```typescript
+const recipe = new AddonRecipeFurnace_1_17()
+recipe
+  .identifier('sapdon:smelt_ore')
+  .input('minecraft:iron_ore', 0)
+  .output('minecraft:iron_ingot')
+  .tags(['furnace'])
+```
+
+### 版本化类
+
+| 类 | format_version |
+|------|------|
+| `AddonRecipeFurnace_1_12` | `1.12` |
+| `AddonRecipeFurnace_1_17` | `1.17` |
+
+---
+
+## RecipeTags
+
+配方标签常量，用于指定配方适用的方块。
+
+```typescript
+import { RecipeTags } from '@sapdon/core'
+```
+
+| 常量 | 值 | 说明 |
+|------|-----|------|
+| `RecipeTags.Furnace` | `"furnace"` | 熔炉配方 |
+| `RecipeTags.smoker` | `"smoker"` | 烟熏炉配方 |
+| `RecipeTags.Campfire` | `"campfire"` | 篝火烹饪配方 |
+| `RecipeTags.SoulCampfire` | `"soul_campfire"` | 灵魂篝火烹饪配方 |
+| `RecipeTags.CraftingTable` | `"crafting_table"` | 工作台合成配方 |
+
+> 注意：`RecipeTags.smoker` 首字母小写，与其余常量命名不一致。
+
+**示例**
+
+```typescript
+// 同时适用于熔炉和烟熏炉
+recipe.tags([RecipeTags.Furnace, RecipeTags.smoker])
+```
+
+---
+
+## RecipeInputTags
+
+物品输入标签常量，用于原料的 `tag` 字段实现宽匹配。
+
+```typescript
+import { RecipeInputTags } from '@sapdon/core'
+```
+
+| 常量 | 值 | 说明 |
+|------|-----|------|
+| `RecipeInputTags.Armor` | `"minecraft:is_armor"` | 盔甲类物品 |
+| `RecipeInputTags.Arrows` | `"minecraft:arrow"` | 箭 |
+| `RecipeInputTags.Banners` | `"minecraft:banner"` | 旗帜 |
+| `RecipeInputTags.Boats` | `"minecraft:boats"` | 船 |
+| `RecipeInputTags.BookshelfBooks` | `"minecraft:bookshelf_books"` | 书架用书 |
+| `RecipeInputTags.ChainmailTier` | `"minecraft:chainmail_tier"` | 锁链级装备 |
+| `RecipeInputTags.ChestBoat` | `"minecraft:chest_boat"` | 带箱子的船 |
+| `RecipeInputTags.Coals` | `"minecraft:coals"` | 煤炭类 |
+| `RecipeInputTags.Cooked` | `"minecraft:is_cooked"` | 已烹饪食物 |
+| `RecipeInputTags.CrimsonStems` | `"minecraft:crimson_stems"` | 绯红菌柄 |
+| `RecipeInputTags.DiamondTier` | `"minecraft:diamond_tier"` | 钻石级装备 |
+| `RecipeInputTags.Digger` | `"minecraft:digger"` | 挖掘工具 |
+| `RecipeInputTags.Door` | `"minecraft:door"` | 门 |
+| `RecipeInputTags.Fish` | `"minecraft:is_fish"` | 鱼类 |
+| `RecipeInputTags.Food` | `"minecraft:is_food"` | 食物类 |
+| `RecipeInputTags.GoldenTier` | `"minecraft:golden_tier"` | 金质装备 |
+| `RecipeInputTags.HangingActor` | `"minecraft:hanging_actor"` | 悬挂实体 |
+| `RecipeInputTags.HangingSign` | `"minecraft:hanging_sign"` | 悬挂告示牌 |
+| `RecipeInputTags.Hatchet` | `"minecraft:is_axe"` | 斧 |
+| `RecipeInputTags.Hoe` | `"minecraft:is_hoe"` | 锄 |
+| `RecipeInputTags.HorseArmor` | `"minecraft:horse_armor"` | 马铠 |
+| `RecipeInputTags.IronTier` | `"minecraft:iron_tier"` | 铁质装备 |
+| `RecipeInputTags.LeatherTier` | `"minecraft:leather_tier"` | 皮革装备 |
+| `RecipeInputTags.LecternBooks` | `"minecraft:lectern_books"` | 讲台用书 |
+| `RecipeInputTags.Logs` | `"minecraft:logs"` | 原木类 |
+| `RecipeInputTags.LogsThatBurn` | `"minecraft:logs_that_burn"` | 可燃原木 |
+| `RecipeInputTags.MangroveLogs` | `"minecraft:mangrove_logs"` | 红树木 |
+| `RecipeInputTags.Meat` | `"minecraft:is_meat"` | 肉类 |
+| `RecipeInputTags.Minecart` | `"minecraft:is_minecart"` | 矿车 |
+| `RecipeInputTags.MusicDiscs` | `"minecraft:music_disc"` | 唱片 |
+| `RecipeInputTags.NetheriteTier` | `"minecraft:netherite_tier"` | 下界合金级装备 |
+| `RecipeInputTags.Pickaxe` | `"minecraft:is_pickaxe"` | 镐 |
+| `RecipeInputTags.PiglinLoved` | `"minecraft:piglin_loved"` | 猪灵喜爱物品 |
+| `RecipeInputTags.PiglinRepellents` | `"minecraft:piglin_repellents"` | 猪灵驱退物品 |
+| `RecipeInputTags.Planks` | `"minecraft:planks"` | 木板 |
+| `RecipeInputTags.Sand` | `"minecraft:sand"` | 沙子 |
+| `RecipeInputTags.Shovel` | `"minecraft:is_shovel"` | 锹 |
+| `RecipeInputTags.Sign` | `"minecraft:sign"` | 告示牌 |
+| `RecipeInputTags.SoulFireBaseBlocks` | `"minecraft:soul_fire_base_blocks"` | 灵魂火基底 |
+| `RecipeInputTags.SpawnEgg` | `"minecraft:spawn_egg"` | 刷怪蛋 |
+| `RecipeInputTags.StoneBricks` | `"minecraft:stone_bricks"` | 石砖 |
+| `RecipeInputTags.StoneCraftingMaterials` | `"minecraft:stone_crafting_materials"` | 石质合成材料 |
+| `RecipeInputTags.StoneTier` | `"minecraft:stone_tier"` | 石质装备 |
+| `RecipeInputTags.StoneToolMaterials` | `"minecraft:stone_tool_materials"` | 石质工具材料 |
+| `RecipeInputTags.Sword` | `"minecraft:is_sword"` | 剑 |
+| `RecipeInputTags.Tool` | `"minecraft:is_tool"` | 工具 |
+| `RecipeInputTags.VibrationDamper` | `"minecraft:vibration_damper"` | 振动阻尼 |
+| `RecipeInputTags.WarpedStems` | `"minecraft:warped_stems"` | 诡异菌柄 |
+| `RecipeInputTags.WoodenSlabs` | `"minecraft:wooden_slabs"` | 木台阶 |
+| `RecipeInputTags.WoodenTier` | `"minecraft:wooden_tier"` | 木质装备 |
+| `RecipeInputTags.Wool` | `"minecraft:wool"` | 羊毛 |
+
+**示例**
+
+```typescript
+import { RecipeAPI, registry, RecipeInputTags } from '@sapdon/core'
+
+// 使用标签匹配所有木板
+RecipeAPI.registerShapeless('sapdon:framed_plank')
+  .ingredients([
+    { tag: RecipeInputTags.Planks },
+    { tag: RecipeInputTags.Planks },
+    { tag: RecipeInputTags.Planks }
+  ])
+  .output('sapdon:framed_plank')
+  .tags(['crafting_table'])
+```
+
+---
+
+## 类型汇总
+
+```typescript
+// 工厂
+RecipeAPI.registerSimpleFurnace(id, output, input)
+RecipeAPI.registerFurnace(id)
+RecipeAPI.registerSimpleShaped(id, output, pattern, key)
+RecipeAPI.registerShaped(id)
+RecipeAPI.registerSimpleShapeless(id, output, ingredients)
+RecipeAPI.registerShapeless(id)
+
+// 有序配方
+class AddonRecipeShaped extends AddonRecipe
+  assumeSymmetry(): void
+  key(map): this
+  pattern(rows): this
+  priority(num): this
+  output(item): this
+  tags(tags[]): this  // 继承
+
+// 无序配方
+class AddonRecipeShapeless extends AddonRecipe
+  priority(num): this
+  ingredients(items): this
+  output(item): this
+  tags(tags[]): this  // 继承
+
+// 熔炉配方
+class AddonRecipeFurnace extends AddonRecipe
+  input(item, data?, count?): this
+  output(item): this
+  tags(tags[]): this  // 继承
+
+// 标签常量
+RecipeTags = { Furnace, smoker, Campfire, SoulCampfire, CraftingTable }
+RecipeInputTags = { Armor, Food, Logs, Planks, ... }
+```

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,84 @@
+# build.config 配置参考
+
+`build.config` 是项目的构建配置文件，位于项目根目录，支持 `//` 和 `/* */` 注释。
+
+## 完整字段
+
+```jsonc
+{
+  "formatVersion": 2,
+  "buildOptions": {
+    "useHMR": true,                       // 是否启用热更新
+    "buildMode": "development",           // "development" | "production"
+    "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
+
+| 值 | 说明 |
+|----|------|
+| `development` | **完整构建**：运行 `main.ts` → 根据代码生成所有 JSON → 打包脚本 → 同步到 Minecraft 目录。Script API 输出带 sourcemap，不压缩。 |
+| `production` | **仅同步**：跳过 `main.ts` 执行和 JSON 生成，将已有 `dev/` 目录直接同步到 Minecraft 目录。适合直接编辑 JSON 文件测试时使用。 |
+
+> 注意：`production` 模式不会运行 `main.ts`，也不会生成物品/实体/方块/配方的 JSON 文件。确保 `dev/` 目录已有正确的 JSON 文件（通常从一次 `development` 构建中获得）。
+
+### 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` 覆盖。