make mini game fully by sapi
npm install sapi-game!依赖 
> 使用纯 ScriptApi 制作基岩版小游戏
---
- 简介
- 安装与使用
- 框架优势
- 架构
- 单局游戏架构
- 系统架构
- 文档与教程
- 示例地图
- 反馈与交流
SAPI-Game 是一款由小阳 x666 研发的,专为 MCBE 小游戏设计的 SAPI 框架。
传统小游戏开发通常依赖命令方块,但命令功能有限,许多复杂逻辑需要使用 SAPI 补充。
SAPI-Game 提供了完整解决方案,将 多层级游戏架构、组件化开发、事件与异步管理 融为一体,使开发者可以专注于游戏逻辑本身,同时充分利用 npm 生态 的工具库。通过 SAPI-Game,你可以轻松构建易维护、可复用、多游戏并行的 MCBE 小游戏项目。
推荐使用 npm+sapi-kit 进行项目构建,其它工具不做保证。
1.安装 sapi-kit
``shell`
npm i -g sapi-kit
2.初始化
`shell`
sapi-kit init
3.安装 SAPI-Game
`shell`
npm i sapi-game
4.在入口文件中配置 SAPI-Game
示例(仅供参考,具体配置请按类型来)
`typescript
import { initSAPIGame } from "sapi-game/main";
import { logLevel } from "sapi-game/utils";
initSAPIGame({
logLevel: logLevel.debug, //日志级别
debugMode: true, //debugMode开关
onEnd() {}, //执行/game end时触发
hub(player) {}, //玩家执行/hub时触发
onJoin(p) {
//玩家进入游戏时执行(可传送到大厅)
},
});
`
- #### 多层级架构
GameEngine → GameState → GameComponent,保证代码清晰、可复用、易维护。
- #### 多游戏支持
轻松运行多个游戏实例,每个实例互不干扰,方便管理并行小游戏。
- #### 事件系统管理
独立 EventManager 与 GameState 生命周期绑定,状态结束时自动清理订阅,避免内存泄漏。
- #### 异步与可取消流程
内置 ScriptRunner 和 runJob 支持可取消的异步任务,安全处理状态切换和延迟逻辑。
- #### 丰富工具集
内置随机、坐标计算、区块计算等常用工具。
- #### 实践验证
框架已在 10+ 小游戏中验证,稳定可靠。
- #### 命令方块特性支持
| 命令方块特性 | SAPI-Game 对应 |
| ---------------- | ------------------- |
| 区块加载才执行 | LazyLoader 组件 |
| 红石断开就不执行 | ScriptRunner |
| 命令方块延迟 | ScriptRunner.wait() |
`mermaid
graph TD
%% ===== 核心引擎部分 =====
subgraph EngineLayer["GameEngine 实例(单局游戏)"]
Context["GameContext(存储游戏全局变量等)"]
PM["PlayerManager(游戏内玩家管理)"]
Engine["GameEngine(状态管理等)"]
Context --> Engine
PM --> Engine
end
subgraph StateA["GameState A"]
A_State["GameStateA"]
A_Event["EventManager_A(独立)"]
A_Runner["RunnerManager"]
A_C1["GameComponent1(实例)"]
A_C2["GameComponent2(实例)"]
A_Runner --- A_State
A_Event --- A_State
A_State --> A_C1
A_State --> A_C2
end
%% ===== 状态 B =====
subgraph StateB["GameState B"]
B_State["GameStateB"]
B_Event["EventManager_B(独立)"]
B_Runner["RunnerManager"]
B_C3["GameComponent3(实例)"]
B_C4["GameComponent4(实例)"]
B_Event --- B_State
B_Runner --- B_State
B_State --> B_C3
B_State --> B_C4
end
%% ===== 连接关系 =====
Engine --> StateA
Engine --> StateB
`
#### GameEngine
控制游戏状态切换,持有全局 Context 与 PlayerManager。
- ##### GameContext
存储游戏上下文信息,如地图、规则、队伍等配置。
- ##### PlayerManager
管理游戏实例内的所有玩家。
#### GameState
定义游戏状态(等待、进行中、结束等),负责组件管理与状态逻辑。
- ##### EventManager
事件系统,生命周期与 State 一致,State 结束后自动清理。
- ##### RunnerManager
管理可取消的异步任务(scriptRunner),确保状态切换时安全中断。
#### GameComponent
功能组件,例如资源生成、地图刷新、边界控制等。组件可访问 Context、订阅事件、调用 Runner。
`mermaid
graph LR
subgraph Manager["GameManager(主控)"]
GM["GameManager"]
end
subgraph Instances["游戏实例"]
subgraph Game1["Game1(GameEngine 实例)"]
G1_Engine["GameEngine"]
G1_PM["PlayerManager(实例内)"]
G1_Engine --> G1_PM
end
subgraph Game2["Game2(GameEngine 实例)"]
G2_Engine["GameEngine"]
G2_PM["PlayerManager(实例内)"]
G2_Engine --> G2_PM
end
subgraph Game3["Game3(GameEngine 实例)"]
G3_Engine["GameEngine"]
G3_PM["PlayerManager(实例内)"]
G3_Engine --> G3_PM
end
end
%% 右侧:全局系统
subgraph Global["全局支持层"]
GameEvent["GameEvents(预定义游戏事件)"]
GlobalPM["GlobalPlayerManager(全局玩家管理)"]
end
%% 连接关系
GM --> Game1
GM --> Game2
GM --> Game3
G1_PM <--> GlobalPM
G2_PM <--> GlobalPM
G3_PM <--> GlobalPM
``
管理游戏实例的启动与销毁,可同时维护多个实例,通过 key 区分。
预定义通用事件(如 IntervalEventSignal、ButtonPushEventSignal 等),
可在 State 或 Component 中通过 eventManager 订阅。
全局玩家管理,负责玩家的分配和回收,游戏获取玩家时会从此尝试分配,游戏结束时会释放玩家。
- 反馈问题:请提交 Issue
- 功能合作:欢迎发 Pull Request
- 交流群:1004513100