For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt, and this page is available as Markdown at /en/reference/sdk/sapi/runtime/index.md.
SFMC
  • English

      • sapi/runtime

      Functions

      FunctionDescription
      setModuleGuard可选扩展点：Command.trigger 执行前检查所属模块是否启用。install 冷启动模型下不注入。
      splitHelpMessage按完整行拆分帮助文本，避免 Minecraft 客户端截断过长消息。
      setDebugEnabled设置是否将调试日志输出到控制台（默认关闭以保持静默）。
      isDebugEnabled查询当前是否已开启控制台调试日志输出。
      setDebugLevel设置控制台输出的最低日志级别（此项仅约束控制台输出，不影响外部 sink 接收日志）。
      addDebugSink注册自定义日志接收器（sink）；同一引用只会注册一次。
      removeDebugSink移除已注册的自定义日志接收器。
      mergeSectionVisible合并 MenuNavigator 节可见性与单个控件的 visible。
      obsStr创建客户端可写（clientWritable: true）的响应式字符串 Observable 对象。
      obsNum创建客户端可写（clientWritable: true）的响应式数字 Observable 对象。
      obsBool创建客户端可写（clientWritable: true）的响应式布尔 Observable 对象。
      getRuntimeMetrics模块可直接读取平台快照，无需安装 monitor 或访问任意数据库。
      getRuntimeTpsStatus-
      registerSystemMsgHandler注册系统频道消息转发回调（例如同步转发至 QQ 桥等外部通道）。 每次通过 Msg.* 发送消息时均会同步触发此回调；传入空实现或 null 可关闭转发。
      pushOrRewind前进到新页则压栈；目标已在栈中则回退到该页。
      replaceOrRewind替换栈顶；目标已在栈中则回退到该页。
      popHistory返回上一级；根页保持不动。
      pointInArea_2D判断平面二维坐标点 (x, z) 是否落在指定的矩形区域内。 起点与终点可为矩形的任意对角顶点（无需预先排序）。
      getRandomInteger生成闭区间 [min, max] 内的随机整数。
      getBase将方向码映射为二维水平单位向量 [dx, dz]。
      getChestCardinal计算用于放置箱子的 cardinal_direction 朝向属性值（"east"
      getSignFacing获取悬挂墙牌所需的 facing_direction 数值属性（与箱子布局匹配）。
      getLayout计算双箱与墙牌布局中的左箱、右箱及告示牌的三维坐标。 常用于商店柜台、领地箱等「双箱 + 墙牌」的标准布局计算。
      ensureDoubleChest确保在指定坐标放置一对朝向正确的大型双箱；若对应位置已存在箱子方块则跳过。
      placeSign在指定坐标放置墙上告示牌并写入说明文本；若写入失败则静默忽略。
      getShanghaiTime获取当前系统时间的东八区（UTC+8 北京/上海时间）日期与时间字符串。
      formatTimestamp将给定的 Unix 毫秒时间戳格式化为东八区标准的 YYYY-MM-DD HH:mm 字符串。
      generateId生成带有业务类型前缀的随机短 ID（例如 CH_a1b2c3d4）。
      dimensionId将 Minecraft 维度对象转换为紧凑数值代号： - 主世界（overworld）→ 0 - 下界（nether）→ 1 - 末地（the_end）→ 2
      toQueryString将键值字典编码为标准 URL 查询字符串（例如 ?a=1&b=2）；若参数为空则返回空字符串。
      ListFormInfo生成列表表单的正文说明文案：首行添加 [*] 标头，末尾追加“请选择操作：”提示。 若传入空数组则直接返回默认的选择操作提示。

      Classes

      ClassDescription
      Command游戏内原生自定义指令的声明表与触发器。
      Money玩家侧余额缓存助手类。 底层统一通过 service registry 访问 economy.account.* 跨模块服务，并在本地维持短期缓存与并发防重。
      HttpDBSAPI 端 db-server HTTP 客户端门面（底层基于 @minecraft/server-net）。 默认连接本地 3001 端口；各业务模块的 db/config/service 客户端按请求注入各自的私有 token。
      MenuNavigator多页 CustomForm 导航器：section 切换、历史栈与异步任务状态。
      FormStatus表单内联状态行（成功/失败/提示/清空）。
      Permission权限等级（与 Minecraft 原生 PlayerPermissionLevel 对齐）： - Guest = -1：访客以下（仅作内部占位，不参与常规比较） - Any = 0：任意玩家 / 访客（Visitor） - Member = 1：普通成员（Member） - OP = 2：管理员（Operator） - Admin = 3：自定义 / 脚本高级管理员（Custom）

      Interfaces

      InterfaceDescription
      EconomyAccount玩家经济账户快照（余额 + 乐观锁版本号）。
      EconomyTransactionRequest经济交易请求（credit/debit 共用形状）。
      EconomyTransactionResult经济交易结果。
      PageCustomForm 页面构建器接口（支持链式添加各类表单控件）。
      RuntimeMetrics-

      Type Aliases

      Type AliasDescription
      CommandCost指令执行费用配置。
      CommandEnumParameter原生命令的单个枚举参数声明。新代码优先使用 parameters。
      CommandParameterType自定义命令参数类型。枚举之外的类型由原生命令直接解析。
      CommandParameter一条原生命令参数。 可选参数必须排在必填参数之后，和 Bedrock 自定义命令的规则一致。
      CommandOptions原生命令名称、别名与参数选项。
      CommandEntry已注册指令的元数据与回调。
      DebugLevel-
      DebugSink调试日志扩展输出目标接口（例如 Sentry 等监控工具可通过此接口接入，无需修改核心分发逻辑）。
      HttpRequestAuthOpts单次 HTTP 请求鉴权选项；模块客户端应按请求传递各自的 token，避免覆盖进程级默认值。
      PageBuildFnsection 构建函数签名：交给 MenuNavigator.section(id, title, build)。
      IDType业务实体 ID 类型前缀：CH 宝箱 / M 货币 / RP 领地 / L 日志 / CP 检查点。

      Variables

      VariableDescription
      LEVELS调试级别映射常量（DEBUG / INFO / WARN / ERROR → 数值）。仅作 DebugLevel 类型来源，请勿直接引用其内部数值。
      debugSAPI 调试日志门面（DEBUG/INFO/WARN 控制台默认关闭；ERROR 始终 console.warn）。 d/i/w/e 对应 DEBUG/INFO/WARN/ERROR；首参为短模块标签。 e 的 args 中若含 Error，Sentry sink 会优先用于 captureException。
      SafeHttpMethod跨版本兼容的 HttpRequestMethod（动态桥接 Bedrock 现代 PascalCase 与 npm 历史大写枚举）。
      ObservableBoolean-
      ObservableNumber-
      ObservableString-
      Msg玩家频道消息门面。统一前缀与文本色彩规范，禁止业务模块直接调用原生的 player.sendMessage()。
      SFMC_SAPI_RUNTIME_VERSION@sfmc-bds/sdk/sapi/runtime 能力面版本号