Skip to content

Dev coolfish #39

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 5 commits into from
May 12, 2026
Merged

Dev coolfish #39

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d760d97
feat(client): 新增音频 API，支持音效与音乐控制
ifishcool May 12, 2026
bb8f63d
feat(neoforge): 添加 Color Zone 模组并更新模组元数据
ifishcool May 12, 2026
20a7a75
docs: 重构类型定义并添加综合指南
ifishcool May 12, 2026
5630ed6
docs(tutorial): 更新英文教程链接，添加 _en 后缀
ifishcool May 12, 2026
4f1d45d
docs: 新增指南并更新文档结构
ifishcool May 12, 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
122 changes: 27 additions & 95 deletions Box3JS-NeoForge-1.21.1/META-INF/neoforge.mods.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,95 +1,27 @@
# This is an example neoforge.mods.toml file. It contains the data relating to the loading mods.
# There are several mandatory fields (#mandatory), and many more that are optional (#optional).
# The overall format is standard TOML format, v0.5.0.
# Note that there are a couple of TOML lists in this file.
# Find more information on toml format here: https://github.com/toml-lang/toml

# The name of the mod loader type to load - for regular FML @Mod mods it should be javafml
modLoader="javafml" #mandatory

# A version range to match for said mod loader - for regular FML @Mod it will be the FML version. This is currently 2.
loaderVersion="${loader_version_range}" #mandatory

# The license for you mod. This is mandatory metadata and allows for easier comprehension of your redistributive properties.
# Review your options at https://choosealicense.com/. All rights reserved is the default copyright stance, and is thus the default here.
license="${mod_license}"

# A URL to refer people to when problems occur with this mod
#issueTrackerURL="https://change.me.to.your.issue.tracker.example.invalid/" #optional

# A list of mods - how many allowed here is determined by the individual mod loader
[[mods]] #mandatory

# The modid of the mod
modId="${mod_id}" #mandatory

# The version number of the mod
version="${mod_version}" #mandatory

# A display name for the mod
displayName="${mod_name}" #mandatory

# A URL to query for updates for this mod. See the JSON update specification https://docs.neoforged.net/docs/misc/updatechecker/
#updateJSONURL="https://change.me.example.invalid/updates.json" #optional

# A URL for the "homepage" for this mod, displayed in the mod UI
#displayURL="https://change.me.to.your.mods.homepage.example.invalid/" #optional

# A file name (in the root of the mod JAR) containing a logo for display
#logoFile="examplemod.png" #optional

# A text field displayed in the mod UI
#credits="" #optional

# The authors of the mod, displayed in the mod UI (optional)
authors="神岛实验室"

# The description text for the mod (multi line!) (#mandatory)
description='''
Box3JS 为 Minecraft 服务端引入 JavaScript 脚本运行时，支持约 100 项 Box3 API 与 90 余项 Minecraft 扩展 API。无需 Java 基础即可编写服务端脚本。
'''

# The [[mixins]] block allows you to declare your mixin config to FML so that it gets loaded.
#[[mixins]]
#config="${mod_id}.mixins.json"

# The [[accessTransformers]] block allows you to declare where your AT file is.
# If this block is omitted, a fallback attempt will be made to load an AT from META-INF/accesstransformer.cfg
#[[accessTransformers]]
#file="META-INF/accesstransformer.cfg"

# The coremods config file path is not configurable and is always loaded from META-INF/coremods.json

# A dependency - use the . to indicate dependency for a specific modid. Dependencies are optional.
[[dependencies.${mod_id}]] #optional
# the modid of the dependency
modId="neoforge" #mandatory
# The type of the dependency. Can be one of "required", "optional", "incompatible" or "discouraged" (case insensitive).
# 'required' requires the mod to exist, 'optional' does not
# 'incompatible' will prevent the game from loading when the mod exists, and 'discouraged' will show a warning
type="required" #mandatory
# Optional field describing why the dependency is required or why it is incompatible
# reason="..."
# The version range of the dependency
versionRange="[${neo_version},)" #mandatory
# An ordering relationship for the dependency.
# BEFORE - This mod is loaded BEFORE the dependency
# AFTER - This mod is loaded AFTER the dependency
ordering="NONE"
# Side this dependency is applied on - BOTH, CLIENT, or SERVER
side="BOTH"

# Here's another dependency
[[dependencies.${mod_id}]]
modId="minecraft"
type="required"
# This version range declares a minimum of the current minecraft version up to but not including the next major version
versionRange="${minecraft_version_range}"
ordering="NONE"
side="BOTH"

# Features are specific properties of the game environment, that you may want to declare you require. This example declares
# that your mod requires GL version 3.2 or higher. Other features will be added. They are side aware so declaring this won't
# stop your mod loading on the server for example.
#[features.${mod_id}]
#openGLVersion="[3.2,)"
modLoader = "javafml"
loaderVersion = "[1,)"
license = "All Rights Reserved"

[[mods]]
modId = "colorzone"
version = "1.0.0"
displayName = "Color Zone"
description = "Territory Rush — competitive parkour mini-game"
credits = "Box3JS2"
displayURL = "https://github.com/Box3Lab/Box3JS"
issueTrackerURL = "https://github.com/Box3Lab/Box3JS/issues"
logoFile = "logo.png"

[[dependencies.colorzone]]
modId = "neoforge"
type = "required"
versionRange = "[21.1,)"
ordering = "NONE"
side = "BOTH"

[[dependencies.colorzone]]
modId = "box3js"
type = "required"
versionRange = "[0.1.0-neoforge-mc1.21.1-beta,)"
ordering = "NONE"
side = "BOTH"
27 changes: 18 additions & 9 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 @@ -27,13 +27,15 @@ Box3JS 是一个内置于 NeoForge 模组的服务端脚本引擎（Mozilla Rhin
```
config/box3/script/mygame/
├── package.json ← npm 依赖（esbuild、Babel、TypeScript）
├── tsconfig.json
├── tsconfig.base.json ← 公共 TS 编译选项
├── tsconfig.server.json ← 服务端 TS 配置
├── tsconfig.client.json ← 客户端 TS 配置
├── build.mjs ← 构建脚本（esbuild → Babel → Rhino）
├── eslint.config.mjs
├── types/
│ ├── shared.d.ts ← 服务端&客户端共享类型
│ ├── server.d.ts ← 服务端专属类型
│ └── client.d.ts ← 客户端专属类型
│ ├── server/ ← 服务端专属类型（server/entity/player/world/voxels）
│ └── client/ ← 客户端专属类型（client/audio/input/ui/chat）
└── src/
├── server/
│ └── app.ts ← 服务端入口（游戏逻辑）
Expand Down Expand Up @@ -64,9 +66,9 @@ npm install && npm run build
| **TypeScript** | 完整 `.d.ts` 类型声明，esbuild + Babel 编译管线，享受智能提示 |
| **20+ 种事件** | onTick、onPlayerJoin、onChat、onEntityDeath、onBlockActivate、onButtonPressed... |
| **视觉效果** | 13+ 粒子、烟花、闪电、爆炸、音效 |
| **客户端 API** | 键盘输入、屏幕 UI、聊天拦截、客户端存储、SQLite、HTTP、双向事件通道 |
| **客户端 API** | 键盘输入、屏幕 UI、聊天拦截、音效/音乐控制、客户端存储、SQLite、HTTP、双向事件通道 |
| **游戏系统** | 计分板、BossBar、队伍、世界边界、跨脚本通信 |
| **自定义物品** | JSON 配置注册自定义物品（食物、稀有度、附魔光效），动态管理配方 |
| **自定义注册表** | JSON 配置注册方块、物品（食物/工具/盔甲）、音效与创造标签页，编译为独立 JAR |
| **数据持久化** | JSON 存储 + SQLite 数据库（排行榜、经济、玩家数据） |
| **独立打包** | `/box3script compile` 将脚本编译为独立 JAR 模组，便于分发部署 |

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

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

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

## 教程

Expand All @@ -113,7 +116,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 @@ -124,6 +127,11 @@ npm install && npm run build

```
docs/
├── guide/ ← 入门指南
│ ├── README.md 指南总览
│ ├── getting-started.md 从零开始（环境、第一个脚本、调试、发布）
│ ├── architecture.md 运行原理（Rhino 引擎、作用域、构建管线）
│ └── js-vs-java.md JS vs Java 模组开发对比
├── api/ ← API 参考
│ ├── README.md 总览 + 功能速查
│ ├── world.md 世界 API（事件、粒子、烟花、计分板...）
Expand All @@ -134,6 +142,7 @@ docs/
│ ├── database.md 数据库 API（SQLite）
│ ├── http.md HTTP 请求 API
│ ├── client.md 客户端 API（UI、输入、聊天、通讯）
│ ├── registries.md 自定义方块/物品/音效
│ ├── math.md 数学 API（Vector3、Color、Quaternion）
│ └── commands.md /box3script 命令参考
├── tutorial/ ← 入门教程
Expand Down
27 changes: 18 additions & 9 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 @@ -27,13 +27,15 @@ This creates a TypeScript project:
```
config/box3/script/mygame/
├── package.json ← npm dependencies (esbuild, Babel, TypeScript)
├── tsconfig.json
├── tsconfig.base.json ← Shared TS compiler options
├── tsconfig.server.json ← Server-side TS config
├── tsconfig.client.json ← Client-side TS config
├── build.mjs ← build script (esbuild → Babel → Rhino)
├── eslint.config.mjs
├── types/
│ ├── shared.d.ts ← types shared by server & client
│ ├── server.d.ts ← server-only types
│ └── client.d.ts ← client-only types
│ ├── server/ ← server-only types (server/entity/player/world/voxels)
│ └── client/ ← client-only types (client/audio/input/ui/chat)
└── src/
├── server/
│ └── app.ts ← server entry (game logic)
Expand Down Expand Up @@ -64,9 +66,9 @@ Edit `src/app.ts`, re-run `npm run build`, then `/box3script reload mygame` —
| **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, client storage, SQLite, HTTP, bidirectional events |
| **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 items** | JSON-configured items (food, rarity, glint), dynamic recipe management |
| **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 |

Expand All @@ -89,13 +91,14 @@ All `<project>` arguments support **Tab completion**. [Full command reference

| Global | Purpose |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `world` | World state, events, particles, fireworks, lightning, sounds, scoreboards, BossBar, teams, border, custom items |
| `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 |
| `client` · `input` · `ui` · `chat` | Client scripts: lifecycle, keyboard, screen text, chat messages |
| `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`) |
Expand All @@ -104,7 +107,7 @@ All `<project>` arguments support **Tab completion**. [Full command reference
| `GameRGBColor` / `GameRGBAColor` | RGB / RGBA color |
| `GameQuaternion` | Quaternion (rotation math) |

[API Overview →](docs/api/README_en.md) · [Find by Task →](docs/api/README_en.md#find-by-task--i-want-to)
[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)

## Tutorials

Expand All @@ -113,7 +116,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, custom items |
| 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 All @@ -124,6 +127,11 @@ From zero to full mini-games. Every example is TypeScript-compiled and ESLint-ve

```
docs/
├── guide/ ← Getting Started
│ ├── README.md Guide overview
│ ├── 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
├── api/ ← API Reference
│ ├── README.md Overview + find by task
│ ├── world.md World API (events, particles, fireworks, scoreboards...)
Expand All @@ -134,6 +142,7 @@ docs/
│ ├── database.md Database API (SQLite)
│ ├── http.md HTTP request API
│ ├── client.md Client API (UI, input, chat, events)
│ ├── registries.md Custom blocks, items & sounds
│ ├── math.md Math API (Vector3, Color, Quaternion)
│ └── commands.md /box3script command reference
├── tutorial/ ← Tutorials
Expand Down
Loading
Loading