sapdon 3.5.0 → 3.5.2

package/prod/templates/ts_sapdon/res/models/entity/animation/animation_item.geo.json

@@ -0,0 +1,26 @@
+{
+	"format_version": "1.12.0",
+	"minecraft:geometry": [
+		{
+			"description": {
+				"identifier": "geometry.animation_item",
+				"texture_width": 32,
+				"texture_height": 32,
+				"visible_bounds_width": 5,
+				"visible_bounds_height": 3.5,
+				"visible_bounds_offset": [0, 1.25, 0]
+			},
+			"bones": [
+				{
+					"name": "body",
+					"pivot": [0, 0, 0]
+				},
+				{
+					"name": "rightitem",
+					"parent": "body",
+					"pivot": [-0.3, 8, 0]
+				}
+			]
+		}
+	]
+}

package/prod/templates/ts_sapdon/res/models/entity/animation/large_item.geo.json

@@ -0,0 +1,28 @@
+{
+    "format_version": "1.16.0",
+    "minecraft:geometry": [
+        {
+            "description": {
+                "identifier": "geometry.large_item",
+                "texture_width": 16,
+                "texture_height": 16,
+                "visible_bounds_width": 2,
+                "visible_bounds_height": 1.5,
+                "visible_bounds_offset": [0, 0.25, 0]
+            },
+            "bones": [
+                {
+                    "name": "rightitem",
+                    "pivot": [0, 0, 0],
+                    "texture_meshes": [
+                        {
+                            "texture": "default",
+                            "position": [0, 0, 0],
+                            "local_pivot": [8, 0, 8]
+                        }
+                    ]
+                }
+            ]
+        }
+    ]
+}

package/prod/templates/ts_sapdon/res/models/entity/dummy.geo.json

@@ -0,0 +1,24 @@
+{
+	"format_version": "1.12.0",
+	"minecraft:geometry": [
+		{
+			"description": {
+				"identifier": "geometry.dummy",
+				"texture_width": 16,
+				"texture_height": 16,
+				"visible_bounds_width": 1,
+				"visible_bounds_height": 1,
+				"visible_bounds_offset": [0, 0, 0]
+			},
+			"bones": [
+				{
+					"name": "dummy",
+					"pivot": [0, 0, 0],
+					"locators": {
+						"locator": [0, 0, 0]
+					}
+				}
+			]
+		}
+	]
+}

package/prod/templates/ts_sapdon/res/models/entity/falling_block.geo.json

@@ -0,0 +1,35 @@
+{
+	"format_version": "1.12.0",
+	"minecraft:geometry": [
+		{
+			"description": {
+				"identifier": "geometry.falling_block",
+				"texture_width": 16,
+				"texture_height": 16,
+				"visible_bounds_width": 3,
+				"visible_bounds_height": 3,
+				"visible_bounds_offset": [0, 0.5, 0]
+			},
+			"bones": [
+				{
+					"name": "bb_main",
+					"pivot": [0, 0, 0],
+					"cubes": [
+						{
+							"origin": [-8, 0, -8],
+							"size": [16, 16, 16],
+							"uv": {
+								"north": {"uv": [0, 0], "uv_size": [16, 16]},
+								"east": {"uv": [0, 0], "uv_size": [16, 16]},
+								"south": {"uv": [0, 0], "uv_size": [16, 16]},
+								"west": {"uv": [0, 0], "uv_size": [16, 16]},
+								"up": {"uv": [16, 16], "uv_size": [-16, -16]},
+								"down": {"uv": [16, 16], "uv_size": [-16, -16]}
+							}
+						}
+					]
+				}
+			]
+		}
+	]
+}

package/prod/templates/ts_sapdon/scripts/index.ts

@@ -0,0 +1,14 @@
+import {
+    MinecraftMain,
+    MinecraftGameInstance,
+    registerBuiltinComponents,
+} from '@sapdon/runtime'
+
+import './custom_components/index.js'
+
+registerBuiltinComponents()
+
+@MinecraftMain
+export class Main extends MinecraftGameInstance {
+    
+}

package/prod/templates/ts_sapdon/tsconfig.json

@@ -0,0 +1,117 @@
+{
+    "compilerOptions": {
+        /* Visit https://aka.ms/tsconfig to read more about this file */
+        /* Projects */
+        // "incremental": true,                              /* Save .tsbuildinfo files to allow for incremental compilation of projects. */
+        // "composite": true,                                /* Enable constraints that allow a TypeScript project to be used with project references. */
+        // "tsBuildInfoFile": "./.tsbuildinfo",              /* Specify the path to .tsbuildinfo incremental compilation file. */
+        // "disableSourceOfProjectReferenceRedirect": true,  /* Disable preferring source files instead of declaration files when referencing composite projects. */
+        // "disableSolutionSearching": true,                 /* Opt a project out of multi-project reference checking when editing. */
+        // "disableReferencedProjectLoad": true,             /* Reduce the number of projects loaded automatically by TypeScript. */
+        /* Language and Environment */
+        "target": "ESNext", /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
+        // "lib": [],                                        /* Specify a set of bundled library declaration files that describe the target runtime environment. */
+        // "jsx": "preserve",                                /* Specify what JSX code is generated. */
+        "experimentalDecorators": true,                   /* Enable experimental support for legacy experimental decorators. */
+        // "emitDecoratorMetadata": true,                    /* Emit design-type metadata for decorated declarations in source files. */
+        // "jsxFactory": "",                                 /* Specify the JSX factory function used when targeting React JSX emit, e.g. 'React.createElement' or 'h'. */
+        // "jsxFragmentFactory": "",                         /* Specify the JSX Fragment reference used for fragments when targeting React JSX emit e.g. 'React.Fragment' or 'Fragment'. */
+        // "jsxImportSource": "",                            /* Specify module specifier used to import the JSX factory functions when using 'jsx: react-jsx*'. */
+        // "reactNamespace": "",                             /* Specify the object invoked for 'createElement'. This only applies when targeting 'react' JSX emit. */
+        // "noLib": true,                                    /* Disable including any library files, including the default lib.d.ts. */
+        // "useDefineForClassFields": true,                  /* Emit ECMAScript-standard-compliant class fields. */
+        // "moduleDetection": "auto",                        /* Control what method is used to detect module-format JS files. */
+        /* Modules */
+        "module": "NodeNext", /* Specify what module code is generated. */
+        "rootDir": "./", /* Specify the root folder within your source files. */
+        "moduleResolution": "nodenext", /* Specify how TypeScript looks up a file from a given module specifier. */
+        "baseUrl": "./", /* Specify the base directory to resolve non-relative module names. */
+        //   "paths": {
+        //       "@core/*": [
+        //         "sapdon/core/*"
+        //       ],
+        //       "@cli/*": [
+        //         "sapdon/cli/*"
+        //       ]
+        //   },                                      /* Specify a set of entries that re-map imports to additional lookup locations. */
+        // "rootDirs": [],                                   /* Allow multiple folders to be treated as one when resolving modules. */
+        // "typeRoots": [],                                  /* Specify multiple folders that act like './node_modules/@types'. */
+        "types": [
+            "@minecraft/server",
+            "@minecraft/server-ui",
+            "node"
+        ], /* Specify type package names to be included without being referenced in a source file. */
+        // "allowUmdGlobalAccess": true,                     /* Allow accessing UMD globals from modules. */
+        // "moduleSuffixes": [],                             /* List of file name suffixes to search when resolving a module. */
+        // "allowImportingTsExtensions": true,               /* Allow imports to include TypeScript file extensions. Requires '--moduleResolution bundler' and either '--noEmit' or '--emitDeclarationOnly' to be set. */
+        // "rewriteRelativeImportExtensions": true,          /* Rewrite '.ts', '.tsx', '.mts', and '.cts' file extensions in relative import paths to their JavaScript equivalent in output files. */
+        // "resolvePackageJsonExports": true,                /* Use the package.json 'exports' field when resolving package imports. */
+        // "resolvePackageJsonImports": true,                /* Use the package.json 'imports' field when resolving imports. */
+        // "customConditions": [],                           /* Conditions to set in addition to the resolver-specific defaults when resolving imports. */
+        // "noUncheckedSideEffectImports": true,             /* Check side effect imports. */
+        // "resolveJsonModule": true,                        /* Enable importing .json files. */
+        // "allowArbitraryExtensions": true,                 /* Enable importing files with any extension, provided a declaration file is present. */
+        // "noResolve": true,                                /* Disallow 'import's, 'require's or '<reference>'s from expanding the number of files TypeScript should add to a project. */
+        /* JavaScript Support */
+        "allowJs": true, /* Allow JavaScript files to be a part of your program. Use the 'checkJS' option to get errors from these files. */
+        // "checkJs": true,                                  /* Enable error reporting in type-checked JavaScript files. */
+        // "maxNodeModuleJsDepth": 1,                        /* Specify the maximum folder depth used for checking JavaScript files from 'node_modules'. Only applicable with 'allowJs'. */
+        /* Emit */
+        // "declaration": true,                              /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
+        // "declarationMap": true,                           /* Create sourcemaps for d.ts files. */
+        // "emitDeclarationOnly": true,                      /* Only output d.ts files and not JavaScript files. */
+        // "sourceMap": true,                                /* Create source map files for emitted JavaScript files. */
+        // "inlineSourceMap": true,                          /* Include sourcemap files inside the emitted JavaScript. */
+        // "noEmit": true,                                   /* Disable emitting files from a compilation. */
+        // "outFile": "./",                                  /* Specify a file that bundles all outputs into one JavaScript file. If 'declaration' is true, also designates a file that bundles all .d.ts output. */
+        "outDir": "./.tmp", /* Specify an output folder for all emitted files. */
+        // "removeComments": true,                           /* Disable emitting comments. */
+        // "importHelpers": true,                            /* Allow importing helper functions from tslib once per project, instead of including them per-file. */
+        // "downlevelIteration": true,                       /* Emit more compliant, but verbose and less performant JavaScript for iteration. */
+        // "sourceRoot": "",                                 /* Specify the root path for debuggers to find the reference source code. */
+        // "mapRoot": "",                                    /* Specify the location where debugger should locate map files instead of generated locations. */
+        // "inlineSources": true,                            /* Include source code in the sourcemaps inside the emitted JavaScript. */
+        // "emitBOM": true,                                  /* Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files. */
+        // "newLine": "crlf",                                /* Set the newline character for emitting files. */
+        // "stripInternal": true,                            /* Disable emitting declarations that have '@internal' in their JSDoc comments. */
+        // "noEmitHelpers": true,                            /* Disable generating custom helper functions like '__extends' in compiled output. */
+        // "noEmitOnError": true,                            /* Disable emitting files if any type checking errors are reported. */
+        // "preserveConstEnums": true,                       /* Disable erasing 'const enum' declarations in generated code. */
+        // "declarationDir": "./",                           /* Specify the output directory for generated declaration files. */
+        /* Interop Constraints */
+        // "isolatedModules": true,                          /* Ensure that each file can be safely transpiled without relying on other imports. */
+        // "verbatimModuleSyntax": true,                     /* Do not transform or elide any imports or exports not marked as type-only, ensuring they are written in the output file's format based on the 'module' setting. */
+        // "isolatedDeclarations": true,                     /* Require sufficient annotation on exports so other tools can trivially generate declaration files. */
+        // "allowSyntheticDefaultImports": true,             /* Allow 'import x from y' when a module doesn't have a default export. */
+        "esModuleInterop": true, /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
+        // "preserveSymlinks": true,                         /* Disable resolving symlinks to their realpath. This correlates to the same flag in node. */
+        "forceConsistentCasingInFileNames": true, /* Ensure that casing is correct in imports. */
+        /* Type Checking */
+        "strict": true, /* Enable all strict type-checking options. */
+        // "noImplicitAny": true,                            /* Enable error reporting for expressions and declarations with an implied 'any' type. */
+        // "strictNullChecks": true,                         /* When type checking, take into account 'null' and 'undefined'. */
+        // "strictFunctionTypes": true,                      /* When assigning functions, check to ensure parameters and the return values are subtype-compatible. */
+        // "strictBindCallApply": true,                      /* Check that the arguments for 'bind', 'call', and 'apply' methods match the original function. */
+        // "strictPropertyInitialization": true,             /* Check for class properties that are declared but not set in the constructor. */
+        // "strictBuiltinIteratorReturn": true,              /* Built-in iterators are instantiated with a 'TReturn' type of 'undefined' instead of 'any'. */
+        // "noImplicitThis": true,                           /* Enable error reporting when 'this' is given the type 'any'. */
+        // "useUnknownInCatchVariables": true,               /* Default catch clause variables as 'unknown' instead of 'any'. */
+        // "alwaysStrict": true,                             /* Ensure 'use strict' is always emitted. */
+        // "noUnusedLocals": true,                           /* Enable error reporting when local variables aren't read. */
+        // "noUnusedParameters": true,                       /* Raise an error when a function parameter isn't read. */
+        // "exactOptionalPropertyTypes": true,               /* Interpret optional property types as written, rather than adding 'undefined'. */
+        // "noImplicitReturns": true,                        /* Enable error reporting for codepaths that do not explicitly return in a function. */
+        // "noFallthroughCasesInSwitch": true,               /* Enable error reporting for fallthrough cases in switch statements. */
+        // "noUncheckedIndexedAccess": true,                 /* Add 'undefined' to a type when accessed using an index. */
+        // "noImplicitOverride": true,                       /* Ensure overriding members in derived classes are marked with an override modifier. */
+        // "noPropertyAccessFromIndexSignature": true,       /* Enforces using indexed accessors for keys declared using an indexed type. */
+        // "allowUnusedLabels": true,                        /* Disable error reporting for unused labels. */
+        // "allowUnreachableCode": true,                     /* Disable error reporting for unreachable code. */
+        /* Completeness */
+        // "skipDefaultLibCheck": true,                      /* Skip type checking .d.ts files that are included with TypeScript. */
+        "skipLibCheck": true /* Skip type checking all .d.ts files. */
+    },
+    "exclude": [
+        "dev"
+    ]
+}

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

@@ -1,409 +0,0 @@
-# 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`/`Guidebook` 已移除。
-
----
-
-## 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
-    )
-})
-```