ci(workflow): 添加 Fabric 26.2 构建任务

.github/workflows/build.yml

@@ -111,6 +111,32 @@ jobs:
           name: Fabric-26.1-artifact
           path: Fabric-26.1/build/libs/
 
+  build-fabric-26-2:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: checkout repository
+        uses: actions/checkout@v4
+      - name: validate gradle wrapper
+        uses: gradle/actions/wrapper-validation@v4
+      - name: setup jdk
+        uses: actions/setup-java@v4
+        with:
+          java-version: "25"
+          distribution: "microsoft"
+      - name: make gradle wrapper executable
+        working-directory: ./Fabric-26.2
+        run: chmod +x ./gradlew
+
+      - name: build Fabric 26.2
+        working-directory: ./Fabric-26.2
+        run: ./gradlew build
+
+      - name: upload artifacts Fabric 26.2
+        uses: actions/upload-artifact@v4
+        with:
+          name: Fabric-26.2-artifact
+          path: Fabric-26.2/build/libs/
+
   build-neoforge-1-21-1:
     runs-on: ubuntu-24.04
     steps:

AGENTS.md

@@ -6,7 +6,7 @@ This file provides guidance to Codex (Codex.ai/code) when working with code in t
 
 Box3Blocks is a Minecraft mod that imports 372 decorative blocks from the Box3 platform into Minecraft, supporting terrain file import/export and model items. It also includes **Box3JS**, a server-side TypeScript/JavaScript scripting engine (Rhino) for creating custom gameplay, mini-games, and world interactions.
 
-The repository is a **multi-project monorepo** with 7 independent subprojects targeting different mod loaders and Minecraft versions. There is no root build system — each subproject has its own Gradle wrapper and `build.gradle`.
+The repository is a **multi-project monorepo** with 8 independent subprojects targeting different mod loaders and Minecraft versions. There is no root build system — each subproject has its own Gradle wrapper and `build.gradle`.
 
 ## Subprojects
 
@@ -16,11 +16,12 @@ The repository is a **multi-project monorepo** with 7 independent subprojects ta
 | `Fabric-1.21.1/`   | Fabric   | 1.21.1     | 21   | `fabric-loom-remap`                      |
 | `Fabric-1.21.11/`  | Fabric   | 1.21.11    | 21   | `fabric-loom-remap`                      |
 | `Fabric-26.1/`     | Fabric   | 26.1       | 25   | `fabric-loom`                            |
+| `Fabric-26.2/`     | Fabric   | 26.2       | 25   | `fabric-loom`                            |
 | `Forge-1.20.1/`    | Forge    | 1.20.1     | 17   | `net.minecraftforge.gradle` v6.x         |
 | `NeoForge-1.21.1/` | NeoForge | 1.21.1     | 21   | **Box3JS lives here** — NeoForge ModDevGradle |
 | `NeoForge-26.1/`   | NeoForge | 26.1       | 25   | NeoForge ModDevGradle                    |
 
-Only NeoForge-1.21.1 has the Box3JS scripting engine. The other 6 subprojects are purely the Box3Blocks decorative block mod.
+Only NeoForge-1.21.1 has the Box3JS scripting engine. The other 7 subprojects are purely the Box3Blocks decorative block mod.
 
 ## Build Commands
 
@@ -36,7 +37,7 @@ cd run/config/box3/script/colorzone
 npm install && npm run build       # esbuild → Babel → Rhino target
 ```
 
-**Important:** Forge-1.20.1 requires Java 17. All other subprojects use Java 21+. NeoForge-26.1 uses Java 25.
+**Important:** Forge-1.20.1 requires Java 17. Fabric-1.21.1 and Fabric-1.21.11 use Java 21. Fabric-26.1, Fabric-26.2, and NeoForge-26.1 use Java 25.
 
 There are no existing tests (`src/test` directories are empty).
 
@@ -45,7 +46,7 @@ There are no existing tests (`src/test` directories are empty).
 Shared resources are centralized to avoid ~20,000 duplicate asset files:
 
 - **`shared-resources/`** — used by ALL subprojects: block textures, models, blockstates, item models, worldgen data, `block-id.json`, `block-spec.json`
-- **`shared-resources-fabric/`** — used by all 4 Fabric subprojects: `models/item/` JSONs + lang files
+- **`shared-resources-fabric/`** — used by all 5 Fabric subprojects: `models/item/` JSONs + lang files
 - **`shared-resources-forge/`** — used by Forge + both NeoForge subprojects: `models/item/` JSONs + lang files
 
 ## Block Mod Architecture
@@ -125,10 +126,11 @@ Consumable/Cooldown/Enchantable/JukeboxPlayable components are NOT available in
 
 ## Version Differences
 
-- `VoxelExport` only in Fabric-1.21.11, Fabric-26.1, and Forge/NeoForge variants
+- `VoxelExport` only in Fabric-1.21.11, Fabric-26.1, Fabric-26.2, and Forge/NeoForge variants
 - `VoxelFluidRenderHandler` only in Fabric-1.21.11
 - NeoForge-26.1 moved client code to `src/client/java`
-- Fabric-26.1 uses `fabric-loom` (not `fabric-loom-remap`) and Java 25
+- Fabric-26.1 and Fabric-26.2 use `fabric-loom` (not `fabric-loom-remap`) and Java 25
+- Fabric-26.2 uses `EntityTypes.ITEM_DISPLAY` (not `EntityType.ITEM_DISPLAY`) and `Vec3.atCenterOf()` (not `BlockPos.getCenter()`)
 
 ## Tools
 

Box3JS-NeoForge-1.21.1/README_NEW.md

@@ -0,0 +1,79 @@
+# Box3JS — Minecraft Scripting Engine
+
+> **Beta** — APIs may change during early development. Feedback is welcome.
+
+**No Java, just TypeScript.** Build Minecraft minigames, RPG systems, and world mechanics with scripts that hot-reload in seconds.
+
+Built on Mozilla Rhino, Box3JS brings the Box3 coding style to Minecraft servers. Write TypeScript, run it instantly — no JDK, no Gradle, no server restarts.
+
+## Features
+
+- **TypeScript-first** — Full type declarations (`.d.ts`) with bilingual JSDoc, auto-complete in any editor
+- **Box3-compatible API** — World, Entity, Player, Voxels, Storage, Database, HTTP, remoteChannel
+- **110+ Minecraft extensions** — Scoreboards, BossBars, teams, world border, particles, fireworks, potions, custom blocks/items/sounds registration, and more
+- **Client-side scripting** — Custom HUD, keyboard input, audio playback, client-side SQLite & HTTP
+- **Project isolation** — Run multiple script projects independently, each with its own scope and callbacks
+- **Sandbox mode** — Test safely; roll back all script-made changes on stop
+- **Standalone compilation** — `/box3script compile` packages your script into a distributable JAR
+
+## Quick Start
+
+```
+/box3script create mygame
+```
+
+```
+npm install && npm run build
+```
+
+```
+/box3script sandbox mygame
+/box3script start mygame
+```
+
+Full guide: [https://docs.box3lab.com/box3js-mc](https://docs.box3lab.com/box3js-mc)
+
+## License
+
+Apache License 2.0
+
+---
+
+# Box3JS（神岛代码）— Minecraft 脚本引擎
+
+> **Beta** — 早期测试阶段，API 可能变动，欢迎反馈。
+
+**不写 Java，只用 TypeScript。** 在 Minecraft 里用脚本开发小游戏、RPG 玩法、世界机制，热重载秒级生效。
+
+Box3JS 基于 Mozilla Rhino 引擎，延续了神奇代码岛的 API 风格。无需 JDK、无需 Gradle、无需重启服务器，写 TypeScript 即写即跑。
+
+## 特性
+
+- **TypeScript 优先** — 完整类型声明（`.d.ts`），双语 JSDoc，任意编辑器均有自动补全
+- **Box3 兼容 API** — World / Entity / Player / Voxels / Storage / Database / HTTP / remoteChannel
+- **110+ MC 扩展** — 记分板、Bossbar、队伍、世界边界、粒子、烟花、药水、自定义方块/物品/音效注册等
+- **客户端脚本** — 自定义 HUD、键盘输入、音效播放、客户端 SQLite & HTTP
+- **项目隔离** — 多脚本项目独立运行，各自拥有独立作用域和回调
+- **沙盒模式** — 放心测试，停止后回滚一切脚本改动
+- **独立编译** — `/box3script compile` 一键打包为可分发 JAR
+
+## 快速开始
+
+```
+/box3script create mygame
+```
+
+```
+npm install && npm run build
+```
+
+```
+/box3script sandbox mygame
+/box3script start mygame
+```
+
+完整教程：[https://docs.box3lab.com/box3js-mc](https://docs.box3lab.com/box3js-mc)
+
+## 许可证
+
+Apache License 2.0

Box3JS-NeoForge-1.21.1/docs/en/index.md

@@ -3,76 +3,61 @@ layout: home
 
 hero:
   name: "Box3JS"
-  text: "JS/TS Scripting Engine for Minecraft"
-  tagline: Build custom gameplay, mini-games, and UIs — no JDK, no Java compilation required.
+  text: "TypeScript Scripting Engine for Minecraft"
+  tagline: No Java. No Gradle. No restarts. Write TypeScript, hot-reload in seconds.
   actions:
     - theme: brand
       text: Get Started
       link: /en/guide/getting-started
+    - theme: alt
+      text: Why Box3JS?
+      link: /en/guide/about-box3js
 
 features:
+  - icon: ⚡
+    title: TypeScript, Zero Java
+    details: Full DTS types with bilingual JSDoc for every API. esbuild + Babel pipeline compiles modern TS to ES5 automatically. No JDK, no Gradle, no IDE setup.
+  - icon: 🔄
+    title: Hot Reload in Seconds
+    details: Edit → save → see changes instantly. No server restarts. Built-in file watcher auto-reloads on every save.
   - icon: 🎮
+    title: Box3-Compatible API
+    details: Same clean API style as Box3 (Shenqi Code Island). World, Entity, Player, Voxels, Storage, Database, HTTP, remoteChannel — all as global objects.
+  - icon: 🧩
+    title: 110+ Minecraft Extensions
+    details: Scoreboards, BossBars, teams, world border, particles, fireworks, lightning, potions, custom blocks/items/sounds, and more.
+  - icon: 🖥️
     title: Server & Client Scripting
-    details: Server-side world manipulation, entities, recipes. Client-side keyboard input, screen UI, sounds, SQLite storage, and HTTP requests.
+    details: Server handles game logic and world manipulation. Client handles keyboard input, HUD, audio, custom GUIs. Bidirectional events via remoteChannel.
+  - icon: 🛡️
+    title: Sandbox Protection
+    details: Enable sandbox to auto-track all script changes. Disable to fully roll back. Test fearlessly — your map is always safe.
   - icon: 📦
-    title: TypeScript First
-    details: Full DTS type definitions for all 17 global objects. Built-in esbuild + Babel pipeline transpiles modern TS to Rhino-compatible ES5.
-  - icon: 🔄
-    title: Hot Reload
-    details: Edit scripts and see changes instantly without restarting the server. File watcher auto-reloads on save.
-  - icon: 🌐
-    title: Bidirectional Communication
-    details: remoteChannel enables server↔client event messaging. Server broadcasts to all players; clients reply independently.
+    title: Standalone JAR Distribution
+    details: /box3script compile packages your scripts into a standalone mod. Drop it into mods/ — no Box3JS dependency required.
   - icon: 🗄️
-    title: Dual-Side Storage & Database
-    details: JSON file persistence and SQLite on both server and client. Pagination, atomic updates, counters, and tagged-template queries.
-  - icon: 🧩
-    title: Custom Blocks & Items
-    details: Block textures, item models, equipment, sounds, and creative tabs — all registered from JSON configs (standalone/JAR mode).
-  - icon: 📚
-    title: Comprehensive Docs
-    details: 50+ pages across API reference, progressive tutorials, cookbook recipes, architecture deep-dive, and FAQ — in Chinese and English.
-  - icon: 🚀
-    title: Standalone JAR Mode
-    details: Compile your script project into a self-contained JAR mod. No runtime dependency on Box3JS — just drop it in your mods folder.
+    title: Built-in Persistence
+    details: JSON file storage and SQLite database on both server and client. Leaderboards, player saves, economies — all built-in.
 
 ---
 
 ## Quick Start
 
 ```bash
-# In-game: create a new project
-/box3script create mygame
+/box3script create mygame       # scaffold a TypeScript project
+```
 
-# Build and watch
+```bash
 cd config/box3/script/mygame
-npm install
-npm run build -- --watch
-
-# TypeScript type checking
-npm run check
+npm install && npm run build     # install deps + build
 ```
 
-```ts
-// src/server/app.ts — your first script
-world.onChat((entity, message) => {
-  if (message === "!hello") {
-    entity.player.directMessage(`Hello, ${entity.player.name}!`);
-    return false;
-  }
-  return true;
-});
+```bash
+/box3script sandbox mygame       # enable sandbox (recommended)
+/box3script start mygame         # start the script
 ```
 
-[Read full docs →](/en/guide/getting-started)
-
-## Version Info
+Open `src/server/app.ts`, write your game logic, save, then `/box3script reload mygame`. Enable `/box3script watch` and it auto-reloads on every save.
 
-| Component | Version |
-|-----------|---------|
-| Minecraft | 1.21.1 |
-| Mod Loader | NeoForge |
-| Java | 21 |
-| JS Engine | Mozilla Rhino 1.9.1 (ES5) |
-| TypeScript | via Babel → ES5 |
+[Full documentation →](/en/guide/getting-started)
 

Box3JS-NeoForge-1.21.1/docs/index.md

@@ -3,76 +3,61 @@ layout: home
 
 hero:
   name: "Box3JS"
-  text: "Minecraft JS/TS 脚本引擎"
-  tagline: 神奇代码岛同款编程体验，用 JS/TS 在 Minecraft 里创造小游戏
+  text: "Minecraft TypeScript 脚本引擎"
+  tagline: 不写 Java，不用 Gradle，不用重启。写 TypeScript，热重载秒级生效。
   actions:
     - theme: brand
       text: 快速开始
       link: /guide/getting-started
+    - theme: alt
+      text: 为什么选择 Box3JS？
+      link: /guide/about-box3js
 
 features:
+  - icon: ⚡
+    title: TypeScript，零 Java
+    details: 所有 API 均提供完整 DTS 类型定义 + 双语 JSDoc。esbuild + Babel 构建管线自动转译现代 TS 到 ES5。无需 JDK、Gradle、IDE 配置。
+  - icon: 🔄
+    title: 秒级热重载
+    details: 修改 → 保存 → 即时生效，不需要重启服务端。内置文件监听，保存即自动重载。
   - icon: 🎮
+    title: Box3 兼容 API
+    details: 延续神奇代码岛的简洁 API 风格。World、Entity、Player、Voxels、Storage、Database、HTTP、remoteChannel——全部全局注入，无需 import。
+  - icon: 🧩
+    title: 110+ MC 扩展
+    details: 记分板、Bossbar、队伍、世界边界、粒子、烟花、闪电、药水、自定义方块/物品/音效注册……覆盖常见玩法需求。
+  - icon: 🖥️
     title: 服务端 & 客户端双端脚本
-    details: 服务端：世界操作、实体、合成配方。客户端：键盘输入、屏幕 UI、音效、SQLite 存储、HTTP 请求。
+    details: 服务端处理游戏逻辑和世界操作，客户端处理键盘、HUD、音效、自定义 GUI。通过 remoteChannel 双向实时通信。
+  - icon: 🛡️
+    title: 沙盒保护
+    details: 开启沙盒自动追踪脚本所有改动，关闭沙盒完整回滚。放心测试，不破坏地图。
   - icon: 📦
-    title: TypeScript 优先
-    details: 17 个全局对象全部提供 DTS 类型定义。内置 esbuild + Babel 构建管线，将现代 TS 转译为 Rhino 兼容的 ES5。
-  - icon: 🔄
-    title: 热重载
-    details: 修改脚本即时生效，无需重启服务端。文件监听器在保存时自动重载。
-  - icon: 🌐
-    title: 双向通信
-    details: remoteChannel 实现服务端↔客户端事件消息传递。服务端广播至所有玩家，客户端独立回复。
+    title: 独立 JAR 分发
+    details: /box3script compile 一键编译为独立模组，放入 mods/ 即可运行，无需 Box3JS 依赖。
   - icon: 🗄️
-    title: 双端存储 & 数据库
-    details: 服务端和客户端均支持 JSON 文件持久化与 SQLite。分页查询、原子更新、计数器、标签模板查询。
-  - icon: 🧩
-    title: 自定义方块 & 物品
-    details: 方块纹理、物品模型、装备、音效、创造标签页——全部通过 JSON 配置注册（独立/JAR 模式）。
-  - icon: 📚
-    title: 完善文档
-    details: 50+ 页面，涵盖 API 参考、渐进式教程、常用配方、架构深入解析和常见问题——支持中英双语。
-  - icon: 🚀
-    title: 独立 JAR 模式
-    details: 将脚本项目编译为独立 JAR 模组，无需依赖 Box3JS 运行时——放入 mods 文件夹即可使用。
+    title: 内置持久化
+    details: 服务端和客户端均支持 JSON 文件存储和 SQLite 数据库。排行榜、玩家存档、经济系统——全部内置。
 
 ---
 
 ## 快速开始
 
 ```bash
-# 游戏内：创建新项目
-/box3script create mygame
+/box3script create mygame       # 创建 TypeScript 项目
+```
 
-# 构建并监听
+```bash
 cd config/box3/script/mygame
-npm install
-npm run build -- --watch
-
-# TypeScript 类型检查
-npm run check
+npm install && npm run build     # 安装依赖 + 构建
 ```
 
-```ts
-// src/server/app.ts — 你的第一个脚本
-world.onChat((entity, message) => {
-  if (message === "!hello") {
-    entity.player.directMessage(`你好，${entity.player.name}！`);
-    return false;
-  }
-  return true;
-});
+```bash
+/box3script sandbox mygame       # 开启沙盒（推荐）
+/box3script start mygame         # 启动脚本
 ```
 
-[查看完整文档 →](/guide/getting-started)
-
-## 版本信息
+打开 `src/server/app.ts` 写游戏逻辑，保存后 `/box3script reload mygame`。开启 `/box3script watch` 后保存即自动重载。
 
-| 组件 | 版本 |
-|------|------|
-| Minecraft | 1.21.1 |
-| 模组加载器 | NeoForge |
-| Java | 21 |
-| JS 引擎 | Mozilla Rhino 1.9.1 (ES5) |
-| TypeScript | 通过 Babel → ES5 |
+[完整文档 →](/guide/getting-started)