#平台架构设计

本文介绍 SFMC 的系统架构分层、SAPI 模块生命周期、数据存储划分以及主仓工作区结构。

#1. 系统分层与拓扑

SFMC 将系统划分为四个层次：

#2. SAPI 生命周期与启动时序

BDS 脚本基于原生事件钩子执行。SFMC 的 installHostBootstrap() 宿主脚本在启动时统一调度生命周期：

#单次配置快照与 Token 注入

启动阶段，ConfigManager 仅发起一次 GET /api/sfmc/configs/all 请求，拉取当前启用的模块列表、系统设置、全局权限表以及各模块专属通信 Token：

• 运行时无需轮询：快照缓存在 SAPI 内存中，避免频繁发起 HTTP 请求影响游戏主刻（Tick）。
• Token 自动注入：ModuleRegistry.bootModule 会自动将该模块的专用 Bearer Token 绑定至 db 客户端上下文，业务模块无需手动配置鉴权密钥。

#3. 模块注册示例

模块在 sapi/src/index.ts 中声明自身的生命周期钩子：

import { ModuleRegistry } from "@sfmc-bds/sdk/module-loader";
import { Command, Msg, Permission } from "@sfmc-bds/sdk/sapi/runtime";

// 原生命令需在顶层注册，公开名称为 /c:tp
Command.register(
  "tp",
  "tp.use",
  (player) => {
    if (player) Msg.info("正在传送至主城...", player);
  },
  "传送至主城",
  "feature-teleport"
);

ModuleRegistry.register({
  id: "feature-teleport",
  afterWorldLoad: false, // 若需在 init 中查询世界实体或维度，设为 true
  lifecycle: {
    // 1. 声明模块所需权限节点
    registerPermissions() {
      Permission.register("tp.use", 0);
      Permission.register("tp.admin", 2);
    },

    // 2. 注册 Minecraft 原生事件监听
    registerEvents() {
      // 在此处通过 world.afterEvents 订阅事件
    },

    // 3. 模块异步初始化
    async init() {
      // 创建 SQLite 数据表、初始化模块内部状态
    },

    // 4. 停机或卸载时的资源释放
    cleanup() {
      // 清理定时器与缓存
    },
  },
});

#4. 核心状态与数据划分

#5. 主仓目录结构

平台主仓采用 pnpm workspaces 管理：

ScriptsForMinecraftServer/
├── modules/
│   ├── sdk/
│   │   ├── @sfmc-sdk/             # SDK 核心包（导出 runtime, db, config, module-loader）
│   │   └── @sfmc-eslint-plugin/   # ESLint 代码规范规则插件
│   └── packages/                  # SFMC_ROOT 下已安装业务模块的目录（主仓默认不包含）
├── packages/
│   ├── db-server/                 # 基于 node:sqlite 的本地 HTTP 持久化中枢
│   ├── qq-bridge/                 # QQ 互通桥接服务（官方机器人与 LLBot）
│   ├── bds-tools/                 # 官方 BDS 核心自动更新、备份与附加包管理
│   ├── devkit/                    # 模块文件监听（Watch）与脚手架转译引擎
│   ├── cli/                       # @sfmc-bds/cli 终端交互与进程管理
│   ├── meta/                      # @sfmc-bds/sfmc 全局命令行入口包装
│   ├── create-module/             # @sfmc-bds/create-module 脚手架生成器
│   ├── sfmc-extension/            # VS Code / Cursor 官方开发扩展
│   └── tools/                     # 仓内专用测试、自检与构建脚本
└── docs/                          # 基于 Rspress 的多语言文档源码

:::note 目录约定

• packages/*：平台基础包与核心工具，均独立发布至 npm。
• modules/packages/*：运行时的业务模块目录，与平台核心代码相互独立。 :::

#桌面端与 UI Studio 的界面分层

packages/ui 提供共享的 SnowUI 令牌与字体、Tabler 图标和 Base UI 控件/浮层（小程序页面图标由同一张图标表生成，原生标签栏仍用 Phosphor）。Desktop 的外观提供者负责 Monaco 与原生窗口配色；Studio 独立运行时保存自己的外观偏好，内嵌时跟随 Desktop。基础视觉和交互只维护一份，领域逻辑由各应用承担。

UI Studio 浏览器源码按 app（路由与宿主）、pages（工程列表与编辑器）、components（工程树、属性面板与画布）、lib（草稿/导入导出/预览派生）、store（工程格式与 IndexedDB）、styles（编辑器布局）组织。Desktop 复用 SDK 的 Vite 配置打包 Studio，内置入口在「开发工具」；切页隐藏文档并保留编辑状态，不依赖实例握手或 CLI 服务。