For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /guide/addons.md.
SFMC
  • 简体中文

      • 附加包管理（Add-ons）

      在 Minecraft 基岩版中，服主常常需要引入社区第三方行为包（BP）与资源包（RP）（如玩法机制、载具系统、材质光影等）。

      SFMC 提供了附加包导入目录与 CurseForge 更新支持，通过 packs（或别名 addon）命令管理生命周期。

      概念辨析：模块 vs 附加包
      • SFMC 业务模块（modules/）：采用 TypeScript 编写的平台轻量级功能包，由 SFMC 动态编译聚合为单一行为包，与 Node 伴生服务深度互通。
      • 第三方附加包（packs/）：现成的 .mcpack、.mcaddon 或 .zip 游戏扩展包，由收件箱直接分发至指定游戏世界的包目录中。 :::

      1. 附加包目录结构

      将下载好的扩展包放入 <SFMC_ROOT>/packs/ 即可自动识别与分发：

      <SFMC_ROOT>/packs/
├── inbox/ (即 packs/ 顶层)   # 直接将 .mcpack / .mcaddon / .zip 放入此处
├── _done/                    # 安装部署成功后的原始归档备份
├── _failed/                  # 格式损坏、缺少 manifest 或校验失败的包
├── _trash/                   # 卸载后的回收站目录
├── _build/                   # SFMC 模块行为包的构建产物（自动生成）
└── pack-sources.json         # 各附加包与 CurseForge 等上游更新源的绑定映射

      2. 常用管理指令

      在 sfmc 控制台内输入命令：

      扫描与安装

      # 扫描 packs 目录中的待装扩展包（交互式识别冲突）
sfmc> packs scan

# 预览扫描结果，不实际写入（Dry Run 预检）
sfmc> packs scan --dry-run

# 安装特定路径下的附加包
sfmc> packs install ./downloads/cool-furniture.mcaddon

# 列出当前世界已装载的所有行为包与资源包
sfmc> packs list
sfmc> packs list --kind bp

      启停、诊断与卸载

      # 启用 / 禁用指定附加包（支持使用 UUID 或格式化文件夹名）
sfmc> packs enable <uuid|folder>
sfmc> packs disable <uuid|folder>

# 健康诊断：检测世界清单引用问题，并查看当前存档实验性开关状态
sfmc> packs doctor

# 仅查看当前存档的实验性开关开启状态
sfmc> packs doctor --experiments

# 一键修复引用问题并补齐依赖的 Beta APIs
sfmc> packs doctor --fix

# 一键修复清单引用并开启全部已知实验性功能
sfmc> packs doctor --fix --all-experiments

# 按需开启指定实验性功能（支持逗号分隔，支持别名）
sfmc> packs doctor --fix --experiments=upcoming,cameras,voxel,villager,drop3,edu

# 打印世界附加包落盘绝对路径
sfmc> packs path

# 安全卸载（移出世界目录并放入 _trash 回收站，自动清理配对 RP）
sfmc> packs uninstall <id>

# 彻底清除（直接永久删除，不保留在回收站）
sfmc> packs uninstall <id> --purge

      存档实验性开关（Experiments）诊断与配置

      许多现代基岩版附加包（如使用自定义方块几何、实体相机、原生脚本或最新特性的包）依赖世界存档 level.dat 中的实验性功能。packs doctor 支持对以下已知实验性特性的安全读写：

      实验性功能NBT 路径 / 特性常用别名作用说明
      测试版 API (Beta APIs)experiments.gametestbeta, gametest供 @minecraft/server 等脚本模块调用测试期接口
      即将推出的创作者功能experiments.upcoming_creator_featuresupcoming启用多方块 Trait 与扩展模型旋转
      创建者照相机的实验性功能experiments.experimental_creator_camerascameras启用自定义机位与 /camera 视口控制
      实验性 Voxel 形状特征experiments.voxel_shapesvoxel启用非方块形状的面剔除（Face Culling）与碰撞
      村民贸易再平衡experiments.villager_trades_rebalancevillager, trades启用按生物群系区分的图书管理员交易及矿车更新
      2026 年第 3 次更新experiments.drop_3_2026drop3, wilderness_bound体验新生物群系与新方块等特性
      Minecraft Education 功能educationFeaturesEnabled (根标签)edu, education开启化学工作台、元素周期表与特殊教育方块

      修改时会自动创建 level.dat.bak 备份，校验 8 字节小端序文件头部，并通过临时文件原子替换，保证存档完整性。

      :::warning 游戏生效机制 由于 Minecraft BDS 资源包清单在进程初始化时读取，任何附加包的安装、启停或卸载操作，均需重启 BDS 服务端方可生效。

      3. 冲突与版本覆盖策略

      当目标世界中已存在相同 UUID 或文件夹名的附加包时，处理规则如下：

      执行环境冲突处理行为
      交互模式（TTY 终端）在控制台对比新旧包的版本号与哈希，提示服主确认是否覆盖。
      非交互模式（开服前自动扫描）默认跳过并打印警告日志，不会静默覆盖；如需强制覆盖，可追加 --force 参数。
      版本升级当检测到待装包的 UUID 与旧包一致且 version 更高时，安装引擎会自动覆盖原目录，保持配置连续性。

      4. CurseForge 扩展包更新与源绑定

      SFMC 支持连接 CurseForge 基岩版资源库。配置 API Key 后，可检索扩展包并检查升级：

      # 在 CurseForge 基岩版资源库中搜索项目
sfmc> packs search "Slash Blade"

# 将世界中已安装的附加包与 CurseForge 项目 slug 绑定
sfmc> packs bind <uuid|folder> slash-blade-addon

# 查看所有已绑定的远端更新源
sfmc> packs sources

# 检查是否存在可用更新
sfmc> packs check

# 一键下载并更新所有已绑定的附加包
sfmc> packs update --all

      关联配置文件

      • 全局策略 (configs/pack-update.json)：配置 CurseForge API Key、开服时是否静默检查以及名称匹配模糊阈值。
      • 本地映射 (packs/pack-sources.json)：维护每个本地包与远端工程的绑定关系，可通过 packs unbind <id> 解除关联。

      强制客户端材质刷新（RP Bump）

      在修改或升级资源包（RP）后，基岩版客户端有时会因本地贴图缓存而未即时加载最新材质。

      执行以下指令，可自动将指定资源包的 patch 版本号自增 1：

      sfmc> packs bump <rp-folder-name>

      客户端在下次连接服务器时，检测到 RP 版本号变更，将自动重新下载并应用新材质。