sapdon 3.3.3 → 3.4.0

package/doc/user/api/neo-guidebook.md

@@ -0,0 +1,409 @@
+# NeoGuidebook API 参考
+
+NeoGuidebook 是基于 Minecraft Bedrock JSON UI 体系的指南书生成框架。使用链式 API 声明式构建页面，构建时自动序列化为 JSON UI，运行时通过 ActionFormData 触发显示。
+
+---
+
+## 目录
+
+1. [概览](#1-概览)
+2. [NeoGuidebook 类](#2-neoguidebook-类)
+3. [NeoGuidebookPage 类](#3-neoguidebookpage-类)
+4. [NeoGuidebookBridge 类](#4-neoguidebookbridge-类)
+5. [ItemComponent 辅助](#5-itemcomponent-辅助)
+6. [page_ids.json 生成](#6-page_idsjson-生成)
+7. [运行时注册](#7-运行时注册)
+
+---
+
+## 1. 概览
+
+### 工作流程
+
+```
+构建时 (main.ts)                     运行时 (index.ts)
+─────────────────                   ─────────────────
+ItemAPI.createItem()                system.beforeEvents.startup
+  + setCustomComponentV2()            → registerCustomComponent()
+  + setMaxStackSize()                 → onUse(event, params)
+  + setDisplayName()                    → ActionFormData
+  + setInteractButton()                   .title("sapdon_ui:book_name")
+                                         .body("page_id")
+NeoGuidebook("ns:name")               → 按钮 .button("prev_button")
+  + addDoublePageStack(id, L, R)        .show(player)
+  + addSinglePageStack(id, P)
+  + addCustomButton(config)           NeoGuidebookBridge
+                                     → 上一页/下一页/首页/章节跳转
+registry.submit()
+→ neo_guidebook.json                 page_ids.json
+→ server_form.json                   供 Bridge 获取页面列表
+→ page_ids.json
+```
+
+### 脚本 ↔ JSON UI 绑定
+
+| ActionForm API | JSON UI 变量 | 说明 |
+|----------------|-------------|------|
+| `.title("sapdon_ui:name")` | `#title_text` | `sapdon_ui:` 前缀路由（SapdonServerUI），精确匹配 `$panel_id` |
+| `.body("page_id")` | `#form_text` | 切换可见页面（匹配页面的 `$binding_text`） |
+| `.button("text")` | `#form_button_text` | 匹配按钮的 `$binding_button_text`，控制哪个按钮 visible |
+
+> NeoGuidebook 已迁移到新接口：注册走 `SapdonServerUI.registerPage`（`panelId = sapdon_ui:<name>`），书拆为 `内容面板 + 按键面板`，导航/章节按钮使用 `SapdonTexturedButton`（模板 `server_form.sapdon_textured_button`），不再依赖旧 `ServerUISystem`/`sapdon_form_button_factory`。
+
+---
+
+## 2. NeoGuidebook 类
+
+用于创建指南书 UI 系统。
+
+```typescript
+import { NeoGuidebook } from '@sapdon/core'
+
+const book = new NeoGuidebook(identifier, path, size?, options?)
+```
+
+### 构造参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `identifier` | `string` | 是 | — | 格式 `"命名空间:名称"`，如 `"my_mod:guidebook"` |
+| `path` | `string` | 是 | — | UI 文件路径，通常 `"ui/"` |
+| `size` | `[number, number]` | 否 | `[320, 207]` | 面板像素尺寸 |
+| `options` | `object` | 否 | `{}` | 可选配置（见下文） |
+
+### options 配置项
+
+```typescript
+{
+    debug?: boolean                  // 是否输出调试信息
+    buttons?: {
+        prev?: { visible: boolean }  // 上一页按钮
+        next?: { visible: boolean }  // 下一页按钮
+        home?: { visible: boolean }  // 首页按钮
+        close?: { visible: boolean } // 关闭按钮
+    }
+    textures?: {
+        prevDefault?: string         // 上一页默认纹理
+        prevHover?: string           // 上一页悬停纹理
+        prevPressed?: string         // 上一页按压纹理
+        nextDefault?: string         // 下一页默认纹理
+        nextHover?: string           // 下一页悬停纹理
+        nextPressed?: string         // 下一页按压纹理
+        homeDefault?: string         // 首页默认纹理
+        homeHover?: string           // 首页悬停纹理
+        homePressed?: string         // 首页按压纹理
+    }
+}
+```
+
+### 方法
+
+#### addDoublePageStack(page_id, left_page, right_page)
+
+注册一个双页跨页（左右两页同时显示）。
+
+```typescript
+book.addDoublePageStack(
+    'page_index0',          // page_id: string — 唯一标识，用于 body() 跳转
+    leftPanel,              // left_page: Panel — NeoGuidebookPage.getPanel()
+    rightPanel,             // right_page: Panel
+    size?: [string, string] // 可选，左右比例，默认 ["50%","50%"]
+)
+```
+
+#### addSinglePageStack(page_id, page)
+
+注册一个单页（占满整个表单宽度）。
+
+```typescript
+book.addSinglePageStack(
+    'page_index7',          // page_id: string
+    pagePanel,              // page: Panel
+    size?: [string, string] // 可选尺寸
+)
+```
+
+#### addCustomButton(config)
+
+添加自定义按钮。
+
+```typescript
+book.addCustomButton({
+    id: 'my_button',                 // 按钮 ID
+    defaultTexture: 'textures/ui/...',
+    hoverTexture?: 'textures/ui/...',
+    pressedTexture?: 'textures/ui/...',
+    anchorFrom?: 'bottom_left',       // 锚点
+    anchorTo?: 'bottom_left',
+    offset?: [number, number],
+    size?: [number | string, number | string]
+})
+```
+
+#### getPageIds()
+
+获取所有已注册页面的 ID 数组。
+
+```typescript
+const ids: string[] = book.getPageIds()
+// → ["page_index0", "page_index1", ...]
+```
+
+#### getPageCount()
+
+获取页面总数。
+
+```typescript
+const count: number = book.getPageCount()
+```
+
+---
+
+## 3. NeoGuidebookPage 类
+
+用于构建单个页面的内容。
+
+```typescript
+import { NeoGuidebookPage } from '@sapdon/core'
+
+const page = new NeoGuidebookPage(id, size?)
+```
+
+### 构造参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `id` | `string` | 是 | — | 页面唯一 ID |
+| `size` | `[string, string]` | 否 | `["100%","100%"]` | 页面尺寸，百分比格式 |
+
+### 布局方法
+
+所有方法返回 `this`，支持链式调用。
+
+#### addBookText(text, size?)
+
+```typescript
+page.addBookText(
+    '这是正文内容',           // text: string
+    ['100%', '70%']          // size?: [string, string]
+)
+```
+
+#### addCategoryTitle(title, size?)
+
+```typescript
+page.addCategoryTitle(
+    '架构概述',               // title: string
+    ['100%', '15%']          // size?: [string, string]
+)
+```
+
+#### addBookTitleBar(text, size?)
+
+```typescript
+page.addBookTitleBar(
+    '欢迎使用手册',           // text: string
+    ['100%', '15%']          // size?: [string, string]
+)
+```
+
+#### addEmptySpace(size?)
+
+```typescript
+page.addEmptySpace(['100%', '5%'])
+```
+
+#### addDivider(size?)
+
+```typescript
+page.addDivider(['100%', '3%'])
+```
+
+#### addRecipeGrid(row, col, items, size?)
+
+```typescript
+page.addRecipeGrid(
+    2,                                   // row: number
+    3,                                   // col: number
+    ['textures/items/iron_ingot', ...],  // items: string[]
+    ['100%', '30%']                      // size?: [string, string]
+)
+```
+
+#### addBookCategory(title, row, col, buttons, size?)
+
+```typescript
+page.addBookCategory(
+    '物品分类',                           // title: string
+    2,                                   // row: number
+    3,                                   // col: number
+    [{ id: 'tools', texture: '...' }],  // buttons
+    ['100%', '60%']                      // size?: [string, string]
+)
+```
+
+#### addChapter(name, texture)
+
+```typescript
+page.addChapter('架构概述', 'textures/items/map')
+```
+
+#### addChapters(chapters)
+
+```typescript
+page.addChapters([
+    { chapter_name: '架构概述', chapter_texture: 'textures/items/map' },
+    { chapter_name: '核心类',   chapter_texture: 'textures/items/iron_ingot' },
+])
+```
+
+#### addControl(control)
+
+添加任意自定义 UI 控件（透传内部 StackPanel，可放任何 `UIElement` 或原生 JSON 控件对象）。
+
+```typescript
+page.addControl(
+    new Label('my_label', undefined)
+        .setText(new Text().setText('自定义文字').setColor([0, 0, 0]))
+)
+```
+
+#### addStack(size, control, debug?)
+
+添加自定义控件并指定占位尺寸（透传 `StackPanel.addStack`）。
+
+```typescript
+page.addStack(
+    ['100%', '20%'],
+    new Image('my_img', undefined).setSprite(new Sprite().setTexture('textures/items/iron_ingot'))
+)
+```
+
+#### buildChapterList(prefix?)
+
+```typescript
+page.buildChapterList()          // 默认前缀 "item"，生成 item_N_button
+page.buildChapterList("sub")     // 多级目录：生成 sub_N_button，避免按钮 id 全局冲突
+```
+
+`prefix` 决定目录按钮的绑定键名：`${prefix}_${index}_button`。单本书只有一个目录页时用默认值；要加子目录/二级目录，不同级别传不同前缀。
+
+#### getPanel()
+
+```typescript
+const panel = page.getPanel()
+book.addDoublePageStack('page_0', panel, rightPanel)
+```
+
+#### clear()
+
+```typescript
+page.clear()
+```
+
+---
+
+## 4. NeoGuidebookBridge 类
+
+运行时导航管理器，封装了 ActionFormData 的显示和页面切换逻辑。
+
+```typescript
+import { NeoGuidebookBridge } from '<path>/page_bridge'
+
+const bridge = new NeoGuidebookBridge(uiName, pageIds, options?)
+```
+
+### 构造参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `uiName` | `string` | 是 | 书名字，必须与 `title()` 一致 |
+| `pageIds` | `string[]` | 是 | 页面 ID 列表，来自 `getPageIds()` |
+| `options` | `object` | 否 | `{ debug: boolean }` |
+
+### 方法
+
+#### show(player, startIndex)
+
+```typescript
+bridge.show(player, 0)  // player: Player, startIndex: number
+```
+
+#### onPage(pageId, callbacks)
+
+```typescript
+bridge.onPage('page_index0', {
+    onEnter: (pageId: string, index: number) => { /* 进入页面时调用 */ },
+    onLeave: (pageId: string, index: number) => { /* 离开页面时调用 */ },
+})
+```
+
+### 内置按钮映射
+
+| ActionForm 按钮文字 | 对应 JSON UI 控件 | 行为 |
+|-------------------|------------------|------|
+| `"prev_button"` | 上一页按钮 | `currentIndex--` |
+| `"next_button"` | 下一页按钮 | `currentIndex++` |
+| `"home_button"` | 首页按钮 | `currentIndex = 0` |
+| `"item_X_button"` | 章节选择按钮 | `currentIndex = X+1` |
+
+---
+
+## 5. ItemComponent 辅助
+
+```typescript
+import { ItemComponent } from '@sapdon/core'
+
+// 设置自定义物品组件（指南书的核心）
+ItemComponent.setCustomComponentV2('sapdon:neo_guibook', {})
+
+// 其他物品组件
+ItemComponent.setMaxStackSize(1)
+ItemComponent.setDisplayName('我的手册')
+ItemComponent.setInteractButton('打开')
+```
+
+### setCustomComponentV2(componentName, options)
+
+参数 `componentName` 必须与运行时 `registerCustomComponent()` 注册的名字一致。这个值也会出现在物品 JSON 的 `components` 中。
+
+---
+
+## 6. page_ids.json 生成
+
+`main.ts` 中调用 `getPageIds()` 后将结果写入文件，供运行时脚本使用：
+
+```typescript
+const pageIds: string[] = neo_guidebook.getPageIds()
+fs.writeFileSync(
+    path.join(process.cwd(), 'scripts', 'page_ids.json'),
+    JSON.stringify(pageIds, null, 2)
+)
+```
+
+生成的 `page_ids.json` 示例：
+
+```json
+["page_index0", "page_index1", "page_index2", "page_index3"]
+```
+
+---
+
+## 7. 运行时注册
+
+```typescript
+// registry.ts — v2 API
+import { system, world } from "@minecraft/server"
+import { GuiBookItemComponent } from "./items/gui_book"
+
+let registered = false
+
+system.beforeEvents.startup.subscribe((initEvent: StartupEvent) => {
+    if (registered) return
+    registered = true
+    initEvent.itemComponentRegistry.registerCustomComponent(
+        "sapdon:neo_guibook",
+        GuiBookItemComponent
+    )
+})
+```

package/doc/user/api/sapdon-ui.md

@@ -0,0 +1,185 @@
+# Sapdon UI 页面壳系统 API 参考
+
+Sapdon UI 是一套「sapdon_ui: 前缀标题路由 + 页面壳」的自定义 Server Form UI 系统。它用 TypeScript 声明式生成 `server_form.json` 路由结构与每个页面的独立 UI 文件，运行时通过 `ActionFormData` 的 title 前缀自动分流：`sapdon_ui:` 开头的标题渲染自定义全屏 UI，其它标题走原版原生表单。
+
+---
+
+## 目录
+
+1. [架构总览](#1-架构总览)
+2. [SapdonServerUI 类](#2-sapdonserverui-类)
+3. [SapdonPanel 类](#3-sapdonpanel-类)
+4. [SapdonButtonPanel 类](#4-sapdonbuttonpanel-类)
+5. [SapdonButton 类](#5-sapdonbutton-类)
+6. [运行时触发](#6-运行时触发)
+7. [已知注意点](#7-已知注意点)
+
+---
+
+## 1. 架构总览
+
+### 生成的文件（`registry.submit()` 后）
+
+| 文件 | 内容 |
+|------|------|
+| `ui/server_form.json` | 路由壳：屏幕、native/自定义分流、页面壳 `custom_panel_content`、按钮模板 `form_button` |
+| `ui/sapdon_ui_xxx.json` | 每个页面一个独立文件（内容面板 + 按键面板） |
+| `ui/_ui_defs.json` | 自动登记所有 UI 文件 |
+
+### 路由结构
+
+```
+third_party_server_screen@common.base_screen   (type: screen)
+└─ $screen_content = custom_full_screen
+   ├─ native_form@main_screen_content
+   │     visible = title 不含 'sapdon_ui:'
+   └─ sapdon_custom_full@sapdon_screen_content
+         visible = title 含 'sapdon_ui:'
+         └─ (每个注册页) @custom_panel_content   ← $panel_id 精确匹配 title
+              ├─ content@$user_content_panel    (下)
+              └─ buttons@$user_buttons_panel    (上, 后绘制覆盖)
+```
+
+### 脚本 ↔ JSON UI 绑定
+
+| ActionForm API | JSON UI 变量 | 说明 |
+|----------------|-------------|------|
+| `.title("sapdon_ui:xxx")` | `#title_text` | 前缀 `sapdon_ui:` = 自定义；`$panel_id` 精确匹配页面 |
+| `.button("text")` | `#form_button_*` | 集合 `form_buttons`，网格按放置顺序绑定各按钮数据 |
+
+---
+
+## 2. SapdonServerUI 类
+
+负责生成 `server_form.json` 的完整路由壳（屏幕、分流、页面壳、form_button 模板），并提供页面注册入口。
+
+```typescript
+import { SapdonServerUI } from '@sapdon/core'
+
+SapdonServerUI.registerPage({
+    panelId: "sapdon_ui:apple",          // title 精确匹配值（必须 sapdon_ui: 前缀）
+    name: "apple",                        // 页面控件名（默认 pageN）
+    contentPanel: "sapdon_ui_apple.apple_content_panel",  // 内容面板引用
+    buttonsPanel: "sapdon_ui_apple.apple_buttons_panel",  // 按键面板引用（可选）
+})
+```
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `panelId` | `string` | ✅ | 触发此页的 ActionForm title（须含 `sapdon_ui:` 前缀） |
+| `contentPanel` | `UIElement \| string` | ✅ | 内容面板元素或 `ns.name` 引用 |
+| `buttonsPanel` | `UIElement \| string` | ❌ | 按键面板元素或引用（壳固定渲染，缺省会报引用缺失，纯内容页请传空面板） |
+| `name` | `string` | ❌ | 注册在 `sapdon_screen_content` 里的控件名 |
+
+### 自动生成的内容
+
+- `third_party_server_screen@common.base_screen`：`$screen_content` 指向 `custom_full_screen`，附带退出动画抑制与 `menu_cancel → menu_exit` 映射。
+- `custom_full_screen`：`native_form`（`((#title_text - 'sapdon_ui:') = #title_text)` → 非自定义显示）与 `sapdon_screen_content`（取反）分流。
+- `sapdon_screen_content`：`sapdon_ui:` 前缀可见，承载所有注册页。
+- `custom_panel_content`：通用页面壳，`(#title_text = $panel_id)` 精确匹配，内容(下)+按键(上)两块。
+- `form_button@common_buttons.light_text_button`：框架固定提供的表单按钮模板（16×16，集合绑定 `form_buttons`）。
+
+---
+
+## 3. SapdonPanel 类
+
+每个页面一个独立 UI 文件。把「内容面板 + 按键面板」组装进该页面的命名空间。
+
+```typescript
+import { SapdonPanel } from '@sapdon/core'
+
+new SapdonPanel("sapdon_ui_apple")      // 生成 ui/sapdon_ui_apple.json (ns: sapdon_ui_apple)
+    .setContent(contentPanel)            // 内容面板 UIElement
+    .setButtons(buttonsPanel)            // 按键面板 UIElement
+    .build()
+```
+
+| 方法 | 说明 |
+|------|------|
+| `setContent(panel)` | 设置内容面板元素（必须是 UIElement，其 id 即 `ns.xxx` 引用名） |
+| `setButtons(panel)` | 设置按键面板元素 |
+| `build()` | 返回生成的 `UISystem` |
+
+> 页面的内容/按键面板元素 id 会作为 `registerPage` 里 `contentPanel`/`buttonsPanel` 的引用名，例如 `new Panel("apple_content_panel")` → `"sapdon_ui_apple.apple_content_panel"`。
+
+---
+
+## 4. SapdonButtonPanel 类
+
+构建按键网格面板（grid）。网格通过 `collection_name: form_buttons` 提供每项数据上下文，`place()` 把按钮按 `grid_position` 摆到指定格（内部即 pos_wrap：面板包裹 + `grid_position`）。
+
+```typescript
+import { SapdonButtonPanel, SapdonButton } from '@sapdon/core'
+
+const buttons = new SapdonButtonPanel("apple_buttons_panel")
+    .setDimensions([2, 1])                       // [列, 行]
+    .setCollection("form_buttons")               // 注入表单按钮集合
+    .setSize(["100%", "100%"])
+    .place([0, 0], new SapdonButton("bt0").setAnchor("bottom_left"))
+    .place([1, 0], new SapdonButton("bt1").setAnchor("bottom_right"))
+    .build()
+```
+
+| 方法 | 说明 |
+|------|------|
+| `setDimensions([cols, rows])` | 网格尺寸（**列 × 行**） |
+| `setCollection(name)` | 注入集合（表单场景固定 `form_buttons`） |
+| `setSize(size)` | 网格尺寸 |
+| `place([col, row], element)` | 摆一个按钮/控件到指定格（自动包一层 pos_wrap） |
+| `build()` | 返回 `Grid` |
+
+> **布局技巧**：`grid_dimensions [2,1]` 把面板切成左右两份；格子内控件默认左上对齐，改锚点 `bottom_left` / `bottom_right` / `top_right` 即可把按钮贴到对应角。
+
+---
+
+## 5. SapdonButton 类
+
+表单按钮的封装：默认模板固定为 `server_form.form_button`（吃 `form_buttons` 集合数据），无需手写模板引用。
+
+```typescript
+import { SapdonButton } from '@sapdon/core'
+
+new SapdonButton("bt0")                 // → bt0@server_form.form_button
+    .setAnchor("bottom_left")           // 锚点对齐，默认 32×32
+```
+
+| 方法 | 说明 |
+|------|------|
+| `setAnchor(anchor)` | 设置 `anchor_from`/`anchor_to` 对齐（如 `bottom_left`、`bottom_right`、`top_right`），默认尺寸 32×32 |
+
+> 右上角的「退出」这类非集合按钮，请用普通 `Button("exit", "common.button")` + `$pressed_button_name: "button.menu_exit"` 手写，不占用表单按钮集合。
+
+---
+
+## 6. 运行时触发
+
+```typescript
+import { world } from "@minecraft/server"
+import { ActionFormData } from "@minecraft/server-ui"
+
+world.afterEvents.itemUse.subscribe((event) => {
+    if (event.itemStack.typeId == "minecraft:apple") {
+        new ActionFormData()
+            .title("sapdon_ui:apple")          // 前缀路由 → 自定义页
+            .body("...")
+            .button("test1").button("test2")   // 喂给集合 form_buttons
+            .show(event.source)
+    }
+})
+```
+
+- title 含 `sapdon_ui:` → 自定义全屏 UI；否则原版原生表单。
+- 自定义页内的按钮点击通过 `button.form_button_click` 返回 `response.selection`（对应集合下标）。
+
+---
+
+## 7. 已知注意点
+
+1. **`grid_position` 顺序**：本项目约定为 `[列, 行]`（与 `grid_dimensions [列, 行]` 一致）。
+2. **grid 内 `offset` 无效**：网格接管子控件定位；要偏移请包一层 panel（pos_wrap），offset 放内层。
+3. **`collection_index` 不是合法 UI 属性**：引擎会报 `Unknown property [collection_index]`。每个按钮对应哪个表单按钮，靠 grid 的集合上下文按放置顺序确定，不要用 `collection_index`。
+4. **壳固定渲染 content+buttons 两块**：纯内容页也必须提供一个（空的）按键面板，否则 `$user_buttons_panel` 引用缺失报错。
+5. **grid 数量绑定**：`#maximum_grid_items` 需 int（用 `#form_button_length`）；collection_panel 才用数组 `#form_button_contents` → `#collection_length`。
+6. **裸引用**：页面壳里的 `content@$user_content_panel` / `buttons@$user_buttons_panel` 必须是裸引用（不带 `type`），否则网格类型被覆盖导致 `grid_dimensions`/`grid_position` 报未知属性。

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

@@ -9,7 +9,7 @@
   "formatVersion": 2,
   "buildOptions": {
     "useHMR": true,                       // 是否启用热更新
-    "buildMode": "development",           // "development" | "production"
+    "buildMode": "dev",                   // "dev" | "prod" | "debug"
     "buildEntry": "main.ts",              // Addon 构建入口文件
     "useJs": false,                       // 是否使用 JavaScript
     "scriptEntry": "scripts/main.ts",     // Script API 入口
@@ -39,10 +39,9 @@
 
 | 值 | 说明 |
 |----|------|
-| `development` | **完整构建**：运行 `main.ts` → 根据代码生成所有 JSON → 打包脚本 → 同步到 Minecraft 目录。Script API 输出带 sourcemap，不压缩。 |
-| `production` | **仅同步**：跳过 `main.ts` 执行和 JSON 生成，将已有 `dev/` 目录直接同步到 Minecraft 目录。适合直接编辑 JSON 文件测试时使用。 |
-
-> 注意：`production` 模式不会运行 `main.ts`，也不会生成物品/实体/方块/配方的 JSON 文件。确保 `dev/` 目录已有正确的 JSON 文件（通常从一次 `development` 构建中获得）。
+| `dev` | **完整构建**：运行 `main.ts` → 根据代码生成所有 JSON → 打包脚本 → 同步到 Minecraft 目录。Script API 输出带 sourcemap，不压缩。 |
+| `prod` | **生产构建**：运行 `main.ts` → 生成 JSON → 打包脚本（terser 压缩混淆）→ 同步。不生成 sourcemap。 |
+| `debug` | **仅同步**：跳过 `main.ts` 执行和 JSON 生成，跳过脚本压缩，将已有 `dev/` 目录直接同步到 Minecraft 目录。适合直接编辑 JSON 文件测试时使用。 |
 
 ### buildEntry
 构建入口文件路径（相对项目根目录）。文件中的 `registry.submit()` 会将注册数据提交到构建系统。

package/doc/user/quick-start.md

@@ -40,7 +40,8 @@ hello_sapdon/
 ├── pack_icon.png        # 模组图标
 ├── res/                 # 资源文件（纹理、模型、音效）
 └── scripts/
-    └── main.ts          # Script API 入口（游戏内逻辑）
+    ├── index.ts         # 脚本入口——注册组件 + 游戏内逻辑
+    └── main.ts          # 游戏主类
 ```
 
 ## 编写代码
@@ -48,12 +49,12 @@ hello_sapdon/
 打开 `main.ts`，编写以下代码：
 
 ```typescript
-import { ItemAPI, registry, ItemComponent } from '@sapdon/core'
+import { ItemAPI, ItemCategory, registry, ItemComponent } from '@sapdon/core'
 
 // 创建一个基础物品
 const item = ItemAPI.createItem(
   'hello_sapdon:my_item',
-  'items',
+  ItemCategory.Items,
   'masterball'
 )
 item.addComponent(ItemComponent.setDisplayName('我的物品'))
@@ -75,14 +76,25 @@ sapdon build .
 
 | 模式 | 行为 |
 |------|------|
-| `development`（默认） | 运行 `main.ts` → 根据代码生成所有 JSON → 打包脚本 → 同步到 Minecraft |
-| `production` | 跳过 `main.ts`，直接同步已有 `dev/` 目录到 Minecraft（适合直接编辑 JSON 测试） |
+| `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 以 production 模式构建（不启动热更新）
 sapdon pack
 ```
 
+输出文件：`dev/<项目名>.mcaddon`
+
 ## 构建输出
 
 构建完成后，`dev/` 目录下生成：
@@ -105,4 +117,6 @@ dev/
 - [物品教程](./tutorials/item.md) — 学习创建各类物品
 - [实体教程](./tutorials/entity.md) — 学习创建实体
 - [方块教程](./tutorials/block.md) — 学习创建方块
+- [指南书教程](./tutorials/neo-guidebook.md) — API 用法
+- [指南书实战经验](./tutorials/neo-guidebook-experience.md) — 接入流程与踩坑清单
 - [API 参考](./api/item.md) — 完整的 API 文档