Dev coolfish

AGENTS.md

@@ -0,0 +1,136 @@
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+
+## Project Overview
+
+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`.
+
+## Subprojects
+
+| Directory          | Loader   | MC Version | Java | Notes                                    |
+| ------------------ | -------- | ---------- | ---- | ---------------------------------------- |
+| `Fabric-1.20.1/`   | Fabric   | 1.20.1     | 17   | `fabric-loom-remap`                      |
+| `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`                            |
+| `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.
+
+## Build Commands
+
+```bash
+# Build a single subproject
+cd NeoForge-1.21.1 && ./gradlew build
+
+# Clean build artifacts
+cd NeoForge-1.21.1 && ./gradlew clean
+
+# Build Box3JS script (in run/config/box3/script/<project>/)
+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.
+
+There are no existing tests (`src/test` directories are empty).
+
+## Shared Resources Architecture
+
+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-forge/`** — used by Forge + both NeoForge subprojects: `models/item/` JSONs + lang files
+
+## Block Mod Architecture
+
+All subprojects (including NeoForge-1.21.1) share the block mod's runtime generation architecture:
+
+- `BlockIndexData` / `BlockIndexUtil` reads `block-id.json` and `block-spec.json` at registration time
+- `VoxelBlockFactories` creates `Block` instances dynamically (no per-block Java classes)
+- Only 6 special blocks have dedicated Java classes: `VoxelBlock`, `GlassVoxelBlock`, `BarrierVoxelBlock`, `BouncePadBlock`, `ConveyorBlock`, `SpiderWebBlock`
+
+## Box3JS Scripting Engine (NeoForge-1.21.1 only)
+
+Box3JS uses Mozilla Rhino to run server-side JavaScript/TypeScript. Scripts live in `run/config/box3/script/<project>/`. Each project has its own isolated scope, callbacks, and tracked state.
+
+### Java Package: `com.box3lab.box3js`
+
+| File | Role |
+|------|------|
+| `Box3JS.java` | `@Mod` entry point, subscribes to NeoForge events, fires callbacks into JS |
+| `script/Box3ScriptEngine.java` | Singleton Rhino engine: load/reload/stop scripts, fire events, manage scopes |
+| `script/Box3ScriptCommand.java` | `/box3script` command handler |
+| `script/Box3ScriptConfig.java` | Config: enabled projects, sandbox state, file watcher |
+| `script/Box3ScriptSandbox.java` | Tracks block/entity/player/world mutations for rollback |
+| `script/Box3ScriptTemplate.java` | Template for `/box3script create` |
+| `script/Box3ScriptWatcher.java` | File watching + auto-reload on `.js` change |
+| `script/Box3JSWorld.java` | `world.*` API: events, entity queries, scoreboard, BossBar, teams, border, particles, fireworks, recipes, structures, custom items |
+| `script/Box3JSEntity.java` | `entity.*` API: position, velocity, HP, tags, AI, equipment, effects |
+| `script/Box3JSPlayer.java` | `player.*` API: inventory, flight, game mode, teleport, XP, food, advancements, tab list |
+| `script/Box3JSVoxels.java` | `voxels.*` API: get/set voxel, fill region, spawner control |
+| `script/Box3JSQuery.java` | `world.querySelectorAll()` / `entitiesInRadius()` etc. |
+| `script/Box3JSEventBus.java` | Per-project callback storage with isolation |
+| `script/Box3JSCallbacks.java` | Callback interface definitions |
+| `script/Box3JSScoreboard.java` | Scoreboard CRUD |
+| `script/Box3JSBossbar.java` | BossBar CRUD |
+| `script/Box3JSTeam.java` | Team CRUD |
+| `script/Box3JSStorage.java` | Per-project JSON file persistence |
+| `script/Box3ScriptUtils.java` | Shared helpers: sound playing, raycast, entity lookAt |
+| `script/GameVector3.java` | 3D vector exposed to JS (`new GameVector3(x, y, z)`) |
+| `script/GameBounds3.java` | AABB bounds |
+| `script/GameRGBColor.java` / `GameRGBAColor.java` | Color types |
+| `script/GameQuaternion.java` | Quaternion math |
+| `script/GameEventHandlerToken.java` | Returned by `world.onXxx()` — has `cancel()` and `active()` |
+| `registries/Box3JSCustomItems.java` | Custom items via Minecraft data components on `minecraft:paper` carrier |
+| `registries/Box3JSRecipeManager.java` | Recipe blacklist via `RecipeManager.replaceRecipes()` |
+
+### DTS Type Constraints
+
+`world.currentTick` and `world.projectName` are **methods** in `globals.d.ts`, not properties:
+```ts
+world.currentTick()  // ✅ returns number
+world.projectName()  // ✅ returns string
+```
+
+### Script Build Pipeline
+
+`build.mjs` in each script project does: `esbuild bundle` → `Babel` (target Rhino 1.9.1) → regex sanitize for Rhino. Entry is always `src/app.ts`, output is `dist/app.js`. Supports `--watch` for hot reload.
+
+### Custom Items System
+
+Uses `minecraft:paper` as carrier with `DataComponents` (CUSTOM_NAME, LORE, CUSTOM_MODEL_DATA, MAX_STACK_SIZE, ENCHANTMENT_GLINT_OVERRIDE, RARITY, FOOD). Client-side textures via resource pack `paper.json` with `custom_model_data` overrides. **No DeferredRegister** — no registry sync needed.
+
+Config: `resourcepacks/box3js-items/items.json` + textures + model JSONs. Loaded via `world.loadCustomItems("box3js-items")`.
+
+Consumable/Cooldown/Enchantable/JukeboxPlayable components are NOT available in NeoForge 21.1.220 (need MC 1.21.2+).
+
+### Recipe Manager
+
+`Box3JSRecipeManager` uses `RecipeManager.replaceRecipes()` (public API, no reflection):
+- `removeRecipe(id)` — filters via replaceRecipes
+- `clearRecipes()` — restores full original list
+- `listRecipes(filter)` — searches by keyword
+
+### Documentation
+
+- `docs/api/` — Full API reference for world, entity, player, voxels, storage, math, commands (Chinese + English)
+- `docs/tutorial/` — 5-part tutorial series (01-basics → 05-examples) with complete PvP arena and parkour game examples
+
+## Version Differences
+
+- `VoxelExport` only in Fabric-1.21.11, Fabric-26.1, 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
+
+## Tools
+
+- **`tools/generate_blocks_fabric.py`** / **`tools/generate_blocks_forge.py`** — generates block registration code
+- **`tools/box3-texture-cut/`** — TypeScript tool for cutting sprite sheets into textures

Box3JS-NeoForge-1.21.1/docs/BOX3_API_COMPARISON.md

@@ -2,7 +2,7 @@
 
 本文档详细对比官方 Box3 平台 API 与 Box3JS 模组（NeoForge 1.21.1）的实现差异。仅涉及**服务端 API**，因为客户端 API（ClientUI、ClientAudio、ClientMedia 等）在 Box3JS 中完全不可用——Minecraft 模组运行在服务端，没有 Box3 平台的客户端渲染环境。
 
-> **图例**: ✅ 已实现 | ⚠️ 部分实现 | ❌ 未实现 | ⬆ MC 独有扩展
+> **图例**: ✅ 已实现 | ⚠️ 部分实现 | ❌ 未实现 | ⬆ 独有扩展
 
 ---
 
@@ -27,9 +27,9 @@
 
 | Box3 API | Box3JS 实现 | 状态 | 差异说明 |
 |----------|-------------|------|---------|
-| `world.projectName` (只读属性) | `world.projectName` (属性) | ✅ | 一致。返回服务端 MOTD 字符串 |
+| `world.projectName()` (只读方法) | `world.projectName` (属性) | ✅ | 返回当前脚本项目名；服务器 MOTD 使用 `world.serverId` |
 | `world.serverId` (属性) | `world.serverId` (读写属性) | ✅ | 一致。映射到服务端 MOTD（get/set） |
-| `world.currentTick` (只读属性) | `world.currentTick` (属性) | ✅ | 一致。返回服务器总 tick 数 |
+| `world.currentTick()` (只读方法) | `world.currentTick` (属性) | ✅ | 返回服务器总 tick 数 |
 | `world.url` (只读属性) | — | ❌ | 未实现。MC 无地图 URL 概念 |
 
 ### 1.2 天气
@@ -217,7 +217,7 @@ Zone 可以设置局部天气/光照/力场参数，这在 MC 服务端无法实
 | `world.clearTimeout(id)` | `world.clearTimeout(id)` | ✅ | 一致 |
 | `world.clearInterval(id)` | `world.clearInterval(id)` | ✅ | 一致 |
 
-**注意**: Box3 的 setTimeout/setInterval 在官方文档中标注为 ⬆ MC 扩展，但 Box3JS 在 `world` 全局对象上直接提供，用法一致。
+**注意**: Box3 的 setTimeout/setInterval 在官方文档中标注为 ，但 Box3JS 在 `world` 全局对象上直接提供，用法一致。
 
 ### 1.15 视觉效果
 

Box3JS-NeoForge-1.21.1/docs/README.md

@@ -36,14 +36,15 @@ Box3JS 是 Minecraft NeoForge 1.21.1 的 JavaScript/TypeScript 脚本引擎模
 
 | 分类 | 文档 | 全局对象 |
 |------|------|---------|
+| **服务端总览** | [server](api/server.md) | 服务端运行边界、事件、玩家/实体、方块、数据、跨端通信 |
 | **世界** | [world](api/world.md) | `world` — 事件、粒子、烟花、音效、计分板 |
 | **实体** | [entity](api/entity.md) | `entity` — 属性、AI、装备、效果 |
 | **玩家** | [player](api/player.md) | `player` — 背包、消息、飞行、传送 |
 | **方块** | [voxels](api/voxels.md) | `voxels` — 读写方块、区域填充 |
 | **存储** | [storage](api/storage.md) | `storage` — JSON 持久化 |
 | **数据库** | [database](api/database.md) | `db` — SQLite 数据库 |
 | **网络** | [http](api/http.md) | `http` — HTTP 请求 |
-| **客户端** | [client](api/client.md) | `audio` `client` `input` `ui` `chat` `remoteChannel` |
+| **客户端** | [client](api/client.md) | `audio` `client` `input` `ui` `chat` `gui` `remoteChannel` |
 | **注册表** | [registries](api/registries.md) | `registries` — 自定义方块/物品/音效 |
 | **数学** | [math](api/math.md) | `GameVector3` `GameBounds3` `GameRGBColor` `GameRGBAColor` `GameQuaternion` |
 | **命令** | [commands](api/commands.md) | `/box3script` CLI 命令 |

Box3JS-NeoForge-1.21.1/docs/README_en.md

@@ -36,14 +36,15 @@ Complete API docs organized by functional category. One document per global obje
 
 | Category | Doc | Globals |
 |----------|-----|---------|
+| **Server Overview** | [server](api/server_en.md) | Server runtime boundary, events, players/entities, blocks, data, cross-side communication |
 | **World** | [world](api/world_en.md) | `world` — events, particles, fireworks, sound, scoreboards |
 | **Entity** | [entity](api/entity_en.md) | `entity` — properties, AI, equipment, effects |
 | **Player** | [player](api/player_en.md) | `player` — inventory, messages, flight, teleport |
 | **Voxels** | [voxels](api/voxels_en.md) | `voxels` — block read/write, region fill |
 | **Storage** | [storage](api/storage_en.md) | `storage` — JSON persistence |
 | **Database** | [database](api/database_en.md) | `db` — SQLite database |
 | **HTTP** | [http](api/http_en.md) | `http` — HTTP requests |
-| **Client** | [client](api/client_en.md) | `audio` `client` `input` `ui` `chat` `remoteChannel` |
+| **Client** | [client](api/client_en.md) | `audio` `client` `input` `ui` `chat` `gui` `remoteChannel` |
 | **Registries** | [registries](api/registries_en.md) | `registries` — custom blocks/items/sounds |
 | **Math** | [math](api/math_en.md) | `GameVector3` `GameBounds3` `GameRGBColor` `GameRGBAColor` `GameQuaternion` |
 | **Commands** | [commands](api/commands_en.md) | `/box3script` CLI commands |