sapdon 2.0.2 → 2.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 junjun260
+Copyright (c) 2025 Meteage
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/doc/BlockAPI.md

@@ -0,0 +1,145 @@
+# 方块工厂类 (BlockAPI) API 文档
+
+## 类描述
+
+`BlockAPI` 是一个工厂函数集合，用于创建和管理多种类型的游戏方块，并自动注册到游戏系统中。支持基础方块、旋转方块、几何方块、矿物方块和作物方块的创建。
+
+---
+
+## BlockAPI 工厂函数
+
+### `createBasicBlock(identifier, category, textures_arr, options = {})`
+
+创建基础方块。
+
+#### 参数
+
+- `identifier` (string): 方块的唯一标识符，格式为"命名空间:名称" (例："my_mod:stone_block")。
+- `category` (string): 在创造模式物品栏的分类，可选值： "construction", "nature", "equipment", "items", and "none"。
+- `textures_arr` (string[]): 6面纹理数组，顺序为 [上, 下, 东, 西, 南, 北]
+- `options` (Object): 可选参数，默认为空。
+    - `group` (string): 分组名称，默认 "construction"。
+    - `hide_in_command` (boolean): 是否在命令中隐藏，默认 `false`。
+
+#### 返回值
+
+- `BasicBlock`: 基础方块实例
+
+---
+
+### `createBlock(identifier, category, variantDatas, options = {})`
+
+创建含变体状态的标准方块。
+
+#### 参数
+
+- `identifier` (string): 方块的唯一标识符。
+- `category` (string): 在创造模式物品栏的分类，可选值： "construction", "nature", "equipment", "items", and "none"
+- `variantDatas` (Array): 变体数据数组，每个元素包含：
+    - `stateTag` (number): 状态标签 0-15 最大15
+    - `textures` (string[]): 对应状态的6面，纹理顺序为 [上, 下, 东, 西, 南, 北]
+- `options` (Object): 可选参数，默认为空。
+    - `options.group` (string): 分组，默认为 "construction"。
+    - `options.hide_in_command` (boolean): 是否在命令中隐藏，默认为 false。
+    - `ambient_occlusion` (boolean): 环境光遮蔽，默认 `false`
+    - `face_dimming` (boolean): 面亮度衰减，默认 `false`
+    - `render_method` (string): 渲染模式，可选 "opaque"/"blend"/"alpha_test"
+
+#### 返回值
+
+- `Block`: 标准方块实例
+
+---
+
+### `createRotatableBlock(identifier, category, textures_arr, options = {})`
+
+创建支持多方向旋转的方块。
+
+#### 参数
+
+- `identifier` (string): 矿物方块的唯一标识符。
+- `category` (string): 在创造模式物品栏的分类，可选值："construction", "nature", "equipment", "items", and "none"
+- `textures_arr` (string[]): 6面纹理数组，顺序为 [上, 下, 东, 西, 南, 北]。
+- `options` (Object): 可选参数，默认为空。
+    - `options.group` (string): 分组，默认为 "construction"。
+    - `options.hide_in_command` (boolean): 是否在命令中隐藏，默认为 false。
+    - `options.rotationType` (string): 旋转类型，默认为 "cardinal"。
+    - `options.yRotationOffset` (number): 初始旋转偏移量，默认为 180。
+
+#### 返回值
+
+- `RotatableBlock`: 旋转方块实例
+
+---
+
+### `createGeometryBlock(identifier, category, geometry, material_instances, options = {})`
+
+创建自定义几何模型方块。
+
+#### 参数
+
+- `identifier` (string): 方块的唯一标识符。
+- `category` (string): 在创造模式物品栏的分类，可选值："construction", "nature", "equipment","items" and "none"。
+- `geometry` (string): 几何模型标识符 (例："geometry.custom_model")。
+- `material_instances` (Object): 材质实例配置。
+    - 撰写文档者不晓得具体内容应该填啥
+- `options` (Object): 可选参数，默认为空。
+    - `options.group` (string): 分组，默认为 "construction"。
+    - `options.hide_in_command` (boolean): 是否在命令中隐藏，默认为 false。
+
+#### 返回值
+
+- `GeometryBlock`: 自定义几何模型方块实例
+
+---
+
+### `createOreBlock(identifier, category, textures_arr, options = {})`
+
+创建矿物生成方块。
+
+#### 参数
+
+- `identifier` (string): 矿物方块的唯一标识符。
+- `category` (string): 在创造模式物品栏的分类，可选值："construction", "nature", "equipment", "items" and "none"。
+- `textures_arr` (string[]): 6面纹理数组，顺序为 [上, 下, 东, 西, 南, 北]。
+- `options` (Object): 可选参数，默认为空。
+    - `options.group` (string): 分组，默认为 "construction"。
+    - `options.hide_in_command` (boolean): 是否在命令中隐藏，默认为 false。
+
+#### 返回值
+
+- `OreBlock`: 矿物方块实例
+
+---
+
+### `createCropBlock(identifier, category, variantDatas, options = {})`
+
+创建农作物方块。
+
+#### 参数
+
+- `identifier` (string): 作物方块的唯一标识符。
+- `category` (string): 在创造模式物品栏的分类，可选值："construction", "nature", "equipment", "items" and "none"。
+- `variantDatas` (Array): 变体数据数组，每个元素包含：
+  - `stateTag` (number): 状态标签 0-15 最大15
+  - `textures` (string[]): 对应状态的6面纹理
+- `options` (Object): 可选参数，默认为空。
+    - `options.group` (string): 分组，默认为 "construction"。
+    - `options.hide_in_command` (boolean): 是否在命令中隐藏，默认为 false。
+    - `options.ambient_occlusion` (boolean): 是否应用环境光遮蔽，默认为 false。
+    - `options.face_dimming` (boolean): 是否根据面的方向进行亮度调整，默认为 false。
+    - `options.render_method` (string): 渲染方法，默认为 "alpha_test"。
+
+#### 返回值
+
+- `CropBlock`: 作物方块实例
+
+---
+
+## 版本兼容性
+
+| 功能 | 最低版本 | 依赖组件 |
+|------|---------|---------|
+| 几何方块 | 1.16.20 | minecraft:geometry |
+| 矿脉生成 | 1.18.30 | ore_feature |
+| 动态碰撞箱 | 1.17.10 | permutation |

package/doc/api.md

@@ -10,7 +10,7 @@
 创建一个新的物品实例。
 
 #### 参数
-- `identifier` (string): 物品的唯一标识符。
+- `identifier` (string): 物品的唯一标识符。由命名空间与名字组成，例如"hello_sapdon:my_item"
 - `category` (string): 物品所属的菜单栏分类，可选值包括："construction", "nature", "equipment", "items", 和 "none"。
 - `texture` (string): 物品的纹理。
 - `options` (Object): 可选参数配置对象。默认为空对象。

package/doc/hello_sapdon/sapdon/344/275/277/347/224/250/346/225/231/347/250/213.md

@@ -0,0 +1,159 @@
+# Sapdon 使用指南
+
+## 1. Sapdon 介绍
+
+Sapdon 是一个基于 JavaScript 开发的 Minecraft 基岩版通用工具箱。它提供了大量的接口，帮助开发者简化传统开发 Addon 的过程，提高开发效率，并减少直接编辑 JSON 文件时可能出现的错误和麻烦。
+
+## 2. 准备工作
+
+在开始使用 Sapdon 之前，您需要准备以下工具和环境：
+
+### 软件要求
+- **Visual Studio Code (VSCode)**：用于编写和编辑代码。
+- **Node.js**：确保已安装 Node.js，因为 Sapdon 是基于 Node.js 开发的。
+
+### 安装 Node.js
+1. 访问 [Node.js 官网](https://nodejs.org/) 下载并安装适合您操作系统的版本。
+2. 安装完成后，打开终端或命令提示符，输入以下命令以验证安装是否成功：
+   ```bash
+   node -v
+   npm -v
+   ```
+   如果显示了版本号，说明安装成功。
+
+### 创建 Node.js 项目
+1. 在您的工作目录中，新建一个文件夹作为项目根目录。
+2. 打开终端，进入该文件夹，并初始化一个新的 Node.js 项目：
+   ```bash
+   npm init -y
+   ```
+3. 安装 Sapdon 作为项目依赖：
+   ```bash
+   npm install sapdon
+   ```
+
+## 3. 新建一个 Sapdon 项目
+
+### 创建命令
+使用以下命令创建一个新的 Sapdon 项目：
+```bash
+npm run create <project-name>
+```
+其中 `<project-name>` 是您的项目名称。
+
+### 示例：创建名为 `hello_sapdon` 的项目
+1. 在 VSCode 的终端中输入以下命令：
+   ```bash
+   npm run create hello_sapdon
+   ```
+2. 终端将交互式地询问一些项目信息，如下所示：
+   ```
+   ✔ Project Name: hello_sapdon
+   ✔ Project Description: A new sapdon project
+   ✔ Author Name: Sapdon
+   ✔ Project Version: 1.0.0
+   ✔ Minimum Engine Version: 1.19.50
+   ```
+   如果您希望采用默认值，只需按下回车键即可。
+
+### 参数解释
+- **Project Name**：项目名称，即模组名称。
+- **Project Description**：项目描述，将在 Minecraft 包中显示。
+- **Author Name**：模组作者的名字。
+- **Minimum Engine Version**：最低支持的 Minecraft 版本。如果 Minecraft 版本低于此版本，模组将不会工作。
+
+### 项目结构
+创建完成后，您的工作目录下将生成一个名为 `hello_sapdon` 的文件夹。展开该文件夹，您将看到以下结构：
+```
+hello_sapdon/
+├── res/            # 资源文件夹，存放贴图、模型、实体动画等资源文件
+├── scripts/        # 脚本文件夹，存放 SAPI 文件，这些文件将在游戏中执行
+├── build.config    # 构建配置文件
+├── main.mjs        # 模组内容注册脚本，使用 Sapdon 提供的接口编写模组内容
+├── mod.info        # 模组信息文件
+└── pack_icon.png   # 模组的图标
+```
+
+### `build.config` 文件解析
+```json
+{
+  "defaultConfig": {
+    "buildMode": "development",
+    "buildEntry": "main.mjs",
+    "scriptEntry": "scripts/index.js",
+    "buildDir": "dev/",
+    "dependencies": [
+      {
+        "module_name": "@minecraft/server",
+        "version": "1.8.0"
+      }
+    ]
+  },
+  "libraries": [
+    {
+      "path": "lib/"
+    }
+  ],
+  "resources": [
+    {
+      "path": "res/"
+    }
+  ],
+  "scripts": [
+    {
+      "path": "scripts/"
+    }
+  ]
+}
+```
+- **buildMode**：构建模式。设置为 `"development"` 时，构建程序将根据 `main.mjs` 中的内容构建 Addon 包，并将输出到 `buildDir` 指定的文件夹中；设置为 `"debug"` 时，仅将 `dev` 文件夹的内容输出到指定路径。
+- **buildEntry**：构建入口文件的路径，即您编写模组内容的文件。
+- **scriptEntry**：脚本入口文件的路径。
+- **buildDir**：构建输出文件夹的路径，构建好的 Addon 包将输出到此文件夹。
+- **dependencies**：依赖的模块。在此示例中，我们依赖了 Minecraft 官方的 `@minecraft/server` 模块，用于 SAPI。
+
+## 4. 编写模组内容
+
+### 创建一个基础物品
+1. 打开 `main.mjs` 文件。
+2. 写入以下内容以创建一个基础物品：
+   ```javascript
+   import { ItemAPI } from "../src/core";
+
+   ItemAPI.createItem("hello_sapdon:my_item", "items", "masterball");
+   ```
+   这段代码将创建一个名为 `my_item` 的物品，其命名空间为 `hello_sapdon`，类型为 `items`，并使用 `masterball` 作为图标。
+
+## 5. 执行构建命令
+
+### 构建 Addon 包
+1. 在终端中输入以下命令以构建 `hello_sapdon` 项目：
+   ```bash
+   npm run build hello_sapdon
+   ```
+2. 构建完成后，您将在 `hello_sapdon` 文件夹下看到一个 `dev` 文件夹，其中包含构建好的 Addon 包。
+
+## 6. 下一步
+
+现在，您已经成功创建并构建了一个简单的 Sapdon 项目。接下来，您可以继续探索 Sapdon 提供的其他功能，如创建方块、实体、配方和 UI 等。通过 Sapdon 的强大接口，您可以更高效地开发 Minecraft 基岩版模组。
+
+## 7. 常见问题
+
+### Q: 如何修改模组的最低支持版本？
+A: 在 `mod.info` 文件中，您可以找到 `min_engine_version` 字段，修改该字段的值即可调整模组的最低支持版本。
+
+### Q: 如何添加更多依赖？
+A: 在 `build.config` 文件的 `dependencies` 数组中，您可以添加更多依赖模块。例如：
+```json
+{
+  "module_name": "@minecraft/server-ui",
+  "version": "1.0.0"
+}
+```
+
+### Q: 构建时出现错误怎么办？
+A: 请检查 `main.mjs` 文件中的代码是否正确，并确保所有依赖模块已正确安装。如果问题仍然存在，请参考 Sapdon 的官方文档或社区支持。
+
+---
+
+通过本指南，您已经掌握了 Sapdon 的基本使用方法。祝您在 Minecraft 模组开发中取得成功！

package/examples/guidebook/build.config

@@ -0,0 +1,33 @@
+{
+  "defaultConfig": {
+    "buildMode":"development",
+    "buildEntry": "main.mjs",
+    "scriptEntry": "scripts/index.js",
+    "buildDir": "dev/",
+    "dependencies": [
+      {
+      "module_name": "@minecraft/server-ui",
+      "version": "1.3.0"
+      },
+      {
+        "module_name": "@minecraft/server",
+        "version": "1.17.0"
+      }
+    ]
+  },
+  "libraries": [
+    {
+      "path": "lib/"
+    }
+  ],
+  "resources": [
+    {
+      "path": "res/"
+    }
+  ],
+  "scripts": [
+    {
+      "path": "scripts/"
+    }
+  ]
+}

package/examples/guidebook/dev/guidebook_BP/items/sapdon_test_guidebook.json

@@ -0,0 +1,19 @@
+{
+  "format_version": "1.21.40",
+  "minecraft:item": {
+    "description": {
+      "identifier": "sapdon:test_guidebook",
+      "menu_category": {
+        "category": "items",
+        "is_hidden_in_commands": false
+      }
+    },
+    "components": {
+      "minecraft:icon": "masterball",
+      "minecraft:max_stack_size": 64,
+      "minecraft:custom_components": [
+        "sapdon:custom_guidebook"
+      ]
+    }
+  }
+}

package/examples/{masterball/dev/masterball_BP/masterball_BP_1_20_20 → guidebook/dev/guidebook_BP}/manifest.json

@@ -1,60 +1,64 @@
-{
-  "format_version": 2,
-  "header": {
-    "name": "examples/masterball_BP",
-    "description": "神奇的大师球",
-    "version": [
-      1,
-      0,
-      0
-    ],
-    "uuid": "1fb20a92-2e4a-4eac-aaf5-bbb2a8559501",
-    "min_engine_version": [
-      1,
-      20,
-      20
-    ]
-  },
-  "modules": [
-    {
-      "description": "行为模块",
-      "type": "data",
-      "uuid": "36f6e998-997f-4212-9708-2b5806306eb9",
-      "version": [
-        1,
-        0,
-        0
-      ]
-    },
-    {
-      "description": "脚本模块",
-      "type": "script",
-      "uuid": "f5593d7d-ef12-4690-b4aa-1905870e8ceb",
-      "version": [
-        1,
-        0,
-        0
-      ],
-      "entry": "scripts/index.js"
-    }
-  ],
-  "dependencies": [
-    {
-      "module_name": "@minecraft/server",
-      "version": "1.8.0"
-    }
-  ],
-  "metadata": {
-    "authors": [
-      "@sapdon"
-    ],
-    "license": "MIT",
-    "generated_with": {
-      "sapdon": [
-        "1.0.0"
-      ]
-    },
-    "product_type": "addon",
-    "url": "https://github.com/junjun260/sapdon"
-  }
+{
+  "format_version": 2,
+  "header": {
+    "name": "guidebook_BP",
+    "description": "通用指导手册",
+    "version": [
+      1,
+      0,
+      0
+    ],
+    "uuid": "be2cf27b-ed81-4ded-92a9-e04db9965eff",
+    "min_engine_version": [
+      1,
+      19,
+      50
+    ]
+  },
+  "modules": [
+    {
+      "description": "行为模块",
+      "type": "data",
+      "uuid": "d6839719-7bb7-41cd-9e5d-a2bf0324e622",
+      "version": [
+        1,
+        0,
+        0
+      ]
+    },
+    {
+      "description": "脚本模块",
+      "type": "script",
+      "uuid": "7e80e5f7-f53f-4631-b270-3b4a721dc320",
+      "version": [
+        1,
+        0,
+        0
+      ],
+      "entry": "scripts/index.js"
+    }
+  ],
+  "dependencies": [
+    {
+      "module_name": "@minecraft/server-ui",
+      "version": "1.3.0"
+    },
+    {
+      "module_name": "@minecraft/server",
+      "version": "1.17.0"
+    }
+  ],
+  "metadata": {
+    "authors": [
+      "@sapdon"
+    ],
+    "license": "MIT",
+    "generated_with": {
+      "sapdon": [
+        "1.0.0"
+      ]
+    },
+    "product_type": "addon",
+    "url": "https://github.com/junjun260/sapdon"
+  }
 }

package/examples/guidebook/dev/guidebook_BP/scripts/custom_components/cropComponent.js

@@ -0,0 +1,50 @@
+import { EquipmentSlot, GameMode, world } from "@minecraft/server";
+
+/**
+ * @param {number} min The minimum integer
+ * @param {number} max The maximum integer
+ * @returns {number} A random integer between the `min` and `max` parameters (inclusive)
+ */
+const randomInt = (min, max) => Math.floor(Math.random() * (max - min + 1)) + min;
+
+const maxGrowth = 3;
+
+/** @type {import("@minecraft/server").BlockCustomComponent} */
+export const CustomCropGrowthBlockComponent = {
+    onRandomTick({ block }) {
+        const growthChance = 1 / 3;
+        if (Math.random() > growthChance) return;
+
+        const growth = block.permutation.getState("sapdon:block_variant_tag");
+        block.setPermutation(block.permutation.withState("sapdon:block_variant_tag", growth + 1));
+    },
+    onPlayerInteract({ block, dimension, player }) {
+        if (!player) return;
+
+        const equippable = player.getComponent("minecraft:equippable");
+        if (!equippable) return;
+
+        const mainhand = equippable.getEquipmentSlot(EquipmentSlot.Mainhand);
+        if (!mainhand.hasItem() || mainhand.typeId !== "minecraft:bone_meal") return;
+
+        if (player.getGameMode() === GameMode.creative) {
+            // Grow crop fully
+            block.setPermutation(block.permutation.withState("sapdon:block_variant_tag", maxGrowth));
+        } else {
+            let growth = block.permutation.getState("sapdon:block_variant_tag");
+
+            // Add random amount of growth
+            growth += randomInt(1, maxGrowth - growth);
+            block.setPermutation(block.permutation.withState("sapdon:block_variant_tag", growth));
+
+            // Decrement stack
+            if (mainhand.amount > 1) mainhand.amount--;
+            else mainhand.setItem(undefined);
+        }
+
+        // Play effects
+        const effectLocation = block.center();
+        dimension.playSound("item.bone_meal.use", effectLocation);
+        dimension.spawnParticle("minecraft:crop_growth_emitter", effectLocation);
+    },
+};

package/examples/guidebook/dev/guidebook_BP/scripts/custom_components/items/gui_book.js

@@ -0,0 +1,37 @@
+import { world } from "@minecraft/server";
+import { ActionFormData} from "@minecraft/server-ui";
+
+const item_ui_list ={
+    "sapdon:test_guidebook":"guidebook"
+};
+
+var page_index = 0;
+/** @type {import("@minecraft/server").ItemCustomComponent} */
+export const GuiBookItemComponent = {
+    onUse({itemStack,source}){
+        if(source.typeId != "minecraft:player") return
+        showGuidebook(source,item_ui_list[itemStack.typeId])
+    }
+}
+
+function showGuidebook(target,ui){
+    const form = new ActionFormData()
+    .title(ui)
+    .body("page_index"+ page_index)
+    .button("test1")
+    .button("test2")
+    
+    form.show(target).then((response) => {
+        if (response.selection === 0) {
+            page_index--;
+            world.sendMessage("上一页")
+            showGuidebook(target,ui)
+
+        }
+        else if (response.selection === 1) {
+            page_index++;
+            world.sendMessage("下一页")
+            showGuidebook(target,ui)
+        }
+    });
+}

package/examples/guidebook/dev/guidebook_BP/scripts/custom_components/registry.js

@@ -0,0 +1,20 @@
+
+import { CustomCropGrowthBlockComponent } from "./cropComponent.js";
+import { GuiBookItemComponent } from "./items/gui_book.js";
+import { world } from "@minecraft/server";
+
+export const registerCustomItemComponent = ()=>{
+    world.beforeEvents.worldInitialize.subscribe(({ itemComponentRegistry }) => {
+        itemComponentRegistry.registerCustomComponent("sapdon:custom_guidebook",GuiBookItemComponent);
+    });
+}
+
+export const registerCustomBlockComponent = ()=>{
+    world.beforeEvents.worldInitialize.subscribe(({ blockComponentRegistry }) => {
+        blockComponentRegistry.registerCustomComponent(
+            "sapdon:crop_growth",
+            CustomCropGrowthBlockComponent
+        );
+    });
+}
+

package/examples/guidebook/dev/guidebook_BP/scripts/index.js

@@ -0,0 +1,3 @@
+import { registerCustomItemComponent } from "./custom_components/registry.js";
+
+registerCustomItemComponent();

package/examples/guidebook/dev/guidebook_RP/blocks.json

@@ -0,0 +1,3 @@
+{
+  "format_version": "1.20.20"
+}

package/examples/guidebook/dev/guidebook_RP/manifest.json

@@ -0,0 +1,44 @@
+{
+  "format_version": 2,
+  "header": {
+    "name": "guidebook_RP",
+    "description": "通用指导手册",
+    "version": [
+      1,
+      0,
+      0
+    ],
+    "uuid": "eb2cf275-03c8-4fc5-95dc-a369e4dcc2e5",
+    "min_engine_version": [
+      1,
+      19,
+      50
+    ]
+  },
+  "modules": [
+    {
+      "description": "资源模块",
+      "type": "resources",
+      "uuid": "1f769715-49a4-440b-a33d-08dedb861460",
+      "version": [
+        1,
+        0,
+        0
+      ]
+    }
+  ],
+  "dependencies": [],
+  "metadata": {
+    "authors": [
+      "@sapdon"
+    ],
+    "license": "MIT",
+    "generated_with": {
+      "sapdon": [
+        "1.0.0"
+      ]
+    },
+    "product_type": "addon",
+    "url": "https://github.com/junjun260/sapdon"
+  }
+}