Script Watchdog

experimental

Watchdog 配置
Watchdog 消息
取消 Watchdog 终止
Watchdog 命令

Watchdog 是脚本引擎的性能监控系统，在 Minecraft 脚本插件中默认启用。

Watchdog 配置

自 1.19.20 版本起，有一组用于管理脚本环境性能的 watchdog 配置选项。这些选项无法在游戏世界或 Realms 中修改，但可以通过 Dedicated Server 的 server.properties 文件进行配置。以下是默认的 watchdog 设置，在所有设备和 Realms 中都相同。

bedrock-server/server.properties

ini

# 启用 watchdog（默认 = true）
script-watchdog-enable=true

# 设置单次 tick 卡顿的 watchdog 阈值（默认 = 3000 毫秒）
script-watchdog-hang-threshold=3000

# 设置单次 tick 性能突增的 watchdog 阈值（默认 = 100 毫秒）
script-watchdog-spike-threshold=100

# 设置多 tick 慢脚本的 watchdog 阈值（默认 = 2 毫秒）
script-watchdog-slow-threshold=2

# 当总内存使用量超过给定阈值（以兆字节为单位）时保存并关闭世界。
# 设置为 0 表示禁用限制。（默认 = 250）
script-watchdog-memory-limit=250

# 当总内存使用量超过给定阈值（以兆字节为单位）时生成内容日志警告。
# 设置为 0 表示禁用警告。（默认 = 100）
script-watchdog-memory-warning=100

# 通过 events.beforeWatchdogTerminate 事件启用 watchdog 异常处理（默认 = true）
script-watchdog-enable-exception-handling=true

# 在未处理的 watchdog 异常情况下启用服务器关闭（默认 = true）
script-watchdog-enable-shutdown=true

# 当发生卡顿时抛出严重异常（默认 = true）
script-watchdog-hang-exception=true

Watchdog 消息

这些 watchdog 消息会以 [Watchdog] 标签在错误或警告中抛出。它们会以警告或错误形式显示，这些错误绝不应被忽略。

在行为包 '%s' 中检测到运行缓慢的脚本（平均 x 毫秒）

脚本运行时间超过特定时间阈值。

在行为包 '%s' 中检测到 x 毫秒的脚本性能突增

脚本运行时间出现突增。

在行为包 '%s' 中检测到内存不足异常

当总内存使用量超过限制时触发此错误。

这会通过 Watchdog 终止保存并关闭世界，且无法通过 BeforeWatchdogTerminateEvent 取消。

在行为包 '%s' 中检测到 x 毫秒的脚本卡顿

脚本在某个位置卡顿超过单次 tick 的 watchdog 阈值。

这通常由迭代（如 while 循环和 for 循环）引起。

在行为包 '%s' 中检测到堆栈溢出

当存在无退出条件的递归函数（调用自身的函数）时发生。

检测到高内存使用量

当总内存使用量超过给定阈值（以兆字节为单位）时生成内容日志警告。

在行为包 '%s' 中检测到未处理的 '%s' 类型严重异常

当发生未处理的严重异常时生成内容日志错误。

Watchdog 决定终止行为包脚本执行的原因有多种：

hang：由于卡顿或无限循环导致脚本无响应。
stackOverflow：过长且可能无限递归的函数调用链。

取消 Watchdog 终止

通过 Minecraft 的脚本 API，您可以连接到一个回调函数，该函数会在脚本运行时因违反性能 watchdog 系统而被终止时调用。

此事件允许您取消脚本运行时的终止，防止 watchdog 停止服务器运行。请注意，根据服务器配置设置，可能不允许取消终止。

import { system } from '@minecraft/server';

system.events.beforeWatchdogTerminate.subscribe((event) => {
  event.cancel = true;
  console.warn(`[Watchdog] 已取消类型为 '${event.cancelationReason}' 的严重异常`);
});