Skip to content

Commit cc6a12b

Browse files
Tanya7zTanya7z
committed
feat(bds-tools,cli): 增强 packs doctor 存档实验性玩法开关诊断与配置
1 parent 74958e0 commit cc6a12b

11 files changed

Lines changed: 738 additions & 277 deletions

File tree

‎.changeset/packs-doctor-world-experiments.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
"@sfmc-bds/bds-tools": minor
3+
"@sfmc-bds/cli": minor
4+
---
5+
6+
feat(bds-tools,cli): 增强 packs doctor 存档实验性玩法开关诊断与自愈配置
7+
8+
- `@sfmc-bds/bds-tools`: 支持检测与修改当前版本已知的全部实验性功能（测试版 API、创作者功能、创作者相机、Voxel形状、村民贸易再平衡、2026年第3次更新、Minecraft Education 功能），提供智能别名解析与安全的原子化 level.dat 修改与灾备。
9+
- `@sfmc-bds/cli`: `packs doctor` 命令支持 `--experiments`、`--all-experiments`、`--experiments=<list>` 开关；在诊断视图中高亮直观展示当前存档的各实验性玩法启用状态。

‎docs/en/guide/addons.md‎

Lines changed: 58 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,14 @@ sfmc> packs list
1111

1212
Path: `<SFMC_ROOT>/packs/`
1313

14-
| Content | Description |
15-
| ------------------- | ------------------------------------ |
16-
| Pending files / dirs | Archives or folders with `manifest.json` |
17-
| `_done/` | Source archives after successful install |
18-
| `_failed/` | Unrecognized or failed installs |
19-
| `_trash/` | Uninstall recycle bin (default) |
20-
| `_build/` | Module behavior pack build output (do not install as add-ons) |
21-
| `pack-sources.json` | CurseForge and other update source bindings |
14+
| Content | Description |
15+
| -------------------- | ------------------------------------------------------------- |
16+
| Pending files / dirs | Archives or folders with `manifest.json` |
17+
| `_done/` | Source archives after successful install |
18+
| `_failed/` | Unrecognized or failed installs |
19+
| `_trash/` | Uninstall recycle bin (default) |
20+
| `_build/` | Module behavior pack build output (do not install as add-ons) |
21+
| `pack-sources.json` | CurseForge and other update source bindings |
2222

2323
The inbox is scanned before `start bds`; for day-to-day work **prefer manual `packs scan`** so you can handle conflicts and update sources.
2424

@@ -31,28 +31,61 @@ flowchart LR
3131

3232
## Common commands
3333

34-
| Command | Purpose |
35-
| ----------------------------------------- | ---------------------- |
36-
| `packs list [--kind bp\|rp\|all]` | List installed packs |
37-
| `packs install [path\|--inbox] [--force]` | Install path or scan inbox |
38-
| `packs scan [--force] [--dry-run]` | Scan inbox |
39-
| `packs enable \| disable <id>` | id is uuid or folder name |
40-
| `packs uninstall [id...] [--purge]` | Remove from world; default to recycle bin |
41-
| `packs doctor` | Diagnose manifest and directory issues |
42-
| `packs path` | Print related paths |
43-
| `packs bump <id>` | RP only: patch version +1 |
34+
| Command | Purpose |
35+
| ---------------------------------------------------------- | -------------------------------------------- |
36+
| `packs list [--kind bp\|rp\|all]` | List installed packs |
37+
| `packs install [path\|--inbox] [--force]` | Install path or scan inbox |
38+
| `packs scan [--force] [--dry-run]` | Scan inbox |
39+
| `packs enable \| disable <id>` | id is uuid or folder name |
40+
| `packs uninstall [id...] [--purge]` | Remove from world; default to recycle bin |
41+
| `packs doctor [--fix] [--all-experiments] [--experiments]` | Diagnose pack wiring & level.dat experiments |
42+
| `packs path` | Print related paths |
43+
| `packs bump <id>` | RP only: patch version +1 |
4444

4545
Full subcommands: [Command reference](./commands.md).
4646

47+
### World experiments diagnosis & toggles
48+
49+
Many modern Bedrock add-ons (custom block geometry, entity cameras, native scripts, or newer gameplay features) depend on experimental features enabled in `level.dat`. `packs doctor` provides native, safe inspection and configuration for known experiments:
50+
51+
```bash
52+
# Diagnose pack wiring and inspect current world experiments status
53+
sfmc> packs doctor
54+
55+
# Inspect level.dat experiments only
56+
sfmc> packs doctor --experiments
57+
58+
# Fix pack wiring and automatically enable required Beta APIs
59+
sfmc> packs doctor --fix
60+
61+
# Fix pack wiring and enable all known experimental toggles
62+
sfmc> packs doctor --fix --all-experiments
63+
64+
# Enable specific experiments (comma-separated, aliases supported)
65+
sfmc> packs doctor --fix --experiments=upcoming,cameras,voxel,villager,drop3,edu
66+
```
67+
68+
| Experiment | NBT Path / Feature | Aliases | Description |
69+
| :------------------------------- | :----------------------------------------- | :-------------------------- | :----------------------------------------------------------------- |
70+
| **Beta APIs** | `experiments.gametest` | `beta`, `gametest` | Enables scripting beta APIs (`@minecraft/server`, etc.) |
71+
| **Upcoming Creator Features** | `experiments.upcoming_creator_features` | `upcoming` | Custom block traits and extended model rotation |
72+
| **Experimental Creator Cameras** | `experiments.experimental_creator_cameras` | `cameras` | Custom camera perspectives and `/camera` commands |
73+
| **Experimental Voxel Shapes** | `experiments.voxel_shapes` | `voxel` | Non-cube block collision and face culling |
74+
| **Villager Trade Rebalance** | `experiments.villager_trades_rebalance` | `villager`, `trades` | Biome-dependent librarian book trades and minecart updates |
75+
| **2026 Drop 3 Update** | `experiments.drop_3_2026` | `drop3`, `wilderness_bound` | Dappled forest, cushions, grass beds, etc. |
76+
| **Minecraft Education Features** | `educationFeaturesEnabled` (root tag) | `edu`, `education` | Chemistry lab table, periodic table elements, and education blocks |
77+
78+
Every modification automatically creates a backup (`level.dat.bak`), recalculates the 8-byte little-endian header length, and commits via atomic file replacement to ensure world safety.
79+
4780
## Install and conflicts
4881

4982
After a successful install, entries are written to `world_behavior_packs.json` / `world_resource_packs.json` (enabled by default). Restart BDS for changes to take effect.
5083

5184
When the target already has the same uuid or formatted folder name:
5285

53-
| Environment | Behavior |
54-
| -------------------------- | -------------------------------------- |
55-
| Interactive (TTY) | Prompt to compare and confirm overwrite |
86+
| Environment | Behavior |
87+
| ------------------------------------ | ----------------------------------------------------- |
88+
| Interactive (TTY) | Prompt to compare and confirm overwrite |
5689
| Non-interactive (e.g. `beforeStart`) | No silent overwrite; skip with warning; use `--force` |
5790

5891
Same uuid with a higher semver can be silently overwritten to the original folder name.
@@ -69,10 +102,10 @@ sfmc> packs update --all
69102
sfmc> packs sources
70103
```
71104

72-
| Config | Purpose |
73-
| -------------------------- | ------------------------------------------------- |
74-
| `configs/pack-update.json` | Master switch, API key, check on startup |
75-
| `packs/pack-sources.json` | Per-pack binding; set `enabled: false` or `packs unbind` |
105+
| Config | Purpose |
106+
| -------------------------- | -------------------------------------------------------- |
107+
| `configs/pack-update.json` | Master switch, API key, check on startup |
108+
| `packs/pack-sources.json` | Per-pack binding; set `enabled: false` or `packs unbind` |
76109

77110
Environment variable `CURSEFORGE_API_KEY` overrides the API key.
78111

‎docs/en/guide/commands.md‎

Lines changed: 35 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -4,54 +4,55 @@ Type `help` in the console for commands available in your environment. Below is
44

55
## Services
66

7-
| Command | Purpose |
8-
| ------ | ------ |
9-
| `status` | Running state |
10-
| `start db\|qq\|llbot\|bds\|-all` | Start |
11-
| `stop …` / `restart …` | Stop / restart |
12-
| `logs <svc> [-n N] [-f]` | Logs (REPL; `Ctrl+L` for in-memory view) |
13-
| `send <svc> <…>` | Send input to a service process (REPL only) |
14-
| `init` | Setup wizard (TTY required) |
15-
| `update [--check-only]` | BDS update |
7+
| Command | Purpose |
8+
| -------------------------------- | ------------------------------------------- |
9+
| `status` | Running state |
10+
| `start db\|qq\|llbot\|bds\|-all` | Start |
11+
| `stop …` / `restart …` | Stop / restart |
12+
| `logs <svc> [-n N] [-f]` | Logs (REPL; `Ctrl+L` for in-memory view) |
13+
| `send <svc> <…>` | Send input to a service process (REPL only) |
14+
| `init` | Setup wizard (TTY required) |
15+
| `update [--check-only]` | BDS update |
1616

1717
## Modules
1818

19-
| Command | Purpose |
20-
| ------ | ------ |
21-
| `mod list` / `mod info <id>` | List / details |
22-
| `mod search` | Search registry |
23-
| `mod install <id>…` | Install |
24-
| `mod uninstall <id>…` | Uninstall |
19+
| Command | Purpose |
20+
| ---------------------------- | ----------------------------------------------------- |
21+
| `mod list` / `mod info <id>` | List / details |
22+
| `mod search` | Search registry |
23+
| `mod install <id>…` | Install |
24+
| `mod uninstall <id>…` | Uninstall |
2525
| `mod enable \| disable <id>` | Enable/disable (writes lock; hot-sync when db online) |
26-
| `mod verify` | Validate |
27-
| `mod build` | Build behavior pack only |
28-
| `mod reload [--build-only]` | Build, deploy, optionally request BDS reload |
26+
| `mod verify` | Validate |
27+
| `mod build` | Build behavior pack only |
28+
| `mod reload [--build-only]` | Build, deploy, optionally request BDS reload |
2929

3030
Author test / Watch / publish: [Module authoring](../dev/module-author.md) (VS Code **SFMC Module** extension). `mod test|watch|publish` are not provided at the top level.
3131

3232
Top-level shortcuts: `install` / `uninstall` / `search` / `verify` ≡ `mod …`.
3333

3434
## Add-ons
3535

36-
| Command | Purpose |
37-
| ------ | ------ |
38-
| `packs list` / `packs search <q>` | List / CurseForge search |
39-
| `packs install` / `packs scan` | Install / scan inbox |
40-
| `packs enable \| disable <id>` | Enable/disable |
41-
| `packs uninstall [id…] [--purge]` | Uninstall |
42-
| `packs bind` / `unbind` / `sources` | Update sources |
43-
| `packs check` / `packs update` | Check / apply updates |
44-
| `packs bump <id>` | Bump RP version |
45-
| `packs doctor` / `packs path` | Diagnose / paths |
36+
| Command | Purpose |
37+
| ----------------------------------- | ---------------------------------------------------------------- |
38+
| `packs list` / `packs search <q>` | List / CurseForge search |
39+
| `packs install` / `packs scan` | Install / scan inbox |
40+
| `packs enable \| disable <id>` | Enable/disable |
41+
| `packs uninstall [id…] [--purge]` | Uninstall |
42+
| `packs bind` / `unbind` / `sources` | Update sources |
43+
| `packs check` / `packs update` | Check / apply updates |
44+
| `packs bump <id>` | Bump RP version |
45+
| `packs doctor` | `sfmc> packs doctor [--fix] [--all-experiments] [--experiments]` | Diagnose wiring and toggle world level.dat experiments |
46+
| `packs path` | Print world pack paths |
4647

4748
## General
4849

49-
| Command | Purpose |
50-
| ------ | ------ |
51-
| `locale` | UI language |
52-
| `version` | Version |
53-
| `help` | Help |
54-
| `quit` | Exit REPL |
50+
| Command | Purpose |
51+
| --------- | ------------------- |
52+
| `locale` | UI language |
53+
| `version` | Version |
54+
| `help` | Help |
55+
| `quit` | Exit REPL |
5556
| `debug …` | Debug (development) |
5657

5758
More detail: [Service management](./services.md), [Modules](./modules.md), [Add-ons](./addons.md).

‎docs/zh/guide/addons.md‎

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -61,9 +61,21 @@ sfmc> packs list --kind bp
6161
sfmc> packs enable <uuid|folder>
6262
sfmc> packs disable <uuid|folder>
6363

64-
# 健康诊断：检测世界清单中是否存在悬空失效的幽灵包
64+
# 健康诊断：检测世界清单接线问题，并查看当前存档实验性开关状态
6565
sfmc> packs doctor
6666

67+
# 仅查看当前存档的实验性开关开启状态
68+
sfmc> packs doctor --experiments
69+
70+
# 一键修复接线问题并补齐依赖的 Beta APIs
71+
sfmc> packs doctor --fix
72+
73+
# 一键自愈接线并开启全部已知实验性功能
74+
sfmc> packs doctor --fix --all-experiments
75+
76+
# 按需开启指定实验性功能（支持逗号分隔，支持别名）
77+
sfmc> packs doctor --fix --experiments=upcoming,cameras,voxel,villager,drop3,edu
78+
6779
# 打印世界附加包落盘绝对路径
6880
sfmc> packs path
6981

@@ -74,6 +86,22 @@ sfmc> packs uninstall <id>
7486
sfmc> packs uninstall <id> --purge
7587
```
7688

89+
#### 存档实验性开关（Experiments）诊断与自愈
90+
91+
许多现代基岩版附加包（尤其是使用自定义方块几何、实体相机、原生脚本或最新玩法的包）依赖世界存档 `level.dat` 中的实验性功能。`packs doctor` 提供了对以下当前版本已知实验性玩法的原生安全读写支持：
92+
93+
| 实验性功能 | NBT 路径 / 特性 | 常用别名 | 作用说明 |
94+
| :--------------------------- | :----------------------------------------- | :-------------------------- | :---------------------------------------------- |
95+
| **测试版 API (Beta APIs)** | `experiments.gametest` | `beta`, `gametest` | 供 `@minecraft/server` 等脚本模块调用测试期接口 |
96+
| **即将推出的创作者功能** | `experiments.upcoming_creator_features` | `upcoming` | 启用多方块 Trait 与扩展模型旋转 |
97+
| **创建者照相机的实验性功能** | `experiments.experimental_creator_cameras` | `cameras` | 启用自定义机位与 `/camera` 视口控制 |
98+
| **实验性Voxel形状特征** | `experiments.voxel_shapes` | `voxel` | 启用非方块形状的面剔除（Face Culling）与碰撞 |
99+
| **村民贸易再平衡** | `experiments.villager_trades_rebalance` | `villager`, `trades` | 启用按生物群系区分的图书管理员交易及矿车更新 |
100+
| **2026年第3次更新** | `experiments.drop_3_2026` | `drop3`, `wilderness_bound` | 提前体验斑驳森林、坐垫、草床等新特性 |
101+
| **Minecraft Education 功能** | `educationFeaturesEnabled` (根标签) | `edu`, `education` | 开启化学工作台、元素周期表与特殊教育方块 |
102+
103+
每次执行修改均会自动创建 `level.dat.bak` 灾备，校准 8 字节小端序文件头部，并通过临时文件原子替换，确保存档安全。
104+
77105
:::warning 游戏生效机制
78106
由于 Minecraft BDS 资源包清单在进程初始化时读取，**任何附加包的安装、启停或卸载操作，均需重启 BDS 服务端方可生效**。
79107
:::
@@ -125,4 +153,3 @@ sfmc> packs bump <rp-folder-name>
125153
```
126154

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

0 commit comments

Comments
 (0)