Shtreimel - 黑貂皮帽工具

Shtreimel - 黑貂皮帽工具

Sable与Create Aeronautics在NeoForge 1.21.1上的服务端管理工具：列出、检查、冻结、存档和移除子网格；在控制台中标出卡顿嫌疑对象；丰富崩溃报告。

Shtreimel

一个面向 Sable 和 Create Aeronautics 的服务器管理工具包。 查找导致卡顿的飞艇，冻结失控实体，撤销意外的破坏，追踪实体消失的确切时间，并识别服务器崩溃时正在运行哪个装置。

支持 NeoForge 和 Fabric 1.21.1。仅需在专用服务器上安装。无需客户端模组。

“Shtreimel”是一种覆在貂皮衬里上的毛皮帽。这是一顶戴在 Sable 之上的帽子。名字是个玩笑；模组本身不是。

为什么你需要它

你运行着一个 Sable 或 Create Aeronautics 服务器。最终会遇到以下情况之一：

  • 有人建造了一个 50,000 方块大小的巨型装置，你的 TPS 骤降。你不知道是谁的、在哪里，也不知道如何在不使用 /stop 的情况下停止它。
  • 一名玩家将飞艇驶出生存范围，它再也没有回来。或者它卡在半空中。又或者它坠入虚空。
  • 你信任的某人对错误的装置执行了 /sable remove，而你没有任何可回滚的数据。
  • Sable 在两刻之间移除了一个主体，而你的日志从未记录原因。
  • 你的服务器崩溃，崩溃报告只显示“physics tick”，没有任何其他信息。

Shtreimel 为上述每种情况都提供了相应命令。

它的功能

查找卡顿源

当某个维度的物理切片负载过高时，Shtreimel 会对最可疑的主体进行排名，并在服务器控制台打印一行信息，包含位置、所有者命名、UUID、边界框和可疑度评分。

控制台输出示例：

[shtreimel.lag] lag suspect dim=minecraft:overworld ewma=7.43ms max60=18.20ms uuid=8a1f... name="Big Blimp" plot=(10005,10003) center=(124.0,72.5,-88.3) bb=24x10x32 suspect=83

排名依据可配置的代理指标：体积、占地面积、已加载区块、Sable actor、速度、网络漂移、反作用轮、排队力、相交实体，以及可选的连接/依赖/票据信号。权重和上限均可在配置中调整。

如果你的服务器负载比通常更重或更轻，在正常运行几小时后运行 /shtreimel lag autotune，它会打印 <world>/shtreimel/dimension-overrides.json 的推荐阈值。

你也可以随时获取实时排名：

  • /shtreimel rank
  • /shtreimel physics-stats
  • /shtreimel list

停止卡顿

  • /shtreimel freeze <uuid>
  • /shtreimel freeze nearest [radius]
  • /shtreimel freeze connected <uuid>
  • /shtreimel freeze list
  • /shtreimel unfreeze <uuid>
  • /shtreimel unfreeze connected <uuid>

freeze 将一个装置固定住，而不会暂停整个维度的物理运算。 connected 会冻结一个主体及其所有关联主体。该固定状态在服务器重启后依然有效，卸载后也会保留，且分裂出的子体继承冻结父体的冻结状态。 unfreeze 将主体唤醒。

  • /shtreimel delete uuid <uuid> --confirm
  • /shtreimel delete at <x> <y> <z> --confirm
  • /shtreimel delete nearest --confirm

delete 会执行 Sable 自身的移除流程。与 /sable remove 具有相同的清理效果。

撤销你的失误

  • /shtreimel archive save <uuid> [tag]
  • /shtreimel archive list [uuid] [limit]
  • /shtreimel archive verify <uuid> <archiveId>
  • /shtreimel archive restore <uuid> <archiveId> [keepUuid] [dimension] [at <pos>]
  • /shtreimel archive prune

archive save 会将装置的完整方块数据写入磁盘，并附带压缩后大小和 SHA-256 元数据。 verify 会在你信任某个存档前对其进行检查。 restore 将其恢复，可选择保留相同 UUID。旧版 0.2/0.3 的存档仍可列出和恢复。支持按装置进行撤销。

检查装置

/shtreimel info <uuid>

显示姿态、边界框、质量、质心、质量和刚体有效性、反作用轮、排队力、网络漂移、连接链和加载依赖计数、拆分父体、冻结状态、上次序列化指针、Sable 2 强制加载票据，以及可配置的加载索引分解。在 Sable 1.2.x 上，票据字段会报告 Sable 2 API 不可用。游戏中，标题处有可点击的 [teleport]、[freeze]、[archive] 按钮。

分析单个主体上的受力

  • /shtreimel forces start <uuid> [seconds]
  • /shtreimel forces show <uuid>
  • /shtreimel forces stop <uuid>

Shtreimel 仅对你明确选择的、且处于有界会话中的主体启用单点受力记录，并在停止、过期、移除或关闭时进行清理。结果显示受力组采样数、单点受力数，以及平均/最大力和力矩。

查找位置

  • /shtreimel at <x> <y> <z>
  • /shtreimel in <fromPos> <toPos>
  • /shtreimel near [radius]
  • /shtreimel who <uuid>
  • /shtreimel watch <uuid> [seconds]
  • /shtreimel unwatch

at 显示某个方块位置所属的装置。 in 列出边界框与某区域相交的所有装置。 near 列出调用玩家周围的事物。 who 显示当前位于某装置内的玩家以及正在追踪该装置的玩家。 watch 允许一名工作人员订阅某装置 N 秒的实时姿态更新（非常适合实时跟踪飞艇）。

传送至装置

  • /shtreimel tp <uuid>
  • /shtreimel tp player <playerName> <uuid>
  • /shtreimel tp back

传送至装置边界框顶部。 tp back 会将你传送回原位置。

查看谁做了什么

  • /shtreimel audit tail [n]
  • /shtreimel audit since 1h
  • /shtreimel audit by Steve
  • /shtreimel audit uuid <uuid>

每个破坏性命令（删除、冻结、存档保存/恢复）都会在 <world>/shtreimel/audit.log 中写入一行记录。 tail 读取当前及轮转的日志。可在游戏内查询。

了解实体消失前发生了什么

  • /shtreimel history [limit]
  • /shtreimel history <uuid> [limit]

Shtreimel 为每个 Sable 容器附加一个 SubLevelObserver，并在 Sable 销毁地块之前的精确回调中记录添加和永久移除操作。永久移除会与有效性、姿态、边界、原因以及（启用时）发起调用的调用者栈帧一起镜像到审计日志中。该日志在主体卸载后依然保留，并能捕获单刻内发生的移除操作。

改进崩溃报告

当服务器崩溃时，Shtreimel 会添加一个有界的 -- Shtreimel snapshot -- 块，列出已加载的装置（UUID、名称、位置、边界框、有效性、票据、拓扑结构）、每个维度的物理计时、最近的生命周期/移除事件、活跃的受力分析摘要以及存储指针。NeoForge 使用 CrashReportCallables；Fabric 通过一个故障弱化的友好报告 mixin 输出相同内容。

在安装了 Create 的 NeoForge 服务器上，崩溃报告还可以标识 ContraptionCollider.collideEntities 内部正在处理的装置（Create Aeronautics 飞艇/螺旋桨崩溃）。Create 装置上下文需要 NeoForge；Create 6 和 Aeronautics 在 1.21.1 上发布 NeoForge 版本。

运行 /shtreimel debug crash-header 可在不崩溃服务器的情况下预览该块。

权限

未安装权限模组时，Shtreimel 使用原版 OP 等级：

  • OP 2： 只读命令（list、info、rank、history、watch、空间查询、physics-stats、dump、snapshot diff、lag autotune）。
  • OP 3： 破坏性和改变状态的命令（delete、freeze、archive save / restore / prune / verify、forces start / stop、audit 查询）。
  • OP 4： 可跳过 --confirm 令牌。服务器控制台和 RCON 为 OP 4。

如果你运行权限模组（LuckPerms、FTB Ranks、Fabric Permissions API 等），命名节点为：

  • shtreimel.observe
  • shtreimel.profile
  • shtreimel.delete
  • shtreimel.delete.confirm_bypass
  • shtreimel.audit.read

安装

  1. 确保你的服务器 mods/ 文件夹中有 Sable 1.2.1 或更新版本。
  2. 从 Releases 下载匹配的 jar 文件并放入同一 mods/ 文件夹：
    • NeoForge 上使用 shtreimel-neoforge-1.21.1-<version>.jar，或
    • Fabric 上使用 shtreimel-fabric-1.21.1-<version>.jar。
  3. 启动服务器。配置文件生成在 <world>/serverconfig/shtreimel-server.toml，编辑文件后会自动重新加载。现有 0.3.x 配置、冻结状态、存档、快照和审计日志仍可读取。

就这样。无需在你的玩家客户端上安装任何内容。

兼容性

NeoForge

组件 所需版本
Minecraft 1.21.1
NeoForge 21.1.219 或更新
Java 21
Sable 1.2.1 至 2.x（>=1.2.1 <3.0.0）

NeoForge 可选模组

模组 新增功能
Create 崩溃报告可以标识 ContraptionCollider.collideEntities 中活跃的装置。可通过服务器配置中的 mixins.createContraptionContextEnabled 进行切换。
Create Aeronautics 与 Create 相同的崩溃上下文，当这些装置通过 Create 的碰撞器处理时，会包含 Aeronautics 装置类型（例如飞艇）。

所有其他 Shtreimel 功能都可以在仅安装 Sable 且未安装 Create 的 NeoForge 服务器上运行。

Fabric

组件 所需版本
Minecraft 1.21.1
Fabric Loader 0.16.9 或更新
Fabric API 0.110.0+1.21.1（需要 fabric-command-api-v2 和 fabric-lifecycle-events-v1）
Java 21
Sable 1.2.1 至 2.x（>=1.2.1 <3.0.0）

Fabric 可选模组

模组 新增功能
— 0.4.0 中没有可选模组集成。所有管理、审计、生命周期、冻结、存档、快照和崩溃增强功能均已内置。Create 装置崩溃上下文仅限 NeoForge，因为 Create 6 和 Create Aeronautics 不发布官方的 1.21.1 Fabric 版本。

Fabric jar 内置组件

组件 用途
Fabric Permissions API 0.3.3 与 NeoForge 相同的权限节点和原版 OP 回退

两个加载器通用说明

  • 仅安装一个 Shtreimel jar：shtreimel-neoforge-1.21.1-<version>.jar 或 shtreimel-fabric-1.21.1-<version>.jar。
  • Sable Companion 随 Sable 一同发布；无需额外安装 Shtreimel。
  • 在专用服务器上，玩家无需在客户端安装 Shtreimel。