Skip to content

Dev coolfish #45

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ifishcool merged 2 commits into from
May 21, 2026
Merged

Dev coolfish #45

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
63c355d
docs(readme): 增强命令文档并添加运行时策略说明
ifishcool May 20, 2026
f1a4d37
build(gradle): 添加 icon.png 到资源并移除独立编译器功能
ifishcool May 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion Box3JS-NeoForge-1.21.1/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,10 +85,12 @@ npm install && npm run build
| `/box3script reload [project]` | 重载脚本（开发用） |
| `/box3script watch` | 切换文件监控（自动热重载） |
| `/box3script sandbox <project>` | 切换沙盒模式（开=追踪 / 关=回滚） |
| `/box3script compile <project>` | 编译为独立 JAR 模组 |
| `/box3script compile <project>` | 预检 + 编译为独立 JAR 模组 |

所有 `<project>` 参数支持 **Tab 自动补全**。[完整命令文档 →](docs/api/commands.md)

> 运行策略：若同名脚本 JAR 已被 NeoForge 加载，则 `/box3script start/reload/watch` 会跳过文件模式（jar 优先），避免重复执行。

## API 速览

| 全局对象 | 用途 |
Expand Down
70 changes: 36 additions & 34 deletions Box3JS-NeoForge-1.21.1/README_en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ In-game (requires OP level ≥ 2):

This creates a TypeScript project:

```
````
config/box3/script/mygame/
├── package.json ← npm dependencies (esbuild, Babel, TypeScript)
├── tsconfig.base.json ← Shared TS compiler options
Expand All @@ -49,7 +49,7 @@ Build and start:
```bash
cd config/box3/script/mygame
npm install && npm run build
```
````

```
/box3script sandbox mygame # (recommended) enable sandbox for safe testing
Expand All @@ -60,19 +60,19 @@ Edit `src/app.ts`, re-run `npm run build`, then `/box3script reload mygame` —

## Why Box3JS?

| Feature | Description |
| -------------------- | -------------------------------------------------------------------------------- |
| **Zero barrier** | Know JS/TS? You can build. No Gradle, no IDE, no restarts |
| **Hot reload** | Edit → build → reload in seconds. Enable `watch` for auto-reload |
| **Sandbox** | Toggle sandbox to track all script changes; disable to fully roll back |
| **TypeScript** | Full `.d.ts` type declarations, esbuild + Babel pipeline, IDE IntelliSense |
| **20+ events** | onTick, onPlayerJoin, onChat, onEntityDeath, onBlockActivate, onButtonPressed... |
| **Visual effects** | 13+ particles, fireworks, lightning, explosions, sounds |
| **Client API** | Keyboard input, screen UI, chat interception, sound/music control, client storage, SQLite, HTTP, bidirectional events |
| **Game systems** | Scoreboards, BossBar, teams, world border, cross-script messaging |
| **Custom registries** | JSON-configured blocks, items (food/tools/armor), sounds & creative tabs, compiled to standalone JAR |
| **Data persistence** | JSON storage + SQLite database (leaderboards, economy, player data) |
| **Standalone JAR** | `/box3script compile` packages scripts into a standalone JAR mod for distribution |
| Feature | Description |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Zero barrier** | Know JS/TS? You can build. No Gradle, no IDE, no restarts |
| **Hot reload** | Edit → build → reload in seconds. Enable `watch` for auto-reload |
| **Sandbox** | Toggle sandbox to track all script changes; disable to fully roll back |
| **TypeScript** | Full `.d.ts` type declarations, esbuild + Babel pipeline, IDE IntelliSense |
| **20+ events** | onTick, onPlayerJoin, onChat, onEntityDeath, onBlockActivate, onButtonPressed... |
| **Visual effects** | 13+ particles, fireworks, lightning, explosions, sounds |
| **Client API** | Keyboard input, screen UI, chat interception, sound/music control, client storage, SQLite, HTTP, bidirectional events |
| **Game systems** | Scoreboards, BossBar, teams, world border, cross-script messaging |
| **Custom registries** | JSON-configured blocks, items (food/tools/armor), sounds & creative tabs, compiled to standalone JAR |
| **Data persistence** | JSON storage + SQLite database (leaderboards, economy, player data) |
| **Standalone JAR** | `/box3script compile` packages scripts into a standalone JAR mod for distribution |

## Commands

Expand All @@ -85,29 +85,31 @@ Edit `src/app.ts`, re-run `npm run build`, then `/box3script reload mygame` —
| `/box3script reload [project]` | Reload scripts (for development) |
| `/box3script watch` | Toggle file watching (auto hot-reload) |
| `/box3script sandbox <project>` | Toggle sandbox (on=track / off=rollback) |
| `/box3script compile <project>` | Compile to standalone JAR |
| `/box3script compile <project>` | Preflight + compile to standalone JAR |

All `<project>` arguments support **Tab completion**. [Full command reference →](docs/api/commands_en.md)

> Runtime policy: if a matching script JAR is already loaded by NeoForge, `/box3script start/reload/watch` skips filesystem mode (jar-first) to avoid duplicate execution.

## API Overview

| Global | Purpose |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `world` | World state, events, particles, fireworks, lightning, sounds, scoreboards, BossBar, teams, border |
| `entity` | Entity properties, AI pathfinding, equipment, potion effects, tags, navigation |
| `player` | Inventory, flight, game mode, teleport, messaging, XP, sounds |
| `voxels` | Block read/write, region fill, spawner control |
| `http` | HTTP requests (sync + async, GET/POST/JSON) |
| `remoteChannel` | Server ↔ client bidirectional event channel |
| `registries` | Custom blocks, items & sounds (compiled JAR mode), see [registries_en.md](docs/api/registries_en.md) |
| `client` · `input` · `ui` · `chat` · `audio` | Client scripts: lifecycle, keyboard, screen text, chat, audio control |
| `storage` | JSON data persistence (server & client) |
| `db` | SQLite database (server & client) |
| `console` | Console logging (`log`/`warn`/`error`/`debug`/`assert`/`clear`) |
| `GameVector3` | 3D vector (coordinate math) |
| `GameBounds3` | Bounding box |
| `GameRGBColor` / `GameRGBAColor` | RGB / RGBA color |
| `GameQuaternion` | Quaternion (rotation math) |
| Global | Purpose |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `world` | World state, events, particles, fireworks, lightning, sounds, scoreboards, BossBar, teams, border |
| `entity` | Entity properties, AI pathfinding, equipment, potion effects, tags, navigation |
| `player` | Inventory, flight, game mode, teleport, messaging, XP, sounds |
| `voxels` | Block read/write, region fill, spawner control |
| `http` | HTTP requests (sync + async, GET/POST/JSON) |
| `remoteChannel` | Server ↔ client bidirectional event channel |
| `registries` | Custom blocks, items & sounds (compiled JAR mode), see [registries_en.md](docs/api/registries_en.md) |
| `client` · `input` · `ui` · `chat` · `audio` | Client scripts: lifecycle, keyboard, screen text, chat, audio control |
| `storage` | JSON data persistence (server & client) |
| `db` | SQLite database (server & client) |
| `console` | Console logging (`log`/`warn`/`error`/`debug`/`assert`/`clear`) |
| `GameVector3` | 3D vector (coordinate math) |
| `GameBounds3` | Bounding box |
| `GameRGBColor` / `GameRGBAColor` | RGB / RGBA color |
| `GameQuaternion` | Quaternion (rotation math) |

[Docs Home →](docs/README_en.md) · [API Overview →](docs/api/README_en.md) · [Find by Task →](docs/api/README_en.md#find-by-task--i-want-to)

Expand All @@ -118,7 +120,7 @@ From zero to full mini-games. Every example is TypeScript-compiled and ESLint-ve
| # | Tutorial | Time | What you'll learn |
| --- | -------------------------------------------------------- | ------ | ----------------------------------------------------------------- |
| 1 | [Getting Started](docs/tutorial/01-basics.md) | 10 min | Project setup, first script, chat commands, timers |
| 2 | [Players & Items](docs/tutorial/02-player-items.md) | 15 min | Teleport, flight, items, enchantments, potions |
| 2 | [Players & Items](docs/tutorial/02-player-items.md) | 15 min | Teleport, flight, items, enchantments, potions |
| 3 | [Events & Entities](docs/tutorial/03-events-entities.md) | 15 min | Event callbacks, entity spawning, AI, combat, patrols |
| 4 | [Advanced Systems](docs/tutorial/04-advanced-systems.md) | 15 min | Scoreboards, BossBar, teams, world border, cross-script messaging |
| 5 | [Mini-Games](docs/tutorial/05-examples.md) | 20 min | PvP arena, particles & fireworks, wave mobs, visual effects |
Expand Down
13 changes: 5 additions & 8 deletions Box3JS-NeoForge-1.21.1/build.gradle
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,6 +179,11 @@ var generateModMetadata = tasks.register("generateModMetadata", ProcessResources
from "src/main/templates"
into "build/generated/sources/modMetadata"
}

tasks.named('processResources', ProcessResources).configure {
from(project.layout.projectDirectory.file('icon.png'))
}

// Include the output of "generateModMetadata" as an input directory for the build
// this works with both building through Gradle and the IDE.
sourceSets.main.resources.srcDir generateModMetadata
Expand All @@ -199,14 +204,6 @@ publishing {
}
}

// Make the mod JAR executable as a standalone script compiler tool.
// Usage: java -jar box3js.jar --project <dir> --output <jar> --modId <id> --name <name>
tasks.named('jar', Jar).configure {
manifest {
attributes('Main-Class': 'com.box3lab.box3js.standalone.Box3ScriptCompiler')
}
}

tasks.withType(JavaCompile).configureEach {
options.encoding = 'UTF-8' // Use the UTF-8 charset for Java compilation
options.compilerArgs.addAll(['-Xlint:deprecation', '-Xlint:unchecked'])
Expand Down
61 changes: 40 additions & 21 deletions Box3JS-NeoForge-1.21.1/docs/api/commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,11 @@

Watch: ● Active Sandbox: ● 1 project(s)

Projects: 1/2 enabled | 1 loaded
Projects: 1/2 enabled | 1 loaded | 1 jar-priority

────────────────────────────
● colorzone ▐SANDBOX▌
◆ mygame ▐JAR_PRIORITY▌
◌ demo
────────────────────────────

Expand All @@ -32,8 +33,9 @@
New /box3script create <name>
```

- `◉` = 已加载运行中，`○` = 已启用但未加载，`◌` = 已禁用
- `◉` = 已加载运行中，`◆` = 已由同名脚本 JAR 接管（jar 优先），`○` = 已启用但未加载，`◌` = 已禁用
- `▐SANDBOX▌` = 沙盒已开启
- `▐JAR_PRIORITY▌` = 当前项目检测到对应脚本 JAR 已加载，文件模式将被跳过

### `/box3script create <name>`

Expand Down Expand Up @@ -73,6 +75,10 @@ npm install && npm run build
/box3script start mygame # 只启用 mygame
```

::: info JAR 优先
若检测到项目对应的脚本 JAR 已被 NeoForge 加载，`start` 会跳过文件模式加载并提示 `jar has priority`，避免同一项目重复运行。
:::

### `/box3script stop [project|all]`

禁用并卸载项目。**不带参数** = 禁用全部。**带项目名** = 只禁用指定项目。**`all`** = 显式禁用全部。
Expand All @@ -94,6 +100,10 @@ npm install && npm run build

修改代码并 `npm run build` 后，用 `reload` 刷新。或者开启 `watch` 自动重载。

::: info JAR 优先
若同名脚本 JAR 已加载，`reload` 会跳过文件模式重载（同样遵循 jar 优先）。
:::

### `/box3script watch`

开启/关闭文件监听。监听所有项目的 `dist/` 目录，`.js` 文件变化时自动重载对应项目。
Expand All @@ -102,6 +112,8 @@ npm install && npm run build
/box3script watch # 切换 开/关
```

当某项目处于 `JAR_PRIORITY` 状态时，watcher 也会跳过该项目的文件重载。

### `/box3script sandbox <project>`

切换沙盒模式。开启后自动追踪该项目所有的方块/实体/世界状态变更，关闭时回滚并显示摘要。
Expand Down Expand Up @@ -135,6 +147,13 @@ npm install && npm run build
/box3script compile mygame
```

`compile` 会先执行内置预检（preflight），在真正打包前输出：

- `warnings`（警告，不阻止编译）
- `problems`（问题，阻止编译）

预检覆盖构建产物、`package.json` 元数据、NeoForge 约束（如 `modId`/`logoFile`）等关键项。

::: warning 依赖
脚本 JAR 不包含 Rhino 或 Box3JS API 类，需将 Box3JS 模组（`box3js`）一同放入 `mods/`。
:::
Expand All @@ -149,17 +168,17 @@ npm install && npm run build
`name` 字段的 modId 会在编译时校验，必须符合 `^[a-z][a-z0-9_]{1,63}$`（小写字母开头，仅含小写字母/数字/下划线，2-64 字符）。不符合的 modId 会导致编译失败并提示具体原因。
:::

| package.json | mods.toml 字段 | 说明 |
|-------------|---------------|------|
| `name` | `modId` | 模组 ID |
| `displayName` | `displayName` | 模组显示名称（默认同 `name`） |
| `version` | `version` | 版本号 |
| `description` | `description` | 模组简介 |
| `author` | `credits` | 作者/致谢 |
| `license` | `license` | 许可证（默认 `All Rights Reserved`） |
| `homepage` | `displayURL` | 项目主页链接 |
| `bugs.url` | `issueTrackerURL` | 问题反馈链接 |
| `logoFile` | `logoFile` | 模组图标（项目中的 PNG 路径，打包为 `logo.png`） |
| package.json | mods.toml 字段 | 说明 |
| ------------- | ----------------- | ------------------------------------------------ |
| `name` | `modId` | 模组 ID |
| `displayName` | `displayName` | 模组显示名称（默认同 `name`） |
| `version` | `version` | 版本号 |
| `description` | `description` | 模组简介 |
| `author` | `credits` | 作者/致谢 |
| `license` | `license` | 许可证（默认 `All Rights Reserved`） |
| `homepage` | `displayURL` | 项目主页链接 |
| `bugs.url` | `issueTrackerURL` | 问题反馈链接 |
| `logoFile` | `logoFile` | 模组图标（项目中的 PNG 路径，打包为 `logo.png`） |

::: tip logoFile 使用说明
填写项目根目录下的 PNG 文件相对路径（如 `"logoFile": "logo.png"`），编译时自动打包为 JAR 根目录的 `logo.png`，无需在 `neoforge.mods.toml` 中手动配置。NeoForge 建议尺寸 128×128 或 256×256，仅支持 PNG 格式。不填则使用默认模组图标。
Expand Down Expand Up @@ -199,14 +218,14 @@ mods/

**与解释模式的区别：**

| | 解释模式 | 编译模式 |
|---|---|---|
| 加载方式 | `/box3script start` | 放入 `mods/` 启动服务器 |
| 命令管理 | `/box3script start/stop/reload` | 不受 `/box3script` 管理 |
| 启用/禁用 | `/box3script start/stop` | 增删 `mods/` 下的 JAR，重启服务器 |
| 需要 Box3JS | 是 | 是 |
| 热重载 | 支持 | 不支持（JAR 重启才生效） |
| 适用场景 | 开发调试 | 分发部署 |
| | 解释模式 | 编译模式 |
| ----------- | ------------------------------- | --------------------------------- |
| 加载方式 | `/box3script start` | 放入 `mods/` 启动服务器 |
| 命令管理 | `/box3script start/stop/reload` | 不受 `/box3script` 管理 |
| 启用/禁用 | `/box3script start/stop` | 增删 `mods/` 下的 JAR，重启服务器 |
| 需要 Box3JS | 是 | 是 |
| 热重载 | 支持 | 不支持（JAR 重启才生效） |
| 适用场景 | 开发调试 | 分发部署 |

::: warning
编译后的 JAR 是标准 NeoForge mod，由 NeoForge mod loader 管理，**不受** `/box3script start/stop/reload` 控制。多个编译 JAR 可同时放入 `mods/`，各自独立运行，互不干扰。
Expand Down
Loading
Loading