sapdon 3.2.2 → 3.3.3

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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "sapdon",
-    "version": "3.2.2",
+    "version": "3.3.3",
     "scripts": {
         "build": "node scripts/build.cjs",
         "pub": "npm run build && npm publish"
@@ -20,6 +20,7 @@
     "devDependencies": {
         "@minecraft/server": "^2.0.0-beta.1.21.80-preview.20",
         "@minecraft/server-ui": "^1.3.0",
+        "@types/d3-array": "^3.2.1",
         "@types/lodash": "^4.17.16",
         "@types/node": "^22.14.0",
         "tsc-alias": "^1.8.13"
@@ -32,6 +33,7 @@
         "@rollup/plugin-typescript": "^12.1.2",
         "chalk": "^5.4.1",
         "commander": "^13.0.0",
+        "d3-array": "^3.2.4",
         "download-git-repo": "^3.0.2",
         "inquirer": "^12.3.1",
         "lodash": "^4.17.21",
@@ -46,7 +48,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 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};