Skip to content

Dev coolfish #41

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 6 commits into from
May 15, 2026
Merged

Dev coolfish #41

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4df6cad
feat(core): 移除 remoteChannel 的客户端检测要求
ifishcool May 13, 2026
e6e5ded
feat(build): 添加 TypeScript 验证任务和编译器警告
ifishcool May 14, 2026
d93e69f
feat(box3js): 添加客户端/服务端双端脚本支持
ifishcool May 14, 2026
ed735c6
docs(README): 增强文档，补充 Box3JS 与 Box3 关系说明
ifishcool May 14, 2026
f8622ca
fix(script): 修正玩家显示名称的字段名
ifishcool May 14, 2026
be4cee5
docs: 更新 BOX3_API_COMPARISON.md 并移除冗余导航
ifishcool May 15, 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
5 changes: 5 additions & 0 deletions Box3JS-NeoForge-1.21.1/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,11 @@ bin/
### Mac OS ###
.DS_Store

### VitePress ###
node_modules/
docs/.vitepress/dist/
docs/.vitepress/cache/

### Minecraft Modding ###
run/
!**/src/**/run/
Expand Down
71 changes: 37 additions & 34 deletions Box3JS-NeoForge-1.21.1/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,9 @@

**无需 Java 知识，用 TypeScript 为你的 Minecraft 服务器创造无限玩法。**

Box3JS 是一个内置于 NeoForge 模组的服务端脚本引擎（Mozilla Rhino），延续了神奇代码岛的 API 风格。告别复杂的 Java 模组开发——写 TypeScript，一键热重载，即时生效。PvP 竞技场、RPG 副本、派对小游戏、世界管理、社交工具，全能用脚本快速实现。
Box3JS 是一个社区驱动的 Minecraft 模组，在服务端嵌入 Mozilla Rhino JavaScript 引擎。它的 API 设计延续了[神奇代码岛](https://box3.fun)（深圳奇梦岛科技有限公司）的风格——把 Box3 平台简洁高效的开发体验带进 Minecraft。告别复杂的 Java 模组开发：写 TypeScript，一键热重载，即时生效。PvP 竞技场、RPG 副本、派对小游戏、世界管理、社交工具，全能用脚本快速实现。

> 了解 Box3JS 与神奇代码岛的关系？→ [Box3JS 与神奇代码岛](docs/guide/about-box3js.md)

## 安装

Expand All @@ -24,7 +26,7 @@ Box3JS 是一个内置于 NeoForge 模组的服务端脚本引擎（Mozilla Rhin

这会创建 TypeScript 项目：

```
````
config/box3/script/mygame/
├── package.json ← npm 依赖（esbuild、Babel、TypeScript）
├── tsconfig.base.json ← 公共 TS 编译选项
Expand All @@ -47,7 +49,7 @@ config/box3/script/mygame/
```bash
cd config/box3/script/mygame
npm install && npm run build
```
````

```
/box3script sandbox mygame # (推荐) 开启沙盒，放心测试
Expand All @@ -58,19 +60,19 @@ npm install && npm run build

## 为什么选择 Box3JS？

| 特性 | 说明 |
| -------------- | -------------------------------------------------------------------------------- |
| **零门槛** | 会 JS/TS 就能写，无需 Gradle、无需 IDE、无需重启 |
| **热重载** | 改代码 → build → reload，秒级生效。开启 `watch` 自动重载 |
| **沙盒保护** | 开启沙盒自动追踪所有脚本修改，关闭时完整回滚，服务器不留痕迹 |
| **TypeScript** | 完整 `.d.ts` 类型声明，esbuild + Babel 编译管线，享受智能提示 |
| **20+ 种事件** | onTick、onPlayerJoin、onChat、onEntityDeath、onBlockActivate、onButtonPressed... |
| **视觉效果** | 13+ 粒子、烟花、闪电、爆炸、音效 |
| **客户端 API** | 键盘输入、屏幕 UI、聊天拦截、音效/音乐控制、客户端存储、SQLite、HTTP、双向事件通道 |
| **游戏系统** | 计分板、BossBar、队伍、世界边界、跨脚本通信 |
| **自定义注册表** | JSON 配置注册方块、物品（食物/工具/盔甲）、音效与创造标签页，编译为独立 JAR |
| **数据持久化** | JSON 存储 + SQLite 数据库（排行榜、经济、玩家数据） |
| **独立打包** | `/box3script compile` 将脚本编译为独立 JAR 模组，便于分发部署 |
| 特性 | 说明 |
| ---------------- | ---------------------------------------------------------------------------------- |
| **零门槛** | 会 JS/TS 就能写，无需 Gradle、无需 IDE、无需重启 |
| **热重载** | 改代码 → build → reload，秒级生效。开启 `watch` 自动重载 |
| **沙盒保护** | 开启沙盒自动追踪所有脚本修改，关闭时完整回滚，服务器不留痕迹 |
| **TypeScript** | 完整 `.d.ts` 类型声明，esbuild + Babel 编译管线，享受智能提示 |
| **20+ 种事件** | onTick、onPlayerJoin、onChat、onEntityDeath、onBlockActivate、onButtonPressed... |
| **视觉效果** | 13+ 粒子、烟花、闪电、爆炸、音效 |
| **客户端 API** | 键盘输入、屏幕 UI、聊天拦截、音效/音乐控制、客户端存储、SQLite、HTTP、双向事件通道 |
| **游戏系统** | 计分板、BossBar、队伍、世界边界、跨脚本通信 |
| **自定义注册表** | JSON 配置注册方块、物品（食物/工具/盔甲）、音效与创造标签页，编译为独立 JAR |
| **数据持久化** | JSON 存储 + SQLite 数据库（排行榜、经济、玩家数据） |
| **独立打包** | `/box3script compile` 将脚本编译为独立 JAR 模组，便于分发部署 |

## 命令

Expand All @@ -89,23 +91,23 @@ npm install && npm run build

## API 速览

| 全局对象 | 用途 |
| -------------------------------- | ----------------------------------------------------------------------------------- |
| `world` | 世界状态、事件回调、粒子、烟花、闪电、音效、计分板、BossBar、队伍、边界 |
| `entity` | 实体属性、AI 寻路、装备、药水效果、标签、导航 |
| `player` | 背包、飞行、游戏模式、传送、消息、经验、音效 |
| `voxels` | 方块读写、区域填充、刷怪笼 |
| `http` | HTTP 网络请求（同步 + 异步，GET/POST/JSON） |
| `remoteChannel` | 服务端 ↔ 客户端双向事件通讯 |
| `registries` | 自定义方块/物品/音效（编译 JAR 模式），见 [registries.md](docs/api/registries.md) |
| `client` · `input` · `ui` · `chat` · `audio` | 客户端脚本：生命周期、键盘、屏幕文字、聊天、音频控制 |
| `storage` | JSON 数据持久化（服务端 & 客户端） |
| `db` | SQLite 数据库（服务端 & 客户端） |
| `console` | 控制台日志输出（`log`/`warn`/`error`/`debug`/`assert`/`clear`） |
| `GameVector3` | 三维向量（坐标运算） |
| `GameBounds3` | 包围盒 |
| `GameRGBColor` / `GameRGBAColor` | RGB/RGBA 颜色 |
| `GameQuaternion` | 四元数（旋转运算） |
| 全局对象 | 用途 |
| -------------------------------------------- | --------------------------------------------------------------------------------- |
| `world` | 世界状态、事件回调、粒子、烟花、闪电、音效、计分板、BossBar、队伍、边界 |
| `entity` | 实体属性、AI 寻路、装备、药水效果、标签、导航 |
| `player` | 背包、飞行、游戏模式、传送、消息、经验、音效 |
| `voxels` | 方块读写、区域填充、刷怪笼 |
| `http` | HTTP 网络请求（同步 + 异步，GET/POST/JSON） |
| `remoteChannel` | 服务端 ↔ 客户端双向事件通讯 |
| `registries` | 自定义方块/物品/音效（编译 JAR 模式），见 [registries.md](docs/api/registries.md) |
| `client` · `input` · `ui` · `chat` · `audio` | 客户端脚本：生命周期、键盘、屏幕文字、聊天、音频控制 |
| `storage` | JSON 数据持久化（服务端 & 客户端） |
| `db` | SQLite 数据库（服务端 & 客户端） |
| `console` | 控制台日志输出（`log`/`warn`/`error`/`debug`/`assert`/`clear`） |
| `GameVector3` | 三维向量（坐标运算） |
| `GameBounds3` | 包围盒 |
| `GameRGBColor` / `GameRGBAColor` | RGB/RGBA 颜色 |
| `GameQuaternion` | 四元数（旋转运算） |

[文档首页 →](docs/README.md) · [API 总览 →](docs/api/README.md) · [按任务速查 →](docs/api/README.md#功能速查---我想)

Expand All @@ -116,7 +118,7 @@ npm install && npm run build
| # | 教程 | 时长 | 学什么 |
| --- | ----------------------------------------------------- | ------ | ---------------------------------------- |
| 1 | [从零开始](docs/tutorial/01-basics.md) | 10 min | 创建项目、第一个脚本、聊天命令、定时任务 |
| 2 | [玩家操控与物品](docs/tutorial/02-player-items.md) | 15 min | 传送、飞行、物品、附魔、药水 |
| 2 | [玩家操控与物品](docs/tutorial/02-player-items.md) | 15 min | 传送、飞行、物品、附魔、药水 |
| 3 | [事件系统与实体](docs/tutorial/03-events-entities.md) | 15 min | 事件回调、实体生成、AI、战斗、巡逻 |
| 4 | [高级游戏系统](docs/tutorial/04-advanced-systems.md) | 15 min | 计分板、BossBar、队伍、边界、跨脚本通信 |
| 5 | [实战小游戏](docs/tutorial/05-examples.md) | 20 min | PvP 竞技场、粒子烟花、波次刷怪、特效大全 |
Expand All @@ -129,6 +131,7 @@ npm install && npm run build
docs/
├── guide/ ← 入门指南
│ ├── README.md 指南总览
│ ├── about-box3js.md Box3JS 与神奇代码岛（起源、关系、优势）
│ ├── getting-started.md 从零开始（环境、第一个脚本、调试、发布）
│ ├── architecture.md 运行原理（Rhino 引擎、作用域、构建管线）
│ └── js-vs-java.md JS vs Java 模组开发对比
Expand Down
5 changes: 4 additions & 1 deletion 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 @@ -6,7 +6,9 @@

**No Java knowledge required. Build unlimited Minecraft gameplay with TypeScript.**

Box3JS is a server-side scripting engine (Mozilla Rhino) built into a NeoForge mod. Forget complex Java mod development — write TypeScript, hot-reload instantly, see changes live. PvP arenas, RPG dungeons, party games, world management, social tools — all achievable with scripts.
Box3JS is a community-driven Minecraft mod (NeoForge 1.21.1) that embeds the Mozilla Rhino JavaScript engine in the server. Its API design is inspired by [Box3](https://box3.fun) (Shenzhen Qimengdao Technology Co., Ltd.) — bringing Box3's clean, efficient developer experience into Minecraft. Forget complex Java mod development: write TypeScript, hot-reload instantly, see changes live. PvP arenas, RPG dungeons, party games, world management, social tools — all achievable with scripts.

> Curious about Box3JS's relationship with the Box3 platform? → [Box3JS & Box3](docs/guide/about-box3js_en.md)

## Installation

Expand Down Expand Up @@ -129,6 +131,7 @@ From zero to full mini-games. Every example is TypeScript-compiled and ESLint-ve
docs/
├── guide/ ← Getting Started
│ ├── README.md Guide overview
│ ├── about-box3js.md Box3JS & Box3 (origin, relationship, advantages)
│ ├── getting-started.md From zero (setup, first script, debug, deploy)
│ ├── architecture.md Internals (Rhino engine, scopes, build pipeline)
│ └── js-vs-java.md JS vs Java modding comparison
Expand Down
11 changes: 11 additions & 0 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 @@ -209,6 +209,17 @@ tasks.named('jar', Jar).configure {

tasks.withType(JavaCompile).configureEach {
options.encoding = 'UTF-8' // Use the UTF-8 charset for Java compilation
options.compilerArgs.addAll(['-Xlint:deprecation', '-Xlint:unchecked'])
}

tasks.register('verifyBox3JSProject', Exec) {
group = 'verification'
description = 'Verifies Box3JS template files, runtime DTS split, and event API token consistency.'
commandLine 'node', 'tools/verify-box3js-project.mjs'
}

tasks.named('check').configure {
dependsOn tasks.named('verifyBox3JSProject')
}

// IDEA no longer automatically downloads sources/javadoc jars for dependencies, so we need to explicitly enable the behavior.
Expand Down
Loading
Loading