#sapi/runtime
#Functions
| Function | Description |
|---|---|
| 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
| Class | Description |
|---|---|
| Command | 游戏内原生自定义指令的声明表与触发器。 |
| Money | 玩家侧余额缓存助手类。 底层统一通过 service registry 访问 economy.account.* 跨模块服务，并在本地维持短期缓存与并发防重。 |
| HttpDB | SAPI 端 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
| Interface | Description |
|---|---|
| EconomyAccount | 玩家经济账户快照（余额 + 乐观锁版本号）。 |
| EconomyTransactionRequest | 经济交易请求（credit/debit 共用形状）。 |
| EconomyTransactionResult | 经济交易结果。 |
| Page | CustomForm 页面构建器接口（支持链式添加各类表单控件）。 |
| RuntimeMetrics | - |
#Type Aliases
| Type Alias | Description |
|---|---|
| CommandCost | 指令执行费用配置。 |
| CommandEnumParameter | 原生命令的单个枚举参数声明。新代码优先使用 parameters。 |
| CommandParameterType | 自定义命令参数类型。枚举之外的类型由原生命令直接解析。 |
| CommandParameter | 一条原生命令参数。 可选参数必须排在必填参数之后，和 Bedrock 自定义命令的规则一致。 |
| CommandOptions | 原生命令名称、别名与参数选项。 |
| CommandEntry | 已注册指令的元数据与回调。 |
| DebugLevel | - |
| DebugSink | 调试日志扩展输出目标接口（例如 Sentry 等监控工具可通过此接口接入，无需修改核心分发逻辑）。 |
| HttpRequestAuthOpts | 单次 HTTP 请求鉴权选项；模块客户端应按请求传递各自的 token，避免覆盖进程级默认值。 |
| PageBuildFn | section 构建函数签名：交给 MenuNavigator.section(id, title, build)。 |
| IDType | 业务实体 ID 类型前缀：CH 宝箱 / M 货币 / RP 领地 / L 日志 / CP 检查点。 |
#Variables
| Variable | Description |
|---|---|
| LEVELS | 调试级别映射常量（DEBUG / INFO / WARN / ERROR → 数值）。仅作 DebugLevel 类型来源，请勿直接引用其内部数值。 |
| debug | SAPI 调试日志门面（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 能力面版本号 |