Skip to content

DogeLakeDev/ScriptsForMinecraftServer

BranchesTags

Repository files navigation

SFMC - ScriptsForMinecraftServer

一套 Minecraft Bedrock Script API (SAPI) 行为包 + Node.js 仓顶服务的 monorepo。

  • 提供基于Minecraft SAPI的原生SDK
  • 外置模块化管理
  • 多功能、适用BDS的cil工具
  • 为模块提供Sqlite数据库管理SDK及其路由服务
  • QQ桥接，群服互通

English version →

version license node typescript sea modules bd discord

项目概览

SFMC 把 Bedrock Dedicated Server 的SAPI能力扩成一套完整的服务端体系:

  • 模块化设计体系,基于 modules/packages/<id>/ 的模块包结构 —— 每个模块都是一等公民,通过 modules/catalog.json 注册并由 ModuleRegistry 装载
  • 4 个仓顶服务 (db-server SQLite REST API / qq-bridge Q群 ⇄ 服务器互通 / bds-tools BDS 进程管理 / sfmc SEA CLI)
  • 使用 sea 打包的 cil 程序 —— 一键启动、开服、管理
  • SDK 工具包 @sfmc/sdk —— 位于 modules/sdk/@sfmc-sdk/,跨 SAPI / Node 两侧共享底层契约(不是模块)
  • 构建时模块 一次性 CLI tools/fetch-module.mjs 从 GitHub Releases 拉模块(SEA 进程不联网)

架构图

flowchart TB
    %% ============== BDS 侧 ==============
    subgraph BDS["Minecraft BDS 1.26.x (host)"]
      direction TB
      BP["behavior_packs/ScriptsForMinecraftServer<br/>scripts/entry.ts → esbuild → main.js"]
      REG["ModuleRegistry<br/>register / bootAll / bootAfterWorldLoad"]
      MODS_SAPI["SAPI 模块(在 BDS 进程内运行)<br/>由 catalog.json 注册"]
      CONF["ConfigManager<br/>GET /api/sfmc/configs/all 一次拉全"]
      BP --> REG --> MODS_SAPI
      REG -. "启动时快照" .-> CONF
    end

    %% ============== 本机服务 ==============
    subgraph HOST["本机(127.0.0.1)"]
      direction TB

      subgraph SEA["sfmc.exe (Node SEA 单文件)"]
        direction LR
        DISP["dispatcher<br/>SFMC_SERVICE switch"]
        CLI["sfmc REPL<br/>用户交互 + start -all"]
        DISP --> CLI
      end

      subgraph SVC["仓顶服务"]
        direction TB
        DB["db-server<br/>SQLite + REST API<br/>:3001 HTTP"]
        QQ["qq-bridge<br/>OneBot 11 反向 WS<br/>:3002"]
        BDS_T["bds-tools<br/>check-update · 进程管理"]
      end

      subgraph MODS["modules/packages/&lt;id&gt;/  (模块包,每个都是一等公民)"]
        direction LR
        M1["core-*<br/>(基础设施模块)<br/>data-backup · gui · ..."]
        M2["feature-*<br/>(特性模块)<br/>land · economy · chat · ..."]

        SDK["modules/sdk/@sfmc-sdk<br/>工具包,非模块<br/>SAPI / Node 共享"]
      end

      CAT["modules/catalog.json<br/>模块清单 + type 字段<br/>(区分 core / feature)"]
      LOCK["modules/module-lock.json<br/>启/禁状态"]
    end

    %% ============== 外部 ==============
    subgraph EXT["外部"]
      LLBOT["LLBot (OneBot 11)<br/>QQ 协议侧"]
      QQUSERS["QQ 群服用户"]
      BDS_USER["MC 玩家"]
    end

    %% ============== 数据流 ==============
    DISP -. "spawn / supervise" .-> DB
    DISP -. "spawn / supervise" .-> QQ
    DISP -. "spawn / supervise" .-> BDS_T

    %% SAPI ↔ db-server
    MODS_SAPI -- "HTTP :3001<br/>GET/POST /api/sfmc/*" --> DB
    CONF -- "HTTP :3001<br/>GET /api/sfmc/configs/all" --> DB

    %% CLI ↔ db-server (启停模块)
    CLI -- "PATCH /api/sfmc/modules/:id<br/>→ 写 module-lock.json" --> DB
    DB -. "ConfigManager.refreshModules()<br/>(重启后生效)" .-> REG

    %% SDK 共享 (编译期,不是模块)
    SDK -. "compile-time deps" .-> MODS_SAPI
    SDK -. "compile-time deps" .-> DB

    %% catalog / module-lock
    CAT -. "注册元数据" .-> REG
    LOCK -. "启动时读取" .-> REG

    %% QQ 桥消息流
    QQUSERS <-->|QQ 消息| LLBOT
    LLBOT -- "WS :3002 (QQ→MC)" --> QQ
    QQ -- "POST :3001 /api/sfmc/messages" --> DB
    DB -- "HTTP :3004 /send_group_msg (MC→QQ)" --> LLBOT

    %% 玩家
    BDS_USER <-->|SAPI events| BP

    %% 构建期模块拉取(SE 下发时 populate)
    FETCH["tools/fetch-module.mjs<br/>(构建期,不联网进 SEA)"]
    FETCH -. "从 GitHub Releases populate<br/>(或 cp -r 本地放包)" .-> MODS_SAPI

    classDef seaBox fill:#FFE5E5,stroke:#FF6B6B,stroke-width:2px
    classDef svcBox fill:#E8F5E9,stroke:#43A047
    classDef modBox fill:#EDE7F6,stroke:#7B68EE
    classDef sdkBox fill:#FFF8E1,stroke:#F9A825
    classDef bdsBox fill:#E3F2FD,stroke:#1976D2
    classDef extBox fill:#FFF3E0,stroke:#FB8C00
    class DISP,CLI seaBox
    class DB,QQ,BDS_T svcBox
    class M1,M2 modBox
    class SDK sdkBox
    class BP,REG,MODS_SAPI,CONF bdsBox
    class LLBOT,QQUSERS,BDS_USER extBox
Loading

模块流程图

flowchart LR
    A["作者<br/>写模块"] -->|manifest.json| B["modules/packages/&lt;id&gt;/"]
    B -->|npm run build:full| C["esbuild bundle<br/>+ manifest 聚合"]
    C -->|复制到| D["BDS behavior_packs"]
    D -->|reload BP| E["SAPI 启动 catalog 中<br/>enabled 的模块"] |
    B -->|db-server 扫| F["db-server 路由注册"]
    E <-->|HttpDB| F
Loading

快速开始

SFMC 提供两条等价的上手路径,选你最舒服的就行。

⚡ SEA 单 exe(推荐 — 不想碰 Node)

# 1. 下载对应平台的 sfmc.exe(从 GitHub Releases),放到一个空目录
# 2. 自检环境
node tools/check-ootb.js     # 或者直接在 exe 同目录跑 ./sfmc.exe wizard

# 3. 首次启动会跑 wizard:填 BDS 路径 / LLBot 路径 / 备份目录,
#    然后选 1+ 个模块 → 自动 install → build → deploy 到 BDS
./sfmc.exe                   # 等同 sfmc

# 4. REPL 起动后,装更多模块不用重启 BDS(锁变更就行)
sfmc> module install <id>
sfmc> behavior-pack build && behavior-pack deploy

# 5. 启动全部服务
sfmc> start -all

⚙️ npm monorepo(开发者 — 改 BP 脚本 / 写自定义模块)

# 1. clone + 装依赖
git clone https://github.com/DogeLakeDev/ScriptsForMinecraftServer
cd ScriptsForMinecraftServer
npm install

# 2. 自检 + 跑 wizard(填 BDS/LLBot/备份目录)
node tools/check-ootb.js
node sfmc/dist/main.js       # 同 sfmc

# 3. 装模块(默认从第一方 sfmc-modules 注册表)
node tools/fetch-module.mjs install peace
node tools/fetch-module.mjs search                  # 看可用模块

# 4. 写自定义 BP / 自定义模块 → 改完
npm run build --workspaces   # 重 build 全部 SDK + 装配工具
sfmc> behavior-pack build && behavior-pack deploy

# 5. 启动
sfmc> start -all

两条路共用同一份:

  • 第一方模块注册表 Shiroha7z/sfmc-modules(GitHub Releases)
  • tools/fetch-module.mjs 拉模块
  • sfmc behavior-pack build/deploy 走同一套 bds-tools/pack-manager
  • modules/module-lock.json 启/禁状态

SEA 不含固定 BP — 行为包是你装了模块后实时装配出来的。未知来源模块(不在第一方 index)会触发顶部黄字警告,确认无误可继续。

目录速览

ScriptsForMinecraftServer/
├── bds-tools/             BDS 自动更新 + 进程管理
├── db-server/             SQLite HTTP REST API (port 3001)
├── qq-bridge/             QQ 桥(LLBot OneBot 11)
├── sfmc/                  REPL 管理 CLI (走 SEA)
├── remote-controller/     远程 agent
├── modules/
│   ├── catalog.json       22 业务模块清单
│   ├── module-lock.json   启/禁状态
│   ├── sdk/@sfmc-sdk/     单一伞包
│   └── packages/          25 个业务模块
├── tools/                 自检 + 构建 + fetch-module.mjs
├── configs-default/       默认配置 JSON
├── build-sea.mjs          SEA 构建入口
└── docs/                  中英双语文档
    ├── user-guide.zh.md
    ├── marketplace.zh.md
    └── dev/{module-author,sdk-reference,manifest-contract}.zh.md

文档索引

中文 English 面向
使用文档 User Guide 运维 / 用户
模块管理指南 Module Management 运维(SEA 装模块)
模块作者指南 Module Author Guide SAPI 模块开发者
SDK 三抽屉 API SDK Reference 模块作者(查表)
manifest 契约 Manifest Contract 模块作者(写契约)
CLAUDE.md 同 给 Claude Code 的项目说明

系统要求

组件 要求
Node.js 22.5+(db-server 原生 node:sqlite)+ 18+(SAPI 打包)
OS Windows 10/11(主要),Linux/macOS 也支持
BDS Bedrock Dedicated Server 1.26.x
磁盘 ~500 MB(含 BP + 服务 + node_modules)

Windows 上需给 BDS 配 Loopback Exemption(命令已合并到 wizard):

CheckNetIsolation LoopbackExempt -is -n=Microsoft.MinecraftUWP_8wekyb3d8bbwe

端口速查

端口 用途
3001 db-server REST API(BP / sfmc / qq-bridge 都打这里)
3002 qq-bridge 接入 LLBot OneBot 11 的反向 WebSocket
3004 db-server → LLBot(MC→QQ 直连,不开 3003)

路线图

  • ✅ Stage I:per-module manifest + emit-manifest + db-server reader
  • ✅ Stage J:shared/* 迁入 @sfmc/sdk,22 模块迁出
  • ✅ Stage K:SEA slim —— 模块从 SEA 剥离,populate 由 tools/fetch-module.mjs 完成
  • 🚧 Stage L:模块 zip 自动解压、sfmc module install --enable-and-deploy 一条龙
  • 🚧 Stage M:模块签名 / 公钥验证(取代纯 SHA-256 指纹)
  • 🚧 Stage N+:服务网格(多 BDS 实例 / 跨节点)

许可证

MIT

English version →

About

No description, website, or topics provided.

Resources

Readme

License

AGPL-3.0 license
Activity
Custom properties

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages