sapdon 3.2.2 → 3.4.0

package/doc/user/tutorials/recipe.md

@@ -0,0 +1,278 @@
+# 配方创建教程
+
+本文档介绍如何使用 sapdon 框架创建各类 Minecraft 配方。
+
+> 开始前请确保已完成[快速入门](../quick-start.md)中的环境搭建。
+
+## 导入
+
+所有配方 API 均从 `@sapdon/core` 导入：
+
+```typescript
+import { RecipeAPI, registry } from '@sapdon/core'
+```
+
+完成后调用 `registry.submit()` 提交所有注册数据。
+
+---
+
+## 1. 有序配方 — 简写
+
+`RecipeAPI.registerSimpleShaped()` 通过 pattern（图案）、key（键映射）和 output（输出）快速创建有序配方。
+
+```typescript
+import { RecipeAPI, registry } from '@sapdon/core'
+
+RecipeAPI.registerSimpleShaped(
+  'sapdon:diamond_sword',
+  'minecraft:diamond_sword',
+  [' X ', ' X ', ' Y '],
+  {
+    X: { item: 'minecraft:diamond' },
+    Y: { item: 'minecraft:stick' }
+  }
+).tags(['crafting_table'])
+
+registry.submit()
+```
+
+**参数说明**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `identifier` | `string` | 配方唯一标识符，格式 `命名空间:名称` |
+| `output` | `string` | 输出物品 ID |
+| `pattern` | `string[]` | 3 行图案，每行 3 字符 |
+| `key` | `object` | 字符到物品的映射 |
+
+方法自动设置 `crafting_table` 标签。`.tags()` 链式调用可覆盖或追加标签。
+
+---
+
+## 2. 有序配方 — 链式
+
+`RecipeAPI.registerShaped()` 返回 `AddonRecipeShaped` 实例，支持完整的链式调用。
+
+```typescript
+import { RecipeAPI, registry } from '@sapdon/core'
+
+RecipeAPI.registerShaped('sapdon:custom_helmet')
+  .key({
+    X: { item: 'minecraft:iron_ingot' }
+  })
+  .pattern(['XXX', 'X X', '   '])
+  .output('sapdon:custom_helmet')
+  .tags(['crafting_table'])
+
+registry.submit()
+```
+
+**可用链式方法**
+
+| 方法 | 说明 |
+|------|------|
+| `.key(map)` | 设置字符到物品的键映射 |
+| `.pattern(rows)` | 设置 3 行图案数组 |
+| `.output(item)` | 设置输出物品，支持 `string` 或 `{ item, count }` 对象 |
+| `.priority(num)` | 设置优先级（数值越小优先级越高） |
+| `.assumeSymmetry()` | 启用对称假设 |
+| `.tags(tags[])` | 设置配方标签数组 |
+
+```typescript
+// 带数量和优先级的完整示例
+RecipeAPI.registerShaped('sapdon:custom_block')
+  .key({
+    A: { item: 'minecraft:diamond' },
+    B: { item: 'minecraft:iron_ingot' }
+  })
+  .pattern(['AAA', 'ABA', 'AAA'])
+  .output({ item: 'sapdon:custom_block', count: 4 })
+  .priority(0)
+  .tags(['crafting_table'])
+```
+
+---
+
+## 3. 无序配方 — 简写
+
+`RecipeAPI.registerSimpleShapeless()` 通过 ingredients 数组快速创建无序配方。
+
+```typescript
+import { RecipeAPI, registry } from '@sapdon/core'
+
+RecipeAPI.registerSimpleShapeless(
+  'sapdon:custom_ingot',
+  'sapdon:custom_ingot',
+  [
+    { item: 'minecraft:iron_ingot' },
+    { item: 'minecraft:gold_ingot' }
+  ]
+).tags(['crafting_table'])
+
+registry.submit()
+```
+
+**参数说明**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `identifier` | `string` | 配方唯一标识符 |
+| `output` | `string` | 输出物品 ID |
+| `ingredients` | `object[]` | 原料数组，无需顺序 |
+
+原料支持标签引用实现宽匹配：
+
+```typescript
+RecipeAPI.registerSimpleShapeless(
+  'sapdon:leather_helmet',
+  'minecraft:leather_helmet',
+  [
+    { item: 'minecraft:leather' },
+    { item: 'minecraft:leather' },
+    { item: 'minecraft:leather' },
+    { item: 'minecraft:leather' },
+    { item: 'minecraft:leather' }
+  ]
+).tags(['crafting_table'])
+```
+
+---
+
+## 4. 无序配方 — 链式
+
+`RecipeAPI.registerShapeless()` 返回 `AddonRecipeShapeless` 实例，支持链式调用。
+
+```typescript
+import { RecipeAPI, registry } from '@sapdon/core'
+
+RecipeAPI.registerShapeless('sapdon:mixed_ingot')
+  .ingredients([
+    { item: 'minecraft:iron_ingot' },
+    { item: 'minecraft:gold_ingot' },
+    { item: 'minecraft:diamond' }
+  ])
+  .output({ item: 'sapdon:mixed_ingot', count: 3 })
+  .tags(['crafting_table'])
+
+registry.submit()
+```
+
+**可用链式方法**
+
+| 方法 | 说明 |
+|------|------|
+| `.ingredients(items[])` | 设置原料数组 |
+| `.output(item)` | 设置输出物品 |
+| `.priority(num)` | 设置优先级 |
+| `.tags(tags[])` | 设置配方标签数组 |
+
+使用物品标签作为原料：
+
+```typescript
+RecipeAPI.registerShapeless('sapdon:wooden_rod')
+  .ingredients([
+    { tag: 'minecraft:planks' },
+    { tag: 'minecraft:planks' }
+  ])
+  .output('sapdon:wooden_rod')
+  .tags(['crafting_table'])
+```
+
+---
+
+## 5. 熔炉配方 — 简写
+
+`RecipeAPI.registerSimpleFurnace()` 快速创建熔炉配方。
+
+```typescript
+import { RecipeAPI, registry } from '@sapdon/core'
+
+RecipeAPI.registerSimpleFurnace(
+  'sapdon:cooked_ruby',
+  'sapdon:ruby',
+  'sapdon:raw_ruby'
+).tags(['furnace'])
+
+registry.submit()
+```
+
+**参数说明**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `identifier` | `string` | 配方唯一标识符 |
+| `output` | `string` | 烧炼输出物品 ID |
+| `input` | `string` | 烧炼输入物品 ID |
+
+方法自动设置 `furnace` 标签。
+
+---
+
+## 6. 熔炉配方 — 链式
+
+`RecipeAPI.registerFurnace()` 返回 `AddonRecipeFurnace` 实例，支持链式调用。
+
+```typescript
+import { RecipeAPI, registry } from '@sapdon/core'
+
+RecipeAPI.registerFurnace('sapdon:smelt_ruby')
+  .input('sapdon:raw_ruby')
+  .output('sapdon:ruby')
+  .tags(['furnace'])
+
+registry.submit()
+```
+
+**可用链式方法**
+
+| 方法 | 说明 |
+|------|------|
+| `.input(item, data?, count?)` | 设置输入物品，可选 data 和 count |
+| `.output(item)` | 设置输出物品 |
+| `.tags(tags[])` | 设置配方标签数组 |
+
+```typescript
+// 带 data 值的熔炉配方
+RecipeAPI.registerFurnace('sapdon:smelt_ore')
+  .input('minecraft:iron_ore', 0, 1)
+  .output('minecraft:iron_ingot')
+  .tags(['furnace', 'blast_furnace'])
+```
+
+---
+
+## 7. 配方标签
+
+配方标签决定配方可在哪些方块中使用。通过 `.tags()` 方法设置：
+
+```typescript
+RecipeAPI.registerShaped('sapdon:example')
+  .pattern(['A', 'A', 'A'])
+  .key({ A: { item: 'minecraft:iron_ingot' } })
+  .output('sapdon:example')
+  .tags(['crafting_table'])
+```
+
+### 可用标签值
+
+| 标签 | 适用方块 | 说明 |
+|------|----------|------|
+| `furnace` | 熔炉 | 标准熔炉烧炼配方 |
+| `smoker` | 烟熏炉 | 食物烧炼配方 |
+| `campfire` | 篝火 | 篝火烹饪配方 |
+| `soul_campfire` | 灵魂篝火 | 灵魂篝火烹饪配方 |
+| `crafting_table` | 工作台 | 工作台合成配方 |
+
+可通过 `RecipeTags` 常量引用：
+
+```typescript
+import { RecipeAPI, registry, RecipeTags } from '@sapdon/core'
+
+RecipeAPI.registerSimpleFurnace(
+  'sapdon:cooked_beef',
+  'minecraft:cooked_beef',
+  'minecraft:beef'
+).tags([RecipeTags.Furnace, RecipeTags.smoker])
+```
+
+> 注：`RecipeTags.smoker` 首字母小写，其余常量均为大写首字母。

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

@@ -0,0 +1,207 @@
+# Sapdon UI 页面壳系统教程
+
+本教程将带你创建一个使用 `sapdon_ui:` 前缀路由的自定义 Server Form UI：一个页面含「内容面板 + 按键面板」（按键盖在内容上层），左下/右下摆表单按钮，右上放退出键。完整可运行示例见 `examples/test_ui`。
+
+---
+
+## 目录
+
+1. [准备工作](#1-准备工作)
+2. [创建构建入口](#2-创建构建入口)
+3. [定义内容面板](#3-定义内容面板)
+4. [定义按键面板](#4-定义按键面板)
+5. [组装页面并注册](#5-组装页面并注册)
+6. [编写运行时脚本](#6-编写运行时脚本)
+7. [构建与部署](#7-构建与部署)
+8. [完整示例](#8-完整示例)
+
+---
+
+## 1. 准备工作
+
+初始化一个 TS 项目并安装依赖：
+
+```bash
+npm init -y
+npm install @minecraft/server@2.8.0 @minecraft/server-ui@2.1.0
+# @sapdon/core 由 postinstall 的 `sapdon lib` 自动同步
+```
+
+项目结构：
+
+```
+test_ui/
+├── main.ts               # 构建入口（声明式定义 UI）
+├── scripts/
+│   └── index.ts          # 运行时入口（触发表单）
+├── build.config          # 构建配置
+├── mod.info              # 模块信息（含 min_engine_version）
+├── tsconfig.json
+├── package.json
+├── pack_icon.png
+└── res/                  # 资源目录
+```
+
+`build.config` 关键项（参考 `examples/test_ui/build.config`）：
+
+```json
+{
+  "formatVersion": 2,
+  "buildOptions": {
+    "buildMode": "dev",
+    "buildEntry": "main.ts",
+    "scriptEntry": "scripts/index.ts",
+    "scriptOutput": "scripts/index.js",
+    "useJs": false,
+    "buildDir": "dev/",
+    "dependencies": [
+      { "module_name": "@minecraft/server-ui", "version": "2.1.0" },
+      { "module_name": "@minecraft/server", "version": "2.8.0" }
+    ]
+  }
+}
+```
+
+---
+
+## 2. 创建构建入口
+
+`main.ts` 是构建时脚本：声明 UI → 注册页面 → `registry.submit()` 生成所有 UI JSON。
+
+```typescript
+import {
+    Label, Layout, Panel, SapdonButton, SapdonButtonPanel, SapdonPanel,
+    SapdonServerUI, StackPanel, Text, registry
+} from '@sapdon/core'
+```
+
+---
+
+## 3. 定义内容面板
+
+内容面板是页面的主体（背景 + 标题/正文），最后会被画在按键面板**下面**。
+
+```typescript
+const apple_content_panel = new Panel("apple_content_panel")
+    .setLayout(new Layout().setSize(["40%", "40%"]))
+    .enableDebug();
+apple_content_panel.addControl(
+    new StackPanel("main", undefined)
+        .addStack(["100%", "30%"],
+            new Label("title", undefined).enableDebug().setText(new Text().setText("苹果界面")))
+        .addStack(["100%", "70%"],
+            new Label("body", undefined).enableDebug().setText(new Text().setText("内容面板")))
+);
+```
+
+> 面板 id（`apple_content_panel`）稍后会作为注册引用 `sapdon_ui_apple.apple_content_panel`。
+
+---
+
+## 4. 定义按键面板
+
+按键面板画在内容面板**上层**。两个表单按钮用 `SapdonButtonPanel`(grid 2×1) 摆到左右下角；右上角放一个普通退出键（不占表单集合）。
+
+```typescript
+import { Button } from '@sapdon/core'
+
+const apple_buttons_panel = new Panel("apple_buttons_panel")
+    .setLayout(new Layout().setSize(["40%", "40%"]))
+    .addControl(
+        new SapdonButtonPanel("apple_buttons_grid")
+            .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()
+    )
+    .addControl(
+        new Button("exit", "common.button")               // 右上：普通退出键
+            .addVariable("pressed_button_name", "button.menu_exit")
+            .setLayout(new Layout().setSize([48, 24]).setAnchorFrom("top_right").setAnchorTo("top_right"))
+            .addControl(new Label("exit_text", undefined).setText(new Text().setText("退出")))
+    );
+```
+
+要点：
+- `grid_dimensions [2,1]` 把按键面板切成左右两半；格子内默认左上对齐，`setAnchor("bottom_left")` / `("bottom_right")` 把按钮落到两个下角。
+- 表单按钮走 `SapdonButton`（自动引用框架模板 `server_form.form_button`，吃 `form_buttons` 集合数据）。
+- 退出键用 `common.button` + `button.menu_exit`，点击关闭表单。
+
+---
+
+## 5. 组装页面并注册
+
+`SapdonPanel` 把内容/按键两块组装进该页面自己的 UI 文件；`SapdonServerUI.registerPage` 注册到路由。
+
+```typescript
+new SapdonPanel("sapdon_ui_apple")           // 生成 ui/sapdon_ui_apple.json
+    .setContent(apple_content_panel)
+    .setButtons(apple_buttons_panel)
+    .build();
+
+SapdonServerUI.registerPage({
+    panelId: "sapdon_ui:apple",              // title 精确匹配
+    name: "apple",
+    contentPanel: "sapdon_ui_apple.apple_content_panel",
+    buttonsPanel: "sapdon_ui_apple.apple_buttons_panel",
+});
+
+registry.submit()                            // 输出 server_form.json + 各页面 ui 文件 + _ui_defs.json
+```
+
+> 纯内容页（无按键）：也需提供一个空的按键面板并注册，否则壳的 `$user_buttons_panel` 引用会报缺失。
+
+---
+
+## 6. 编写运行时脚本
+
+`scripts/index.ts`：使用物品触发带 `sapdon_ui:` 前缀 title 的 ActionForm。
+
+```typescript
+import { world } from "@minecraft/server";
+import { ActionFormData } from "@minecraft/server-ui";
+
+world.afterEvents.itemUse.subscribe((event) => {
+    if (event.itemStack.typeId != "minecraft:apple") return;
+    new ActionFormData()
+        .title("sapdon_ui:apple")            // 前缀路由 → 自定义页
+        .body("触发苹果页")
+        .button("test1")                     // 喂给集合 form_buttons
+        .button("test2")
+        .show(event.source)
+        .then((r) => world.sendMessage("selection: " + r.selection));
+});
+```
+
+- title 含 `sapdon_ui:` → 显示自定义全屏 UI；否则走原版原生表单。
+- 按钮点击返回 `response.selection`（对应集合下标）。
+
+---
+
+## 7. 构建与部署
+
+```bash
+npm i          # postinstall 自动执行 sapdon lib，同步 @sapdon/core
+npm run build  # 构建并复制到开发包目录
+```
+
+构建产物（`dev/test_ui_RP/ui/`）：
+
+```
+server_form.json        # 路由壳（custom_full_screen / sapdon_screen_content / custom_panel_content / form_button）
+sapdon_ui_apple.json    # 页面：内容面板 + 按键面板
+_ui_defs.json           # 自动登记
+```
+
+进入游戏用苹果触发，验证：
+1. 内容面板在底层、按键面板覆盖在上层。
+2. 左下/右下各一个表单按钮（数据对应 test1/test2）。
+3. 右上「退出」点击关闭表单。
+
+---
+
+## 8. 完整示例
+
+完整可运行代码见仓库 `examples/test_ui`（含页面 A 内容+按键、页面 B 纯内容两个页面）。API 细节见《Sapdon UI 页面壳系统 API 参考》（`doc/user/api/sapdon-ui.md`）。

package/package.json

@@ -1,8 +1,10 @@
 {
     "name": "sapdon",
-    "version": "3.2.2",
+    "version": "3.4.0",
     "scripts": {
         "build": "node scripts/build.cjs",
+        "test": "tsc && tsc-alias && node --test \"tests/*.test.mjs\"",
+        "build:demo": "cd examples/block_demo && npm run build",
         "pub": "npm run build && npm publish"
     },
     "keywords": [
@@ -20,6 +22,8 @@
     "devDependencies": {
         "@minecraft/server": "^2.0.0-beta.1.21.80-preview.20",
         "@minecraft/server-ui": "^1.3.0",
+        "@types/archiver": "^6.0.0",
+        "@types/d3-array": "^3.2.1",
         "@types/lodash": "^4.17.16",
         "@types/node": "^22.14.0",
         "tsc-alias": "^1.8.13"
@@ -32,6 +36,8 @@
         "@rollup/plugin-typescript": "^12.1.2",
         "chalk": "^5.4.1",
         "commander": "^13.0.0",
+        "d3-array": "^3.2.4",
+        "archiver": "^7.0.0",
         "download-git-repo": "^3.0.2",
         "inquirer": "^12.3.1",
         "lodash": "^4.17.21",
@@ -46,7 +52,6 @@
     },
     "files": [
         "prod/**/*",
-        "doc/**/*",
-        "src/templates/**/*"
+        "doc/**/*"
     ]
 }

package/prod/cli/index.js

@@ -1 +1 @@
-import e from"http";Symbol.metadata||(Symbol.metadata=Symbol("[[metadata]]"));const t=Symbol("isRawJSON");const r=["boolean","number"],n=["string","undefined"];function o(e,o){const i=typeof o;if(null===i)return null;if(n.includes(i))return o;if(r.includes(i))return JSON.rawJSON(o);if("object"===i)return JSON.isRawJSON(o)?o:function(e){return!0===e?.[t]}(o)?JSON.rawJSON(o.rawJSON):o;if("bigint"===i)return JSON.rawJSON(o.toString());throw new Error("Unexpected value")}const i={encode:e=>JSON.stringify(e,o),decode:JSON.parse};function s(e,t=i){return t.encode(e)}const a={port:49037},{port:c}=a;const{port:l}=a;const d=new class{cliServerHandlers=new Map;listening=!1;isListening(){return this.listening}bootstrap(){this.listening=!0;const t=e.createServer((async(e,t)=>{const r=this.cliServerHandlers.get((e.url??"/").slice(1));if(r){try{const{promise:t,resolve:n,reject:o}=Promise.withResolvers();let s=Buffer.alloc(0);e.on("data",(e=>s=Buffer.concat([s,e]))),e.on("end",(()=>{try{n(function(e,t=i){return t.decode(e)}(s))}catch(e){o(e)}})),await r(...await t)}catch(e){return console.error(e),t.writeHead(500),void t.end()}t.writeHead(200),t.end()}else t.writeHead(404),t.end()})).listen(l,(()=>console.log(`Dev Server listening on port ${l}`)));return t.on("error",(()=>this.listening=!1)),t}handle(e,t){this.cliServerHandlers.set(e,t)}getHandler(e){return this.cliServerHandlers.get(e)}interceptHandler(e,t){const r=t(this.getHandler(e)??Function.prototype);return this.cliServerHandlers.set(e,r),r}},u={call:async(e,...t)=>await async function(e,...t){try{await fetch(`http://localhost:${c}/${e}`,{method:"POST",headers:{"Content-Type":"application/json"},body:s(t)})}catch(e){console.error(e),console.error("尝试在构建脚本中使用 server.startDevServer() 启动开发服务器")}}(e,...t)};export{u as client,d as devServer};
+import e from"http";Symbol.metadata||(Symbol.metadata=Symbol("[[metadata]]"));const r=Symbol("isRawJSON");const t=["boolean","number"],n=["string","undefined"];function o(e,o){const s=typeof o;if(null===s)return null;if(n.includes(s))return o;if(t.includes(s))return JSON.rawJSON(o);if("object"===s)return JSON.isRawJSON(o)?o:function(e){return!0===e?.[r]}(o)?JSON.rawJSON(o.rawJSON):o;if("bigint"===s)return JSON.rawJSON(o.toString());throw new Error("Unexpected value")}const s={encode:e=>JSON.stringify(e,o),decode:JSON.parse};function i(e,r=s){return r.encode(e)}const a={port:49037},{port:c}=a;const{port:l}=a;const d=new class{cliServerHandlers=new Map;listening=!1;isListening(){return this.listening}bootstrap(){this.listening=!0;const r=e.createServer(async(e,r)=>{const t=this.cliServerHandlers.get((e.url??"/").slice(1));if(t){try{const{promise:r,resolve:n,reject:o}=Promise.withResolvers();let i=Buffer.alloc(0);e.on("data",e=>i=Buffer.concat([i,e])),e.on("end",()=>{try{n(function(e,r=s){return r.decode(e)}(i))}catch(e){o(e)}}),await t(...await r)}catch(e){return console.error(e),r.writeHead(500),void r.end()}r.writeHead(200),r.end()}else r.writeHead(404),r.end()}).listen(l,()=>console.log(`Dev Server listening on port ${l}`));return r.on("error",e=>{throw this.listening=!1,function(e){return"object"==typeof e&&null!==e&&"EADDRINUSE"===e.code}(e)&&(console.error(`[sapdon] Dev Server 端口 ${l} 已被其他 sapdon 进程占用。`),console.error("[sapdon] 请先结束残留的 sapdon 进程，再重新构建，否则本次构建的数据可能被写入错误的包目录。"),process.exit(1)),e}),r}handle(e,r){this.cliServerHandlers.set(e,r)}getHandler(e){return this.cliServerHandlers.get(e)}interceptHandler(e,r){const t=r(this.getHandler(e)??Function.prototype);return this.cliServerHandlers.set(e,t),t}},u={call:async(e,...r)=>await async function(e,...r){try{await fetch(`http://localhost:${c}/${e}`,{method:"POST",headers:{"Content-Type":"application/json"},body:i(r)})}catch(e){console.error(e),console.error("尝试在构建脚本中使用 server.startDevServer() 启动开发服务器")}}(e,...r)};export{u as client,d as devServer};