sapdon 3.3.3 → 3.5.0

package/prod/core/index.d.ts

@@ -248,7 +248,7 @@ declare class AddonAttachable {
     format_version: string;
     definitions: AddonAttachableDefinition;
     constructor(format_version: string, definitions: AddonAttachableDefinition);
-    toObject(): Record<string, any>;
+    toObject(): Record<string, unknown>;
 }
 declare class AddonAttachableDefinition {
     description: AddonAttachableDescription;
@@ -262,8 +262,8 @@ declare class AddonAttachableDescription {
     animations?: Record<string, string>;
     animation_controllers?: Record<string, string>[];
     render_controllers?: string[];
-    locators?: Record<string, any>;
-    scripts?: Record<string, any>;
+    locators?: Record<string, unknown>;
+    scripts?: Record<string, unknown>;
     constructor(identifier: string);
     addMaterial(name: string, material: string): this;
     addTexture(name: string, texture: string): this;
@@ -271,25 +271,25 @@ declare class AddonAttachableDescription {
     addAnimation(name: string, animation: string): this;
     addAnimationController(name: string, controller: string): this;
     addRenderController(controller: string): this;
-    addLocator(name: string, locator: any): this;
-    setScript(key: string, value: string): this;
+    addLocator(name: string, locator: unknown): this;
+    setScript(key: string, value: unknown): this;
 }
 
 declare class AddonItem {
     format_version: string;
     definitions: AddonItemDefinition;
     constructor(format_version: string, definitions: AddonItemDefinition);
-    toObject(): Record<string, any>;
+    toObject(): Record<string, unknown>;
 }
 declare class AddonItemDefinition {
     description: AddonItemDescription;
-    components: Record<string, any>;
-    constructor(description: AddonItemDescription, components: Record<string, any>);
+    components: Record<string, unknown>;
+    constructor(description: AddonItemDescription, components: Record<string, unknown>);
 }
 declare class AddonItemDescription {
     identifier: string;
-    menu_category: any;
-    constructor(identifier: string, menu_category: any);
+    menu_category: AddonMenuCategory;
+    constructor(identifier: string, menu_category: AddonMenuCategory);
 }
 
 declare class AddonRecipe {
@@ -455,9 +455,9 @@ declare class BasicBlock {
     /**
      * 添加方块变体
      * @param {string} condition 变体条件
-     * @param {Map} componentMap 组件 Map
+     * @param {Map|Object} component 组件 Map 或普通对象
      */
-    addPermutation(condition: string, componentMap: Map<any, any>): this;
+    addPermutation(condition: string, component: Map<any, any> | Object): this;
     /**
      * 将方块对象转换为 JSON 格式
      * @returns {Object} JSON 格式的方块对象
@@ -497,38 +497,37 @@ declare class Block extends BasicBlock {
     #private;
 }
 
-declare class BlockComponent {
+/** @template T */
+declare class BlockComponent<T> {
     /**
-     *
-     * @param {string} texture
-     * @param {string?} tint_method
-     * @returns
+     * @param {string} texture - 纹理短名
+     * @param {Object|string} [options] - 可选参数对象，或旧版 tint_method 字符串
+     * @param {number} [options.particle_count] - 粒子数量 (0-255，默认 100)
+     * @param {string} [options.tint_method] - 染色方法（如 "grass"）
+     * @returns {Map<string, any>}
      */
-    static setDestructionParticles(texture: string, tint_method: string | null): Map<string, {
-        texture: string;
-        tint_method: string | null;
-    }>;
+    static setDestructionParticles(texture: string, options?: Object | string): Map<string, any>;
     /**
      * 自定义方块组件
      * [warning] 需要 Scripting V2.0.0
      * @param {string} component_id 组件标识符
      * @param {object} params 自定义参数接口对象
-     * @returns {Map} 物品组件Map
+     * @returns {Map<string, any>} 物品组件Map
      */
-    static setCustomComponentV2(component_id: string, params: object): Map<any, any>;
+    static setCustomComponentV2(component_id: string, params: object): Map<string, any>;
     /**
      *
      * @param {Array} interval_range
      * @param {boolean} looping
-     * @returns
-     */
-    static setTick(interval_range: any[], looping: boolean): Map<any, any>;
+      * @returns {Map<string, any>}
+      */
+    static setTick(interval_range: any[], looping: boolean): Map<string, any>;
     /**
      *
-     * @param {Array} custom_components
-     * @returns
-     */
-    static setCustomComponents(custom_components: any[]): Map<any, any>;
+      * @param {Array} custom_components
+      * @returns {Map<string, any>}
+      */
+    static setCustomComponents(custom_components: any[]): Map<string, any>;
     /**
    * 创建一个用于 Minecraft 方块的变换对象，并返回一个 Map。
    * @param {number[]} [translation=[0, 0, 0]] - 平移向量 [x, y, z]。
@@ -536,177 +535,299 @@ declare class BlockComponent {
    * @param {number[]} [scale_pivot=[0, 0, 0]] - 缩放的枢轴点 [x, y, z]。
    * @param {number[]} [rotation=[0, 0, 0]] - 旋转向量（角度）[x, y, z]。
    * @param {number[]} [rotation_pivot=[0, 0, 0]] - 旋转的枢轴点 [x, y, z]。
-   * @returns {Map} - 一个包含变换数据的 Map 对象。
+   * @returns {Map<string, any>} - 一个包含变换数据的 Map 对象。
    * @throws {Error} - 如果任何参数无效，则抛出错误。
    */
-    static setTransformation(translation?: number[], scale?: number[], scale_pivot?: number[], rotation?: number[], rotation_pivot?: number[]): Map<any, any>;
+    static setTransformation(translation?: number[], scale?: number[], scale_pivot?: number[], rotation?: number[], rotation_pivot?: number[]): Map<string, any>;
     /**
      * 设置方块的呼吸行为。
      * @param {String} value - 呼吸行为，可选值为 "solid" 或 "air"。
-     * @returns {Map} - 新的组件集合。
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setBreathability(value: string): Map<any, any>;
+    static setBreathability(value: string): Map<string, any>;
     /**
      * 启用或禁用方块的碰撞箱。
      * @param {Boolean} enabled - 是否启用碰撞箱。
-     * @returns {Map} - 新的组件集合。
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setCollisionBoxEnabled(enabled: boolean): Map<any, any>;
+    static setCollisionBoxEnabled(enabled: boolean): Map<string, any>;
     /**
      * 设置自定义的碰撞箱。
      * @param {Array} origin - 碰撞箱的起点坐标 [x, y, z]。
      * @param {Array} size - 碰撞箱的大小 [width, height, depth]。
-     * @returns {Map} - 新的组件集合。
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setCollisionBoxCustom(origin: any[], size: any[]): Map<any, any>;
+    static setCollisionBoxCustom(origin: any[], size: any[]): Map<string, any>;
     /**
      * 设置方块的合成台属性。
      * @param {Array} craftingTags - 合成标签。
      * @param {String} tableName - 合成台名称。
-     * @returns {Map} - 新的组件集合。
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setCraftingTable(craftingTags: any[], tableName: string): Map<any, any>;
+    static setCraftingTable(craftingTags: any[], tableName: string): Map<string, any>;
     /**
      * 启用或禁用方块的爆炸抗性。
      * @param {Boolean} enabled - 是否启用爆炸抗性。
-     * @returns {Map} - 新的组件集合。
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setDestructibleByExplosionEnabled(enabled: boolean): Map<any, any>;
+    static setDestructibleByExplosionEnabled(enabled: boolean): Map<string, any>;
     /**
      * 设置自定义的爆炸抗性。
      * @param {Number} explosionResistance - 爆炸抗性值。
-     * @returns {Map} - 新的组件集合。
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setDestructibleByExplosionCustom(explosionResistance: number): Map<any, any>;
+    static setDestructibleByExplosionCustom(explosionResistance: number): Map<string, any>;
     /**
      * 启用或禁用方块的挖掘抗性。
      * @param {Boolean} enabled - 是否启用挖掘抗性。
-     * @returns {Map} - 新的组件集合。
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setDestructibleByMiningEnabled(enabled: boolean): Map<any, any>;
+    static setDestructibleByMiningEnabled(enabled: boolean): Map<string, any>;
     /**
      * 设置自定义的挖掘抗性。
      * @param {Number} secondsToDestroy - 破坏所需时间（秒）。
      * @param {Array} itemSpecificSpeeds - 特定工具的挖掘速度。
-     * @returns {Map} - 新的组件集合。
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setDestructibleByMiningCustom(secondsToDestroy: number, itemSpecificSpeeds: any[]): Map<any, any>;
+    static setDestructibleByMiningCustom(secondsToDestroy: number, itemSpecificSpeeds: any[]): Map<string, any>;
     /**
      * 设置方块的显示名称。
      * @param {String} displayName - 显示名称。
-     * @returns {Map} - 新的组件集合。
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setDisplayName(displayName: string): Map<any, any>;
+    static setDisplayName(displayName: string): Map<string, any>;
     /**
      * 启用或禁用方块的易燃性。
      * @param {Boolean} enabled - 是否启用易燃性。
-     * @returns {Map} - 新的组件集合。
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setFlammableEnabled(enabled: boolean): Map<any, any>;
+    static setFlammableEnabled(enabled: boolean): Map<string, any>;
     /**
      * 设置自定义的易燃性。
      * @param {Number} catchChanceModifier - 着火概率。
      * @param {Number} destroyChanceModifier - 被火焰摧毁的概率。
-     * @returns {Map} - 新的组件集合。
+     * @param {String} [lava_flammable] - 岩浆能否点燃该方块 ("always"|"never"，默认 "never")
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setFlammableCustom(catchChanceModifier: number, destroyChanceModifier: number): Map<any, any>;
+    static setFlammableCustom(catchChanceModifier: number, destroyChanceModifier: number, lava_flammable?: string): Map<string, any>;
     /**
      * 设置方块的摩擦力。
      * @param {Number} value - 摩擦力值，范围为 0.0 到 0.9。
-     * @returns {Map} - 新的组件集合。
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setFriction(value: number): Map<any, any>;
+    static setFriction(value: number): Map<string, any>;
     /**
      * 设置方块的几何模型。
      * @param {String} identifier - 几何模型标识符。
-     * @param {Object} bone_visibility - 骨骼可见性配置。
-     * @returns {Map} - 新的组件集合。
-     */
-    static setGeometry(identifier: string, bone_visibility: Object): Map<any, any>;
+     * @param {Object} [options] - 可选参数。
+     * @param {Object} [options.bone_visibility] - 骨骼可见性配置。
+     * @param {String} [options.culling] - 裁剪规则标识符（格式: <namespace>:culling.<name>）。
+     * @param {String} [options.culling_layer] - 裁剪层标识符（如 "minecraft:culling_layer.leaves"）。
+     * @param {String} [options.culling_shape] - 体素形状（仅支持 "minecraft:unit_cube"）。
+     * @param {Boolean|String[]} [options.uv_lock] - 是否锁定 UV 旋转，或指定骨骼名称数组。
+     * @returns {Map<string, any>} - 新的组件集合。
+     */
+    static setGeometry(identifier: string, options?: {
+        bone_visibility?: Object | undefined;
+        culling?: string | undefined;
+        culling_layer?: string | undefined;
+        culling_shape?: string | undefined;
+        uv_lock?: boolean | string[] | undefined;
+    }): Map<string, any>;
     /**
      * 设置方块的骨骼可见性。
      * @param {Object} bone_visibility - 骨骼可见性配置。
-     * @returns {Map} - 新的组件集合。
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setBoneVisibility(bone_visibility: Object): Map<any, any>;
+    static setBoneVisibility(bone_visibility: Object): Map<string, any>;
     /**
      * 设置方块的物品视觉属性。
      * @param {String} geometry - 几何模型标识符。
      * @param {Object} materialInstances - 材质实例配置。
-     * @returns {Map} - 新的组件集合。
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setItemVisual(geometry: string, materialInstances: Object): Map<any, any>;
+    static setItemVisual(geometry: string, materialInstances: Object): Map<string, any>;
     /**
      * 设置方块的光衰减值。
      * @param {Number} value - 光的衰减值，范围为 0 到 15。
-     * @returns {Map} - 新的组件集合。
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setLightDampening(value: number): Map<any, any>;
+    static setLightDampening(value: number): Map<string, any>;
     /**
      * 设置方块的光照强度。
      * @param {Number} value - 光照强度，范围为 0 到 15。
-     * @returns {Map} - 新的组件集合。
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setLightEmission(value: number): Map<any, any>;
+    static setLightEmission(value: number): Map<string, any>;
     /**
      * 设置方块的液体检测属性。
-     * @param {Boolean} canContainLiquid - 是否可以包含液体。
-     * @param {String} liquidType - 液体类型。
-     * @param {String} onLiquidTouches - 对液体的反应方式。
-     * @param {Array} stopsLiquidFlowingFromDirection - 阻止液体流动的方向。
-     * @returns {Map} - 新的组件集合。
+     * @param {Boolean|Object} canContainLiquid - 是否可容纳液体，或是完整选项对象
+     * @param {String} [liquidType] - 液体类型
+     * @param {String} [onLiquidTouches] - 对液体的反应方式
+     * @param {Array} [stopsLiquidFlowingFromDirection] - 阻止液体流动的方向
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setLiquidDetection(canContainLiquid: boolean, liquidType: string, onLiquidTouches: string, stopsLiquidFlowingFromDirection: any[]): Map<any, any>;
+    static setLiquidDetection(canContainLiquid: boolean | Object, liquidType?: string, onLiquidTouches?: string, stopsLiquidFlowingFromDirection?: any[]): Map<string, any>;
     /**
      * 设置方块的战利品表路径。
      * @param {String} path - 战利品表路径。
-     * @returns {Map} - 新的组件集合。
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setLoot(path: string): Map<any, any>;
+    static setLoot(path: string): Map<string, any>;
     /**
      * 设置方块的地图颜色。
-     * @param {String|Array} value - 地图颜色，可以是十六进制字符串或 RGB 数组。
-     * @returns {Map} - 新的组件集合。
+     * @param {String|Array|Object} value - 地图颜色，可以是十六进制字符串、RGB 数组或对象格式。
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setMapColor(value: string | any[]): Map<any, any>;
+    static setMapColor(value: string | any[] | Object): Map<string, any>;
     /**
      * 设置方块的材质实例。
      * @param {Object} instances - 材质实例配置。
-     * @returns {Map} - 新的组件集合。
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setMaterialInstances(instances: Object): Map<any, any>;
+    static setMaterialInstances(instances: Object): Map<string, any>;
     /**
      * 设置方块的放置过滤条件。
      * @param {Array} conditions - 放置条件列表。
-     * @returns {Map} - 新的组件集合。
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setPlacementFilter(conditions: any[]): Map<any, any>;
+    static setPlacementFilter(conditions: any[]): Map<string, any>;
     /**
      * 设置方块的红石导电性。
      * @param {Boolean} allowsWireToStepDown - 是否允许红石线向下阶梯连接。
      * @param {Boolean} redstoneConductor - 方块是否可以被红石信号激活。
-     * @returns {Map} - 新的组件集合。
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setRedstoneConductivity(allowsWireToStepDown: boolean, redstoneConductor: boolean): Map<any, any>;
+    static setRedstoneConductivity(allowsWireToStepDown: boolean, redstoneConductor: boolean): Map<string, any>;
     /**
      * 启用或禁用方块的选择框。
      * @param {Boolean} enabled - 是否启用选择框。
-     * @returns {Map} - 新的组件集合。
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setSelectionBoxEnabled(enabled: boolean): Map<any, any>;
+    static setSelectionBoxEnabled(enabled: boolean): Map<string, any>;
     /**
      * 设置自定义的选择框。
      * @param {Array} origin - 选择框的起点坐标 [x, y, z]。
      * @param {Array} size - 选择框的大小 [width, height, depth]。
-     * @returns {Map} - 新的组件集合。
+     * @returns {Map<string, any>} - 新的组件集合。
+     */
+    static setSelectionBoxCustom(origin: any[], size: any[]): Map<string, any>;
+    /**
+     * 设置方块实体（Block Entity，实验性功能，需开启 Upcoming Creator Features）。
+     * @param {Boolean} [dynamic_properties=false] - 是否启用动态属性存储。
+     * @returns {Map<string, any>} - 新的组件集合。
+     */
+    static setBlockEntity(dynamic_properties?: boolean): Map<string, any>;
+    /**
+     * 设置方块的活塞移动行为。
+     * @param {String} movement_type - 移动类型: "immovable" | "popped" | "push" | "push_pull"。
+     * @param {String} [sticky] - 黏性行为: "same" 可复制黏液块/蜂蜜块功能。
+     * @returns {Map<string, any>} - 新的组件集合。
+     */
+    static setMovable(movement_type: string, sticky?: string): Map<string, any>;
+    /**
+     * 设置方块的监听红石信号行为（配合自定义组件 onRedstoneUpdate 使用）。
+     * @param {Number} min_power - 最小触发红石信号强度 (0-15)。
+     * @param {Boolean} [propagates_power] - 是否传导红石信号。
+     * @returns {Map<string, any>} - 新的组件集合。
+     */
+    static setRedstoneConsumer(min_power: number, propagates_power?: boolean): Map<string, any>;
+    /**
+     * 设置方块产生红石信号。
+     * @param {Number} power - 信号强度 (0-15)。
+     * @param {String} strongly_powered_face - 强充能方向: "up" | "down" | "north" | "south" | "east" | "west"。
+     * @param {String[]} [connected_faces] - 连接的方向数组。
+     * @param {Boolean} [transform_relative] - 面方向是否相对于变换组件的旋转。
+     * @returns {Map<string, any>} - 新的组件集合。
+     */
+    static setRedstoneProducer(power: number, strongly_powered_face: string, connected_faces?: string[], transform_relative?: boolean): Map<string, any>;
+    /**
+     * 设置方块可被替换（放置其他方块时替换此方块）。
+     * @returns {Map<string, any>} - 新的组件集合。
+     */
+    static setReplaceable(): Map<string, any>;
+    /**
+     * 设置方块的支撑形状。
+     * @param {String} shape - 支撑形状: "fence" | "stair"。
+     * @returns {Map<string, any>} - 新的组件集合。
+     */
+    static setSupport(shape: string): Map<string, any>;
+    /**
+     * 设置方块标签。
+     * @param {String[]} tags - 标签数组。
+     * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setSelectionBoxCustom(origin: any[], size: any[]): Map<any, any>;
+    static setTags(tags: string[]): Map<string, any>;
+    /**
+     * 设置方块可被拴绳拴住（类似栅栏）。
+     * @param {Number[]} [offset=[0, 12, 0]] - 拴绳结位置偏移 [x, y, z]。
+     * @returns {Map<string, any>} - 新的组件集合。
+     */
+    static setLeashable(offset?: number[]): Map<string, any>;
+    /**
+     * 设置方块对实体坠落事件的触发。
+     * @param {Number} min_fall_distance - 最小坠落距离（方块数）。
+     * @returns {Map<string, any>} - 新的组件集合。
+     */
+    static setEntityFallOn(min_fall_distance: number): Map<string, any>;
+    /**
+     * 设置方块可放入花盆（配合 setEmbeddedVisual 使用）。
+     * @returns {Map<string, any>} - 新的组件集合。
+     */
+    static setFlowerPottable(): Map<string, any>;
+    /**
+     * 设置方块与降水（雨/雪）的交互行为。
+     * @param {String} behavior - 降水行为: "obstruct_rain_accumulate_snow" | "obstruct_rain" | "snowlogging" | "none"。
+     * @returns {Map<string, any>} - 新的组件集合。
+     */
+    static setPrecipitationInteractions(behavior: string): Map<string, any>;
+    /**
+     * 设置方块的随机偏移（碰撞箱/选择框/几何）。
+     * @param {Object} axis_config - 每个轴的偏移配置。
+     * @param {Object} [axis_config.x] - X 轴配置。
+     * @param {Object} [axis_config.y] - Y 轴配置。
+     * @param {Object} [axis_config.z] - Z 轴配置。
+     * @param {Object} axis_config.x.range - 范围 {min, max}。
+     * @param {Number} [axis_config.x.steps=0] - 步数（0=任意值）。
+     * @returns {Map<string, any>} - 新的组件集合。
+     */
+    static setRandomOffset(axis_config: {
+        x?: Object | undefined;
+        y?: Object | undefined;
+        z?: Object | undefined;
+    }): Map<string, any>;
+    /**
+     * 设置方块对箱子开启的遮挡行为。
+     * @param {String} rule - 遮挡规则: "always" | "never" | "shape"。
+     * @returns {Map<string, any>} - 新的组件集合。
+     */
+    static setChestObstruction(rule: string): Map<string, any>;
+    /**
+     * 设置方块在花盆中的显示外观。
+     * @param {String|Object} geometry - 几何标识符或几何对象。
+     * @param {Object} material_instances - 材质实例。
+     * @returns {Map<string, any>} - 新的组件集合。
+     */
+    static setEmbeddedVisual(geometry: string | Object, material_instances: Object): Map<string, any>;
+    /**
+     * 设置方块与栅栏/墙等方块的连接规则。
+     * @param {String} [accepts_from="all"] - 连接来源: "all" | "only_fences" | "none"。
+     * @param {String[]} [enabled_directions] - 允许连接的方向数组。
+     * @returns {Map<string, any>} - 新的组件集合。
+     */
+    static setConnectionRule(accepts_from?: string, enabled_directions?: string[]): Map<string, any>;
+    /**
+     * 设置方块的声音。
+     * @param {String} sound - 声音名称。
+     * @returns {Map<string, any>} - 新的组件集合。
+     */
+    static setSound(sound: string): Map<string, any>;
     /**
      * 将多个组件集合合并为一个。
      * @param {...Map} componentMaps - 多个组件集合。
-     * @returns {Map} - 合并后的组件集合。
+     * @returns {Map<string, any>} - 合并后的组件集合。
      */
-    static combineComponents(...componentMaps: Map<any, any>[]): Map<any, any>;
+    static combineComponents(...componentMaps: Map<any, any>[]): Map<string, any>;
     /**
      * 获取当前组件的 JSON 表示。
      * @param {Map} components - 组件集合。
@@ -715,6 +836,144 @@ declare class BlockComponent {
     static toJSON(components: Map<any, any>): Object;
 }
 
+interface BeforeOnPlayerPlaceEvent {
+    block: any;
+    cancel: boolean;
+    dimension: any;
+    face: string;
+    permutationToPlace: any;
+    player?: any;
+}
+interface OnBlockStateChangeEvent {
+    block: any;
+    dimension: any;
+    previousPermutation: any;
+}
+interface OnBreakEvent {
+    block: any;
+    dimension: any;
+    blockDestructionSource?: any;
+    brokenBlockPermutation: any;
+    entitySource?: any;
+}
+interface OnEntityEvent {
+    block: any;
+    blockPermutation: any;
+    dimension: any;
+    entitySource: any;
+    name: string;
+}
+interface OnEntityFallOnEvent {
+    block: any;
+    dimension: any;
+    entity?: any;
+    fallDistance: number;
+}
+interface OnPlaceEvent {
+    block: any;
+    dimension: any;
+    previousBlock: any;
+}
+interface OnPlayerBreakEvent {
+    block: any;
+    brokenBlockPermutation: any;
+    dimension: any;
+    player?: any;
+}
+interface OnPlayerInteractEvent {
+    block: any;
+    dimension: any;
+    face: string;
+    faceLocation: any;
+    player?: any;
+}
+interface OnRandomTickEvent {
+    block: any;
+    dimension: any;
+}
+interface OnRedstoneUpdateEvent {
+    block: any;
+    dimension: any;
+    power: number;
+}
+interface OnStepOffEvent {
+    block: any;
+    dimension: any;
+    entity?: any;
+}
+interface OnStepOnEvent {
+    block: any;
+    dimension: any;
+    entity?: any;
+}
+interface OnTickEvent {
+    block: any;
+    dimension: any;
+}
+interface BlockCustomComponentHandlers {
+    beforeOnPlayerPlace?: (event: BeforeOnPlayerPlaceEvent) => void;
+    onBlockStateChange?: (event: OnBlockStateChangeEvent) => void;
+    onBreak?: (event: OnBreakEvent) => void;
+    onEntity?: (event: OnEntityEvent) => void;
+    onEntityFallOn?: (event: OnEntityFallOnEvent) => void;
+    onPlace?: (event: OnPlaceEvent) => void;
+    onPlayerBreak?: (event: OnPlayerBreakEvent) => void;
+    onPlayerInteract?: (event: OnPlayerInteractEvent) => void;
+    onRandomTick?: (event: OnRandomTickEvent) => void;
+    onRedstoneUpdate?: (event: OnRedstoneUpdateEvent) => void;
+    onStepOff?: (event: OnStepOffEvent) => void;
+    onStepOn?: (event: OnStepOnEvent) => void;
+    onTick?: (event: OnTickEvent) => void;
+}
+/**
+ * 块自定义组件构建器 - 提供流式 API 定义块事件处理器，
+ * 并提供类型安全的事件参数绑定。
+ *
+ * @example
+ * ```ts
+ * const comp = new BlockCustomComponentBuilder('wiki:my_comp')
+ *   .onTick()                        // 只声明事件类型，生成骨架代码
+ *   .onPlayerInteract(({ player }) => { ... })  // 带完整 handler
+ *
+ * // 在 block JSON 中注册组件 ID
+ * block.addComponent(BlockComponent.setCustomComponents([comp.id()]))
+ * ```
+ */
+declare class BlockCustomComponentBuilder {
+    private static allInstances;
+    private componentId;
+    private handlers;
+    private declaredEvents;
+    constructor(componentId: string);
+    /** 返回所有已创建的构建器实例 */
+    static getAllInstances(): BlockCustomComponentBuilder[];
+    /** 重置实例列表（用于测试/热重载） */
+    static resetInstances(): void;
+    /** 返回组件标识符，用于 setCustomComponents */
+    id(): string;
+    /** 返回已声明（含 handler）的事件名称列表 */
+    declaredEventNames(): string[];
+    /** 返回已注册的事件处理器数量 */
+    handlerCount(): number;
+    beforeOnPlayerPlace(handler?: (event: BeforeOnPlayerPlaceEvent) => void): this;
+    onBlockStateChange(handler?: (event: OnBlockStateChangeEvent) => void): this;
+    onBreak(handler?: (event: OnBreakEvent) => void): this;
+    onEntity(handler?: (event: OnEntityEvent) => void): this;
+    onEntityFallOn(handler?: (event: OnEntityFallOnEvent) => void): this;
+    onPlace(handler?: (event: OnPlaceEvent) => void): this;
+    onPlayerBreak(handler?: (event: OnPlayerBreakEvent) => void): this;
+    onPlayerInteract(handler?: (event: OnPlayerInteractEvent) => void): this;
+    onRandomTick(handler?: (event: OnRandomTickEvent) => void): this;
+    onRedstoneUpdate(handler?: (event: OnRedstoneUpdateEvent) => void): this;
+    onStepOff(handler?: (event: OnStepOffEvent) => void): this;
+    onStepOn(handler?: (event: OnStepOnEvent) => void): this;
+    onTick(handler?: (event: OnTickEvent) => void): this;
+    /** 构建处理器对象，可用于 runtime 的 registerCustomComponent */
+    build(): BlockCustomComponentHandlers;
+    /** 生成 runtime 脚本模块源码 */
+    generateRuntimeCode(): string;
+}
+
 declare class CropBlock extends Block {
     stageNum: number;
 }
@@ -855,9 +1114,8 @@ declare class FeatureRule {
     toObject(): any;
 }
 
-declare class OreBlock {
+declare class OreBlock extends BasicBlock {
     constructor(identifier: any, category: any, textures_arr: any, options?: {});
-    block: BasicBlock;
     feature: OreFeature;
     feature_rules: FeatureRule;
 }
@@ -878,7 +1136,7 @@ declare class RotatableBlock extends BasicBlock {
      * @param {string} options.group 分组，默认为 "construction"
      * @param {boolean} options.hide_in_command 是否在命令中隐藏，默认为 false
      * @param {string} options.rotationType 旋转类型，默认为 "cardinal"
-     * @param {number} options.yRotationOffset 初始旋转偏移量，默认为 180
+     * @param {number} options.yRotationOffset 初始旋转偏移量，默认为 0
      */
     constructor(identifier: string, category: string, textures_arr: any[], options?: {
         group: string;
@@ -1060,6 +1318,71 @@ declare class TileBlock {
     setScript(key: any, value: any): void;
 }
 
+declare class GlassBlock extends BasicBlock {
+    constructor(identifier: any, category: any, texture: any, options?: {});
+}
+
+declare class HeadBlock extends BasicBlock {
+    constructor(identifier: any, category: any, texture: any, options?: {});
+    #private;
+}
+
+declare class FenceBlock extends BasicBlock {
+    constructor(identifier: any, category: any, textures_arr: any, options?: {});
+}
+
+declare class StairBlock extends BasicBlock {
+    constructor(identifier: any, category: any, textures_arr: any, options?: {});
+    #private;
+}
+
+declare class TrapdoorBlock extends BasicBlock {
+    constructor(identifier: any, category: any, texture: any, options?: {});
+    #private;
+}
+
+declare const TintMethod: {
+    readonly GRASS: "grass";
+    readonly WATER: "water";
+    readonly DEFAULT_FOLIAGE: "default_foliage";
+    readonly EVERGREEN_FOLIAGE: "evergreen_foliage";
+    readonly DRY_FOLIAGE: "dry_foliage";
+    readonly BIRCH_FOLIAGE: "birch_foliage";
+};
+type TintMethod = (typeof TintMethod)[keyof typeof TintMethod];
+
+interface FlipbookEntry {
+    flipbook_texture: string;
+    atlas_tile?: string;
+    ticks_per_frame?: number;
+    blend_frames?: boolean;
+    replicate?: number;
+}
+declare class FlipbookTextureConfig {
+    private entries;
+    addEntry(entry: FlipbookEntry): this;
+    addEntries(entries: FlipbookEntry[]): this;
+    toObject(): {
+        flipbook_textures: FlipbookEntry[];
+    };
+}
+
+interface TextureVariation {
+    path: string;
+    weight?: number;
+}
+interface TextureEntry {
+    textures: string | TextureVariation[];
+}
+declare class TextureVariationConfig {
+    private textureData;
+    addTexture(name: string, path: string): this;
+    addTextureWithVariations(name: string, variations: TextureVariation[]): this;
+    toObject(): {
+        texture_data: Record<string, TextureEntry>;
+    };
+}
+
 declare class DummyEntity extends Entity {
     constructor(identifier: any, texture: any, options: {} | undefined, behData: any, resData: any);
 }
@@ -1306,6 +1629,62 @@ declare class PickupItemsBehavior {
     toObject(): Map<string, object>;
 }
 
+declare class MoveTowardsHomeRestrictionBehavior {
+    /**
+     * 创建 minecraft:behavior.move_towards_home_restriction 组件。
+     * @param {number} priority 行为的优先级
+     */
+    constructor(priority: number);
+    priority: number;
+    speed_multiplier: number;
+    /**
+     * 设置移动速度倍数。
+     * @param {number} speedMultiplier 移动速度倍数
+     * @returns {MoveTowardsHomeRestrictionBehavior} 返回当前实例以支持链式调用
+     */
+    setSpeedMultiplier(speedMultiplier: number): MoveTowardsHomeRestrictionBehavior;
+    /**
+     * 将组件转换为 JSON 对象。
+     * @returns {Object} minecraft:behavior.move_towards_home_restriction 组件的 JSON 对象
+     */
+    toObject(): Object;
+}
+
+declare class GoHomeBehavior {
+    /**
+     * 创建 minecraft:behavior.go_home 组件。
+     * @param {number} priority 行为的优先级
+     */
+    constructor(priority: number);
+    priority: number;
+    speed_multiplier: number;
+    goal_radius: number;
+    interval: number;
+    /**
+     * 设置移动速度倍数。
+     * @param {number} speedMultiplier 移动速度倍数
+     * @returns {GoHomeBehavior} 返回当前实例以支持链式调用
+     */
+    setSpeedMultiplier(speedMultiplier: number): GoHomeBehavior;
+    /**
+     * 设置回家目标判定半径。
+     * @param {number} goalRadius 判定半径（方块格）
+     * @returns {GoHomeBehavior} 返回当前实例以支持链式调用
+     */
+    setGoalRadius(goalRadius: number): GoHomeBehavior;
+    /**
+     * 设置回家行为执行的间隔时间（游戏刻）。
+     * @param {number} interval 间隔时间（游戏刻）
+     * @returns {GoHomeBehavior} 返回当前实例以支持链式调用
+     */
+    setInterval(interval: number): GoHomeBehavior;
+    /**
+     * 将组件转换为 JSON 对象。
+     * @returns {Object} minecraft:behavior.go_home 组件的 JSON 对象
+     */
+    toObject(): Object;
+}
+
 declare class BasicBundle {
     /**
      * 添加组件到捆绑包
@@ -1807,6 +2186,53 @@ declare class EntityComponent {
         uncertaintyBase: number;
         uncertaintyMultiplier: number;
     }): Map<any, any>;
+    /**
+     * 设置实体的家（工作站点）组件，用于限制实体的活动范围。
+     * @param {Object} [options] - 配置选项
+     * @param {number} [options.restriction_radius=16] - 限制半径（方块格）
+     * @param {string[]} [options.home_block_list=["minecraft:chest"]] - 可绑定为家的方块列表
+     * @param {string} [options.restriction_type] - 限制类型（可选，如 "limited"），需 format_version >= 1.21.40
+     * @returns {Map} 返回 Minecraft home 组件
+     *
+     * @example // 基础用法 - 16格半径，箱子作为家
+     * const home = EntityComponent.setHome();
+     *
+     * @example // 自定义配置
+     * const customHome = EntityComponent.setHome({
+     *   restriction_radius: 32,
+     *   home_block_list: ["minecraft:chest", "minecraft:barrel"],
+     *   restriction_type: "limited"
+     * });
+     */
+    static setHome({ restriction_radius, home_block_list, restriction_type }?: {
+        restriction_radius?: number | undefined;
+        home_block_list?: string[] | undefined;
+        restriction_type?: string | undefined;
+    }): Map<any, any>;
+    /**
+     * 设置可分享物品列表（该实体感兴趣并会主动拾取的物品）
+     * 与 minecraft:behavior.pickup_items 配合使用
+     * @param {Object} [options] - 配置选项
+     * @param {Array<Object>} [options.items=[]] - 物品条目列表
+     * @param {string} options.items[].item - 物品ID
+     * @param {number} [options.items[].want_amount] - 想要保留的数量
+     * @param {number} [options.items[].surplus_amount] - 溢出阈值（超出此数量可分享给玩家）
+     * @param {number} [options.items[].priority] - 优先级（数值越小优先级越高）
+     * @param {number} [options.items[].max_amount] - 最大持有数
+     * @param {number} [options.items[].pickup_limit] - 单次拾取数限制
+     * @param {boolean} [options.items[].pickup_only] - 是否只拾取不分享
+     * @param {boolean} [options.items[].stored_in_inventory] - 是否存入库存
+     * @param {boolean} [options.items[].consume_item] - 是否消耗物品
+     * @param {Object} [options.items[].admire] - 欣赏物品行为
+     * @param {Object} [options.items[].barter] - 以物易物配置
+     * @param {Object} [options.items[].craft_into] - 合成转换配置
+     * @param {boolean} [options.all_items=false] - 是否接受任意物品
+     * @param {boolean} [options.singular_pickup=false] - 是否一次只拾取一个
+     * @returns {Map} 返回 Minecraft shareables 组件
+     */
+    static setShareables({ items, all_items, singular_pickup }?: {
+        items?: Object[] | undefined;
+    }): Map<any, any>;
 }
 
 type BehaviorLiterals = 'beh' | 'behavior' | 'behaviour';
@@ -1866,13 +2292,18 @@ declare namespace BlockAPI {
     }): RotatableBlock;
     function createGeometryBlock(identifier: any, category: any, geometry: any, material_instances: any, options?: {}): GeometryBlock;
     function createOreBlock(identifier: any, category: any, textures_arr: any, options?: {}): OreBlock;
-    function createCropBlock(identifier: string, category: string, variantDatas: any[], options?: {
+    function createHeadBlock(identifier: string, category: string, texture: any, options?: {
         group: string;
         hide_in_command: boolean;
         ambient_occlusion: boolean;
         face_dimming: boolean;
         render_method: string;
     }): CropBlock;
+    function createGlassBlock(identifier: any, category: any, texture: any, options?: {}): GlassBlock;
+    function createFenceBlock(identifier: any, category: any, textures_arr: any, options?: {}): FenceBlock;
+    function createStairBlock(identifier: any, category: any, textures_arr: any, options?: {}): StairBlock;
+    function createTrapdoorBlock(identifier: any, category: any, texture: any, options?: {}): TrapdoorBlock;
+    function createCropBlock(identifier: any, category: any, variantDatas: any, options?: {}): CropBlock;
 }
 
 declare function registerEntity(behData: any, resData: any): void;
@@ -1900,6 +2331,10 @@ declare namespace FeatureAPI {
     function createFeatureRules(identifier: any, places_feature: any): FeatureRule;
 }
 
+/**
+ * 物品菜单栏分类枚举
+ * 用于 Item / Food / FlipbookItem 及 ItemAPI 的 category 参数
+ */
 declare enum ItemCategory {
     Commands = "commands",
     Construction = "construction",
@@ -1908,179 +2343,621 @@ declare enum ItemCategory {
     Items = "items",
     None = "none"
 }
-
-declare class Item {
+/**
+ * 物品组件 Map：以 Minecraft 组件名为 key
+ */
+type ItemComponentMap = Map<string, unknown>;
+/**
+ * 物品选项
+ * snake_case（对应 Minecraft JSON 字段）与 camelCase 互为别名，camelCase 优先
+ */
+interface ItemOptions {
+    group?: string;
+    hide_in_command?: boolean;
+    hideInCommand?: boolean;
+    max_stack_size?: number;
+    maxStackSize?: number;
+    format_version?: string;
+    formatVersion?: string;
     /**
-     * 物品类
-     * @param {string} identifier 物品唯一标识符
-     * @param {string} category 菜单栏分类 可选："construction", "nature", "equipment", "items", and "none"
-     * @param {string} texture 物品纹理
-     * @param {Object?} options 可选参数
-     * @param {string|undefined} options.group 分组
-     * @param {boolean|undefined} options.hide_in_command 是否在命令中隐藏，默认为 false
+     * 图标纹理名称；传 null 表示不添加 minecraft:icon 组件
      */
-    constructor(identifier: string, category: string, texture: string, options?: Object | null);
-    identifier: string;
-    category: string;
-    texture: string;
-    group: any;
-    hide_in_command: any;
-    format_version: any;
-    components: Map<any, any>;
+    icon?: string | null;
+    displayName?: string;
+}
+/**
+ * 3D 手持物品骨骼变换（动画中的 position/rotation/scale）
+ */
+interface ModelBoneTransform {
+    position?: [number, number, number];
+    rotation?: [number, number, number];
+    scale?: number | [number, number, number];
+}
+/**
+ * 3D 手持物品选项（Method 2：model binding）
+ */
+interface CreateModelItemOptions extends ItemOptions {
     /**
-     * 添加组件
-     * @param {Map} componentMap 组件 Map
+     * 几何根骨骼名，内置动画将作用于该骨骼；必须与用户 geometry 中带
+     * binding（q.item_slot_to_bone_name）的骨骼名一致。默认 "rightitem"。
      */
-    addComponent(componentMap: Map<any, any>): this;
+    boneName?: string;
     /**
-     * 移除组件
-     * @param {string} key 组件名称
+     * 默认材质。默认 "entity"（不透明，同官方示例）；
+     * 模型含透明像素时可用 "entity_alphatest"。
      */
-    removeComponent(key: string): this;
+    material?: string;
     /**
-     * 将物品转换为 JSON 格式
-     * @returns {Object} JSON 格式的物品对象
+     * 覆盖内置第一人称握持姿态（默认参照官方示例）
      */
-    toObject(): Object;
-}
-
-declare class Food extends Item {
+    holdFirstPerson?: ModelBoneTransform;
     /**
-     * 物品类
-     * @param {string} identifier 物品唯一标识符
-     * @param {string} category 菜单栏分类 可选："construction", "nature", "equipment", "items", and "none"
-     * @param {string} texture 物品纹理
-     * @param {Object} options 可选参数
-     * @param {string} options.group 分组
-     * @param {boolean} options.hide_in_command 是否在命令中隐藏，默认为 false
-     * @param {string} options.animation 使用动画，默认为 "eat"
-     * @param {boolean} options.canAlwaysEat 是否总是可以食用，默认为 false
-     * @param {number} options.nutrition 营养价值，默认为 0
-     * @param {number} options.saturationModifier 饱和度修正值，默认为 1
+     * 覆盖内置第三人称握持姿态（默认参照官方示例）
      */
-    constructor(identifier: string, category: string, texture: string, options?: {
-        group: string;
-        hide_in_command: boolean;
-        animation: string;
-        canAlwaysEat: boolean;
-        nutrition: number;
-        saturationModifier: number;
-    });
-}
-
-declare class Attachable extends AddonAttachableDescription {
-    constructor(identifier: any);
-    getId(): string;
-    toObject(): any;
-}
-
-declare class Armor {
-    constructor(identifier: any, category: any, item_texture: any, texture_path: any, options?: {});
-    identifier: any;
-    item: Item;
-    attachable: Attachable;
-    setArrachableGeometry(key: any, geometry: any): this;
+    holdThirdPerson?: ModelBoneTransform;
 }
-declare class Chestplate extends Armor {
-    constructor(identifier: any, item_texture: any, texture_path: any, options?: {});
-}
-declare class Boot extends Armor {
-    constructor(identifier: any, item_texture: any, texture_path: any, options?: {});
-}
-declare class Leggings extends Armor {
-    constructor(identifier: any, item_texture: any, texture_path: any, options?: {});
-}
-declare class Helmet extends Armor {
-    constructor(identifier: any, item_texture: any, texture_path: any, options?: {});
-}
-
 /**
- * 翻书物品配置选项接口
+ * 食物选项
  */
-interface FlipbookItemOptions {
-    /**
-     * 物品分组 - 用于在创造模式物品栏中分组显示
-     * @example "construction" - 建筑类
-     * @example "equipment" - 装备类
-     * @example "nature" - 自然类
-     */
-    group?: string;
-    /**
-     * 是否在命令自动补全中隐藏该物品
-     * @default false - 默认在命令中显示
-     */
-    hide_in_command?: boolean;
+interface FoodOptions extends ItemOptions {
+    animation?: string;
+    movement?: number;
+    useDuration?: number;
+    canAlwaysEat?: boolean;
+    nutrition?: number;
+    saturationModifier?: number;
     /**
-     * 每个动画帧持续的游戏刻数（tick）
-     * 1秒 = 20游戏刻，因此8刻 = 0.4秒
-     * @default 8 - 默认每帧显示0.4秒
-     * @minimum 1 - 最小值1刻
+     * 是否为肉类（自动追加 minecraft:is_meat 标签）
      */
-    ticks_per_frame?: number;
+    isMeat?: boolean;
     /**
-     * 物品的最大堆叠数量
-     * @default 64 - 默认堆叠64个
-     * @minimum 1 - 最小值1
-     * @maximum 99 - 最大堆叠限制
+     * 是否为鱼类（自动追加 minecraft:is_fish 标签）
      */
-    max_stack_size?: number;
+    isFish?: boolean;
     /**
-     * 资源包的格式版本号
-     * @example "1.20.0" - 1.20版本
-     * @example "1.19.0" - 1.19版本
-     * @default "1.20.0" - 默认使用最新版本
+     * 是否为熟食（自动追加 minecraft:is_cooked 标签）
      */
-    format_version?: string;
+    isCooked?: boolean;
 }
 /**
- * 翻书物品类
- * 继承自Item类，用于创建具有动态翻书动画效果的物品
- * 该类会自动创建对应的几何方块并注册翻书材质动画
+ * 可投掷组件选项
  */
-declare class FlipbookItem extends Item {
-    /**
-     * 关联的外观方块实例
-     * 用于在游戏中显示该翻书物品的3D模型
-     */
-    block: GeometryBlock;
-    /**
-     * 创建并注册翻书物品
-     *
-     * @param identifier - 物品的唯一标识符（如："my_mod:flipbook_item"）
-     * @param category - 物品所属的分类（如："construction", "equipment"等）
-     * @param texture - 纹理名称（不包含路径和后缀，如："my_flipbook_texture"）
-     * @param options - 可选的配置参数对象
-     * @param options.group - 物品分组，用于在创造模式物品栏中分组显示
-     * @param options.hide_in_command - 是否在命令自动补全中隐藏该物品
-     * @param options.ticks_per_frame - 每个动画帧持续的游戏刻数（tick），默认8刻
-     * @param options.max_stack_size - 物品的最大堆叠数量
-     * @param options.format_version - 格式版本号
-     */
-    constructor(identifier: string, category: string, texture: string, options?: FlipbookItemOptions);
+interface ThrowableOptions {
+    doSwingAnimation?: boolean;
+    launchPowerScale?: number;
+    maxDrawDuration?: number;
+    maxLaunchPower?: number;
+    minDrawDuration?: number;
+    scalePowerByDrawDuration?: boolean;
 }
-
-declare namespace ItemAPI {
-    function createItem(identifier: string, category: string, texture: string, options?: {
-        group: string;
-        hight_resolution: boolean;
-        hide_in_command: boolean;
-    }): Item;
-    function createFood(identifier: string, category: string, texture: string, options?: {
-        group: string;
-        hide_in_command: boolean;
-        animation: string;
-        canAlwaysEat: boolean;
-        nutrition: number;
-        saturationModifier: number;
-    }): Food;
-    function createAttachable(identifier: string, texture: string, material: string, options?: Object): Attachable;
-    function createChestplateArmor(identifier: any, item_texture: any, texture_path: any, options?: {}): Chestplate;
-    function createHelmetArmor(identifier: any, item_texture: any, texture_path: any, options?: {}): Helmet;
-    function createBootArmor(identifier: any, item_texture: any, texture_path: any, options?: {}): Boot;
-    function createLeggingsArmor(identifier: any, item_texture: any, texture_path: any, options?: {}): Leggings;
-    function createFlipbookItem(identifier: string, category: string, texture: string, options?: Object | null): FlipbookItem;
+/**
+ * 食物组件选项
+ */
+interface FoodComponentOptions {
+    nutrition?: number;
+    saturationModifier?: number;
+    canAlwaysEat?: boolean;
+    usingConvertsTo?: string;
 }
-
+/**
+ * 方块描述符：字符串、带状态的名称对象或标签 Molang 查询对象
+ */
+type BlockDescriptor = string | {
+    name: string;
+    states?: Record<string, unknown>;
+} | {
+    tags: string;
+};
+/**
+ * 数值范围
+ */
+interface Range {
+    min: number;
+    max: number;
+}
+/**
+ * 物品稀有度
+ */
+type ItemRarity = 'common' | 'uncommon' | 'rare' | 'epic';
+/**
+ * 放置方块组件选项
+ */
+interface BlockPlacerOptions {
+    replaceBlockItem?: boolean;
+    alignedPlacement?: boolean;
+    useOn?: BlockDescriptor[];
+}
+/**
+ * 使用修饰组件选项
+ */
+interface UseModifiersOptions {
+    movementModifier?: number;
+    useDuration?: number;
+    emitVibrations?: boolean;
+    startSound?: string;
+    startUsing?: 'always' | 'if_first';
+}
+/**
+ * 图标纹理（对象格式）
+ */
+interface IconTextures {
+    default: string;
+    dyed?: string;
+    iconTrim?: string;
+    bundleOpenBack?: string;
+    bundleOpenFront?: string;
+}
+/**
+ * 冷却组件选项
+ */
+interface CooldownOptions {
+    category: string;
+    duration: number;
+    type?: 'use' | 'attack';
+}
+/**
+ * 挖掘组件选项
+ */
+interface DiggerOptions {
+    destroySpeeds: {
+        block: BlockDescriptor;
+        speed: number;
+    }[];
+    useEfficiency?: boolean;
+}
+/**
+ * 耐久传感器阈值
+ */
+interface DurabilityThreshold {
+    durability: number;
+    particleType?: string;
+    soundEvent?: string;
+}
+/**
+ * 耐久传感器组件选项
+ */
+interface DurabilitySensorOptions {
+    durabilityThresholds: DurabilityThreshold[];
+}
+/**
+ * 放置实体组件选项
+ */
+interface EntityPlacerOptions {
+    dispenseOn?: BlockDescriptor[];
+    useOn?: BlockDescriptor[];
+}
+/**
+ * 动能武器组件选项
+ */
+interface KineticWeaponOptions {
+    delay: number;
+    hitboxMargin?: number;
+    reach?: Range;
+    creativeReach?: Range;
+    damageMultiplier?: number;
+    damageModifier?: number;
+    damageConditions?: Record<string, unknown>;
+    dismountConditions?: Record<string, unknown>;
+    knockbackConditions?: Record<string, unknown>;
+}
+/**
+ * 穿刺武器组件选项
+ */
+interface PiercingWeaponOptions {
+    hitboxMargin?: number;
+    reach?: Range;
+    creativeReach?: Range;
+}
+/**
+ * 唱片组件选项
+ */
+interface RecordOptions {
+    comparatorSignal: number;
+    duration: number;
+    soundEvent: string;
+}
+/**
+ * 修复条目
+ */
+interface RepairItem {
+    items: (string | {
+        tags: string;
+    })[];
+    repairAmount?: number | string;
+}
+/**
+ * 射击组件弹药
+ */
+interface ShooterAmmunition {
+    item: string;
+    searchInventory?: boolean;
+    useInCreative?: boolean;
+    useOffhand?: boolean;
+}
+/**
+ * 射击组件选项
+ */
+interface ShooterOptions {
+    ammunition: ShooterAmmunition[];
+    chargeOnDraw?: boolean;
+    maxDrawDuration?: number;
+    scalePowerByDrawDuration?: boolean;
+}
+/**
+ * 容器物品组件选项
+ */
+interface StorageItemOptions {
+    maxSlots: number;
+    allowNestedStorageItems: boolean;
+    allowedItems?: string[];
+    bannedItems?: string[];
+}
+/**
+ * 挥砍音效组件选项
+ */
+interface SwingSoundsOptions {
+    attackMiss?: string;
+    attackHit?: string;
+    attackCriticalHit?: string;
+}
+
+declare class Attachable extends AddonAttachableDescription {
+    #private;
+    constructor(identifier: string, formatVersion?: string);
+    getId(): string;
+    toObject(): Record<string, any>;
+}
+
+declare class Item {
+    identifier: string;
+    category: string;
+    texture: string;
+    group?: string;
+    hide_in_command: boolean;
+    format_version: string;
+    components: ItemComponentMap;
+    attachable?: Attachable;
+    /**
+     * 物品类
+     * @param identifier 物品唯一标识符
+     * @param category 菜单栏分类，见 {@link ItemCategory}
+     * @param texture 物品纹理
+     * @param options 可选参数
+     */
+    constructor(identifier: string, category: ItemCategory, texture: string, options?: ItemOptions);
+    /**
+     * 添加组件
+     * @param componentMap 组件 Map
+     */
+    addComponent(componentMap: ItemComponentMap): this;
+    /**
+     * 移除组件
+     * @param key 组件名称
+     */
+    removeComponent(key: string): this;
+    getAttachable(): Attachable | undefined;
+    /**
+     * 将物品转换为 JSON 格式
+     * @returns JSON 格式的物品对象
+     */
+    toObject(): Record<string, any>;
+}
+
+/**
+ * 盔甲类型枚举
+ */
+declare enum ArmorType {
+    Chestplate = "chestplate",
+    Helmet = "helmet",
+    Boots = "boots",
+    Leggings = "leggings"
+}
+/**
+ * 盔甲类型规格
+ * 参考 Bedrock Wiki "Custom Armor"：https://wiki.bedrock.dev/items/custom-armor
+ */
+interface ArmorSpec {
+    group: string;
+    geometry: string;
+    script: string;
+    protection: number;
+    slot: string;
+    enchantSlot: string;
+    maxDurability: number;
+    displayName: string;
+}
+/**
+ * 盔甲选项
+ * 参考 Bedrock Wiki "Custom Armor"：https://wiki.bedrock.dev/items/custom-armor
+ */
+interface ArmorOptions extends ItemOptions {
+    displayName?: string;
+    /**
+     * 附魔槽位与等级（参考 wiki 规范，默认 { slot: 按部位, value: 10 }）
+     */
+    enchantable?: {
+        slot: string;
+        value?: number;
+    };
+    /**
+     * 最大耐久（参考 wiki 规范，默认按部位：头盔 363 / 胸甲 528 / 护腿 495 / 靴子 429）
+     */
+    maxDurability?: number;
+    /**
+     * 修复条目（参考 wiki 规范，默认木棍，每次恢复 25% 最大耐久）
+     */
+    repairItems?: RepairItem[];
+    /**
+     * 附加标签（参考 wiki 规范，默认 ["minecraft:is_armor", "minecraft:trimmable_armors"]）
+     */
+    tags?: string[];
+    /**
+     * 渲染控制器，默认 "controller.render.armor"（兼容旧版），可传 "controller.render.armor.v2"
+     */
+    renderController?: string;
+}
+/**
+ * 盔甲类
+ * 由 ArmorType 数据表驱动，同时生成物品（Item）与可附着物（Attachable）
+ */
+declare class Armor {
+    type: ArmorType;
+    identifier: string;
+    item: Item;
+    attachable: Attachable;
+    constructor(identifier: string, item_texture: string, texture_path: string, type?: ArmorType, options?: ArmorOptions);
+    /**
+     * 设置可附着物的几何模型
+     * @param key 几何模型名称
+     * @param geometry 几何模型标识符
+     * @returns 当前实例，支持链式调用
+     */
+    setAttachableGeometry(key: string, geometry: string): this;
+    /**
+     * 获取行为包与资源包的 JSON 表示
+     * @returns { behavior, resource } 两个包的注册内容
+     */
+    toObject(): {
+        behavior: Record<string, any>;
+        resource: Record<string, any>;
+    };
+}
+
+declare class Food extends Item {
+    /**
+     * 食物类
+     * @param identifier 物品唯一标识符
+     * @param category 菜单栏分类，见 {@link ItemCategory}
+     * @param texture 物品纹理
+     * @param options 可选参数
+     */
+    constructor(identifier: string, category: ItemCategory, texture: string, options?: FoodOptions);
+}
+
+/**
+ * 翻书物品配置选项接口
+ */
+interface FlipbookItemOptions {
+    /**
+     * 物品分组 - 用于在创造模式物品栏中分组显示
+     * @example "construction" - 建筑类
+     * @example "equipment" - 装备类
+     * @example "nature" - 自然类
+     */
+    group?: string;
+    /**
+     * 是否在命令自动补全中隐藏该物品
+     * @default false - 默认在命令中显示
+     */
+    hide_in_command?: boolean;
+    /**
+     * 每个动画帧持续的游戏刻数（tick）
+     * 1秒 = 20游戏刻，因此8刻 = 0.4秒
+     * @default 8 - 默认每帧显示0.4秒
+     * @minimum 1 - 最小值1刻
+     */
+    ticks_per_frame?: number;
+    /**
+     * 物品的最大堆叠数量
+     * @default 64 - 默认堆叠64个
+     * @minimum 1 - 最小值1
+     * @maximum 99 - 最大堆叠限制
+     */
+    max_stack_size?: number;
+    /**
+     * 资源包的格式版本号
+     * @example "1.20.0" - 1.20版本
+     * @example "1.19.0" - 1.19版本
+     * @default "1.20.0" - 默认使用最新版本
+     */
+    format_version?: string;
+    /**
+     * 翻书纹理文件的完整路径（不含 .png 后缀）。
+     * @default `"textures/blocks/${texture}"` - 默认使用方块纹理目录
+     */
+    texture_path?: string;
+}
+/**
+ * 翻书物品类
+ * 继承自Item类，用于创建具有动态翻书动画效果的物品
+ * 该类会自动创建对应的几何方块并注册翻书材质动画
+ */
+declare class FlipbookItem extends Item {
+    /**
+     * 关联的外观方块实例
+     * 用于在游戏中显示该翻书物品的3D模型
+     */
+    block: GeometryBlock;
+    /**
+     * 创建并注册翻书物品
+     *
+     * @param identifier - 物品的唯一标识符（如："my_mod:flipbook_item"）
+     * @param category - 物品所属的分类（如："construction", "equipment"等）
+     * @param texture - 纹理名称（不包含路径和后缀，如："my_flipbook_texture"）
+     * @param options - 可选的配置参数对象
+     * @param options.group - 物品分组，用于在创造模式物品栏中分组显示
+     * @param options.hide_in_command - 是否在命令自动补全中隐藏该物品
+     * @param options.ticks_per_frame - 每个动画帧持续的游戏刻数（tick），默认8刻
+     * @param options.max_stack_size - 物品的最大堆叠数量
+     * @param options.format_version - 格式版本号
+     */
+    constructor(identifier: string, category: ItemCategory, texture: string, options?: FlipbookItemOptions);
+}
+
+/**
+ * 物品目录分类
+ * 参考 Bedrock Wiki Item Catalog：仅支持 construction / equipment / items / nature 四类
+ */
+type ItemCatalogCategory = 'construction' | 'equipment' | 'items' | 'nature';
+/**
+ * 可展开分组配置
+ */
+interface ItemCatalogGroupOptions {
+    /**
+     * 分组图标使用的物品
+     */
+    icon?: string;
+    /**
+     * 分组的本地化键，如 "wiki:itemGroup.name.ore"；同时可用作物品/方块的 menu_category.group
+     */
+    name?: string;
+}
+/**
+ * 物品目录
+ * 生成 BP/item_catalog/crafting_item_catalog.json，
+ * 用于指定物品在创造菜单与配方手册中的分组位置。
+ */
+declare class ItemCatalog {
+    format_version: string;
+    private categories;
+    /**
+     * @param format_version 格式版本，默认 "1.26.30"
+     */
+    constructor(format_version?: string);
+    /**
+     * 添加一组物品到指定分类
+     * @param category 创造菜单分类（construction/equipment/items/nature）
+     * @param items 物品标识符列表
+     * @param options 可展开分组配置
+     * @returns 当前实例，支持链式调用
+     */
+    addGroup(category: ItemCatalogCategory, items: string[], options?: ItemCatalogGroupOptions): this;
+    /**
+     * 添加单个物品到指定分类
+     * @param category 创造菜单分类（construction/equipment/items/nature）
+     * @param item 物品标识符
+     * @param options 可展开分组配置
+     * @returns 当前实例，支持链式调用
+     */
+    addItem(category: ItemCatalogCategory, item: string, options?: ItemCatalogGroupOptions): this;
+    /**
+     * 注册到行为包的 item_catalog/ 目录
+     * @returns 当前实例
+     */
+    register(): this;
+    /**
+     * 将物品目录转换为 JSON 格式
+     * @returns JSON 格式的物品目录对象
+     */
+    toObject(): Record<string, any>;
+}
+
+declare const ItemAPI: {
+    /**
+     * 创建一个普通物品。
+     * @param identifier 物品的唯一标识符。
+     * @param category 物品在创造菜单中的分类，见 {@link ItemCategory}。
+     * @param texture 物品的纹理。
+     * @param options 额外选项。
+     * @returns 创建的物品。
+     */
+    createItem(identifier: string, category: ItemCategory, texture: string, options?: ItemOptions): Item;
+    /**
+     * 创建一个大型物品（Item + Attachable）。
+     * 用于在手持时显示为大型 3D 模型（如部分 3D 物品）。
+     * @param identifier 物品的唯一标识符。
+     * @param category 物品在创造菜单中的分类，见 {@link ItemCategory}。
+     * @param texture 物品的纹理。
+     * @param options 额外选项。
+     * @returns 创建的物品。
+     */
+    createLargeItem(identifier: string, category: ItemCategory, texture: string, options?: ItemOptions): Item;
+    /**
+     * 创建一个 3D 手持物品（Item + Attachable + 内置默认握持动画）。
+     * 采用 Bedrock Wiki "Attachables" 的 Method 2（model binding）：attachable 使用
+     * scripts.animate 按 context.is_first_person 切换首/第三人称动画，并搭配
+     * controller.render.item_default 渲染控制器。内置动画姿态参照官方示例
+     * （首/第三人称各用固定值），骨骼名须与用户 geometry 中的根骨骼一致。
+     * 用户需自行将几何模型放入 RP（geometry 根骨骼应使用
+     * "q.item_slot_to_bone_name(c.item_slot)" 绑定槽位）。
+     * @param identifier 物品的唯一标识符（如 "my_mod:model_sword"）。
+     * @param category 物品在创造菜单中的分类，见 {@link ItemCategory}。
+     * @param icon 物品图标（创造菜单/物品栏显示的短名，需登记在 item_texture.json）。
+     *             与 texture 相互独立，可分别指定。
+     * @param texture attachable 的 3D 贴图路径。传完整路径（如 "textures/entity/skeleton/skeleton"）
+     *                将直接用作贴图；传短名（如 "amethyst_shard"）则自动拼接 "textures/items/" 前缀。
+     * @param geometry 用户几何标识符（如 "geometry.my_model"）。
+     * @param options 额外选项，见 {@link CreateModelItemOptions}。
+     * @returns 创建的物品。
+     */
+    createModelItem(identifier: string, category: ItemCategory, icon: string, texture: string, geometry: string, options?: CreateModelItemOptions): Item;
+    /**
+     * 创建一个食物物品。
+     * @param identifier 食物的唯一标识符。
+     * @param category 食物在创造菜单中的分类，见 {@link ItemCategory}。
+     * @param texture 食物的纹理。
+     * @param options 额外选项。
+     * @returns 创建的食物物品。
+     */
+    createFood(identifier: string, category: ItemCategory, texture: string, options?: FoodOptions): Food;
+    /**
+     * 创建一个可附着物品。
+     * @param identifier 可附着物品的唯一标识符。
+     * @param texture 可附着物品的纹理。
+     * @param material 可附着物品的材质。
+     * @param options 额外选项。
+     * @returns 创建的可附着物品。
+     */
+    createAttachable(identifier: string, texture: string, material: string, options?: ItemOptions): Attachable;
+    /**
+     * 创建一个胸甲（Item + Attachable）。
+     * @param identifier 物品的唯一标识符。
+     * @param item_texture 物品图标纹理名称。
+     * @param texture_path 盔甲模型纹理路径。
+     * @param options 额外选项。
+     * @returns 创建的盔甲实例。
+     */
+    createChestplateArmor(identifier: string, item_texture: string, texture_path: string, options?: ItemOptions): Armor;
+    /**
+     * 创建一个头盔（Item + Attachable）。
+     */
+    createHelmetArmor(identifier: string, item_texture: string, texture_path: string, options?: ItemOptions): Armor;
+    /**
+     * 创建一个靴子（Item + Attachable）。
+     */
+    createBootArmor(identifier: string, item_texture: string, texture_path: string, options?: ItemOptions): Armor;
+    /**
+     * 创建一个护腿（Item + Attachable）。
+     */
+    createLeggingsArmor(identifier: string, item_texture: string, texture_path: string, options?: ItemOptions): Armor;
+    /**
+     * 创建并注册翻书物品。
+     * @param identifier 物品的唯一标识符（如："my_mod:flipbook_item"）。
+     * @param category 物品所属的分类，见 {@link ItemCategory}。
+     * @param texture 纹理名称（不包含路径和后缀，如："my_flipbook_texture"）。
+     * @param options 可选的配置参数对象。
+     * @returns 创建的翻书物品。
+     */
+    createFlipbookItem(identifier: string, category: ItemCategory, texture: string, options?: FlipbookItemOptions): FlipbookItem;
+    /**
+     * 创建物品目录（生成 BP/item_catalog/crafting_item_catalog.json）。
+     * 用于指定物品在创造菜单与配方手册中的分组位置。
+     * @param formatVersion 格式版本，默认 "1.26.30"
+     * @returns 物品目录实例
+     */
+    createItemCatalog(formatVersion?: string): ItemCatalog;
+};
+
 declare const RecipeAPI: RecipeRegistry;
 declare class RecipeRegistry {
     /**
@@ -2096,21 +2973,148 @@ declare class RecipeRegistry {
     registerShapeless(identifier: any): AddonRecipeShapeless_1_17;
 }
 
+type Any$1 = any;
 declare class UISystem {
-    constructor(identifier: any, path: any);
-    identifier: any;
-    namespace: any;
-    name: any;
-    path: any;
-    elements: Map<any, any>;
-    animations: Map<any, any>;
-    addElement(element: any): this;
-    getElement(element_name: any): any;
-    addAnimation(name: any, value: any): void;
-    getAnimation(animation_name: any): any;
-    toObject(): {
-        namespace: any;
-    };
+    identifier: string;
+    namespace: string;
+    name: string;
+    path: string;
+    elements: Map<string, Any$1>;
+    animations: Map<string, Any$1>;
+    constructor(identifier: string, path: string);
+    addElement(element: Any$1): this;
+    getElement(element_name: string): Any$1;
+    addAnimation(name: string, value: Any$1): void;
+    getAnimation(animation_name: string): Any$1;
+    toObject(): Record<string, Any$1>;
+}
+
+/** 共享 UI 类型定义（JSON UI 规范的受控映射） */
+/** 尺寸向量（像素数字或百分比/计算字符串），如 [320, 207] / ["50%", "100%"] */
+type Size2 = [number | string, number | string];
+/** 偏移向量 [x, y]（像素） */
+type Offset2 = [number, number];
+/** 锚点（anchor_from / anchor_to）可选值 */
+type Anchor = 'top_left' | 'top_middle' | 'top_right' | 'left_middle' | 'center' | 'right_middle' | 'bottom_left' | 'bottom_middle' | 'bottom_right';
+/** 数据绑定类型 */
+type BindingType = 'global' | 'view' | 'collection' | 'collection_details' | 'none';
+/** 数据绑定条件 */
+type BindingCondition = 'always' | 'always_when_visible' | 'visible' | 'once' | 'none' | 'visibility_changed';
+/** 调制操作类型（Modifications.OPERATION 的字面量） */
+type ModificationOperation = 'insert_back' | 'insert_front' | 'insert_after' | 'insert_before' | 'move_back' | 'move_front' | 'move_after' | 'move_before' | 'swap' | 'replace' | 'remove';
+/** 支持任意键的 JSON UI 属性包（类内部索引签名基类型） */
+type JsonUIBag = {
+    [key: string]: any;
+};
+
+/**
+ * DataBindingObject 类
+ *
+ * 该类表示数据绑定配置，用于将硬编码值或变量绑定到元素属性。
+ *
+ * 属性：
+ * - ignored: boolean - 是否忽略绑定（默认值：false）
+ * - binding_type: enum - 绑定类型（可能值：global, view, collection, collection_details, none）
+ * - binding_name: string - 数据绑定名称或条件的值
+ * - binding_name_override: string - 应用 binding_name 值的 UI 元素属性名称
+ * - binding_collection_name: string - 要使用的集合名称
+ * - binding_collection_prefix: string - 集合前缀
+ * - binding_condition: enum - 数据绑定的条件（可能值：always, always_when_visible, visible, once, none, visibility_changed）
+ * - source_control_name: string - 要观察其属性值的 UI 元素名称
+ * - source_property_name: string - 存储 source_control_name 引用的 UI 元素的属性值
+ * - target_property_name: string - 应用 source_property_name 值的 UI 元素属性
+ * - resolve_sibling_scope: boolean - 是否允许选择同级元素而非子元素（默认值：false）
+ */
+
+type BindingTypeOrString = BindingType | string;
+type BindingConditionOrString = BindingCondition | string;
+declare class DataBindingObject {
+    [key: string]: unknown;
+    ignored: boolean;
+    binding_type: BindingTypeOrString;
+    binding_name: string;
+    binding_name_override: string;
+    binding_collection_name: string;
+    binding_collection_prefix: string;
+    binding_condition: BindingConditionOrString;
+    source_control_name: string;
+    source_property_name: string;
+    target_property_name: string;
+    resolve_sibling_scope: boolean;
+    /**
+     * 设置是否忽略绑定。
+     * @param {boolean} ignored - 是否忽略绑定（默认值：false）
+     * @returns {DataBindingObject} 返回当前实例以支持链式调用
+     */
+    setIgnored(ignored?: boolean): this;
+    /**
+     * 设置绑定类型。
+     * @param {BindingTypeOrString} type - 绑定类型（可能值：global, view, collection, collection_details, none）
+     * @returns {DataBindingObject} 返回当前实例以支持链式调用
+     */
+    setBindingType(type: BindingTypeOrString): this;
+    /**
+     * 设置数据绑定名称或条件的值。
+     * @param {string} name - 数据绑定名称或条件的值
+     * @returns {DataBindingObject} 返回当前实例以支持链式调用
+     */
+    setBindingName(name: string): this;
+    /**
+     * 设置应用 binding_name 值的 UI 元素属性名称。
+     * @param {string} nameOverride - 应用 binding_name 值的 UI 元素属性名称
+     * @returns {DataBindingObject} 返回当前实例以支持链式调用
+     */
+    setBindingNameOverride(nameOverride: string): this;
+    /**
+     * 设置要使用的集合名称。
+     * @param {string} collectionName - 集合名称
+     * @returns {DataBindingObject} 返回当前实例以支持链式调用
+     */
+    setBindingCollectionName(collectionName: string): this;
+    /**
+     * 设置集合前缀。
+     * @param {string} prefix - 集合前缀
+     * @returns {DataBindingObject} 返回当前实例以支持链式调用
+     */
+    setBindingCollectionPrefix(prefix: string): this;
+    /**
+     * 设置数据绑定的条件。
+     * @param {BindingConditionOrString} condition - 数据绑定的条件（可能值：always, always_when_visible, visible, once, none, visibility_changed）
+     * @returns {DataBindingObject} 返回当前实例以支持链式调用
+     */
+    setBindingCondition(condition: BindingConditionOrString): this;
+    /**
+     * 设置要观察其属性值的 UI 元素名称。
+     * @param {string} controlName - UI 元素名称
+     * @returns {DataBindingObject} 返回当前实例以支持链式调用
+     */
+    setSourceControlName(controlName: string): this;
+    /**
+     * 设置存储 source_control_name 引用的 UI 元素的属性值。
+     * @param {string} propertyName - 属性名称
+     * @returns {DataBindingObject} 返回当前实例以支持链式调用
+     */
+    setSourcePropertyName(propertyName: string): this;
+    /**
+     * 设置应用 source_property_name 值的 UI 元素属性。
+     * @param {string} propertyName - 属性名称
+     * @returns {DataBindingObject} 返回当前实例以支持链式调用
+     */
+    setTargetPropertyName(propertyName: string): this;
+    /**
+     * 设置是否允许选择同级元素而非子元素。
+     * @param {boolean} resolve - 是否允许选择同级元素（默认值：false）
+     * @returns {DataBindingObject} 返回当前实例以支持链式调用
+     */
+    setResolveSiblingScope(resolve?: boolean): this;
+}
+
+declare class DataBinding {
+    [key: string]: unknown;
+    bindings: DataBindingObject[];
+    binding: DataBindingObject;
+    setBinding(binding: DataBindingObject): this;
+    addDataBinding(dataBindingObject: DataBindingObject): this;
 }
 
 /**
@@ -2142,190 +3146,165 @@ declare class UISystem {
  * - grid_position: Vector [row, column] - Position that the control will take inside the grid. This also allows to modify specific grid items of a hardcoded grid
  * - collection_index: int - Index that the control takes in the collection
  */
-/**
- * Control 类
- *
- * 该类表示一个具有各种属性和方法的 UI 控件元素，用于操作其状态。
- *
- * 属性：
- * - visible: boolean - 控制 UI 元素是否可见（默认值：true）
- * - enabled: boolean - 如果为 true，且 UI 元素或其任何子元素处于锁定状态，则它们将被锁定（默认值：true）
- * - layer: int - 相对于父元素的 Z-Index/层级（类似于 CSS 中的 zindex）。较高的层级将渲染在上方（默认值：0）
- * - alpha: float - 元素的透明度。仅影响 UI 元素本身，其子元素不受影响。如果希望透明度同时应用于父元素和子元素，请使用 propagate_alpha（默认值：1.0）
- * - propagate_alpha: boolean - 透明度是否应同时应用于父元素及其所有子元素（默认值：false）
- * - clips_children: boolean - 是否在视觉上和交互上裁剪超出 UI 元素边界的内容（默认值：false）
- * - allow_clipping: boolean - 是否允许在 UI 元素中启用裁剪。否则，clips_children 将无效（默认值：true）
- * - clip_offset: Vector [x, y] - 裁剪起始点的偏移量（默认值：[0, 0]）
- * - clip_state_change_event: string - 裁剪状态更改时触发的事件
- * - enable_scissor_test: boolean - 是否启用裁剪测试（默认值：false）
- * - property_bag: object - 属性包，包含与数据相关的属性/变量，而不是 UI 元素的实际结构和外观
- * - selected: boolean - 文本框是否默认被选中
- * - use_child_anchors: boolean - 是否使用 UI 元素子元素的 anchor_from 和 anchor_to（默认值：false）
- * - controls: array - 用于向元素添加子元素
- * - anims: string[] - 动画名称数组
- * - disable_anim_fast_forward: boolean - 是否禁用动画快进
- * - animation_reset_name: string - 重置动画的名称
- * - ignored: boolean - 是否忽略该 UI 元素（默认值：false）
- * - variables: array 或 object - 一组条件，用于更改变量的值
- * - modifications: array - 允许修改资源包中的 UI 文件（最底层为原版资源包）
- * - grid_position: Vector [row, column] - 控件在网格中的位置。此属性还允许修改硬编码网格中的特定网格项
- * - collection_index: int - 控件在集合中的索引
- */
+
+/** 附加到 Control.controls 的子元素：可序列化元素对象或 JSON UI 控件对象 */
+type ChildControl = Record<string, unknown>;
 declare class Control {
+    [key: string]: unknown;
+    visible: boolean;
+    enabled: boolean;
+    layer: number;
+    alpha: number;
+    propagate_alpha: boolean;
+    clips_children: boolean;
+    allow_clipping: boolean;
+    clip_offset: Offset2;
+    clip_state_change_event: string;
+    enable_scissor_test: boolean;
+    property_bag: JsonUIBag;
+    selected: boolean;
+    use_child_anchors: boolean;
+    controls: ChildControl[];
+    anims: string[];
+    disable_anim_fast_forward: boolean;
+    animation_reset_name: string;
+    ignored: boolean;
+    variables: JsonUIBag;
+    modifications: unknown[];
+    grid_position: Offset2;
+    collection_index: number;
     /**
      * 设置控件的可见性。
      * @param {boolean} visible - 控件是否可见（默认值：true）
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setVisible(visible?: boolean): Control;
-    visible: boolean | undefined;
+    setVisible(visible?: boolean): this;
     /**
      * 设置控件的启用状态。
      * @param {boolean} enabled - 控件是否启用（默认值：true）
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setEnabled(enabled?: boolean): Control;
-    enabled: boolean | undefined;
+    setEnabled(enabled?: boolean): this;
     /**
      * 设置控件的层级（z-index）。
      * @param {number} layer - 要设置的层级（默认值：0）
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setLayer(layer?: number): Control;
-    layer: number | undefined;
+    setLayer(layer?: number): this;
     /**
      * 设置控件的透明度。
      * @param {number} alpha - 要设置的透明度值（默认值：1.0）
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setAlpha(alpha?: number): Control;
-    alpha: number | undefined;
+    setAlpha(alpha?: number): this;
     /**
      * 设置透明度是否应传播到子元素。
      * @param {boolean} propagate - 透明度是否应传播（默认值：false）
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setPropagateAlpha(propagate?: boolean): Control;
-    propagate_alpha: boolean | undefined;
+    setPropagateAlpha(propagate?: boolean): this;
     /**
      * 设置控件是否应裁剪其子元素。
      * @param {boolean} clips - 控件是否应裁剪其子元素（默认值：false）
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setClipsChildren(clips?: boolean): Control;
-    clips_children: boolean | undefined;
+    setClipsChildren(clips?: boolean): this;
     /**
      * 设置控件是否允许裁剪。
      * @param {boolean} allow - 是否允许裁剪（默认值：true）
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setAllowClipping(allow?: boolean): Control;
-    allow_clipping: boolean | undefined;
+    setAllowClipping(allow?: boolean): this;
     /**
      * 设置控件的裁剪偏移量。
-     * @param {number[]} offset - 裁剪偏移量，格式为 [x, y]（默认值：[0, 0]）
+     * @param {Offset2} offset - 裁剪偏移量，格式为 [x, y]（默认值：[0, 0]）
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setClipOffset(offset?: number[]): Control;
-    clip_offset: number[] | undefined;
+    setClipOffset(offset?: Offset2): this;
     /**
      * 设置裁剪状态更改事件。
      * @param {string} event - 裁剪状态更改时触发的事件名称
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setClipStateChangeEvent(event: string): Control;
-    clip_state_change_event: string | undefined;
+    setClipStateChangeEvent(event: string): this;
     /**
      * 设置是否启用裁剪测试。
      * @param {boolean} enable - 是否启用裁剪测试（默认值：false）
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setEnableScissorTest(enable?: boolean): Control;
-    enable_scissor_test: boolean | undefined;
+    setEnableScissorTest(enable?: boolean): this;
     /**
      * 设置控件的属性包。
-     * @param {object} bag - 要设置的属性包
+     * @param {JsonUIBag} bag - 要设置的属性包
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setPropertyBag(bag: object): Control;
-    property_bag: object | undefined;
+    setPropertyBag(bag: JsonUIBag): this;
     /**
      * 设置控件是否被选中。
      * @param {boolean} selected - 控件是否被选中（默认值：false）
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setSelected(selected?: boolean): Control;
-    selected: boolean | undefined;
+    setSelected(selected?: boolean): this;
     /**
      * 设置控件是否使用子元素的锚点。
      * @param {boolean} use - 是否使用子元素的锚点（默认值：false）
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setUseChildAnchors(use?: boolean): Control;
-    use_child_anchors: boolean | undefined;
+    setUseChildAnchors(use?: boolean): this;
     /**
      * 向控件添加子控件。
-     * @param {Control} control - 要添加的子控件
+     * @param {ChildControl} control - 要添加的子控件
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    addControl(control: Control): Control;
-    controls: any[] | undefined;
+    addControl(control: ChildControl): this;
     /**
      * 设置控件的动画。
      * @param {string[]} anims - 动画名称数组
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setAnimations(anims: string[]): Control;
-    anims: string[] | undefined;
+    setAnimations(anims: string[]): this;
     /**
      * 设置是否禁用动画快进。
      * @param {boolean} disable - 是否禁用动画快进（默认值：false）
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setDisableAnimFastForward(disable?: boolean): Control;
-    disable_anim_fast_forward: boolean | undefined;
+    setDisableAnimFastForward(disable?: boolean): this;
     /**
      * 设置动画重置名称。
      * @param {string} name - 要重置的动画名称
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setAnimationResetName(name: string): Control;
-    animation_reset_name: string | undefined;
+    setAnimationResetName(name: string): this;
     /**
      * 设置是否忽略该控件。
      * @param {boolean} ignored - 是否忽略该控件（默认值：false）
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setIgnored(ignored?: boolean): Control;
-    ignored: boolean | undefined;
+    setIgnored(ignored?: boolean): this;
     /**
      * 设置控件的变量。
-     * @param {object} variables - 要设置的变量
+     * @param {JsonUIBag} variables - 要设置的变量
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setVariables(variables: object): Control;
-    variables: object | undefined;
+    setVariables(variables: JsonUIBag): this;
     /**
      * 设置控件的修改项。
-     * @param {array} modifications - 要设置的修改项
+     * @param {unknown[]} modifications - 要设置的修改项
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setModifications(modifications: array): Control;
-    modifications: any;
+    setModifications(modifications: unknown[]): this;
     /**
      * 设置控件在网格中的位置。
-     * @param {number[]} position - 网格位置，格式为 [行, 列]
+     * @param {Offset2} position - 网格位置，格式为 [行, 列]
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setGridPosition(position: number[]): Control;
-    grid_position: number[] | undefined;
+    setGridPosition(position: Offset2): this;
     /**
      * 设置控件在集合中的索引。
      * @param {number} index - 要设置的索引
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setCollectionIndex(index: number): Control;
-    collection_index: number | undefined;
+    setCollectionIndex(index: number): this;
 }
 
 /**
@@ -2347,125 +3326,163 @@ declare class Control {
  * - draggable: enum - 是否使元素可拖动（可能值：vertical, horizontal, both）
  * - follows_cursor: boolean - 是否使元素跟随光标（默认值：false）
  */
+
+type AnchorOrString = Anchor | string;
+type SizeOrString = Size2 | string;
 declare class Layout {
+    [key: string]: unknown;
+    size: SizeOrString;
+    max_size: Size2;
+    min_size: Size2;
+    offset: Offset2;
+    anchor_from: AnchorOrString;
+    anchor_to: AnchorOrString;
+    inherit_max_sibling_width: boolean;
+    inherit_max_sibling_height: boolean;
+    use_anchored_offset: boolean;
+    contained: boolean;
+    draggable: 'vertical' | 'horizontal' | 'both';
+    follows_cursor: boolean;
     /**
      * 设置 UI 元素的大小。
-     * @param {any[]} size - 大小，格式为 [width, height]（默认值：["default", "default"]）
+     * @param {Size2} size - 大小，格式为 [width, height]（默认值：["default", "default"]）
      * @returns {Layout} 返回当前实例以支持链式调用
      */
-    setSize(size?: any[]): Layout;
-    size: any[] | undefined;
+    setSize(size?: SizeOrString): this;
     /**
      * 设置 UI 元素的最大大小。
-     * @param {string[]} maxSize - 最大大小，格式为 [width, height]（默认值：["default", "default"]）
+     * @param {Size2} maxSize - 最大大小，格式为 [width, height]（默认值：["default", "default"]）
      * @returns {Layout} 返回当前实例以支持链式调用
      */
-    setMaxSize(maxSize?: string[]): Layout;
-    max_size: string[] | undefined;
+    setMaxSize(maxSize?: Size2): this;
     /**
      * 设置 UI 元素的最小大小。
-     * @param {string[]} minSize - 最小大小，格式为 [width, height]（默认值：["default", "default"]）
+     * @param {Size2} minSize - 最小大小，格式为 [width, height]（默认值：["default", "default"]）
      * @returns {Layout} 返回当前实例以支持链式调用
      */
-    setMinSize(minSize?: string[]): Layout;
-    min_size: string[] | undefined;
+    setMinSize(minSize?: Size2): this;
     /**
      * 设置 UI 元素相对于父元素的位置。
-     * @param {number[]} offset - 偏移量，格式为 [x, y]（默认值：[0, 0]）
+     * @param {Offset2} offset - 偏移量，格式为 [x, y]（默认值：[0, 0]）
      * @returns {Layout} 返回当前实例以支持链式调用
      */
-    setOffset(offset?: number[]): Layout;
-    offset: number[] | undefined;
+    setOffset(offset?: Offset2): this;
     /**
      * 设置父元素中的锚点。
-     * @param {string} anchorFrom - 锚点（可能值：top_left, top_middle, top_right, left_middle, center, right_middle, bottom_left, bottom_middle, bottom_right）（默认值：center）
+     * @param {AnchorOrString} anchorFrom - 锚点（可能值：top_left, top_middle, top_right, left_middle, center, right_middle, bottom_left, bottom_middle, bottom_right）（默认值：center）
      * @returns {Layout} 返回当前实例以支持链式调用
      */
-    setAnchorFrom(anchorFrom?: string): Layout;
-    anchor_from: string | undefined;
+    setAnchorFrom(anchorFrom?: AnchorOrString): this;
     /**
      * 设置元素自身的锚点。
-     * @param {string} anchorTo - 锚点（可能值：top_left, top_middle, top_right, left_middle, center, right_middle, bottom_left, bottom_middle, bottom_right）（默认值：center）
+     * @param {AnchorOrString} anchorTo - 锚点（可能值：top_left, top_middle, top_right, left_middle, center, right_middle, bottom_left, bottom_middle, bottom_right）（默认值：center）
      * @returns {Layout} 返回当前实例以支持链式调用
      */
-    setAnchorTo(anchorTo?: string): Layout;
-    anchor_to: string | undefined;
+    setAnchorTo(anchorTo?: AnchorOrString): this;
     /**
      * 设置是否使用兄弟元素的最大宽度。
      * @param {boolean} inherit - 是否使用兄弟元素的最大宽度（默认值：false）
      * @returns {Layout} 返回当前实例以支持链式调用
      */
-    setInheritMaxSiblingWidth(inherit?: boolean): Layout;
-    inherit_max_sibling_width: boolean | undefined;
+    setInheritMaxSiblingWidth(inherit?: boolean): this;
     /**
      * 设置是否使用兄弟元素的最大高度。
      * @param {boolean} inherit - 是否使用兄弟元素的最大高度（默认值：false）
      * @returns {Layout} 返回当前实例以支持链式调用
      */
-    setInheritMaxSiblingHeight(inherit?: boolean): Layout;
-    inherit_max_sibling_height: boolean | undefined;
+    setInheritMaxSiblingHeight(inherit?: boolean): this;
     /**
      * 设置是否使用基于锚点的偏移。
      * @param {boolean} use - 是否使用基于锚点的偏移（默认值：false）
      * @returns {Layout} 返回当前实例以支持链式调用
      */
-    setUseAnchoredOffset(use?: boolean): Layout;
-    use_anchored_offset: boolean | undefined;
+    setUseAnchoredOffset(use?: boolean): this;
     /**
      * 设置是否限制元素在父元素边界内。
      * @param {boolean} contained - 是否限制元素在父元素边界内（默认值：false）
      * @returns {Layout} 返回当前实例以支持链式调用
      */
-    setContained(contained?: boolean): Layout;
-    contained: boolean | undefined;
+    setContained(contained?: boolean): this;
     /**
      * 设置是否使元素可拖动。
-     * @param {string} draggable - 是否使元素可拖动（可能值：vertical, horizontal, both）
+     * @param {'vertical' | 'horizontal' | 'both'} draggable - 是否使元素可拖动（可能值：vertical, horizontal, both）
      * @returns {Layout} 返回当前实例以支持链式调用
      */
-    setDraggable(draggable: string): Layout;
-    draggable: string | undefined;
+    setDraggable(draggable: 'vertical' | 'horizontal' | 'both'): this;
     /**
      * 设置是否使元素跟随光标。
      * @param {boolean} follows - 是否使元素跟随光标（默认值：false）
      * @returns {Layout} 返回当前实例以支持链式调用
      */
-    setFollowsCursor(follows?: boolean): Layout;
-    follows_cursor: boolean | undefined;
+    setFollowsCursor(follows?: boolean): this;
 }
 
-declare class DataBinding {
-    setBinding(binding: any): this;
-    bindings: any[] | undefined;
-    binding: any;
-    addDataBinding(dataBindingObject: any): this;
-}
+/**
+ * Elements
+    A JSON UI element is the basic form of data within JSON UI. Elements must have a unique name for each namespace so as to not have a conflict with other elements of the same name yet may have different functions.
+
+    Here the element type is label so it will render a text of Hello World when called:
+
+    vanilla/ui/example_file.json
+
+    {
+        "test_element": {
+            "type": "label",
+            "text": "Hello World"
+        }
+    }
+    Types
+    The following are some of the element types, which are possible values for the type property:
 
+    label - for creating text objects
+    image - for rendering images from a filepath provided
+    button - for creating interactive and clickable elements
+    panel - an empty container where you can store all other elements that may overlap to each other
+    stack_panel - an empty container where you can store all other elements in a stack that doesn't overlap to each other
+    grid - uses another element as a template, and then renders it repeatedly in multiple rows and columns
+    factory - renders an element based off of another element, is capable of calling hardcoded values and variables
+    custom - is paired with another property renderer which renders hardcoded JSON UI elements
+    screen - elements that are called by the game directly, usually root panel elements
+ */
+
+type SerializedElement = Record<string, JsonUIBag>;
+type AnyJSON = any;
 declare class UIElement {
-    constructor(name: any, type: any, template: any);
-    type: any;
-    id: any;
-    name: any;
+    type: string | undefined;
+    id: string;
+    name: string;
     control: Control;
     layout: Layout;
-    properties: Map<any, any>;
-    variables: Map<any, any>;
+    properties: Map<string, AnyJSON>;
+    variables: Map<string, AnyJSON>;
     dataBinding: DataBinding;
-    modifications: any[];
-    enableDebug(): this;
-    setLayout(layout: any): this;
-    setControl(control: any): this;
-    addControl(control: any): this;
-    addControls(controls: any): this;
-    addVariable(name: any, value: any): this;
-    addProp(name: any, value: any): this;
-    addModification(modification: any): this;
-    serialize(): {
-        [x: number]: any;
-    };
+    modifications: {
+        array_name: string;
+        operation: ModificationOperation;
+        value: AnyJSON;
+    }[];
+    constructor(name: string, type?: string, template?: string);
+    enableDebug(color?: [number, number, number, number]): this;
+    setLayout(layout: Layout): this;
+    setControl(control: Control): this;
+    addControl(control: UIElement | JsonUIBag): this;
+    addControls(controls: (UIElement | JsonUIBag)[]): this;
+    addVariable(name: string, value: AnyJSON): this;
+    addProp(name: string, value: AnyJSON): this;
+    addModification(modification: {
+        array_name: string;
+        operation: ModificationOperation;
+        value: AnyJSON;
+    }): this;
+    /**
+     * 声明待序列化合并的属性包（子类覆写以加入自己的专属属性包）。
+     * 合并顺序对结果无影响：重复键值均相同。
+     */
+    protected serializableSources(): object[];
+    serialize(): SerializedElement;
 }
 /**
- * Modifications ​
+ * Modifications
     To modify JSON UI in a non-intrusive way, you can use the modifications property to modify previously existing JSON UI elements from other packs (usually vanilla JSON UI files). Doing this makes sure only necessary parts are modified unless otherwise intended, to improve compatibility with other packs that modify the JSON UI.
 
     Modification	Description
@@ -2483,17 +3500,17 @@ declare class UIElement {
  */
 declare class Modifications {
     static OPERATION: Readonly<{
-        INSERT_BACK: "insert_back";
-        INSERT_FRONT: "insert_front";
-        INSERT_AFTER: "insert_after";
-        INSERT_BEFORE: "insert_before";
-        MOVE_BACK: "move_back";
-        MOVE_FRONT: "move_front";
-        MOVE_AFTER: "move_after";
-        MOVE_BEFORE: "move_before";
-        SWAP: "swap";
-        REPLACE: "replace";
-        REMOVE: "remove";
+        readonly INSERT_BACK: "insert_back";
+        readonly INSERT_FRONT: "insert_front";
+        readonly INSERT_AFTER: "insert_after";
+        readonly INSERT_BEFORE: "insert_before";
+        readonly MOVE_BACK: "move_back";
+        readonly MOVE_FRONT: "move_front";
+        readonly MOVE_AFTER: "move_after";
+        readonly MOVE_BEFORE: "move_before";
+        readonly SWAP: "swap";
+        readonly REPLACE: "replace";
+        readonly REMOVE: "remove";
     }>;
 }
 
@@ -2506,44 +3523,46 @@ declare class Modifications {
  * - control_name: string - 工厂的子控件名
  * - control_ids: object - 工厂的子控件 ID 对象组
  */
+
 declare class Factory {
+    [key: string]: unknown;
+    factory: JsonUIBag;
     /**
      * 设置工厂的名。
      * @param {string} name - 名（格式：name）
      * @returns {Factory} 返回当前实例以支持链式调用
      */
-    setName(name: string): Factory;
-    factory: {} | undefined;
+    setName(name: string): this;
     /**
      * 设置工厂的子控件名。
      * @param {string} name - 子控件名（格式：namespace.controls_name）
      * @returns {Factory} 返回当前实例以支持链式调用
      */
-    setControlName(name: string): Factory;
+    setControlName(name: string): this;
     /**
      * 设置工厂的子控件 ID 对象组。
-     * @param {object} ids - 子控件 ID 对象组
+     * @param {JsonUIBag} ids - 子控件 ID 对象组
      * @returns {Factory} 返回当前实例以支持链式调用
      */
-    setControlIds(ids: object): Factory;
+    setControlIds(ids: JsonUIBag): this;
     /**
      * 添加一个子控件 ID。
      * @param {string} key - 子控件的键名
      * @param {string} value - 子控件的 ID 值
      * @returns {Factory} 返回当前实例以支持链式调用
      */
-    addControlId(key: string, value: string): Factory;
+    addControlId(key: string, value: string): this;
 }
 
 declare class Panel extends UIElement {
+    factory: Factory;
     /**
-     *
-     * @param {*} id
-     * @param {*} [template]
+     * @param {string} id
+     * @param {string} [template]
      */
-    constructor(id: any, template?: any);
-    factory: Factory;
-    setLayout(layout: any): this;
+    constructor(id: string, template?: string);
+    setLayout(layout: Layout): this;
+    protected serializableSources(): object[];
 }
 
 /**
@@ -2572,147 +3591,152 @@ declare class Panel extends UIElement {
  * - force_texture_reload: boolean - 是否在纹理路径更改时强制重新加载图像
  * - base_size: Vector [width, height] - 基础大小
  */
+type UV = [number, number];
+type ClipDirection = 'left' | 'right' | 'up' | 'down' | 'center';
+type TextureFileSystem = 'InUserPackage' | 'InAppPackage' | 'RawPath' | 'RawPersistent' | 'InSettingsDir' | 'InExternalDir' | 'InServerPackage' | 'InDataDir' | 'InUserDir' | 'InWorldDir' | 'StoreCache' | string;
 declare class Sprite {
+    [key: string]: unknown;
+    texture: string;
+    allow_debug_missing_texture: boolean;
+    uv: UV;
+    uv_size: UV;
+    texture_file_system: TextureFileSystem;
+    nineslice_size: number | [number, number, number, number];
+    tiled: boolean | 'x' | 'y';
+    tiled_scale: [number, number];
+    clip_direction: ClipDirection | string;
+    clip_ratio: number;
+    clip_pixelperfect: boolean;
+    keep_ratio: boolean;
+    bilinear: boolean;
+    fill: boolean;
+    $fit_to_width: boolean;
+    zip_folder: string;
+    grayscale: boolean;
+    force_texture_reload: boolean;
+    base_size: [number, number];
     /**
      * 设置图像纹理路径。
      * @param {string} texture - 图像路径（例如："textures/ui/White"）
      * @returns {Sprite} 返回当前实例以支持链式调用
      */
-    setTexture(texture: string): Sprite;
-    texture: string | undefined;
+    setTexture(texture: string): this;
     /**
      * 设置是否在纹理未找到时显示缺失纹理。
      * @param {boolean} allow - 是否显示缺失纹理（默认值：true）
      * @returns {Sprite} 返回当前实例以支持链式调用
      */
-    setAllowDebugMissingTexture(allow?: boolean): Sprite;
-    allow_debug_missing_texture: boolean | undefined;
+    setAllowDebugMissingTexture(allow?: boolean): this;
     /**
      * 设置纹理映射的起始位置。
-     * @param {number[]} uv - 起始位置，格式为 [u, v]
+     * @param {UV} uv - 起始位置，格式为 [u, v]
      * @returns {Sprite} 返回当前实例以支持链式调用
      */
-    setUV(uv: number[]): Sprite;
-    uv: number[] | undefined;
+    setUV(uv: UV): this;
     /**
      * 设置纹理映射的大小。
-     * @param {number[]} uvSize - 大小，格式为 [width, height]
+     * @param {UV} uvSize - 大小，格式为 [width, height]
      * @returns {Sprite} 返回当前实例以支持链式调用
      */
-    setUVSize(uvSize: number[]): Sprite;
-    uv_size: number[] | undefined;
+    setUVSize(uvSize: UV): this;
     /**
      * 设置纹理来源。
-     * @param {string} source - 纹理来源（可能值：InUserPackage, InAppPackage, RawPath, RawPersistent, InSettingsDir, InExternalDir, InServerPackage, InDataDir, InUserDir, InWorldDir, StoreCache, Usage is Unknown）
+     * @param {TextureFileSystem} source - 纹理来源（可能值：InUserPackage, InAppPackage 等）
      * @returns {Sprite} 返回当前实例以支持链式调用
      */
-    setTextureFileSystem(source?: string): Sprite;
-    texture_file_system: string | undefined;
+    setTextureFileSystem(source?: TextureFileSystem): this;
     /**
      * 设置 9-slice 分割大小。
-     * @param {number|number[]} size - 9-slice 分割大小（可以是单个数字或 [x0, y0, x1, y1] 数组）
+     * @param {number | [number, number, number, number]} size - 9-slice 分割大小
      * @returns {Sprite} 返回当前实例以支持链式调用
      */
-    setNineSliceSize(size: number | number[]): Sprite;
-    nineslice_size: number | number[] | undefined;
+    setNineSliceSize(size: number | [number, number, number, number]): this;
     /**
      * 设置是否平铺纹理。
-     * @param {boolean|string} tiled - 是否平铺纹理（可能值：true/false, x, y）
+     * @param {boolean | 'x' | 'y'} tiled - 是否平铺纹理（可能值：true/false, x, y）
      * @returns {Sprite} 返回当前实例以支持链式调用
      */
-    setTiled(tiled: boolean | string): Sprite;
-    tiled: string | boolean | undefined;
+    setTiled(tiled: boolean | 'x' | 'y'): this;
     /**
      * 设置平铺纹理的缩放比例。
-     * @param {number[]} scale - 缩放比例，格式为 [sX, sY]（默认值：[1, 1]）
+     * @param {[number, number]} scale - 缩放比例，格式为 [sX, sY]（默认值：[1, 1]）
      * @returns {Sprite} 返回当前实例以支持链式调用
      */
-    setTiledScale(scale?: number[]): Sprite;
-    tiled_scale: number[] | undefined;
+    setTiledScale(scale?: [number, number]): this;
     /**
      * 设置裁剪方向的起始点。
-     * @param {string} direction - 裁剪方向（可能值：left, right, up, down, center）
+     * @param {ClipDirection} direction - 裁剪方向（可能值：left, right, up, down, center）
      * @returns {Sprite} 返回当前实例以支持链式调用
      */
-    setClipDirection(direction: string): Sprite;
-    clip_direction: string | undefined;
+    setClipDirection(direction: ClipDirection | string): this;
     /**
      * 设置裁剪比例。
      * @param {number} ratio - 裁剪比例（范围：0.0 到 1.0）
      * @returns {Sprite} 返回当前实例以支持链式调用
      */
-    setClipRatio(ratio: number): Sprite;
-    clip_ratio: number | undefined;
+    setClipRatio(ratio: number): this;
     /**
      * 设置是否尽可能保持像素精确裁剪。
      * @param {boolean} pixelPerfect - 是否保持像素精确裁剪
      * @returns {Sprite} 返回当前实例以支持链式调用
      */
-    setClipPixelPerfect(pixelPerfect?: boolean): Sprite;
-    clip_pixelperfect: boolean | undefined;
+    setClipPixelPerfect(pixelPerfect?: boolean): this;
     /**
      * 设置是否在调整大小时保持比例。
      * @param {boolean} keep - 是否保持比例（默认值：true）
      * @returns {Sprite} 返回当前实例以支持链式调用
      */
-    setKeepRatio(keep?: boolean): Sprite;
-    keep_ratio: boolean | undefined;
+    setKeepRatio(keep?: boolean): this;
     /**
      * 设置是否在调整大小时使用双线性函数。
      * @param {boolean} bilinear - 是否使用双线性函数（默认值：false）
      * @returns {Sprite} 返回当前实例以支持链式调用
      */
-    setBilinear(bilinear?: boolean): Sprite;
-    bilinear: boolean | undefined;
+    setBilinear(bilinear?: boolean): this;
     /**
      * 设置是否拉伸图像以适应大小。
      * @param {boolean} fill - 是否拉伸图像（默认值：false）
      * @returns {Sprite} 返回当前实例以支持链式调用
      */
-    setFill(fill?: boolean): Sprite;
-    fill: boolean | undefined;
+    setFill(fill?: boolean): this;
     /**
      * 设置是否适应宽度。
      * @param {boolean} fit - 是否适应宽度
      * @returns {Sprite} 返回当前实例以支持链式调用
      */
-    setFitToWidth(fit?: boolean): Sprite;
-    $fit_to_width: boolean | undefined;
+    setFitToWidth(fit?: boolean): this;
     /**
      * 设置压缩文件夹路径。
      * @param {string} folder - 压缩文件夹路径
      * @returns {Sprite} 返回当前实例以支持链式调用
      */
-    setZipFolder(folder: string): Sprite;
-    zip_folder: string | undefined;
+    setZipFolder(folder: string): this;
     /**
      * 设置是否以黑白渲染图像。
      * @param {boolean} grayscale - 是否以黑白渲染图像（默认值：false）
      * @returns {Sprite} 返回当前实例以支持链式调用
      */
-    setGrayscale(grayscale?: boolean): Sprite;
-    grayscale: boolean | undefined;
+    setGrayscale(grayscale?: boolean): this;
     /**
      * 设置是否在纹理路径更改时强制重新加载图像。
-     * @param {boolean} force - 是否强制重新加载图像
+     * @param {boolean} force - 是否强制重新加载图像（默认值：false）
      * @returns {Sprite} 返回当前实例以支持链式调用
      */
-    setForceTextureReload(force?: boolean): Sprite;
-    force_texture_reload: boolean | undefined;
+    setForceTextureReload(force?: boolean): this;
     /**
      * 设置基础大小。
-     * @param {number[]} size - 基础大小，格式为 [width, height]
+     * @param {[number, number]} size - 基础大小，格式为 [width, height]
      * @returns {Sprite} 返回当前实例以支持链式调用
      */
-    setBaseSize(size: number[]): Sprite;
-    base_size: number[] | undefined;
+    setBaseSize(size: [number, number]): this;
 }
 
 declare class Image extends UIElement {
-    constructor(id: any, template: any);
     sprite: Sprite;
     factory: Factory;
-    setSprite(sprite: any): this;
+    constructor(id: string, template?: string);
+    setSprite(sprite: Sprite): this;
+    protected serializableSources(): object[];
 }
 
 /**
@@ -2737,126 +3761,131 @@ declare class Image extends UIElement {
  * - backup_font_type: enum - 备用字体类型（默认值：default）
  * - text_alignment: enum - 文本对齐方式（未定义时根据 anchor_from 和 anchor_to 自动调整）
  */
+type RGB = [number, number, number];
+type FontSize = 'small' | 'normal' | 'large' | 'extra_large';
+type TextAlignment = 'left' | 'right' | 'center';
 declare class Text {
+    [key: string]: unknown;
+    text: string;
+    color: RGB;
+    locked_color: RGB;
+    shadow: boolean;
+    hide_hyphen: boolean;
+    notify_on_ellipses: string[];
+    enable_profanity_filter: boolean;
+    locked_alpha: number;
+    font_size: FontSize;
+    font_scale_factor: number;
+    localize: boolean;
+    line_padding: number;
+    font_type: string;
+    backup_font_type: string;
+    text_alignment: TextAlignment;
     /**
      * 设置文本内容。
      * @param {string} text - 文本内容
      * @returns {Text} 返回当前实例以支持链式调用
      */
-    setText(text?: string): Text;
-    text: string | undefined;
+    setText(text?: string): this;
     /**
      * 设置文本颜色。
-     * @param {number[]} color - RGB 颜色值（格式：[r, g, b]，默认值：[1.0, 1.0, 1.0]）
+     * @param {RGB} color - RGB 颜色值（格式：[r, g, b]，默认值：[1.0, 1.0, 1.0]）
      * @returns {Text} 返回当前实例以支持链式调用
      */
-    setColor(color?: number[]): Text;
-    color: number[] | undefined;
+    setColor(color?: RGB): this;
     /**
      * 设置父级禁用时的文本颜色。
-     * @param {number[]} lockedColor - RGB 颜色值（格式：[r, g, b]）
+     * @param {RGB} lockedColor - RGB 颜色值（格式：[r, g, b]）
      * @returns {Text} 返回当前实例以支持链式调用
      */
-    setLockedColor(lockedColor: number[]): Text;
-    locked_color: number[] | undefined;
+    setLockedColor(lockedColor: RGB): this;
     /**
      * 设置是否显示文本阴影。
      * @param {boolean} shadow - 是否显示阴影（默认值：false）
      * @returns {Text} 返回当前实例以支持链式调用
      */
-    setShadow(shadow?: boolean): Text;
-    shadow: boolean | undefined;
+    setShadow(shadow?: boolean): this;
     /**
      * 设置是否隐藏断词连字符。
      * @param {boolean} hide - 是否隐藏连字符（默认值：false）
      * @returns {Text} 返回当前实例以支持链式调用
      */
-    setHideHyphen(hide?: boolean): Text;
-    hide_hyphen: boolean | undefined;
+    setHideHyphen(hide?: boolean): this;
     /**
      * 设置文本出现省略号时需通知的控件名称数组。
      * @param {string[]} controls - 控件名称数组
      * @returns {Text} 返回当前实例以支持链式调用
      */
-    setNotifyOnEllipses(controls: string[]): Text;
-    notify_on_ellipses: string[] | undefined;
+    setNotifyOnEllipses(controls: string[]): this;
     /**
      * 添加一个需通知省略号事件的控件名称。
      * @param {string} controlName - 控件名称
      * @returns {Text} 返回当前实例以支持链式调用
      */
-    addNotifyOnEllipses(controlName: string): Text;
+    addNotifyOnEllipses(controlName: string): this;
     /**
      * 设置是否启用脏话过滤。
      * @param {boolean} enable - 是否启用过滤（默认值：false）
      * @returns {Text} 返回当前实例以支持链式调用
      */
-    setEnableProfanityFilter(enable?: boolean): Text;
-    enable_profanity_filter: boolean | undefined;
+    setEnableProfanityFilter(enable?: boolean): this;
     /**
      * 设置父级禁用时的透明度。
      * @param {number} alpha - 透明度（范围：0.0 到 1.0）
      * @returns {Text} 返回当前实例以支持链式调用
      */
-    setLockedAlpha(alpha: number): Text;
-    locked_alpha: number | undefined;
+    setLockedAlpha(alpha: number): this;
     /**
      * 设置字体大小。
-     * @param {string} size - 字体大小（可能值：small, normal, large, extra_large，默认值：normal）
+     * @param {FontSize} size - 字体大小（可能值：small, normal, large, extra_large，默认值：normal）
      * @returns {Text} 返回当前实例以支持链式调用
      */
-    setFontSize(size?: string): Text;
-    font_size: string | undefined;
+    setFontSize(size?: FontSize): this;
     /**
      * 设置字体缩放比例。
      * @param {number} factor - 缩放比例（默认值：1.0）
      * @returns {Text} 返回当前实例以支持链式调用
      */
-    setFontScaleFactor(factor?: number): Text;
-    font_scale_factor: number | undefined;
+    setFontScaleFactor(factor?: number): this;
     /**
      * 设置是否启用本地化翻译。
      * @param {boolean} localize - 是否启用本地化（默认值：false）
      * @returns {Text} 返回当前实例以支持链式调用
      */
-    setLocalize(localize?: boolean): Text;
-    localize: boolean | undefined;
+    setLocalize(localize?: boolean): this;
     /**
      * 设置行间距。
      * @param {number} padding - 行间距
      * @returns {Text} 返回当前实例以支持链式调用
      */
-    setLinePadding(padding: number): Text;
-    line_padding: number | undefined;
+    setLinePadding(padding: number): this;
     /**
      * 设置字体类型。
      * @param {string} font - 字体类型（可能值：default, rune, unicode 等，默认值：default）
      * @returns {Text} 返回当前实例以支持链式调用
      */
-    setFontType(font?: string): Text;
-    font_type: string | undefined;
+    setFontType(font?: string): this;
     /**
      * 设置备用字体类型。
      * @param {string} backupFont - 备用字体类型（默认值：default）
      * @returns {Text} 返回当前实例以支持链式调用
      */
-    setBackupFontType(backupFont?: string): Text;
-    backup_font_type: string | undefined;
+    setBackupFontType(backupFont?: string): this;
     /**
      * 设置文本对齐方式。
-     * @param {string} alignment - 对齐方式（例如：left, right, center）
+     * @param {TextAlignment} alignment - 对齐方式（例如：left, right, center）
      * @returns {Text} 返回当前实例以支持链式调用
      */
-    setTextAlignment(alignment: string): Text;
-    text_alignment: string | undefined;
+    setTextAlignment(alignment: TextAlignment): this;
 }
 
 declare class Label extends UIElement {
-    constructor(id: any, template: any);
     text: Text;
     factory: Factory;
-    setLayout(layout: any): this;
-    setText(text: any): this;
+    constructor(id: string, template?: string);
+    setLayout(layout: Layout): this;
+    setText(text: Text): this;
+    protected serializableSources(): object[];
 }
 
 declare namespace UiAPI {
@@ -2870,129 +3899,354 @@ declare namespace UiAPI {
 declare class ItemComponent {
     /**
      * 设置交互按钮
-     * @param {string} interact_text 交互文本
+     * @param interact_text 交互文本；传 true 使用通用 "Use Item" 文案，传 false 不显示
      * @returns 交互按钮组件
      */
-    static setInteractButton(interact_text: string): Map<string, string>;
+    static setInteractButton(interact_text: string | boolean): ItemComponentMap;
     /**
      * 自定义物品组件
      * [warning] 需要物品格式版本 format_version >1.21.90 and Scripting V2.0.0
-     * @param {string} component_id 组件标识符
-     * @param {object} params 自定义参数接口对象
-     * @returns {Map} 物品组件Map
+     * @param component_id 组件标识符
+     * @param params 自定义参数接口对象
+     * @returns 物品组件 Map
      */
-    static setCustomComponentV2(component_id: string, params: object): Map<any, any>;
+    static setCustomComponentV2(component_id: string, params: object): ItemComponentMap;
     /**
      * 物品的耐久度组件
-     * @param {number} max_durability 最大耐久
-     * @param {number} damage_chance_min 损坏最小几率
-     * @param {number} damage_chance_max 损坏最大几率
-     * @returns {ItemComponent}
-     */
-    static setDurability(max_durability: number, damage_chance_min?: number, damage_chance_max?: number): ItemComponent;
-    static setBlockPlacer(block: any, replace_block_item: any, use_on: any): Map<any, any>;
-    /**
-  *
-  * @param {Array} custom_components
-  * @returns
-  */
-    static setCustomComponents(custom_components: any[]): Map<any, any>;
+     * @param max_durability 最大耐久
+     * @param damage_chance_min 损坏最小几率
+     * @param damage_chance_max 损坏最大几率
+     * @returns 耐久度组件 Map
+     */
+    static setDurability(max_durability: number, damage_chance_min?: number, damage_chance_max?: number): ItemComponentMap;
+    /**
+     * 设置放置方块组件
+     * @param block 被放置的方块标识符
+     * @param options 放置配置
+     * @param options.replaceBlockItem 是否替换原方块物品
+     * @param options.alignedPlacement 是否启用对齐放置
+     * @param options.useOn 允许放置的目标方块描述符列表；省略则可放置于任何方块
+     * @returns 组件 Map
+     */
+    static setBlockPlacer(block: string, options?: BlockPlacerOptions): ItemComponentMap;
+    /**
+   * 设置自定义组件列表
+   * @param custom_components 自定义组件 ID 数组
+   * @returns 组件 Map
+   */
+    static setCustomComponents(custom_components: string[]): ItemComponentMap;
     /**
      * 设置物品的可投掷组件。
-     * @param {Boolean} doSwingAnimation - 是否使用挥动动画。
-     * @param {Number} launchPowerScale - 投掷力量的缩放比例。
-     * @param {Number} maxDrawDuration - 最大蓄力时间。
-     * @param {Number} maxLaunchPower - 最大投掷力量。
-     * @param {Number} minDrawDuration - 最小蓄力时间。
-     * @param {Boolean} scalePowerByDrawDuration - 投掷力量是否随蓄力时间增加。
-     * @returns {Map} - 新的组件集合。
+     * @param doSwingAnimation 是否使用挥动动画。
+     * @param launchPowerScale 投掷力量的缩放比例。
+     * @param maxDrawDuration 最大蓄力时间。
+     * @param maxLaunchPower 最大投掷力量。
+     * @param minDrawDuration 最小蓄力时间。
+     * @param scalePowerByDrawDuration 投掷力量是否随蓄力时间增加。
+     * @returns 新的组件集合。
      */
-    static setThrowable(doSwingAnimation?: boolean, launchPowerScale?: number, maxDrawDuration?: number, maxLaunchPower?: number, minDrawDuration?: number, scalePowerByDrawDuration?: boolean): Map<any, any>;
+    static setThrowable(doSwingAnimation?: boolean, launchPowerScale?: number, maxDrawDuration?: number, maxLaunchPower?: number, minDrawDuration?: number, scalePowerByDrawDuration?: boolean): ItemComponentMap;
     /**
      * 设置物品的显示名称。
-     * @param {String} displayName - 显示名称或本地化键。
-     * @returns {Map} - 新的组件集合。
+     * @param displayName 显示名称或本地化键。
+     * @returns 新的组件集合。
      */
-    static setDisplayName(displayName: string): Map<any, any>;
+    static setDisplayName(displayName: string): ItemComponentMap;
     /**
      * 设置物品的食物组件。
-     * @param {Boolean} canAlwaysEat - 是否随时可以食用。
-     * @param {Number} nutrition - 营养值。
-     * @param {Number} saturationModifier - 饱和度修正值。
-     * @param {String} [usingConvertsTo] - 食用后转换的目标物品。
-     * @returns {Map} - 新的组件集合。
+     * @param options 食物组件配置。
+     * @param options.canAlwaysEat 是否随时可以食用。
+     * @param options.nutrition 营养值。
+     * @param options.saturationModifier 饱和度修正值。
+     * @param options.usingConvertsTo 食用后转换的目标物品。
+     * @returns 新的组件集合。
      */
-    static setFoodComponent(canAlwaysEat: boolean, nutrition: number, saturationModifier: number, usingConvertsTo?: string): Map<any, any>;
+    static setFoodComponent(options?: FoodComponentOptions): ItemComponentMap;
     /**
      * 设置物品的燃料组件。
-     * @param {Number} duration - 燃料燃烧的持续时间（秒），最小值为 0.05。
-     * @returns {Map} - 新的组件集合。
+     * @param duration 燃料燃烧的持续时间（秒），最小值为 0.05。
+     * @returns 新的组件集合。
      */
-    static setFuel(duration: number): Map<any, any>;
+    static setFuel(duration: number): ItemComponentMap;
     /**
      * 设置物品的附魔光效组件。
-     * @param {Boolean} hasGlint - 是否显示附魔光效。
-     * @returns {Map} - 新的组件集合。
+     * @param hasGlint 是否显示附魔光效。
+     * @returns 新的组件集合。
      */
-    static setGlint(hasGlint: boolean): Map<any, any>;
+    static setGlint(hasGlint: boolean): ItemComponentMap;
     /**
      * 设置物品的手持渲染方式组件。
-     * @param {Boolean} isHandEquipped - 是否像工具一样渲染。
-     * @returns {Map} - 新的组件集合。
+     * @param isHandEquipped 是否像工具一样渲染。
+     * @returns 新的组件集合。
      */
-    static setHandEquipped(isHandEquipped: boolean): Map<any, any>;
+    static setHandEquipped(isHandEquipped: boolean): ItemComponentMap;
     /**
      * 设置物品的图标组件。
-     * @param {String} texture - 图标纹理名称。
-     * @returns {Map} - 新的组件集合。
+     * 支持字符串（default 纹理）或对象（多纹理）两种格式。
+     * @param texture 图标纹理名称，或包含 default/dyed/iconTrim 等纹理的对象。
+     * @returns 新的组件集合。
      */
-    static setIcon(texture: string): Map<any, any>;
+    static setIcon(texture: string | IconTextures): ItemComponentMap;
     /**
      * 设置物品的最大堆叠数量组件。
-     * @param {Number} maxStackSize - 最大堆叠数量，默认值为 64。
-     * @returns {Map} - 新的组件集合。
+     * @param maxStackSize 最大堆叠数量，默认值为 64。
+     * @returns 新的组件集合。
      */
-    static setMaxStackSize(maxStackSize?: number): Map<any, any>;
+    static setMaxStackSize(maxStackSize?: number): ItemComponentMap;
     /**
      * 设置物品的投射物组件。
-     * @param {Number} [minimumCriticalPower] - 投射物需要蓄力多久才能造成暴击。
-     * @param {String} [projectileEntity] - 作为投射物发射的实体名称。
-     * @returns {Map} - 新的组件集合。
+     * @param minimumCriticalPower 投射物需要蓄力多久才能造成暴击。
+     * @param projectileEntity 作为投射物发射的实体名称。
+     * @returns 新的组件集合。
      */
-    static setProjectile(minimumCriticalPower?: number, projectileEntity?: string): Map<any, any>;
+    static setProjectile(minimumCriticalPower?: number, projectileEntity?: string): ItemComponentMap;
     /**
      * 设置物品的使用修饰组件。
-     * @param {Number} [movementModifier] - 使用物品时玩家移动速度的缩放值。
-     * @param {Number} [useDuration] - 物品使用所需的时间（秒）。
-     * @returns {Map} - 新的组件集合。
+     * @param options 使用修饰配置。
+     * @param options.movementModifier 使用物品时玩家移动速度的缩放值（0.0-1.0）。
+     * @param options.useDuration 物品使用所需的时间（秒）。
+     * @param options.emitVibrations 是否在开始/停止使用时发出振动。
+     * @param options.startSound 开始使用时触发的音效。
+     * @param options.startUsing 使用修饰生效的时机（"always" 或 "if_first"）。
+     * @returns 新的组件集合。
      */
-    static setUseModifiers(movementModifier?: number, useDuration?: number): Map<any, any>;
+    static setUseModifiers(options?: UseModifiersOptions): ItemComponentMap;
     /**
      * 设置物品的可穿戴组件。
-     * @param {Number} [protection=0] - 物品提供的保护值。
-     * @param {String} [slot] - 物品可以穿戴的槽位（如 "head"、"chest" 等）。
-     * @returns {Map} - 新的组件集合。
+     * @param protection 物品提供的保护值。
+     * @param slot 物品可以穿戴的槽位（如 "slot.armor.head"、"slot.weapon.offhand" 等）。
+     * @param hidesPlayerLocation 穿戴时是否从定位栏与定位地图中隐藏。
+     * @returns 新的组件集合。
      */
-    static setWearable(protection?: number, slot?: string): Map<any, any>;
+    static setWearable(protection?: number, slot?: string, hidesPlayerLocation?: boolean): ItemComponentMap;
     /**
-    * 设置物品的使用动画组件。
-    * @param {String} animation - 物品使用时的动画类型（如 "eat"、"drink" 等）。
-    * @returns {Map} - 新的组件集合。
-    * @throws {Error} - 如果 animation 不是字符串类型。
-    */
-    static setUseAnimation(animation: string): Map<any, any>;
+     * 设置物品的使用动画组件。
+     * @param animation 物品使用时的动画类型（如 "eat"、"drink" 等）。
+     * @returns 新的组件集合。
+     */
+    static setUseAnimation(animation: string): ItemComponentMap;
+    /**
+     * 设置物品是否可装备至副手。
+     * @param allowed 是否允许装备至副手。
+     * @returns 新的组件集合。
+     */
+    static setAllowOffHand(allowed: boolean): ItemComponentMap;
+    /**
+     * 设置 Bundle 交互组件（需要同时具备 storage_item 组件）。
+     * @param numViewableSlots 可查看的槽位数量（1-64）。
+     * @returns 新的组件集合。
+     */
+    static setBundleInteraction(numViewableSlots: number): ItemComponentMap;
+    /**
+     * 设置创造模式下能否破坏方块。
+     * @param canDestroy 是否可破坏。
+     * @returns 新的组件集合。
+     */
+    static setCanDestroyInCreative(canDestroy: boolean): ItemComponentMap;
+    /**
+     * 设置堆肥组件。
+     * @param compostingChance 堆肥等级增加的概率（0-100）。
+     * @returns 新的组件集合。
+     */
+    static setCompostable(compostingChance: number): ItemComponentMap;
+    /**
+     * 设置物品的冷却组件。
+     * @param options 冷却配置。
+     * @param options.category 冷却分类，相同分类的物品共享冷却。
+     * @param options.duration 冷却时长（秒），负数会使物品无法使用。
+     * @param options.type 冷却影响的输入类型（"use" 或 "attack"）。
+     * @returns 新的组件集合。
+     */
+    static setCooldown(options: CooldownOptions): ItemComponentMap;
+    /**
+     * 设置物品的伤害组件。
+     * @param damage 额外伤害值（0-32767）。
+     * @returns 新的组件集合。
+     */
+    static setDamage(damage: number): ItemComponentMap;
+    /**
+     * 设置伤害吸收组件（需要同时具备 durability 组件并装备于盔甲槽位）。
+     * @param absorbableCauses 可被吸收的伤害原因列表，如 ["all"]。
+     * @returns 新的组件集合。
+     */
+    static setDamageAbsorption(absorbableCauses: string[]): ItemComponentMap;
+    /**
+     * 设置挖掘组件。
+     * @param options 挖掘配置。
+     * @param options.destroySpeeds 破坏速度列表，speed 为 0 表示无法破坏该方块。
+     * @param options.useEfficiency 效率附魔是否能影响破坏速度。
+     * @returns 新的组件集合。
+     */
+    static setDigger(options: DiggerOptions): ItemComponentMap;
+    /**
+     * 设置耐久传感器组件。
+     * @param options 耐久传感器配置。
+     * @param options.durabilityThresholds 耐久阈值列表，达到阈值时触发粒子或音效。
+     * @returns 新的组件集合。
+     */
+    static setDurabilitySensor(options: DurabilitySensorOptions): ItemComponentMap;
+    /**
+     * 设置可染色组件。
+     * @param defaultColor 默认颜色，如 "#ffffff"。
+     * @returns 新的组件集合。
+     */
+    static setDyeable(defaultColor: string): ItemComponentMap;
+    /**
+     * 设置可附魔组件。
+     * @param slot 可应用的附魔槽位，如 "sword"、"bow"。
+     * @param value 附魔质量与数量（0-255）。
+     * @returns 新的组件集合。
+     */
+    static setEnchantable(slot: string, value: number): ItemComponentMap;
+    /**
+     * 设置放置实体组件。
+     * @param entity 被放置的实体标识符，可带出生事件如 "wiki:entity<wiki:event>"。
+     * @param options 放置配置。
+     * @param options.dispenseOn 允许发射器放置的目标方块列表。
+     * @param options.useOn 允许放置的目标方块列表。
+     * @returns 新的组件集合。
+     */
+    static setEntityPlacer(entity: string, options?: EntityPlacerOptions): ItemComponentMap;
+    /**
+     * 设置防火组件。
+     * @param value 是否防火。
+     * @returns 新的组件集合。
+     */
+    static setFireResistant(value: boolean): ItemComponentMap;
+    /**
+     * 设置物品名颜色组件。
+     * @param color 颜色名称，如 "minecoin_gold"。
+     * @returns 新的组件集合。
+     */
+    static setHoverTextColor(color: string): ItemComponentMap;
+    /**
+     * 设置动能武器组件。
+     * @param options 动能武器配置。
+     * @param options.delay 动能伤害开始生效前的延迟（tick）。
+     * @param options.hitboxMargin 命中箱额外边距（格）。
+     * @param options.reach 生效距离范围（格）。
+     * @param options.creativeReach 创造模式下生效距离范围（格）。
+     * @param options.damageMultiplier 基础伤害倍率。
+     * @param options.damageModifier 附加伤害。
+     * @param options.damageConditions 造成伤害的条件。
+     * @param options.dismountConditions 解除骑乘的条件。
+     * @param options.knockbackConditions 造成击退的条件。
+     * @returns 新的组件集合。
+     */
+    static setKineticWeapon(options: KineticWeaponOptions): ItemComponentMap;
+    /**
+     * 设置物品是否与液体方块交互。
+     * @param clipped 是否在液体内部交互。
+     * @returns 新的组件集合。
+     */
+    static setLiquidClipped(clipped: boolean): ItemComponentMap;
+    /**
+     * 设置穿刺武器组件。
+     * @param options 穿刺武器配置。
+     * @param options.hitboxMargin 命中箱额外边距（格）。
+     * @param options.reach 生效距离范围（格）。
+     * @param options.creativeReach 创造模式下生效距离范围（格）。
+     * @returns 新的组件集合。
+     */
+    static setPiercingWeapon(options?: PiercingWeaponOptions): ItemComponentMap;
+    /**
+     * 设置物品稀有度组件（会被 hover_text_color 覆盖）。
+     * @param rarity 稀有度："common"、"uncommon"、"rare"、"epic"。
+     * @returns 新的组件集合。
+     */
+    static setRarity(rarity: ItemRarity): ItemComponentMap;
+    /**
+     * 设置唱片组件。
+     * @param options 唱片配置。
+     * @param options.comparatorSignal 比较器信号强度（0-15）。
+     * @param options.duration 播放时长（秒）。
+     * @param options.soundEvent 播放的原版音效事件。
+     * @returns 新的组件集合。
+     */
+    static setRecord(options: RecordOptions): ItemComponentMap;
+    /**
+     * 设置可修复组件。
+     * @param repairItems 修复条目列表；repair_amount 可为数字或 Molang 表达式字符串。
+     * @returns 新的组件集合。
+     */
+    static setRepairable(repairItems: RepairItem[]): ItemComponentMap;
+    /**
+     * 设置射击组件（需要同时具备 use_modifiers 组件）。
+     * @param options 射击配置。
+     * @param options.ammunition 弹药列表，item 必须具有 projectile 组件。
+     * @param options.chargeOnDraw 是否在拉弓时上弹（如弩）。
+     * @param options.maxDrawDuration 自动发射前的最大拉弓时长（秒）。
+     * @param options.scalePowerByDrawDuration 发射威力是否随拉弓时长增加。
+     * @returns 新的组件集合。
+     */
+    static setShooter(options: ShooterOptions): ItemComponentMap;
+    /**
+     * 设置是否应该消失组件。
+     * @param shouldDespawn 掉落物是否最终消失。
+     * @returns 新的组件集合。
+     */
+    static setShouldDespawn(shouldDespawn: boolean): ItemComponentMap;
+    /**
+     * 设置按数据堆叠组件。
+     * @param stackedByData 不同数据值的同种物品是否分开堆叠。
+     * @returns 新的组件集合。
+     */
+    static setStackedByData(stackedByData: boolean): ItemComponentMap;
+    /**
+     * 设置容器物品组件（需要 max_stack_size 为 1）。
+     * @param options 容器配置。
+     * @param options.maxSlots 容器槽位数量（1-64）。
+     * @param options.allowNestedStorageItems 是否允许嵌套其他容器物品。
+     * @param options.allowedItems 仅允许存入的物品列表。
+     * @param options.bannedItems 禁止存入的物品列表。
+     * @returns 新的组件集合。
+     */
+    static setStorageItem(options: StorageItemOptions): ItemComponentMap;
+    /**
+     * 设置容器重量上限组件（需要同时具备 storage_item 组件）。
+     * @param maxWeightLimit 容器内物品总重量上限。
+     * @returns 新的组件集合。
+     */
+    static setStorageWeightLimit(maxWeightLimit: number): ItemComponentMap;
+    /**
+     * 设置容器重量修正组件（0 表示不允许放入其他容器）。
+     * @param weightInStorageItem 该物品放入容器时占用的重量（0-64）。
+     * @returns 新的组件集合。
+     */
+    static setStorageWeightModifier(weightInStorageItem: number): ItemComponentMap;
+    /**
+     * 设置挥动时长组件。
+     * @param value 基础挥动时长（秒）。
+     * @returns 新的组件集合。
+     */
+    static setSwingDuration(value: number): ItemComponentMap;
+    /**
+     * 设置挥砍音效组件。
+     * @param options 音效配置。
+     * @param options.attackMiss 未命中时播放的原版音效。
+     * @param options.attackHit 普通命中时播放的原版音效。
+     * @param options.attackCriticalHit 暴击命中时播放的原版音效。
+     * @returns 新的组件集合。
+     */
+    static setSwingSounds(options?: SwingSoundsOptions): ItemComponentMap;
+    /**
+     * 设置物品标签组件。
+     * @param tags 标签列表。
+     * @returns 新的组件集合。
+     */
+    static setTags(tags: string[]): ItemComponentMap;
     /**
      * 将多个组件集合合并为一个。
-     * @param {...Map} componentMaps - 多个组件集合。
-     * @returns {Map} - 合并后的组件集合。
+     * @param componentMaps 多个组件集合。
+     * @returns 合并后的组件集合。
      */
-    static combineComponents(...componentMaps: Map<any, any>[]): Map<any, any>;
+    static combineComponents(...componentMaps: ItemComponentMap[]): ItemComponentMap;
     /**
-     * 获取当前组件的 JSON 表示。
-     * @param {Map} components - 组件集合。
-     * @returns {Object} - 组件的 JSON 对象。
+     * 获取当前组件的 JSON 表示。
+     * @param components 组件集合。
+     * @returns 组件的 JSON 对象。
      */
-    static toJSON(components: Map<any, any>): Object;
+    static toJSON(components: ItemComponentMap): Record<string, unknown>;
 }
 
 /**
@@ -3013,7 +4267,8 @@ declare class ItemComponent {
  * - handle_deselect: boolean - 是否处理取消选择事件
  * - button_up_right_of_first_refusal: boolean - 是否在首次拒绝后处理按钮释放事件
  */
-declare class ButtonMapping$1 {
+declare class ButtonMapping {
+    [key: string]: unknown;
     ignored: boolean;
     from_button_id: string;
     to_button_id: string;
@@ -3025,170 +4280,113 @@ declare class ButtonMapping$1 {
     handle_select: boolean;
     handle_deselect: boolean;
     button_up_right_of_first_refusal: boolean;
+    constructor();
     /**
      * 设置是否忽略映射。
      * @param {boolean} ignored - 是否忽略映射（默认值：false）
      * @returns {ButtonMapping} 返回当前实例以支持链式调用
      */
-    setIgnored(ignored?: boolean): ButtonMapping$1;
+    setIgnored(ignored?: boolean): this;
     /**
      * 设置触发事件的按钮 ID。
      * @param {string} fromButtonId - 触发事件的按钮 ID
      * @returns {ButtonMapping} 返回当前实例以支持链式调用
      */
-    setFromButtonId(fromButtonId: string): ButtonMapping$1;
+    setFromButtonId(fromButtonId: string): this;
     /**
      * 设置事件触发时执行的按钮 ID。
      * @param {string} toButtonId - 事件触发时执行的按钮 ID
      * @returns {ButtonMapping} 返回当前实例以支持链式调用
      */
-    setToButtonId(toButtonId: string): ButtonMapping$1;
+    setToButtonId(toButtonId: string): this;
     /**
      * 设置映射类型。
      * @param {string} mappingType - 映射类型（可能值：global, pressed, double_pressed, focused）
      * @returns {ButtonMapping} 返回当前实例以支持链式调用
      */
-    setMappingType(mappingType: string): ButtonMapping$1;
+    setMappingType(mappingType: string): this;
     /**
      * 设置映射范围。
      * @param {string} scope - 映射范围（可能值：view, controller）
      * @returns {ButtonMapping} 返回当前实例以支持链式调用
      */
-    setScope(scope: string): ButtonMapping$1;
+    setScope(scope: string): this;
     /**
      * 设置输入模式条件。
      * @param {string} condition - 输入模式条件（可能值：not_gaze, not_gamepad, gamepad_and_not_gaze）
      * @returns {ButtonMapping} 返回当前实例以支持链式调用
      */
-    setInputModeCondition(condition: string): ButtonMapping$1;
+    setInputModeCondition(condition: string): this;
     /**
      * 设置是否忽略输入范围。
      * @param {boolean} ignore - 是否忽略输入范围
      * @returns {ButtonMapping} 返回当前实例以支持链式调用
      */
-    setIgnoreInputScope(ignore?: boolean): ButtonMapping$1;
+    setIgnoreInputScope(ignore?: boolean): this;
     /**
      * 设置是否消耗事件。
      * @param {boolean} consume - 是否消耗事件
      * @returns {ButtonMapping} 返回当前实例以支持链式调用
      */
-    setConsumeEvent(consume?: boolean): ButtonMapping$1;
+    setConsumeEvent(consume?: boolean): this;
     /**
      * 设置是否处理选择事件。
      * @param {boolean} handle - 是否处理选择事件
      * @returns {ButtonMapping} 返回当前实例以支持链式调用
      */
-    setHandleSelect(handle?: boolean): ButtonMapping$1;
+    setHandleSelect(handle?: boolean): this;
     /**
      * 设置是否处理取消选择事件。
      * @param {boolean} handle - 是否处理取消选择事件
      * @returns {ButtonMapping} 返回当前实例以支持链式调用
      */
-    setHandleDeselect(handle?: boolean): ButtonMapping$1;
+    setHandleDeselect(handle?: boolean): this;
     /**
      * 设置是否在首次拒绝后处理按钮释放事件。
      * @param {boolean} handle - 是否处理按钮释放事件
      * @returns {ButtonMapping} 返回当前实例以支持链式调用
      */
-    setButtonUpRightOfFirstRefusal(handle?: boolean): ButtonMapping$1;
+    setButtonUpRightOfFirstRefusal(handle?: boolean): this;
 }
 
-/**
- * DataBinding 类
- *
- * 该类表示数据绑定配置，用于将硬编码值或变量绑定到元素属性。
- *
- * 属性：
- * - ignored: boolean - 是否忽略绑定（默认值：false）
- * - binding_type: enum - 绑定类型（可能值：global, view, collection, collection_details, none）
- * - binding_name: string - 数据绑定名称或条件的值
- * - binding_name_override: string - 应用 binding_name 值的 UI 元素属性名称
- * - binding_collection_name: string - 要使用的集合名称
- * - binding_collection_prefix: string - 集合前缀
- * - binding_condition: enum - 数据绑定的条件（可能值：always, always_when_visible, visible, once, none, visibility_changed）
- * - source_control_name: string - 要观察其属性值的 UI 元素名称
- * - source_property_name: string - 存储 source_control_name 引用的 UI 元素的属性值
- * - target_property_name: string - 应用 source_property_name 值的 UI 元素属性
- * - resolve_sibling_scope: boolean - 是否允许选择同级元素而非子元素（默认值：false）
- */
-declare class DataBindingObject {
-    /**
-     * 设置是否忽略绑定。
-     * @param {boolean} ignored - 是否忽略绑定（默认值：false）
-     * @returns {DataBindingObject} 返回当前实例以支持链式调用
-     */
-    setIgnored(ignored?: boolean): DataBindingObject;
-    ignored: boolean | undefined;
-    /**
-     * 设置绑定类型。
-     * @param {string} type - 绑定类型（可能值：global, view, collection, collection_details, none）
-     * @returns {DataBindingObject} 返回当前实例以支持链式调用
-     */
-    setBindingType(type: string): DataBindingObject;
-    binding_type: string | undefined;
-    /**
-     * 设置数据绑定名称或条件的值。
-     * @param {string} name - 数据绑定名称或条件的值
-     * @returns {DataBindingObject} 返回当前实例以支持链式调用
-     */
-    setBindingName(name: string): DataBindingObject;
-    binding_name: string | undefined;
-    /**
-     * 设置应用 binding_name 值的 UI 元素属性名称。
-     * @param {string} nameOverride - 应用 binding_name 值的 UI 元素属性名称
-     * @returns {DataBindingObject} 返回当前实例以支持链式调用
-     */
-    setBindingNameOverride(nameOverride: string): DataBindingObject;
-    binding_name_override: string | undefined;
-    /**
-     * 设置要使用的集合名称。
-     * @param {string} collectionName - 集合名称
-     * @returns {DataBindingObject} 返回当前实例以支持链式调用
-     */
-    setBindingCollectionName(collectionName: string): DataBindingObject;
-    binding_collection_name: string | undefined;
-    /**
-     * 设置集合前缀。
-     * @param {string} prefix - 集合前缀
-     * @returns {DataBindingObject} 返回当前实例以支持链式调用
-     */
-    setBindingCollectionPrefix(prefix: string): DataBindingObject;
-    binding_collection_prefix: string | undefined;
-    /**
-     * 设置数据绑定的条件。
-     * @param {string} condition - 数据绑定的条件（可能值：always, always_when_visible, visible, once, none, visibility_changed）
-     * @returns {DataBindingObject} 返回当前实例以支持链式调用
-     */
-    setBindingCondition(condition: string): DataBindingObject;
-    binding_condition: string | undefined;
-    /**
-     * 设置要观察其属性值的 UI 元素名称。
-     * @param {string} controlName - UI 元素名称
-     * @returns {DataBindingObject} 返回当前实例以支持链式调用
-     */
-    setSourceControlName(controlName: string): DataBindingObject;
-    source_control_name: string | undefined;
-    /**
-     * 设置存储 source_control_name 引用的 UI 元素的属性值。
-     * @param {string} propertyName - 属性名称
-     * @returns {DataBindingObject} 返回当前实例以支持链式调用
-     */
-    setSourcePropertyName(propertyName: string): DataBindingObject;
-    source_property_name: string | undefined;
-    /**
-     * 设置应用 source_property_name 值的 UI 元素属性。
-     * @param {string} propertyName - 属性名称
-     * @returns {DataBindingObject} 返回当前实例以支持链式调用
-     */
-    setTargetPropertyName(propertyName: string): DataBindingObject;
-    target_property_name: string | undefined;
-    /**
-     * 设置是否允许选择同级元素而非子元素。
-     * @param {boolean} resolve - 是否允许选择同级元素（默认值：false）
-     * @returns {DataBindingObject} 返回当前实例以支持链式调用
-     */
-    setResolveSiblingScope(resolve?: boolean): DataBindingObject;
-    resolve_sibling_scope: boolean | undefined;
+interface ProgressBarLayer {
+    color: [number, number, number];
+    clipRatio: number;
+}
+interface HudProgressBarOptions {
+    id: string;
+    texture: string;
+    uv?: [number, number];
+    uvSize?: [number, number];
+    barSize?: [string | number, string | number];
+    layers: ProgressBarLayer[];
+    states: number;
+    fillColor?: [number, number, number];
+    fillUv?: [number, number];
+    segments?: {
+        count: number;
+        color: [number, number, number];
+    };
+    hudSize?: [string | number, string | number];
+    anchorFrom?: string;
+    anchorTo?: string;
+    offset?: [number, number];
+    clipDirection?: string;
+}
+declare class HudProgressBar {
+    private panel;
+    private options;
+    constructor(options: HudProgressBarOptions);
+    private build;
+    getPanel(): Panel;
+    mountToHud(): void;
+}
+
+type AnyUI = any;
+declare class UISystemRegistry {
+    #private;
+    static registerUISystem(ui_system: AnyUI): void;
+    static addOuterUIdefs(ui_defs: string[]): void;
 }
 
 /**
@@ -3209,84 +4407,86 @@ declare class DataBindingObject {
  * - consume_hover_events: boolean - 是否消耗悬停事件
  * - gesture_tracking_button: string - 手势跟踪按钮
  */
+
 declare class Input {
+    [key: string]: unknown;
+    button_mappings: JsonUIBag[];
+    modal: boolean;
+    inline_modal: boolean;
+    always_listen_to_input: boolean;
+    always_handle_pointer: boolean;
+    always_handle_controller_direction: boolean;
+    hover_enabled: boolean;
+    prevent_touch_input: boolean;
+    consume_event: boolean;
+    consume_hover_events: boolean;
+    gesture_tracking_button: string;
     /**
      * 设置按钮映射配置。
-     * @param {ButtonMapping[]} mappings - 按钮映射配置数组
+     * @param {JsonUIBag[]} mappings - 按钮映射配置数组
      * @returns {Input} 返回当前实例以支持链式调用
      */
-    setButtonMappings(mappings: ButtonMapping[]): Input;
-    button_mappings: ButtonMapping[] | undefined;
+    setButtonMappings(mappings: JsonUIBag[]): this;
     /**
      * 设置是否为模态输入。
      * @param {boolean} modal - 是否为模态输入
      * @returns {Input} 返回当前实例以支持链式调用
      */
-    setModal(modal?: boolean): Input;
-    modal: boolean | undefined;
+    setModal(modal?: boolean): this;
     /**
      * 设置是否为内联模态输入。
      * @param {boolean} inlineModal - 是否为内联模态输入
      * @returns {Input} 返回当前实例以支持链式调用
      */
-    setInlineModal(inlineModal?: boolean): Input;
-    inline_modal: boolean | undefined;
+    setInlineModal(inlineModal?: boolean): this;
     /**
      * 设置是否始终监听输入。
      * @param {boolean} alwaysListen - 是否始终监听输入
      * @returns {Input} 返回当前实例以支持链式调用
      */
-    setAlwaysListenToInput(alwaysListen?: boolean): Input;
-    always_listen_to_input: boolean | undefined;
+    setAlwaysListenToInput(alwaysListen?: boolean): this;
     /**
      * 设置是否始终处理指针事件。
      * @param {boolean} alwaysHandle - 是否始终处理指针事件
      * @returns {Input} 返回当前实例以支持链式调用
      */
-    setAlwaysHandlePointer(alwaysHandle?: boolean): Input;
-    always_handle_pointer: boolean | undefined;
+    setAlwaysHandlePointer(alwaysHandle?: boolean): this;
     /**
      * 设置是否始终处理控制器方向事件。
      * @param {boolean} alwaysHandle - 是否始终处理控制器方向事件
      * @returns {Input} 返回当前实例以支持链式调用
      */
-    setAlwaysHandleControllerDirection(alwaysHandle?: boolean): Input;
-    always_handle_controller_direction: boolean | undefined;
+    setAlwaysHandleControllerDirection(alwaysHandle?: boolean): this;
     /**
      * 设置是否启用悬停事件。
      * @param {boolean} enabled - 是否启用悬停事件
      * @returns {Input} 返回当前实例以支持链式调用
      */
-    setHoverEnabled(enabled?: boolean): Input;
-    hover_enabled: boolean | undefined;
+    setHoverEnabled(enabled?: boolean): this;
     /**
      * 设置是否阻止触摸输入。
      * @param {boolean} prevent - 是否阻止触摸输入
      * @returns {Input} 返回当前实例以支持链式调用
      */
-    setPreventTouchInput(prevent?: boolean): Input;
-    prevent_touch_input: boolean | undefined;
+    setPreventTouchInput(prevent?: boolean): this;
     /**
      * 设置是否消耗事件。
      * @param {boolean} consume - 是否消耗事件
      * @returns {Input} 返回当前实例以支持链式调用
      */
-    setConsumeEvent(consume?: boolean): Input;
-    consume_event: boolean | undefined;
+    setConsumeEvent(consume?: boolean): this;
     /**
      * 设置是否消耗悬停事件。
      * @param {boolean} consume - 是否消耗悬停事件
      * @returns {Input} 返回当前实例以支持链式调用
      */
-    setConsumeHoverEvents(consume?: boolean): Input;
-    consume_hover_events: boolean | undefined;
+    setConsumeHoverEvents(consume?: boolean): this;
     /**
      * 设置手势跟踪按钮。
      * @param {string} button - 手势跟踪按钮
      * @returns {Input} 返回当前实例以支持链式调用
      */
-    setGestureTrackingButton(button: string): Input;
-    gesture_tracking_button: string | undefined;
+    setGestureTrackingButton(button: string): this;
 }
 
 /**
@@ -3300,62 +4500,75 @@ declare class Input {
  * - sound_pitch: float - 声音音调（默认值：1.0）
  * - sounds: Array of sound objects - 触发事件时播放的声音数组
  */
+
 declare class Sound {
+    [key: string]: unknown;
+    sound_name: string;
+    sound_volume: number;
+    sound_pitch: number;
+    sounds: JsonUIBag[];
     /**
      * 设置声音名称。
      * @param {string} name - 声音名称（定义在 RP/sounds/sound_definitions.json 文件中）
      * @returns {Sound} 返回当前实例以支持链式调用
      */
-    setSoundName(name: string): Sound;
-    sound_name: string | undefined;
+    setSoundName(name: string): this;
     /**
      * 设置声音音量。
      * @param {number} volume - 音量（范围：0.0 到 1.0，默认值：1.0）
      * @returns {Sound} 返回当前实例以支持链式调用
      */
-    setSoundVolume(volume?: number): Sound;
-    sound_volume: number | undefined;
+    setSoundVolume(volume?: number): this;
     /**
      * 设置声音音调。
      * @param {number} pitch - 音调（默认值：1.0）
      * @returns {Sound} 返回当前实例以支持链式调用
      */
-    setSoundPitch(pitch?: number): Sound;
-    sound_pitch: number | undefined;
+    setSoundPitch(pitch?: number): this;
     /**
      * 设置触发事件时播放的声音数组。
-     * @param {object[]} sounds - 声音对象数组
+     * @param {JsonUIBag[]} sounds - 声音对象数组
      * @returns {Sound} 返回当前实例以支持链式调用
      */
-    setSounds(sounds: object[]): Sound;
-    sounds: object[] | undefined;
+    setSounds(sounds: JsonUIBag[]): this;
     /**
      * 添加一个声音对象到声音数组。
-     * @param {object} sound - 声音对象
+     * @param {JsonUIBag} sound - 声音对象
      * @returns {Sound} 返回当前实例以支持链式调用
      */
-    addSound(sound: object): Sound;
+    addSound(sound: JsonUIBag): this;
 }
 
+/**
+ * Button
+    Property Name	Type	Default Value	Description
+    default_control	string		Name of the child control that will be displayed only in the default state
+    hover_control	string		Name of the child control that will be displayed only in the hover state
+    pressed_control	string		Name of the child control that will be displayed only in the pressed state
+    locked_control	string		Name of the child control that will be displayed only in the locked state
+ */
+
 declare class Button extends UIElement {
-    constructor(id: any, template: any);
     input: Input;
     sound: Sound;
     factory: Factory;
-    setDefaultControl(default_control: any): this;
-    setHoverControl(hover_control: any): this;
-    setPressedControl(pressed_control: any): this;
-    setLockedControl(locked_control: any): this;
-    setInput(input: any): this;
-    setSound(sound: any): this;
-    setLayout(layout: any): this;
+    constructor(id: string, template?: string);
+    setDefaultControl(default_control: string): this;
+    setHoverControl(hover_control: string): this;
+    setPressedControl(pressed_control: string): this;
+    setLockedControl(locked_control: string): this;
+    setInput(input: Input): this;
+    setSound(sound: Sound): this;
+    setLayout(layout: Layout): this;
+    protected serializableSources(): object[];
 }
 
 declare class CollectionPanel extends UIElement {
-    constructor(id: any, template: any);
     factory: Factory;
-    setCollectionName(collection_name: any): this;
-    setLayout(layout: any): this;
+    constructor(id: string, template?: string);
+    setCollectionName(collection_name: string): this;
+    setLayout(layout: Layout): this;
+    protected serializableSources(): object[];
 }
 
 /**
@@ -3373,62 +4586,66 @@ declare class CollectionPanel extends UIElement {
  * - precached_grid_item_count: int - 预缓存的网格项目数量
  */
 declare class GridProp {
+    [key: string]: unknown;
+    grid_dimensions: [number, number];
+    maximum_grid_items: number;
+    grid_dimension_binding: string;
+    grid_rescaling_type: 'vertical' | 'horizontal' | 'none';
+    grid_fill_direction: 'vertical' | 'horizontal' | 'none';
+    grid_item_template: string;
+    precached_grid_item_count: number;
     /**
      * 设置网格的列数和行数。
-     * @param {number[]} dimensions - 格式为 [columns, rows]
+     * @param {[number, number]} dimensions - 格式为 [columns, rows]
      * @returns {GridProp} 返回当前实例以支持链式调用
      */
-    setGridDimensions(dimensions: number[]): GridProp;
-    grid_dimensions: number[] | undefined;
+    setGridDimensions(dimensions: [number, number]): this;
     /**
      * 设置网格生成的最大项目数。
      * @param {number} maxItems - 最大项目数
      * @returns {GridProp} 返回当前实例以支持链式调用
      */
-    setMaximumGridItems(maxItems: number): GridProp;
-    maximum_grid_items: number | undefined;
+    setMaximumGridItems(maxItems: number): this;
     /**
      * 设置网格尺寸的绑定名称。
      * @param {string} binding - 绑定名称
      * @returns {GridProp} 返回当前实例以支持链式调用
      */
-    setGridDimensionBinding(binding: string): GridProp;
-    grid_dimension_binding: string | undefined;
+    setGridDimensionBinding(binding: string): this;
     /**
      * 设置网格重新缩放方向。
-     * @param {string} type - 可能值：vertical, horizontal, none（默认值：none）
+     * @param {'vertical' | 'horizontal' | 'none'} type - 可能值：vertical, horizontal, none（默认值：none）
      * @returns {GridProp} 返回当前实例以支持链式调用
      */
-    setGridRescalingType(type?: string): GridProp;
-    grid_rescaling_type: string | undefined;
+    setGridRescalingType(type?: 'vertical' | 'horizontal' | 'none'): this;
     /**
      * 设置网格填充方向。
-     * @param {string} direction - 可能值：vertical, horizontal, none（默认值：none）
+     * @param {'vertical' | 'horizontal' | 'none'} direction - 可能值：vertical, horizontal, none（默认值：none）
      * @returns {GridProp} 返回当前实例以支持链式调用
      */
-    setGridFillDirection(direction?: string): GridProp;
-    grid_fill_direction: string | undefined;
+    setGridFillDirection(direction?: 'vertical' | 'horizontal' | 'none'): this;
     /**
      * 设置处理集合的子元素名称。
      * @param {string} template - 元素名称（例如："common.container_item"）
      * @returns {GridProp} 返回当前实例以支持链式调用
      */
-    setGridItemTemplate(template: string): GridProp;
-    grid_item_template: string | undefined;
+    setGridItemTemplate(template: string): this;
     /**
      * 设置预缓存的网格项目数量。
      * @param {number} count - 预缓存数量
      * @returns {GridProp} 返回当前实例以支持链式调用
      */
-    setPrecachedGridItemCount(count: number): GridProp;
-    precached_grid_item_count: number | undefined;
+    setPrecachedGridItemCount(count: number): this;
 }
 
 declare class Grid extends CollectionPanel {
     gridNum: number;
     grid: GridProp;
-    setGridProp(grid_prop: any): this;
-    addGridItem(grid_position: any, content: any): this;
+    constructor(id: string, template?: string);
+    setGridProp(grid_prop: GridProp): this;
+    addGridItem(grid_position: Offset2, content: UIElement | JsonUIBag, name?: string, debugColor?: [number, number, number, number]): this;
+    protected serializableSources(): object[];
+    serialize(): SerializedElement;
 }
 
 /**
@@ -3451,282 +4668,221 @@ declare class Grid extends CollectionPanel {
  * - jump_to_bottom_on_update: boolean - 是否在更新时跳转到底部
  */
 declare class ScrollView {
+    [key: string]: unknown;
+    scrollbar_track_button: string;
+    scrollbar_touch_button: string;
+    scroll_speed: number;
+    gesture_control_enabled: boolean;
+    always_handle_scrolling: boolean;
+    touch_mode: boolean;
+    scrollbar_box: string;
+    scrollbar_track: string;
+    scroll_view_port: string;
+    scroll_content: string;
+    scroll_box_and_track_panel: string;
+    jump_to_bottom_on_update: boolean;
     /**
      * 设置滚动条轨道按钮的 ID。
      * @param {string} buttonId - 滚动条轨道按钮的 ID
      * @returns {ScrollView} 返回当前实例以支持链式调用
      */
-    setScrollbarTrackButton(buttonId: string): ScrollView;
-    scrollbar_track_button: string | undefined;
+    setScrollbarTrackButton(buttonId: string): this;
     /**
      * 设置滚动条触摸按钮的 ID。
      * @param {string} buttonId - 滚动条触摸按钮的 ID
      * @returns {ScrollView} 返回当前实例以支持链式调用
      */
-    setScrollbarTouchButton(buttonId: string): ScrollView;
-    scrollbar_touch_button: string | undefined;
+    setScrollbarTouchButton(buttonId: string): this;
     /**
      * 设置滚动速度。
      * @param {number} speed - 滚动速度
      * @returns {ScrollView} 返回当前实例以支持链式调用
      */
-    setScrollSpeed(speed: number): ScrollView;
-    scroll_speed: number | undefined;
+    setScrollSpeed(speed: number): this;
     /**
      * 设置是否启用手势控制。
      * @param {boolean} enabled - 是否启用手势控制（默认值：false）
      * @returns {ScrollView} 返回当前实例以支持链式调用
      */
-    setGestureControlEnabled(enabled?: boolean): ScrollView;
-    gesture_control_enabled: boolean | undefined;
+    setGestureControlEnabled(enabled?: boolean): this;
     /**
      * 设置是否始终处理滚动。
      * @param {boolean} alwaysHandle - 是否始终处理滚动（默认值：false）
      * @returns {ScrollView} 返回当前实例以支持链式调用
      */
-    setAlwaysHandleScrolling(alwaysHandle?: boolean): ScrollView;
-    always_handle_scrolling: boolean | undefined;
+    setAlwaysHandleScrolling(alwaysHandle?: boolean): this;
     /**
      * 设置是否启用触摸模式。
      * @param {boolean} touchMode - 是否启用触摸模式（默认值：false）
      * @returns {ScrollView} 返回当前实例以支持链式调用
      */
-    setTouchMode(touchMode?: boolean): ScrollView;
-    touch_mode: boolean | undefined;
+    setTouchMode(touchMode?: boolean): this;
     /**
      * 设置滚动条滑块子元素的名称。
      * @param {string} boxName - 滚动条滑块子元素的名称
      * @returns {ScrollView} 返回当前实例以支持链式调用
      */
-    setScrollbarBox(boxName: string): ScrollView;
-    scrollbar_box: string | undefined;
+    setScrollbarBox(boxName: string): this;
     /**
      * 设置滚动条轨道子元素的名称。
      * @param {string} trackName - 滚动条轨道子元素的名称
      * @returns {ScrollView} 返回当前实例以支持链式调用
      */
-    setScrollbarTrack(trackName: string): ScrollView;
-    scrollbar_track: string | undefined;
+    setScrollbarTrack(trackName: string): this;
     /**
      * 设置视口子元素的名称。
      * @param {string} viewPortName - 视口子元素的名称
      * @returns {ScrollView} 返回当前实例以支持链式调用
      */
-    setScrollViewPort(viewPortName: string): ScrollView;
-    scroll_view_port: string | undefined;
+    setScrollViewPort(viewPortName: string): this;
     /**
      * 设置内容根父元素的名称。
      * @param {string} contentName - 内容根父元素的名称
      * @returns {ScrollView} 返回当前实例以支持链式调用
      */
-    setScrollContent(contentName: string): ScrollView;
-    scroll_content: string | undefined;
+    setScrollContent(contentName: string): this;
     /**
      * 设置包含滚动条滑块和轨道的子元素名称。
      * @param {string} panelName - 包含滚动条滑块和轨道的子元素名称
      * @returns {ScrollView} 返回当前实例以支持链式调用
      */
-    setScrollBoxAndTrackPanel(panelName: string): ScrollView;
-    scroll_box_and_track_panel: string | undefined;
+    setScrollBoxAndTrackPanel(panelName: string): this;
     /**
      * 设置是否在更新时跳转到底部。
      * @param {boolean} jump - 是否在更新时跳转到底部（默认值：false）
      * @returns {ScrollView} 返回当前实例以支持链式调用
      */
-    setJumpToBottomOnUpdate(jump?: boolean): ScrollView;
-    jump_to_bottom_on_update: boolean | undefined;
+    setJumpToBottomOnUpdate(jump?: boolean): this;
 }
 
 declare class ScrollingPanel extends UIElement {
-    constructor(id: any, template: any);
     input: Input;
     scrollView: ScrollView;
     factory: Factory;
+    constructor(id: string, template?: string);
+    protected serializableSources(): object[];
 }
 
 declare class StackPanel extends Panel {
-    constructor(id: any, template: any);
-    type: string;
     orientation: string;
     stackNum: number;
-    addStack(size: any, content: any, debug?: boolean): this;
+    constructor(id: string, template?: string);
+    addStack(size: Size2 | string, content: UIElement | JsonUIBag, debug?: boolean): this;
     /**
      * Possible values:
-        vertical
-        horizontal
-     * @param {*} orientation
-     */
-    setOrientation(orientation: any): this;
-}
-
-declare class ChestUISystem {
-    static chest_screen: UISystem;
-    static registerContainerUI(new_container_title: any, ui_system_root_panel: any): void;
-}
-
-/**
- * 自定义容器 UI 系统类，用于创建和管理容器界面。
- * 支持动态添加网格项、设置标题、调整尺寸等功能。
- */
-declare class ContainerUISystem {
-    /**
-     * 构造函数，初始化容器 UI 系统。
-     * @param {string} identifier - 容器的唯一标识符。
-     * @param {string} path - 资源路径。
-     */
-    constructor(identifier: string, path: string);
-    system: UISystem;
-    title: string;
-    root_panel_size: number[];
-    gridDimension: number[];
-    output_grids: any[];
-    main_panel: Panel;
-    grids: Grid;
-    setInputGrid(output_arr: any): void;
-    /**
-     * 向网格中添加一个网格项。
-     * @param {number[]} grid_position - 网格项的位置 [行, 列] 用于定位实体的背包槽。
-     * @param {number[]} offset - 网格项的偏移量 [x, y]。
-     * @param {Object} [options] - 可选参数，用于配置网格项。
-     * @param {boolean} [options.enable=true] - 是否启用该网格项，默认为 true。
-     * @param {number[]} [options.size] - 网格项的大小 [宽度, 高度]。
-     * @param {UIElement[]} [options.background_images] - 网格项的背景图片控件。
-     * @returns {ContainerUISystem} 返回当前实例以支持链式调用。
-     */
-    addGridItem(grid_position: number[], offset: number[], options?: {
-        enable?: boolean | undefined;
-        size?: number[] | undefined;
-        background_images?: UIElement[] | undefined;
-    }): ContainerUISystem;
-    addInputGrid(grid_position: any, offset: any, options: any): void;
-    addOutputGrid(grid_position: any, offset: any, options: any): void;
-    /**
-     * 向主面板中添加一个 UI 元素。
-     * @param {Object} element - 要添加的 UI 元素。
-     * @returns {ContainerUISystem} 返回当前实例以支持链式调用。
-     */
-    addElementToMain(element: Object): ContainerUISystem;
-    /**
-     * 设置网格的维度（行和列）。
-     * @param {number[]} dimension - 网格的维度 [行数, 列数]。
-     * @returns {ContainerUISystem} 返回当前实例以支持链式调用。
-     */
-    setGridDimension(dimension: number[]): ContainerUISystem;
-    /**
-     * 设置容器的标题。
-     * @param {string} title - 容器的标题。
-     * @returns {ContainerUISystem} 返回当前实例以支持链式调用。
-     */
-    setTitle(title: string): ContainerUISystem;
-    /**
-     * 设置根面板的尺寸。
-     * @param {number[]} size - 根面板的尺寸 [宽度, 高度]。
-     * @returns {ContainerUISystem} 返回当前实例以支持链式调用。
-     */
-    setSize(size: number[]): ContainerUISystem;
-    setItemMatrix(n: any, matrix: any): void;
-    #private;
-}
-
-declare const ServerFormSystem: UISystem;
-declare class ServerFormButton extends UIElement {
-    /**
-     * 定义一个新的表单按钮
-     * @param {*} name
-     * @param {*} binding_button_name
-     */
-    constructor(name: any, binding_button_name: any);
-    /**
-     *
-     * @param {string} texture
-     * @returns
+       vertical
+       horizontal
+     * @param {string} orientation
      */
-    setDefaultTexture(texture: string): this;
-    setPressedTexture(texture: any): this;
-    setHoverTexture(texture: any): this;
-}
-declare const form_button_panel: Panel;
-declare class ServerUISystem {
-    static "__#private@#binding_map": Map<any, any>;
-    static "__#private@#binding_title_list": any[];
-    static addBindingTitle(title_name: any): void;
-    static getBindingTitleList(): any[];
-    static getBindingContentList(): any[];
-    static bindingTitlewithContent(title_name: any, content: any): void;
-    static "__#private@#updateServerFormSystem"(): void;
-}
-
-declare class Guidebook {
-    constructor(identifier: any, path: any);
-    system: UISystem;
-    addPageBinding(page_name: any, left_control_name: any, right_control_name: any): this;
-    addPage(page_name: any, left_control: any, right_control: any): this;
-    addElement(element: any): this;
-    #private;
-}
-
-declare class UISystemRegistry {
-    static "__#private@#ui_system_map": {};
-    static "__#private@#ui_def_list": any[];
-    static registerUISystem(ui_system: any): void;
-    static addOuterUIdefs(ui_defs: any): void;
+    setOrientation(orientation: string): this;
+    serialize(): SerializedElement;
 }
 
+type CustomButtonConfig = {
+    id: string;
+    position: "bottom_left" | "bottom_right" | "bottom_middle" | "top_left" | "top_right";
+    offset: [number, number];
+    size: [number | string, number | string];
+    defaultTexture: string;
+    hoverTexture: string;
+    pressedTexture: string;
+    bindingButtonName: string;
+};
+type ButtonTextures = {
+    prevDefault?: string;
+    prevHover?: string;
+    prevPressed?: string;
+    nextDefault?: string;
+    nextHover?: string;
+    nextPressed?: string;
+    homeDefault?: string;
+    homeHover?: string;
+    homePressed?: string;
+    closeDefault?: string;
+    closeHover?: string;
+    closePressed?: string;
+};
+type NeoGuidebookOptions = {
+    size?: [number, number];
+    background?: string;
+    debug?: boolean;
+    buttons?: {
+        prev?: {
+            visible?: boolean;
+        };
+        next?: {
+            visible?: boolean;
+        };
+        home?: {
+            visible?: boolean;
+        };
+        close?: {
+            visible?: boolean;
+        };
+    };
+    textures?: ButtonTextures;
+};
 declare class NeoGuidebook {
-    private identifer;
+    private identifier;
     private book_pages;
     private size;
     private background_image;
     private debug_mode;
     private system;
-    private root_panel_id;
-    private root_panel_name;
+    private content_panel_name;
+    private content_panel_id;
+    private buttons_panel_name;
+    private buttons_panel_id;
     private root_panel_elements;
-    /**
-     * @param {string} identifer - UI唯一标识符（格式 "命名空间:名称"）
-     * @param {string} path - UI路径 例如"ui/"
-     * @param {[number, number]} size - 面板尺寸 [宽, 高]
-     */
-    constructor(identifer: string, path: string, size?: [number, number]);
-    /**添加单页书面 */
+    private custom_buttons;
+    private button_visibility;
+    private textures;
+    private dirty;
+    constructor(identifier: string, path: string, size?: [number, number], options?: NeoGuidebookOptions);
+    getPageIds(): string[];
+    getPageCount(): number;
+    addCustomButton(config: CustomButtonConfig): this;
     addSinglePageStack(page_id: string, page_content: Panel): void;
-    /**添加双页书面 */
-    addDoublePageStack(page_id: string, left_page: Panel, right_page: Panel): void;
+    addDoublePageStack(page_id: string, left_page: Panel, right_page: Panel, ratio?: [string, string]): void;
+    private flush;
     private createPagesPanel;
     private initUI;
-    private updataUI;
-    /** 创建关闭按钮 */
+    private createNavButtons;
+    private createCustomButtons;
+    private updateUI;
+    private tex;
     private createCloseButton;
-    /** 创建翻页按钮（通用方法） */
     private createPageButton;
-    /**创建返回章节目录按键 */
     private createHomeButton;
-    /**创建书页 */
     private createBookPage;
-    /**创建调试数据内容文本 */
     private createDebugText;
-    /**
-     * 向系统注册一个元素
-     * @param {UIElement} element
-     */
     registerElement(element: UIElement): this;
-    /**
-     * 向根面板添加元素
-     */
     addRootElement(element: UIElement): this;
-    /**
-    * 向根面板添加多个元素
-    * @param {Array} elements
-    */
     addRootElements(elements: UIElement[]): this;
 }
 
+/**
+ * @deprecated 图标/纹理按钮请改用 FormButton（@common.button + 三态纹理 + 门控绑定）。
+ * 本类仅为兼容 NeoGuidebook 保留；后续随 guidebook 迁移一并移除。
+ */
+declare class SapdonTexturedButton extends UIElement {
+    constructor(id: string, bindingButtonName?: string);
+    setDefaultTexture(texture: string): this;
+    setHoverTexture(texture: string): this;
+    setPressedTexture(texture: string): this;
+    /** 设置锚点对齐 */
+    setAnchor(anchor: string, size?: [number | string, number | string]): this;
+}
+
 declare class EmptySpace extends Panel {
     constructor(id: string, size?: [string, string]);
 }
 declare class BookTitle extends Label {
     constructor(id: string, title: string, size?: [string, string]);
 }
+declare class BookText extends Label {
+    constructor(id: string, text: string, size?: [string, string]);
+}
 declare class BookTitleBar extends Panel {
     private size;
     constructor(id: string, text: string, size?: [string, string]);
@@ -3735,7 +4891,7 @@ declare class BookTitleBar extends Panel {
 declare class Divider extends StackPanel {
     constructor(id: string, size?: [string, string]);
 }
-declare class BookButton extends ServerFormButton {
+declare class BookButton extends SapdonTexturedButton {
     constructor(id: string, texture: string, size?: [string, string]);
 }
 declare class BookImage extends Image {
@@ -3751,7 +4907,7 @@ declare class BookRecipeGrid extends StackPanel {
     constructor(id: string, row: number, col: number, items: string[]);
 }
 declare class ChapterItem extends Panel {
-    constructor(index: number, chapterName: string, texture: string);
+    constructor(index: number, chapterName: string, texture: string, prefix?: string);
 }
 declare class NeoGuidebookPage {
     private panel;
@@ -3773,7 +4929,9 @@ declare class NeoGuidebookPage {
         chapter_name: string;
         chapter_texture: string;
     }>): this;
-    buildChapterList(): this;
+    buildChapterList(prefix?: string): this;
+    addControl(control: UIElement): this;
+    addStack(size: [string, string], control: UIElement, debug?: boolean): this;
     getPanel(): StackPanel;
     clear(): this;
 }
@@ -3797,6 +4955,257 @@ declare class HudStatePanel {
     getPanel(): Panel;
 }
 
+declare class ChestUISystem {
+    static chest_screen: UISystem;
+    static registerContainerUI(new_container_title: string, ui_system_root_panel: string): void;
+}
+
+type Any = any;
+/**
+ * 自定义容器 UI 系统类，用于创建和管理容器界面。
+ * 支持动态添加网格项、设置标题、调整尺寸等功能。
+ */
+declare class ContainerUISystem {
+    #private;
+    system: UISystem;
+    title: string;
+    root_panel_size: [number, number];
+    gridDimension: [number, number];
+    output_grids: number[][];
+    main_panel: Panel;
+    grids: Grid;
+    constructor(identifier: string, path: string);
+    setInputGrid(output_arr: number[][]): void;
+    /**
+     * 向网格中添加一个网格项。
+     * @param {number[]} grid_position - 网格项的位置 [行, 列] 用于定位实体的背包槽。
+     * @param {number[]} offset - 网格项的偏移量 [x, y]。
+     * @param {Object} [options] - 可选参数，用于配置网格项。
+     * @param {boolean} [options.enable=true] - 是否启用该网格项，默认为 true。
+     * @param {number[]} [options.size] - 网格项的大小 [宽度, 高度]。
+     * @param {UIElement[]} [options.background_images] - 网格项的背景图片控件。
+     * @returns {ContainerUISystem} 返回当前实例以支持链式调用。
+     */
+    addGridItem(grid_position: Offset2, offset: Offset2, options?: {
+        enable?: boolean;
+        size?: Any;
+        background_images?: Any;
+    }): this;
+    addInputGrid(grid_position: Offset2, offset: Offset2, options?: {
+        enable?: boolean;
+        size?: Any;
+        background_images?: Any;
+    }): void;
+    addOutputGrid(grid_position: Offset2, offset: Offset2, options?: {
+        enable?: boolean;
+        size?: Any;
+        background_images?: Any;
+    }): void;
+    /**
+     * 向主面板中添加一个 UI 元素。
+     * @param {Any} element - 要添加的 UI 元素。
+     * @returns {ContainerUISystem} 返回当前实例以支持链式调用。
+     */
+    addElementToMain(element: Any): this;
+    /**
+     * 设置网格的维度（行和列）。
+     * @param {number[]} dimension - 网格的维度 [行数, 列数]。
+     * @returns {ContainerUISystem} 返回当前实例以支持链式调用。
+     */
+    setGridDimension(dimension: number[]): this;
+    /**
+     * 设置容器的标题。
+     * @param {string} title - 容器的标题。
+     * @returns {ContainerUISystem} 返回当前实例以支持链式调用。
+     */
+    setTitle(title: string): this;
+    /**
+     * 设置根面板的尺寸。
+     * @param {number[]} size - 根面板的尺寸 [宽度, 高度]。
+     * @returns {ContainerUISystem} 返回当前实例以支持链式调用。
+     */
+    setSize(size: number[]): this;
+    setItemMatrix(n: number, matrix: number[][]): void;
+}
+
+/**
+ * sapdon_ui: 页面壳路由系统（生成 server_form.json）
+ *
+ * 采用 Bedrock Wiki「Modifying Server Forms — Action Form」官方路由：
+ *   main_screen_content ─(modification: insert_back controls)→ sapdon_form_factory
+ *     └─ factory { name: server_form_factory, control_ids.long_form } → @server_form.sapdon_long_form_panel
+ *          └─ (modifications insert_back) 所有注册页 Panel（$panel_id 前缀门控）
+ *             └─ content@$user_content_panel (下) + buttons@$user_buttons_panel (上)
+ *   vanilla long_form ─(modification: bindings)→ title 含 'sapdon_ui:' 时隐藏原生表单
+ *
+ * 关键收益：自定义页处于 main_screen_content 作用域 → #form_text / #title_text 均可解析。
+ */
+interface SapdonPageRegistration {
+    panelId: string;
+    contentPanel: UIElement | string;
+    buttonsPanel?: UIElement | string;
+    /** 页面控件名（默认 pageN） */
+    name?: string;
+}
+declare class SapdonServerUI {
+    static readonly MARKER = "sapdon_ui:";
+    static readonly NS = "server_form";
+    private static _system;
+    private static _factories;
+    private static _pageCount;
+    private static _ensureBuilt;
+    /** 页面根壳：在页面自己的 UISystem 里生成 <name> 元素（门控 + content/buttons 子控件 + 变量），供工厂 long_form 引用 */
+    static createPageRoot(reg: {
+        name: string;
+        panelId: string;
+        contentRef: string;
+        buttonsRef: string;
+    }): UIElement;
+    /** 注册一个自定义页面：向 main_screen_content 追加一个纯 gated factory（long_form → @<页ns>.<name>），门控在页面根 */
+    static registerPage(reg: SapdonPageRegistration): void;
+    static getSystem(): UISystem | null;
+}
+
+/**
+ * SapdonPanel：一个自定义页面 = 一个 UI 文件(text_ui_xxx.json)
+ * 由「内容面板 + 按键面板」两个元素组成。
+ */
+declare class SapdonPanel {
+    private system;
+    constructor(namespace: string);
+    /** 设置内容面板元素 */
+    setContent(content: UIElement): this;
+    /** 设置按键面板元素 */
+    setButtons(buttons: UIElement): this;
+    build(): UISystem;
+}
+
+/**
+ * FormButton：服务端表单按钮（纯样式）。
+ * 只管长什么样（三态纹理 / 尺寸 / 锚点 / 门控键），不含几何与绑定。
+ * 必须 addButton 进 FormButtonGrid 才被注入集合/门控绑定并定位生效。
+ */
+declare class FormButton extends Button {
+    constructor(id: string);
+    /** 三态纹理 default/hover/pressed */
+    setTexture(defaultTex: string, hoverTex: string, pressedTex: string): this;
+    /** 尺寸（原地改，保留锚点/offset） */
+    setSize(w: number | string, h: number | string): this;
+    /** 锚点对齐（原地改，导航贴角用） */
+    setAnchor(anchor: string): this;
+    /** 门控键：仅当运行时 emit 的 #form_button_text 等于该键时可见（绑定由 Grid 注入） */
+    setBinding(key: string): this;
+}
+
+/**
+ * FormButtonGrid：按键格盘（几何 + 激活）。
+ * 内部一个 Grid（collection: form_buttons），把面板按 dimensions 分格；
+ * addButton 时按 index 派生基准格 base 并注入 FormButton 的三组绑定。
+ */
+declare class FormButtonGrid {
+    private grid;
+    private cols;
+    private rows;
+    private index;
+    private debug;
+    private static readonly RED;
+    constructor(id: string, options: {
+        dimensions: [number, number];
+        size: [number | string, number | string];
+    });
+    /** 给每个格子描红调试框 */
+    enableDebug(): this;
+    /** 加一枚内容：index 决定基准格（off_col = index%c, off_row = index/c）；给 pos 则叠加。仅 FormButton 注入集合/门控绑定。 */
+    addButton(index: number, btn: FormButton | UIElement, pos?: [number, number]): this;
+    /** 注入 FormButton 的集合/门控绑定（离开 Grid 则无效） */
+    private injectBindings;
+    build(): UIElement;
+}
+
+/**
+ * SapdonGuideBook —— 帕秋莉式手册（分类索引 INDEX + 词条列表 CAT + 内容页 ENT + home/prev/next 导航）。
+ *
+ * 线协议（运行时发射）：
+ *   body = "INDEX"          → 显示分类索引网格（子按钮 = 各分类，setBinding 精确门控）
+ *   body = "CAT:<id>|p<N>"   → 分类页（p0 左简介/右 list，p1+ 左右 list）
+ *   body = "ENT:<id>:<gi>|p<N>" → 词条内容页（按 pageType 渲染、可分页）
+ *   title = "sapdon_ui:<name>"
+ *   button(...)             → 集合 form_buttons：分类按钮 or 导航，均 exact-match 门控
+ */
+type GuideBookPageType = 'text' | 'crafting' | 'spotlight' | 'image';
+interface GuideBookChapter {
+    name: string;
+    icon: string;
+    /** 词条正文（多行，ENT 页逐行渲染；text 类型按 5 行/半页分页） */
+    lines: string[];
+    /** 页类型（默认 text） */
+    pageType?: GuideBookPageType;
+    /** crafting：3×3 合成格（9 项，空位 ''）+ 输出图标 */
+    craft?: {
+        grid: string[];
+        output: string;
+    };
+    /** spotlight：大图标 + 描述 */
+    spotlight?: {
+        icon: string;
+        desc: string;
+    };
+    /** image：整页图 + 说明 */
+    image?: {
+        texture: string;
+        caption: string;
+    };
+}
+interface GuideBookCategory {
+    /** 英文 id（路由用，如 intro / routing / controls / undecided） */
+    id: string;
+    /** 中文标题（左页标题 / 索引卡名称） */
+    title: string;
+    /** 分类图标（索引卡） */
+    icon: string;
+    /** 简介正文（左页，多行，逐行渲染） */
+    introLines: string[];
+    /** 右页章节条目 */
+    chapters: GuideBookChapter[];
+}
+declare class SapdonGuideBook {
+    private system;
+    private namespace;
+    private name;
+    private size;
+    private background;
+    private debug;
+    private coverTitle;
+    private coverLines;
+    constructor(identifier: string, size?: [number, number], background?: string);
+    enableDebug(): this;
+    /** 自定义封面：标题（可含 \n）+ 简介行 */
+    setCover(title: string, lines: string[]): this;
+    /** 布局容器：<tag> 命中 #form_text（含 tag 即显示） */
+    private gateLayout;
+    private navButton;
+    private closeButton;
+    /** NeoGuidebook 书页纸面：页脊 + 页边模板（左/右半页） */
+    private bookPagePane;
+    /** 全幅纸页基底：横向 50/50 左右半页（crease+edge），layer 0 常显 */
+    private bookPageBase;
+    /** 给游离 FormButton 注入集合/门控绑定（非 FormButtonGrid 场景，如章节条目行） */
+    private wireButton;
+    /** 章节列表列（章节标题 + 分割线 + ≤8 行条目） */
+    private catListColumn;
+    /** 介绍列（标题 + 分割线 + 简介逐行）——仅 p0 左页 */
+    private catIntroColumn;
+    /**
+     * CAT 页（L2）：按词条数分页容器，门控 CAT:<id>|p<N>。
+     * p0：左=介绍，右=章节 list（≤8）；p1+：左、右都是章节 list（容量 8+8=16，先填左列再右列）。
+     */
+    private catPages;
+    /** ENT 词条内容页（L3）：按 pageType 分派布局；text 按 5 行/半页分页；门控 ENT:<id>:<gi>|p<N> */
+    private entPages;
+    build(categories: GuideBookCategory[]): this;
+    getSystem(): UISystem;
+}
+
 declare class ItemTextureManager {
     static item_texture_sets: Map<any, any>;
     static getItemTextureSet(): Map<any, any>;
@@ -3846,13 +5255,6 @@ interface ISerializer {
 declare function jsonEncoderReplacer(_: string, v: any): any;
 declare const defaultSerializer: ISerializer;
 declare function Serializable(serializer?: ISerializer): (_: any, ctx: DecoratorContext) => void;
-/**
- * 只能应用一个 Serializer
- *
- * 重复的 Serializer 会被覆盖
- * @param target
- * @param ctx
- */
 declare const Serializer: MethodDecorator;
 declare function serialize<R, T extends object>(inst: T): R;
 declare const jsonEncodeDecoder: EncodeDecoder<any, string>;
@@ -3881,5 +5283,5 @@ declare namespace registry {
     function submit(): void;
 }
 
-export { AddonAnimationController, AddonAnimationStateMachine, AddonAttachable, AddonAttachableDefinition, AddonAttachableDescription, AddonBiome, AddonBiomeDefinition, AddonBiomeDescription, AddonBlock, AddonBlockDefinition, AddonBlockDescription, AddonClientEntity, AddonClientEntityDefinition, AddonClientEntityDescription, AddonEntity, AddonEntityDefinition, AddonEntityDescription, AddonFeatureRule, AddonFeatureRuleDecription, AddonFeatureRuleDenifition, AddonItem, AddonItemDefinition, AddonItemDescription, AddonManifest, AddonManifestDependency, AddonManifestHeader, AddonManifestMetadata, AddonManifestModule, AddonMenuCategory, AddonOreFeature, AddonOreFeatureDefinition, AddonOreFeatureDescription, AddonRecipe, AddonRecipeFurnace, AddonRecipeFurnace_1_12, AddonRecipeFurnace_1_17, AddonRecipeShaped, AddonRecipeShaped_1_12, AddonRecipeShaped_1_17, AddonRecipeShaped_1_19, AddonRecipeShaped_1_20, AddonRecipeShapeless, AddonRecipeShapeless_1_12, AddonRecipeShapeless_1_17, AddonRenderController, AddonRenderControllerGroup, AddonSemanticVersion, Armor, Attachable, BasicBlock, BasicBundle, BasicEntity, BasicMovementBundle, Biome, BiomeAPI, BiomeComponent, BiomeFilter, Block, BlockAPI, BlockComponent, BookButton, BookCategoryGrid, BookImage, BookRecipeGrid, BookTitle, BookTitleBar, Boot, Button, ButtonMapping$1 as ButtonMapping, ChapterItem, ChestUISystem, Chestplate, ClientEntity, CollectionPanel, ContainerUISystem, Control, CoordinateDistribution, CropBlock, DataBinding, DataBindingObject, Divider, DummyEntity, EmptySpace, Entity, EntityAPI, EntityComponent, Factory, FeatureAPI, FeatureConditions, FeatureDistribution, FeatureRule, FlipbookItem, FlipbookTextures, FollowMobBehavior, FollowParentBehavior, Food, GeometryBlock, Grid, GridProp, Guidebook, Helmet, HudStatePanel, HudUISystem, Image, Input, Item, ItemAPI, ItemCategory, ItemComponent, ItemTextureManager, Label, Layout, Leggings, Modifications, NativeEntity, NativeEntityData, Navigation, NearestAttackableTargetBehavor, NeoGuidebook, NeoGuidebookPage, NonNullMap, OreBlock, OreFeature, Panel, PickupItemsBehavior, Projectile, RandomStrollBehavior, RecipeAPI, RecipeInputTags, RecipeTags, RecipeTypes, RotatableBlock, RotationTypes, ScrollView, ScrollingPanel, Serializable, Serializer, ServerFormButton, ServerFormSystem, ServerUISystem, Sound, Sprite, StackPanel, TemptBehavior, TerrainTextureManager, Text, TileBlock, UIElement, UISystem, UISystemRegistry, UiAPI, decode, defaultSerializer, encode, f64, form_button_panel, getMetadata, getOrCreateMetadata, isRawJSON, jsonEncodeDecoder, jsonEncoderReplacer, mixin, registerBlock, registerEntity, registry, serialize };
-export type { ConstructorOf, EncodeDecoder, FlipbookItemOptions, FloatLiteral, ISerializer, RawType };
+export { AddonAnimationController, AddonAnimationStateMachine, AddonAttachable, AddonAttachableDefinition, AddonAttachableDescription, AddonBiome, AddonBiomeDefinition, AddonBiomeDescription, AddonBlock, AddonBlockDefinition, AddonBlockDescription, AddonClientEntity, AddonClientEntityDefinition, AddonClientEntityDescription, AddonEntity, AddonEntityDefinition, AddonEntityDescription, AddonFeatureRule, AddonFeatureRuleDecription, AddonFeatureRuleDenifition, AddonItem, AddonItemDefinition, AddonItemDescription, AddonManifest, AddonManifestDependency, AddonManifestHeader, AddonManifestMetadata, AddonManifestModule, AddonMenuCategory, AddonOreFeature, AddonOreFeatureDefinition, AddonOreFeatureDescription, AddonRecipe, AddonRecipeFurnace, AddonRecipeFurnace_1_12, AddonRecipeFurnace_1_17, AddonRecipeShaped, AddonRecipeShaped_1_12, AddonRecipeShaped_1_17, AddonRecipeShaped_1_19, AddonRecipeShaped_1_20, AddonRecipeShapeless, AddonRecipeShapeless_1_12, AddonRecipeShapeless_1_17, AddonRenderController, AddonRenderControllerGroup, AddonSemanticVersion, Armor, ArmorType, Attachable, BasicBlock, BasicBundle, BasicEntity, BasicMovementBundle, Biome, BiomeAPI, BiomeComponent, BiomeFilter, Block, BlockAPI, BlockComponent, BlockCustomComponentBuilder, BookButton, BookCategoryGrid, BookImage, BookRecipeGrid, BookText, BookTitle, BookTitleBar, Button, ButtonMapping, ChapterItem, ChestUISystem, ClientEntity, CollectionPanel, ContainerUISystem, Control, CoordinateDistribution, CropBlock, DataBinding, DataBindingObject, Divider, DummyEntity, EmptySpace, Entity, EntityAPI, EntityComponent, Factory, FeatureAPI, FeatureConditions, FeatureDistribution, FeatureRule, FenceBlock, FlipbookItem, FlipbookTextureConfig, FlipbookTextures, FollowMobBehavior, FollowParentBehavior, Food, FormButton, FormButtonGrid, GeometryBlock, GlassBlock, GoHomeBehavior, Grid, GridProp, HeadBlock, HudProgressBar, HudStatePanel, HudUISystem, Image, Input, Item, ItemAPI, ItemCatalog, ItemCategory, ItemComponent, ItemTextureManager, Label, Layout, Modifications, MoveTowardsHomeRestrictionBehavior, NativeEntity, NativeEntityData, Navigation, NearestAttackableTargetBehavor, NeoGuidebook, NeoGuidebookPage, NonNullMap, OreBlock, OreFeature, Panel, PickupItemsBehavior, Projectile, RandomStrollBehavior, RecipeAPI, RecipeInputTags, RecipeTags, RecipeTypes, RotatableBlock, RotationTypes, SapdonGuideBook, SapdonPanel, SapdonServerUI, SapdonTexturedButton, ScrollView, ScrollingPanel, Serializable, Serializer, Sound, Sprite, StackPanel, StairBlock, TemptBehavior, TerrainTextureManager, Text, TextureVariationConfig, TileBlock, TintMethod, TrapdoorBlock, UIElement, UISystem, UISystemRegistry, UiAPI, decode, defaultSerializer, encode, f64, getMetadata, getOrCreateMetadata, isRawJSON, jsonEncodeDecoder, jsonEncoderReplacer, mixin, registerBlock, registerEntity, registry, serialize };
+export type { ArmorOptions, ArmorSpec, BeforeOnPlayerPlaceEvent, BlockCustomComponentHandlers, BlockDescriptor, BlockPlacerOptions, ConstructorOf, CooldownOptions, CreateModelItemOptions, DiggerOptions, DurabilitySensorOptions, DurabilityThreshold, EncodeDecoder, EntityPlacerOptions, FlipbookEntry, FlipbookItemOptions, FloatLiteral, FoodComponentOptions, FoodOptions, GuideBookCategory, GuideBookChapter, GuideBookPageType, ISerializer, IconTextures, ItemCatalogCategory, ItemCatalogGroupOptions, ItemComponentMap, ItemOptions, ItemRarity, KineticWeaponOptions, ModelBoneTransform, OnBlockStateChangeEvent, OnBreakEvent, OnEntityEvent, OnEntityFallOnEvent, OnPlaceEvent, OnPlayerBreakEvent, OnPlayerInteractEvent, OnRandomTickEvent, OnRedstoneUpdateEvent, OnStepOffEvent, OnStepOnEvent, OnTickEvent, PiercingWeaponOptions, Range, RawType, RecordOptions, RepairItem, SapdonPageRegistration, SerializedElement, ShooterAmmunition, ShooterOptions, StorageItemOptions, SwingSoundsOptions, TextureEntry, TextureVariation, ThrowableOptions, UseModifiersOptions };