Skip to content

Dev coolfish #38

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 3 commits into from
May 11, 2026
Merged

Dev coolfish #38

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
159badb
feat: 新增 HTTP 请求 API 支持
ifishcool May 11, 2026
762abb8
feat(http): 为 HTTP fetch API 添加异步支持
ifishcool May 11, 2026
0b1a3fc
feat: 添加客户端脚本支持及双向通信功能
ifishcool May 11, 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
109 changes: 60 additions & 49 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 @@ -31,10 +31,14 @@ config/box3/script/mygame/
├── build.mjs ← 构建脚本（esbuild → Babel → Rhino）
├── eslint.config.mjs
├── types/
│ └── globals.d.ts ← 完整 API 类型声明（IDE 自动补全）
│ ├── shared.d.ts ← 服务端&客户端共享类型
│ ├── server.d.ts ← 服务端专属类型
│ └── client.d.ts ← 客户端专属类型
└── src/
└── app.ts ← 入口文件，代码写在这里
```
├── server/
│ └── app.ts ← 服务端入口（游戏逻辑）
└── client/
└── app.ts ← 客户端入口（UI/按键/网络）

构建并启动：

Expand All @@ -52,62 +56,67 @@ npm install && npm run build

## 为什么选择 Box3JS？

| 特性 | 说明 |
|------|------|
| **零门槛** | 会 JS/TS 就能写，无需 Gradle、无需 IDE、无需重启 |
| **热重载** | 改代码 → build → reload，秒级生效。开启 `watch` 自动重载 |
| **沙盒保护** | 开启沙盒自动追踪所有脚本修改，关闭时完整回滚，服务器不留痕迹 |
| **TypeScript** | 完整 `.d.ts` 类型声明，esbuild + Babel 编译管线，享受智能提示 |
| **17 种事件** | onTick、onPlayerJoin、onChat、onEntityDeath、onBlockActivate、onButtonPressed... |
| **视觉效果** | 13+ 粒子、烟花、闪电、爆炸、音效 |
| **游戏系统** | 计分板、BossBar、队伍、世界边界、跨脚本通信 |
| **自定义物品** | JSON 配置注册自定义物品（食物、稀有度、附魔光效），动态管理配方 |
| **数据持久化** | JSON 存储 + SQLite 数据库（排行榜、经济、玩家数据） |
| 特性 | 说明 |
| -------------- | -------------------------------------------------------------------------------- |
| **零门槛** | 会 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 配置注册自定义物品（食物、稀有度、附魔光效），动态管理配方 |
| **数据持久化** | JSON 存储 + SQLite 数据库（排行榜、经济、玩家数据） |
| **独立打包** | `/box3script compile` 将脚本编译为独立 JAR 模组，便于分发部署 |

## 命令

| 命令 | 说明 |
|------|------|
| `/box3script` | 查看项目状态总览 |
| `/box3script create <name>` | 创建新 TypeScript 项目 |
| `/box3script start [project\|all]` | 启用并加载项目 |
| `/box3script stop [project\|all]` | 禁用并卸载项目 |
| `/box3script reload [project]` | 重载脚本（开发用） |
| `/box3script watch` | 切换文件监控（自动热重载） |
| `/box3script sandbox <project>` | 切换沙盒模式（开=追踪 / 关=回滚） |
| `/box3script compile <project>` | 编译为独立 JAR 模组（无需 Box3JS） |
| 命令 | 说明 |
| ---------------------------------- | --------------------------------- |
| `/box3script` | 查看项目状态总览 |
| `/box3script create <name>` | 创建新 TypeScript 项目 |
| `/box3script start [project\|all]` | 启用并加载项目 |
| `/box3script stop [project\|all]` | 禁用并卸载项目 |
| `/box3script reload [project]` | 重载脚本（开发用） |
| `/box3script watch` | 切换文件监控（自动热重载） |
| `/box3script sandbox <project>` | 切换沙盒模式（开=追踪 / 关=回滚） |
| `/box3script compile <project>` | 编译为独立 JAR 模组 |

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

## API 速览

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

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

## 教程

从零到完整小游戏，每个示例均经过 TypeScript 编译 + ESLint 验证：

| # | 教程 | 时长 | 学什么 |
|---|------|------|--------|
| 1 | [从零开始](docs/tutorial/01-basics.md) | 10 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 竞技场、粒子烟花、波次刷怪、特效大全 |
| # | 教程 | 时长 | 学什么 |
| --- | ----------------------------------------------------- | ------ | ---------------------------------------- |
| 1 | [从零开始](docs/tutorial/01-basics.md) | 10 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 竞技场、粒子烟花、波次刷怪、特效大全 |

[教程总览 →](docs/tutorial/README.md)

Expand All @@ -123,6 +132,8 @@ docs/
│ ├── voxels.md 方块 API（读写、填充、刷怪笼）
│ ├── storage.md 存储 API（JSON 持久化）
│ ├── database.md 数据库 API（SQLite）
│ ├── http.md HTTP 请求 API
│ ├── client.md 客户端 API（UI、输入、聊天、通讯）
│ ├── math.md 数学 API（Vector3、Color、Quaternion）
│ └── commands.md /box3script 命令参考
├── tutorial/ ← 入门教程
Expand All @@ -137,15 +148,15 @@ docs/

## 示例项目

`run/config/box3/script/colorzone/` 包含完整的领地争夺战游戏和 7 个功能示例，涵盖 Hello World 到波次刷怪的全部教学场景。
`run/config/box3/script/colorzone/` 包含完整的双向通讯游戏和 7 个功能示例，涵盖服务端逻辑、客户端 UI、键盘输入、HTTP 请求、数据库等全部教学场景。

## 依赖说明

| 功能 | 依赖 |
|------|------|
| 脚本引擎核心 | 内嵌 Rhino 1.9.1，无需额外安装 |
| 功能 | 依赖 |
| ------------------ | ------------------------------------------------------------------------------------- |
| 脚本引擎核心 | 内嵌 Rhino 1.9.1，无需额外安装 |
| `db` API（SQLite） | 需安装 [`minecraft-sqlite-jdbc`](https://modrinth.com/mod/minecraft-sqlite-jdbc) 模组 |
| 其他 API | 无额外依赖 |
| 其他 API | 无额外依赖 |

> 未安装 `minecraft-sqlite-jdbc` 时，`db` 以外的所有 API 正常工作。只有调用 `db.sql()` 才会提示需要安装。

Expand Down
Loading
Loading