@esengine/behavior-tree 1.0.0 → 1.0.2

package/dist/index.d.ts

@@ -0,0 +1,2012 @@
+import * as _esengine_ecs_framework from '@esengine/ecs-framework';
+import { Component, IService, Entity, EntitySystem, ServiceContainer } from '@esengine/ecs-framework';
+
+/**
+ * Behavior Tree Constants
+ * 行为树常量
+ */
+declare const BehaviorTreeAssetType: "behavior-tree";
+
+/**
+ * 任务执行状态
+ */
+declare enum TaskStatus {
+    /** 无效状态 - 节点未初始化或已被重置 */
+    Invalid = 0,
+    /** 成功 - 节点执行成功完成 */
+    Success = 1,
+    /** 失败 - 节点执行失败 */
+    Failure = 2,
+    /** 运行中 - 节点正在执行，需要在后续帧继续 */
+    Running = 3
+}
+/**
+ * 内置节点类型常量
+ */
+declare const NodeType: {
+    /** 根节点 - 行为树的起始节点 */
+    readonly Root: "root";
+    /** 复合节点 - 有多个子节点 */
+    readonly Composite: "composite";
+    /** 装饰器节点 - 有一个子节点 */
+    readonly Decorator: "decorator";
+    /** 动作节点 - 叶子节点 */
+    readonly Action: "action";
+    /** 条件节点 - 叶子节点 */
+    readonly Condition: "condition";
+};
+/**
+ * 节点类型（支持自定义扩展）
+ *
+ * 使用内置类型或自定义字符串
+ *
+ * @example
+ * ```typescript
+ * // 使用内置类型
+ * type: NodeType.Action
+ *
+ * // 使用自定义类型
+ * type: 'custom-behavior'
+ * ```
+ */
+type NodeType = typeof NodeType[keyof typeof NodeType] | string;
+/**
+ * 复合节点类型
+ */
+declare enum CompositeType {
+    /** 序列 - 按顺序执行，全部成功才成功 */
+    Sequence = "sequence",
+    /** 选择 - 按顺序执行，任一成功则成功 */
+    Selector = "selector",
+    /** 并行 - 同时执行所有子节点 */
+    Parallel = "parallel",
+    /** 并行选择 - 并行执行，任一成功则成功 */
+    ParallelSelector = "parallel-selector",
+    /** 随机序列 - 随机顺序执行序列 */
+    RandomSequence = "random-sequence",
+    /** 随机选择 - 随机顺序执行选择 */
+    RandomSelector = "random-selector"
+}
+/**
+ * 装饰器节点类型
+ */
+declare enum DecoratorType {
+    /** 反转 - 反转子节点结果 */
+    Inverter = "inverter",
+    /** 重复 - 重复执行子节点 */
+    Repeater = "repeater",
+    /** 直到成功 - 重复直到成功 */
+    UntilSuccess = "until-success",
+    /** 直到失败 - 重复直到失败 */
+    UntilFail = "until-fail",
+    /** 总是成功 - 无论子节点结果都返回成功 */
+    AlwaysSucceed = "always-succeed",
+    /** 总是失败 - 无论子节点结果都返回失败 */
+    AlwaysFail = "always-fail",
+    /** 条件装饰器 - 基于条件执行子节点 */
+    Conditional = "conditional",
+    /** 冷却 - 冷却时间内阻止执行 */
+    Cooldown = "cooldown",
+    /** 超时 - 超时则返回失败 */
+    Timeout = "timeout"
+}
+/**
+ * 中止类型
+ *
+ * 用于动态优先级和条件重新评估
+ */
+declare enum AbortType {
+    /** 无 - 不中止任何节点 */
+    None = "none",
+    /** 自身 - 条件变化时可以中止自身的执行 */
+    Self = "self",
+    /** 低优先级 - 条件满足时可以中止低优先级的兄弟节点 */
+    LowerPriority = "lower-priority",
+    /** 两者 - 可以中止自身和低优先级节点 */
+    Both = "both"
+}
+/**
+ * 黑板变量类型
+ */
+declare enum BlackboardValueType$1 {
+    String = "string",
+    Number = "number",
+    Boolean = "boolean",
+    Vector2 = "vector2",
+    Vector3 = "vector3",
+    Object = "object",
+    Array = "array"
+}
+/**
+ * 黑板变量定义
+ */
+interface BlackboardVariable {
+    name: string;
+    type: BlackboardValueType$1;
+    value: any;
+    readonly?: boolean;
+    description?: string;
+}
+
+/**
+ * 行为树节点定义（纯数据结构）
+ *
+ * 不依赖Entity，可以被多个实例共享
+ */
+interface BehaviorNodeData {
+    /** 节点唯一ID */
+    id: string;
+    /** 节点名称（用于调试） */
+    name: string;
+    /** 节点类型 */
+    nodeType: NodeType;
+    /** 节点实现类型（对应Component类名） */
+    implementationType: string;
+    /** 子节点ID列表 */
+    children?: string[];
+    /** 节点特定配置数据 */
+    config: Record<string, any>;
+    /** 属性到黑板变量的绑定映射 */
+    bindings?: Record<string, string>;
+    /** 中止类型（条件装饰器使用） */
+    abortType?: AbortType;
+}
+/**
+ * 行为树定义（可共享的Asset）
+ */
+interface BehaviorTreeData {
+    /** 树ID */
+    id: string;
+    /** 树名称 */
+    name: string;
+    /** 根节点ID */
+    rootNodeId: string;
+    /** 所有节点（扁平化存储） */
+    nodes: Map<string, BehaviorNodeData>;
+    /** 黑板变量定义 */
+    blackboardVariables?: Map<string, any>;
+}
+/**
+ * 节点运行时状态
+ *
+ * 每个BehaviorTreeRuntimeComponent实例独立维护
+ */
+interface NodeRuntimeState {
+    /** 当前执行状态 */
+    status: TaskStatus;
+    /** 当前执行的子节点索引（复合节点使用） */
+    currentChildIndex: number;
+    /** 执行顺序号（用于调试和可视化） */
+    executionOrder?: number;
+    /** 开始执行时间（某些节点需要） */
+    startTime?: number;
+    /** 上次执行时间（冷却节点使用） */
+    lastExecutionTime?: number;
+    /** 当前重复次数（重复节点使用） */
+    repeatCount?: number;
+    /** 缓存的结果（某些条件节点使用） */
+    cachedResult?: any;
+    /** 洗牌后的索引（随机节点使用） */
+    shuffledIndices?: number[];
+    /** 是否被中止 */
+    isAborted?: boolean;
+    /** 上次条件评估结果（条件装饰器使用） */
+    lastConditionResult?: boolean;
+    /** 正在观察的黑板键（条件装饰器使用） */
+    observedKeys?: string[];
+}
+/**
+ * 创建默认的运行时状态
+ */
+declare function createDefaultRuntimeState(): NodeRuntimeState;
+
+/**
+ * @zh 资产管理器接口（可选依赖）
+ * @en Asset manager interface (optional dependency)
+ *
+ * @zh 行为树系统的可选资产管理器接口。
+ * 当与 ESEngine 的 asset-system 集成时，传入 IAssetManager 实例。
+ * 不使用 ESEngine 时，可以直接使用 BehaviorTreeAssetManager.loadFromEditorJSON()。
+ *
+ * @en Optional asset manager interface for behavior tree system.
+ * When integrating with ESEngine's asset-system, pass an IAssetManager instance.
+ * When not using ESEngine, use BehaviorTreeAssetManager.loadFromEditorJSON() directly.
+ */
+
+/**
+ * @zh 行为树资产内容
+ * @en Behavior tree asset content
+ */
+interface IBehaviorTreeAssetContent {
+    /** @zh 行为树数据 @en Behavior tree data */
+    data: BehaviorTreeData;
+    /** @zh 文件路径 @en File path */
+    path: string;
+}
+/**
+ * @zh 简化的资产管理器接口
+ * @en Simplified asset manager interface
+ *
+ * @zh 这是行为树系统需要的最小资产管理器接口。
+ * ESEngine 的 IAssetManager 实现此接口。
+ * 其他引擎可以提供自己的实现。
+ *
+ * @en This is the minimal asset manager interface required by the behavior tree system.
+ * ESEngine's IAssetManager implements this interface.
+ * Other engines can provide their own implementation.
+ */
+interface IBTAssetManager {
+    /**
+     * @zh 通过 GUID 加载资产
+     * @en Load asset by GUID
+     */
+    loadAsset(guid: string): Promise<{
+        asset: IBehaviorTreeAssetContent | null;
+    } | null>;
+    /**
+     * @zh 通过 GUID 获取已加载的资产
+     * @en Get loaded asset by GUID
+     */
+    getAsset<T = IBehaviorTreeAssetContent>(guid: string): T | null;
+}
+
+/**
+ * 黑板变化监听器
+ */
+type BlackboardChangeListener = (key: string, newValue: any, oldValue: any) => void;
+/**
+ * 行为树运行时组件
+ *
+ * 挂载到游戏Entity上，引用共享的BehaviorTreeData
+ * 维护该Entity独立的运行时状态
+ */
+declare class BehaviorTreeRuntimeComponent extends Component {
+    /**
+     * 引用的行为树资产ID（可序列化）
+     */
+    treeAssetId: string;
+    /**
+     * 是否自动启动
+     */
+    autoStart: boolean;
+    /**
+     * 是否正在运行
+     */
+    isRunning: boolean;
+    /**
+     * 节点运行时状态（每个节点独立）
+     * 不序列化，每次加载时重新初始化
+     */
+    private nodeStates;
+    /**
+     * 黑板数据（该Entity独立的数据）
+     * 不序列化，通过初始化设置
+     */
+    private blackboard;
+    /**
+     * 黑板观察者列表
+     */
+    private blackboardObservers;
+    /**
+     * 当前激活的节点ID列表（用于调试）
+     */
+    activeNodeIds: Set<string>;
+    /**
+     * 标记是否需要在下一个tick重置状态
+     */
+    needsReset: boolean;
+    /**
+     * 需要中止的节点ID列表
+     */
+    nodesToAbort: Set<string>;
+    /**
+     * 执行顺序计数器（用于调试和可视化）
+     */
+    executionOrderCounter: number;
+    /**
+     * 获取节点运行时状态
+     */
+    getNodeState(nodeId: string): NodeRuntimeState;
+    /**
+     * 重置节点状态
+     */
+    resetNodeState(nodeId: string): void;
+    /**
+     * 重置所有节点状态
+     */
+    resetAllStates(): void;
+    /**
+     * 获取黑板值
+     */
+    getBlackboardValue<T = any>(key: string): T | undefined;
+    /**
+     * 设置黑板值
+     */
+    setBlackboardValue(key: string, value: any): void;
+    /**
+     * 检查黑板是否有某个键
+     */
+    hasBlackboardKey(key: string): boolean;
+    /**
+     * 初始化黑板（从树定义的默认值）
+     */
+    initializeBlackboard(variables?: Map<string, any>): void;
+    /**
+     * 清空黑板
+     */
+    clearBlackboard(): void;
+    /**
+     * 启动行为树
+     */
+    start(): void;
+    /**
+     * 停止行为树
+     */
+    stop(): void;
+    /**
+     * 暂停行为树
+     */
+    pause(): void;
+    /**
+     * 恢复行为树
+     */
+    resume(): void;
+    /**
+     * 注册黑板观察者
+     */
+    observeBlackboard(nodeId: string, keys: string[], callback: BlackboardChangeListener): void;
+    /**
+     * 取消注册黑板观察者
+     */
+    unobserveBlackboard(nodeId: string): void;
+    /**
+     * 通知黑板变化
+     */
+    private notifyBlackboardChange;
+    /**
+     * 请求中止节点
+     */
+    requestAbort(nodeId: string): void;
+    /**
+     * 检查节点是否需要中止
+     */
+    shouldAbort(nodeId: string): boolean;
+    /**
+     * 清除中止请求
+     */
+    clearAbortRequest(nodeId: string): void;
+    /**
+     * 清除所有中止请求
+     */
+    clearAllAbortRequests(): void;
+}
+
+/**
+ * 行为树资产管理器（服务）
+ *
+ * 管理所有共享的BehaviorTreeData
+ * 多个实例可以引用同一份数据
+ *
+ * 使用方式：
+ * ```typescript
+ * // 注册服务
+ * Core.services.registerSingleton(BehaviorTreeAssetManager);
+ *
+ * // 使用服务
+ * const assetManager = Core.services.resolve(BehaviorTreeAssetManager);
+ * ```
+ */
+declare class BehaviorTreeAssetManager implements IService {
+    /**
+     * 已加载的行为树资产
+     */
+    private assets;
+    /**
+     * 加载行为树资产
+     */
+    loadAsset(asset: BehaviorTreeData): void;
+    /**
+     * 从编辑器 JSON 格式加载行为树资产
+     *
+     * @param json 编辑器导出的 JSON 字符串
+     * @returns 加载的行为树数据
+     *
+     * @example
+     * ```typescript
+     * const assetManager = Core.services.resolve(BehaviorTreeAssetManager);
+     * const jsonContent = await readFile('path/to/tree.btree');
+     * const treeData = assetManager.loadFromEditorJSON(jsonContent);
+     * ```
+     */
+    loadFromEditorJSON(json: string): BehaviorTreeData;
+    /**
+     * 批量加载多个行为树资产（从编辑器JSON）
+     *
+     * @param jsonDataList JSON字符串列表
+     * @returns 成功加载的资产数量
+     */
+    loadMultipleFromEditorJSON(jsonDataList: string[]): number;
+    /**
+     * 获取行为树资产
+     */
+    getAsset(assetId: string): BehaviorTreeData | undefined;
+    /**
+     * 检查资产是否存在
+     */
+    hasAsset(assetId: string): boolean;
+    /**
+     * 卸载行为树资产
+     */
+    unloadAsset(assetId: string): boolean;
+    /**
+     * 清空所有资产
+     */
+    clearAll(): void;
+    /**
+     * 获取已加载资产数量
+     */
+    getAssetCount(): number;
+    /**
+     * 获取所有资产ID
+     */
+    getAllAssetIds(): string[];
+    /**
+     * 释放资源（实现IService接口）
+     */
+    dispose(): void;
+}
+
+/**
+ * 节点执行上下文
+ *
+ * 包含执行节点所需的所有信息
+ */
+interface NodeExecutionContext {
+    /** 游戏Entity（行为树宿主） */
+    readonly entity: Entity;
+    /** 节点数据 */
+    readonly nodeData: BehaviorNodeData;
+    /** 节点运行时状态 */
+    readonly state: NodeRuntimeState;
+    /** 运行时组件（访问黑板等） */
+    readonly runtime: BehaviorTreeRuntimeComponent;
+    /** 行为树数据（访问子节点等） */
+    readonly treeData: BehaviorTreeData;
+    /** 当前帧增量时间 */
+    readonly deltaTime: number;
+    /** 总时间 */
+    readonly totalTime: number;
+    /** 执行子节点 */
+    executeChild(childId: string): TaskStatus;
+}
+/**
+ * 节点执行器接口
+ *
+ * 所有节点类型都需要实现对应的执行器
+ * 执行器是无状态的，状态存储在NodeRuntimeState中
+ */
+interface INodeExecutor {
+    /**
+     * 执行节点逻辑
+     *
+     * @param context 执行上下文
+     * @returns 执行结果状态
+     */
+    execute(context: NodeExecutionContext): TaskStatus;
+    /**
+     * 重置节点状态（可选）
+     *
+     * 当节点完成或被中断时调用
+     */
+    reset?(context: NodeExecutionContext): void;
+}
+/**
+ * 绑定辅助工具
+ *
+ * 处理配置属性的黑板绑定
+ */
+declare class BindingHelper {
+    /**
+     * 获取配置值（考虑黑板绑定）
+     *
+     * @param context 执行上下文
+     * @param configKey 配置键名
+     * @param defaultValue 默认值
+     * @returns 解析后的值
+     */
+    static getValue<T = any>(context: NodeExecutionContext, configKey: string, defaultValue?: T): T;
+    /**
+     * 检查配置是否绑定到黑板变量
+     */
+    static hasBinding(context: NodeExecutionContext, configKey: string): boolean;
+    /**
+     * 获取绑定的黑板变量名
+     */
+    static getBindingKey(context: NodeExecutionContext, configKey: string): string | undefined;
+}
+/**
+ * 节点执行器注册表
+ *
+ * 管理所有节点类型的执行器
+ */
+declare class NodeExecutorRegistry {
+    private executors;
+    /**
+     * 注册执行器
+     *
+     * @param implementationType 节点实现类型（对应BehaviorNodeData.implementationType）
+     * @param executor 执行器实例
+     */
+    register(implementationType: string, executor: INodeExecutor): void;
+    /**
+     * 获取执行器
+     */
+    get(implementationType: string): INodeExecutor | undefined;
+    /**
+     * 检查是否有执行器
+     */
+    has(implementationType: string): boolean;
+    /**
+     * 注销执行器
+     */
+    unregister(implementationType: string): boolean;
+    /**
+     * 清空所有执行器
+     */
+    clear(): void;
+}
+
+/**
+ * 根节点执行器
+ *
+ * 行为树的入口节点，执行其唯一的子节点
+ */
+declare class RootExecutor implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+    reset(_context: NodeExecutionContext): void;
+}
+
+/**
+ * 序列节点执行器
+ *
+ * 按顺序执行子节点，全部成功才成功，任一失败则失败
+ */
+declare class SequenceExecutor implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+    reset(context: NodeExecutionContext): void;
+}
+
+/**
+ * 选择器节点执行器
+ *
+ * 按顺序执行子节点，任一成功则成功，全部失败才失败
+ */
+declare class SelectorExecutor implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+    reset(context: NodeExecutionContext): void;
+}
+
+/**
+ * 并行节点执行器
+ *
+ * 同时执行所有子节点
+ */
+declare class ParallelExecutor implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+    private stopAllChildren;
+    reset(context: NodeExecutionContext): void;
+}
+
+/**
+ * 并行选择器执行器
+ *
+ * 并行执行子节点，任一成功则成功
+ */
+declare class ParallelSelectorExecutor implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+    private stopAllChildren;
+    reset(context: NodeExecutionContext): void;
+}
+
+/**
+ * 随机序列执行器
+ *
+ * 随机顺序执行子节点序列，全部成功才成功
+ */
+declare class RandomSequenceExecutor implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+    private shuffleIndices;
+    reset(context: NodeExecutionContext): void;
+}
+
+/**
+ * 随机选择器执行器
+ *
+ * 随机顺序执行子节点，任一成功则成功
+ */
+declare class RandomSelectorExecutor implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+    private shuffleIndices;
+    reset(context: NodeExecutionContext): void;
+}
+
+/**
+ * 反转装饰器执行器
+ *
+ * 反转子节点的执行结果
+ */
+declare class InverterExecutor implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+    reset(context: NodeExecutionContext): void;
+}
+
+/**
+ * 重复装饰器执行器
+ *
+ * 重复执行子节点指定次数
+ */
+declare class RepeaterExecutor implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+    reset(context: NodeExecutionContext): void;
+}
+
+/**
+ * 总是成功装饰器执行器
+ *
+ * 无论子节点结果如何都返回成功
+ */
+declare class AlwaysSucceedExecutor implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+    reset(context: NodeExecutionContext): void;
+}
+
+/**
+ * 总是失败装饰器执行器
+ *
+ * 无论子节点结果如何都返回失败
+ */
+declare class AlwaysFailExecutor implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+    reset(context: NodeExecutionContext): void;
+}
+
+/**
+ * 直到成功装饰器执行器
+ *
+ * 重复执行子节点直到成功
+ */
+declare class UntilSuccessExecutor implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+    reset(context: NodeExecutionContext): void;
+}
+
+/**
+ * 直到失败装饰器执行器
+ *
+ * 重复执行子节点直到失败
+ */
+declare class UntilFailExecutor implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+    reset(context: NodeExecutionContext): void;
+}
+
+/**
+ * 条件装饰器执行器
+ *
+ * 根据条件决定是否执行子节点
+ * 支持动态优先级和中止机制
+ */
+declare class ConditionalExecutor implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+    private evaluateCondition;
+    /**
+     * 设置黑板观察者
+     */
+    private setupObserver;
+    /**
+     * 处理条件变为true
+     */
+    private handleConditionBecameTrue;
+    /**
+     * 处理条件变为false
+     */
+    private handleConditionBecameFalse;
+    /**
+     * 请求中止低优先级节点
+     */
+    private requestAbortLowerPriority;
+    reset(context: NodeExecutionContext): void;
+}
+
+/**
+ * 冷却装饰器执行器
+ *
+ * 子节点执行成功后进入冷却时间
+ */
+declare class CooldownExecutor implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+    reset(context: NodeExecutionContext): void;
+}
+
+/**
+ * 超时装饰器执行器
+ *
+ * 限制子节点的执行时间
+ */
+declare class TimeoutExecutor implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+    reset(context: NodeExecutionContext): void;
+}
+
+/**
+ * Service执行接口
+ */
+interface IServiceExecutor {
+    /**
+     * Service开始执行
+     */
+    onServiceStart?(context: NodeExecutionContext): void;
+    /**
+     * Service每帧更新
+     */
+    onServiceTick(context: NodeExecutionContext): void;
+    /**
+     * Service结束执行
+     */
+    onServiceEnd?(context: NodeExecutionContext): void;
+}
+/**
+ * Service注册表
+ */
+declare class ServiceRegistry {
+    private static services;
+    static register(name: string, service: IServiceExecutor): void;
+    static get(name: string): IServiceExecutor | undefined;
+    static has(name: string): boolean;
+    static unregister(name: string): boolean;
+}
+/**
+ * Service装饰器执行器
+ *
+ * 在子节点执行期间持续运行后台逻辑
+ */
+declare class ServiceDecorator implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+    reset(context: NodeExecutionContext): void;
+}
+
+/**
+ * 等待动作执行器
+ *
+ * 等待指定时间后返回成功
+ */
+declare class WaitAction implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+    reset(context: NodeExecutionContext): void;
+}
+
+/**
+ * 日志动作执行器
+ *
+ * 输出日志信息
+ */
+declare class LogAction implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+    private replaceBlackboardVariables;
+    private log;
+}
+
+/**
+ * 设置黑板值动作执行器
+ *
+ * 设置黑板中的变量值
+ */
+declare class SetBlackboardValue implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+}
+
+/**
+ * 修改黑板值动作执行器
+ *
+ * 对黑板中的数值进行运算
+ */
+declare class ModifyBlackboardValue implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+}
+
+/**
+ * 执行动作执行器
+ *
+ * 执行自定义动作逻辑
+ */
+declare class ExecuteAction implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+}
+
+/**
+ * SubTree执行器
+ *
+ * 引用并执行其他行为树，实现模块化和复用
+ */
+declare class SubTreeExecutor implements INodeExecutor {
+    private assetManager;
+    private getAssetManager;
+    execute(context: NodeExecutionContext): TaskStatus;
+    private executeSubTreeNode;
+    reset(context: NodeExecutionContext): void;
+}
+
+/**
+ * 黑板比较条件执行器
+ *
+ * 比较黑板中的值
+ */
+declare class BlackboardCompare implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+    private compare;
+}
+
+/**
+ * 黑板存在检查条件执行器
+ *
+ * 检查黑板中是否存在指定的键
+ */
+declare class BlackboardExists implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+}
+
+/**
+ * 随机概率条件执行器
+ *
+ * 根据概率返回成功或失败
+ */
+declare class RandomProbability implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+}
+
+/**
+ * 执行条件执行器
+ *
+ * 执行自定义条件逻辑
+ */
+declare class ExecuteCondition implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus;
+}
+
+/**
+ * 行为树执行系统
+ *
+ * 统一处理所有行为树的执行
+ */
+declare class BehaviorTreeExecutionSystem extends EntitySystem {
+    private btAssetManager;
+    private executorRegistry;
+    private _services;
+    /** 引用外部资产管理器（可选，由外部模块设置） */
+    private _assetManager;
+    /** 已警告过的缺失资产，避免重复警告 */
+    private _warnedMissingAssets;
+    constructor(services?: ServiceContainer);
+    /**
+     * @zh 设置外部资产管理器引用（可选）
+     * @en Set external asset manager reference (optional)
+     *
+     * @zh 当与 ESEngine 集成时，由 BehaviorTreeRuntimeModule 调用。
+     * 不使用 ESEngine 时，可以不调用此方法，
+     * 直接使用 BehaviorTreeAssetManager.loadFromEditorJSON() 加载资产。
+     *
+     * @en Called by BehaviorTreeRuntimeModule when integrating with ESEngine.
+     * When not using ESEngine, you can skip this and use
+     * BehaviorTreeAssetManager.loadFromEditorJSON() to load assets directly.
+     */
+    setAssetManager(assetManager: IBTAssetManager | null): void;
+    /**
+     * 启动所有 autoStart 的行为树（用于预览模式）
+     * Start all autoStart behavior trees (for preview mode)
+     *
+     * 由于编辑器模式下系统默认禁用，实体添加时 onAdded 不会处理自动启动。
+     * 预览开始时需要手动调用此方法来启动所有需要自动启动的行为树。
+     */
+    startAllAutoStartTrees(): void;
+    /**
+     * 当实体添加到系统时，处理自动启动
+     * Handle auto-start when entity is added to system
+     */
+    protected onAdded(entity: Entity): void;
+    /**
+     * 确保行为树资产已加载
+     * Ensure behavior tree asset is loaded
+     */
+    private ensureAssetLoaded;
+    private getBTAssetManager;
+    /**
+     * 获取行为树数据
+     * Get behavior tree data from AssetManager or BehaviorTreeAssetManager
+     *
+     * 优先从 AssetManager 获取（新方式），如果没有再从 BehaviorTreeAssetManager 获取（兼容旧方式）
+     */
+    private getTreeData;
+    /**
+     * 注册所有执行器（包括内置和插件提供的）
+     */
+    private registerBuiltInExecutors;
+    /**
+     * 获取执行器注册表
+     */
+    getExecutorRegistry(): NodeExecutorRegistry;
+    protected process(entities: readonly Entity[]): void;
+    /**
+     * 执行整个行为树
+     */
+    private executeTree;
+    /**
+     * 执行单个节点
+     */
+    private executeNode;
+    /**
+     * 创建执行上下文
+     */
+    private createContext;
+    /**
+     * 执行子节点列表
+     */
+    executeChildren(context: NodeExecutionContext, childIndices?: number[]): TaskStatus[];
+}
+
+/**
+ * 配置参数定义
+ */
+interface ConfigFieldDefinition {
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    default?: any;
+    description?: string;
+    min?: number;
+    max?: number;
+    options?: string[];
+    supportBinding?: boolean;
+    allowMultipleConnections?: boolean;
+}
+/**
+ * 子节点约束配置
+ */
+interface ChildrenConstraints {
+    min?: number;
+    max?: number;
+    required?: boolean;
+}
+/**
+ * 节点元数据
+ */
+interface NodeMetadata {
+    implementationType: string;
+    nodeType: NodeType;
+    displayName: string;
+    description?: string;
+    category?: string;
+    configSchema?: Record<string, ConfigFieldDefinition>;
+    childrenConstraints?: ChildrenConstraints;
+}
+/**
+ * 节点元数据注册表
+ */
+declare class NodeMetadataRegistry {
+    private static metadataMap;
+    private static executorClassMap;
+    private static executorConstructors;
+    static register(target: Function, metadata: NodeMetadata): void;
+    static getMetadata(implementationType: string): NodeMetadata | undefined;
+    static getAllMetadata(): NodeMetadata[];
+    static getByCategory(category: string): NodeMetadata[];
+    static getByNodeType(nodeType: NodeType): NodeMetadata[];
+    static getImplementationType(executorClass: Function): string | undefined;
+    static getExecutorConstructor(implementationType: string): (new () => any) | undefined;
+    static getAllExecutorConstructors(): Map<string, new () => any>;
+}
+/**
+ * 节点执行器元数据装饰器
+ */
+declare function NodeExecutorMetadata(metadata: NodeMetadata): (target: Function) => void;
+
+/**
+ * 行为树启动辅助类
+ *
+ * 提供便捷方法来启动、停止行为树
+ */
+declare class BehaviorTreeStarter {
+    /**
+     * 启动行为树
+     *
+     * @param entity 游戏实体
+     * @param treeData 行为树数据
+     * @param autoStart 是否自动开始执行
+     */
+    static start(entity: Entity, treeData: BehaviorTreeData, autoStart?: boolean): void;
+    /**
+     * 停止行为树
+     *
+     * @param entity 游戏实体
+     */
+    static stop(entity: Entity): void;
+    /**
+     * 暂停行为树
+     *
+     * @param entity 游戏实体
+     */
+    static pause(entity: Entity): void;
+    /**
+     * 恢复行为树
+     *
+     * @param entity 游戏实体
+     */
+    static resume(entity: Entity): void;
+    /**
+     * 重启行为树
+     *
+     * @param entity 游戏实体
+     */
+    static restart(entity: Entity): void;
+}
+
+/**
+ * 行为树构建器
+ *
+ * 提供流式API构建行为树数据结构
+ */
+declare class BehaviorTreeBuilder {
+    private treeData;
+    private nodeStack;
+    private nodeIdCounter;
+    private constructor();
+    /**
+     * 创建构建器
+     */
+    static create(treeName?: string): BehaviorTreeBuilder;
+    /**
+     * 定义黑板变量
+     */
+    defineBlackboardVariable(key: string, initialValue: any): BehaviorTreeBuilder;
+    /**
+     * 添加序列节点
+     */
+    sequence(name?: string): BehaviorTreeBuilder;
+    /**
+     * 添加选择器节点
+     */
+    selector(name?: string): BehaviorTreeBuilder;
+    /**
+     * 添加并行节点
+     */
+    parallel(name?: string, config?: {
+        successPolicy?: string;
+        failurePolicy?: string;
+    }): BehaviorTreeBuilder;
+    /**
+     * 添加并行选择器节点
+     */
+    parallelSelector(name?: string, config?: {
+        failurePolicy?: string;
+    }): BehaviorTreeBuilder;
+    /**
+     * 添加随机序列节点
+     */
+    randomSequence(name?: string): BehaviorTreeBuilder;
+    /**
+     * 添加随机选择器节点
+     */
+    randomSelector(name?: string): BehaviorTreeBuilder;
+    /**
+     * 添加反转装饰器
+     */
+    inverter(name?: string): BehaviorTreeBuilder;
+    /**
+     * 添加重复装饰器
+     */
+    repeater(repeatCount: number, name?: string): BehaviorTreeBuilder;
+    /**
+     * 添加总是成功装饰器
+     */
+    alwaysSucceed(name?: string): BehaviorTreeBuilder;
+    /**
+     * 添加总是失败装饰器
+     */
+    alwaysFail(name?: string): BehaviorTreeBuilder;
+    /**
+     * 添加直到成功装饰器
+     */
+    untilSuccess(name?: string): BehaviorTreeBuilder;
+    /**
+     * 添加直到失败装饰器
+     */
+    untilFail(name?: string): BehaviorTreeBuilder;
+    /**
+     * 添加条件装饰器
+     */
+    conditional(blackboardKey: string, expectedValue: any, operator?: string, name?: string): BehaviorTreeBuilder;
+    /**
+     * 添加冷却装饰器
+     */
+    cooldown(cooldownTime: number, name?: string): BehaviorTreeBuilder;
+    /**
+     * 添加超时装饰器
+     */
+    timeout(timeout: number, name?: string): BehaviorTreeBuilder;
+    /**
+     * 添加等待动作
+     */
+    wait(duration: number, name?: string): BehaviorTreeBuilder;
+    /**
+     * 添加日志动作
+     */
+    log(message: string, name?: string): BehaviorTreeBuilder;
+    /**
+     * 添加设置黑板值动作
+     */
+    setBlackboardValue(key: string, value: any, name?: string): BehaviorTreeBuilder;
+    /**
+     * 添加修改黑板值动作
+     */
+    modifyBlackboardValue(key: string, operation: string, value: number, name?: string): BehaviorTreeBuilder;
+    /**
+     * 添加执行动作
+     */
+    executeAction(actionName: string, name?: string): BehaviorTreeBuilder;
+    /**
+     * 添加黑板比较条件
+     */
+    blackboardCompare(key: string, compareValue: any, operator?: string, name?: string): BehaviorTreeBuilder;
+    /**
+     * 添加黑板存在检查条件
+     */
+    blackboardExists(key: string, name?: string): BehaviorTreeBuilder;
+    /**
+     * 添加随机概率条件
+     */
+    randomProbability(probability: number, name?: string): BehaviorTreeBuilder;
+    /**
+     * 添加执行条件
+     */
+    executeCondition(conditionName: string, name?: string): BehaviorTreeBuilder;
+    /**
+     * 结束当前节点，返回父节点
+     */
+    end(): BehaviorTreeBuilder;
+    /**
+     * 构建行为树数据
+     */
+    build(): BehaviorTreeData;
+    private addCompositeNode;
+    private addDecoratorNode;
+    private addActionNode;
+    private addConditionNode;
+    private generateNodeId;
+}
+
+/**
+ * 节点数据JSON格式
+ */
+interface NodeDataJSON {
+    nodeType: string;
+    compositeType?: string;
+    decoratorType?: string;
+    actionType?: string;
+    conditionType?: string;
+    [key: string]: any;
+}
+/**
+ * 行为树节点属性类型常量
+ * Behavior tree node property type constants
+ */
+declare const NodePropertyType: {
+    /** 字符串 */
+    readonly String: "string";
+    /** 数值 */
+    readonly Number: "number";
+    /** 布尔值 */
+    readonly Boolean: "boolean";
+    /** 选择框 */
+    readonly Select: "select";
+    /** 黑板变量引用 */
+    readonly Blackboard: "blackboard";
+    /** 代码编辑器 */
+    readonly Code: "code";
+    /** 变量引用 */
+    readonly Variable: "variable";
+    /** 资产引用 */
+    readonly Asset: "asset";
+};
+/**
+ * 节点属性类型（支持自定义扩展）
+ * Node property type (supports custom extensions)
+ *
+ * @example
+ * ```typescript
+ * // 使用内置类型
+ * type: NodePropertyType.String
+ *
+ * // 使用自定义类型
+ * type: 'color-picker'
+ * type: 'curve-editor'
+ * ```
+ */
+type NodePropertyType = (typeof NodePropertyType)[keyof typeof NodePropertyType] | string;
+/**
+ * 属性定义（用于编辑器）
+ */
+interface PropertyDefinition {
+    name: string;
+    type: NodePropertyType;
+    label: string;
+    description?: string;
+    defaultValue?: any;
+    options?: Array<{
+        label: string;
+        value: any;
+    }>;
+    min?: number;
+    max?: number;
+    step?: number;
+    required?: boolean;
+    /**
+     * 字段编辑器配置
+     *
+     * 指定使用哪个字段编辑器以及相关选项
+     *
+     * @example
+     * ```typescript
+     * fieldEditor: {
+     *   type: 'asset',
+     *   options: { fileExtension: '.btree' }
+     * }
+     * ```
+     */
+    fieldEditor?: {
+        type: string;
+        options?: Record<string, any>;
+    };
+    /**
+     * 自定义渲染配置
+     *
+     * 用于指定编辑器如何渲染此属性
+     *
+     * @example
+     * ```typescript
+     * renderConfig: {
+     *   component: 'ColorPicker',  // 渲染器组件名称
+     *   props: {                   // 传递给组件的属性
+     *     showAlpha: true,
+     *     presets: ['#FF0000', '#00FF00']
+     *   }
+     * }
+     * ```
+     */
+    renderConfig?: {
+        /** 渲染器组件名称或路径 */
+        component?: string;
+        /** 传递给渲染器的属性配置 */
+        props?: Record<string, any>;
+        /** 渲染器的样式类名 */
+        className?: string;
+        /** 渲染器的内联样式 */
+        style?: Record<string, any>;
+        /** 其他自定义配置 */
+        [key: string]: any;
+    };
+    /**
+     * 验证规则
+     *
+     * 用于在编辑器中验证输入
+     *
+     * @example
+     * ```typescript
+     * validation: {
+     *   pattern: /^\d+$/,
+     *   message: '只能输入数字',
+     *   validator: (value) => value > 0
+     * }
+     * ```
+     */
+    validation?: {
+        /** 正则表达式验证 */
+        pattern?: RegExp | string;
+        /** 验证失败的提示信息 */
+        message?: string;
+        /** 自定义验证函数 */
+        validator?: string;
+        /** 最小长度（字符串） */
+        minLength?: number;
+        /** 最大长度（字符串） */
+        maxLength?: number;
+    };
+    /**
+     * 是否允许多个连接
+     * 默认 false，只允许一个黑板变量连接
+     */
+    allowMultipleConnections?: boolean;
+}
+/**
+ * 节点模板（用于编辑器）
+ */
+interface NodeTemplate {
+    type: NodeType;
+    displayName: string;
+    category: string;
+    icon?: string;
+    description: string;
+    color?: string;
+    className?: string;
+    componentClass?: Function;
+    requiresChildren?: boolean;
+    minChildren?: number;
+    maxChildren?: number;
+    defaultConfig: Partial<NodeDataJSON>;
+    properties: PropertyDefinition[];
+}
+/**
+ * 节点模板库
+ */
+declare class NodeTemplates {
+    /**
+     * 获取所有节点模板
+     */
+    static getAllTemplates(): NodeTemplate[];
+    /**
+     * 根据类型和子类型获取模板
+     */
+    static getTemplate(type: NodeType, subType: string): NodeTemplate | undefined;
+    /**
+     * 将NodeMetadata转换为NodeTemplate
+     */
+    private static convertMetadataToTemplate;
+    /**
+     * 获取节点类型的默认约束
+     */
+    private static getDefaultConstraintsByNodeType;
+    /**
+     * 将ConfigSchema转换为PropertyDefinition数组
+     */
+    private static convertConfigSchemaToProperties;
+    /**
+     * 映射字段类型到属性类型
+     */
+    private static mapFieldTypeToPropertyType;
+    /**
+     * NodeType转字符串
+     */
+    private static nodeTypeToString;
+    /**
+     * 根据NodeType获取默认分类
+     */
+    private static getCategoryByNodeType;
+    /**
+     * 根据节点类型获取默认图标和颜色
+     */
+    private static getIconAndColorByType;
+}
+
+/**
+ * 行为树资产元数据
+ */
+interface AssetMetadata {
+    name: string;
+    description?: string;
+    version: string;
+    createdAt?: string;
+    modifiedAt?: string;
+}
+/**
+ * 黑板变量定义
+ */
+interface BlackboardVariableDefinition {
+    name: string;
+    type: BlackboardValueType$1;
+    defaultValue: any;
+    readonly?: boolean;
+    description?: string;
+}
+/**
+ * 行为树节点配置数据
+ */
+interface BehaviorNodeConfigData {
+    className?: string;
+    [key: string]: any;
+}
+/**
+ * 行为树节点数据（运行时格式）
+ */
+interface BehaviorTreeNodeData {
+    id: string;
+    name: string;
+    nodeType: NodeType;
+    data: BehaviorNodeConfigData;
+    children: string[];
+}
+/**
+ * 属性绑定定义
+ */
+interface PropertyBinding {
+    nodeId: string;
+    propertyName: string;
+    variableName: string;
+}
+/**
+ * 行为树资产（运行时格式）
+ *
+ * 这是用于游戏运行时的优化格式，不包含编辑器UI信息
+ */
+interface BehaviorTreeAsset {
+    /**
+     * 资产格式版本
+     */
+    version: string;
+    /**
+     * 元数据
+     */
+    metadata: AssetMetadata;
+    /**
+     * 根节点ID
+     */
+    rootNodeId: string;
+    /**
+     * 所有节点数据（扁平化存储，通过children建立层级）
+     */
+    nodes: BehaviorTreeNodeData[];
+    /**
+     * 黑板变量定义
+     */
+    blackboard: BlackboardVariableDefinition[];
+    /**
+     * 属性绑定
+     */
+    propertyBindings?: PropertyBinding[];
+}
+/**
+ * 资产验证结果
+ */
+interface AssetValidationResult {
+    valid: boolean;
+    errors?: string[];
+    warnings?: string[];
+}
+/**
+ * 资产验证器
+ */
+declare class BehaviorTreeAssetValidator {
+    /**
+     * 验证资产数据的完整性和正确性
+     */
+    static validate(asset: BehaviorTreeAsset): AssetValidationResult;
+    /**
+     * 获取资产统计信息
+     */
+    static getStats(asset: BehaviorTreeAsset): {
+        nodeCount: number;
+        actionCount: number;
+        conditionCount: number;
+        compositeCount: number;
+        decoratorCount: number;
+        blackboardVariableCount: number;
+        propertyBindingCount: number;
+        maxDepth: number;
+    };
+}
+
+/**
+ * 编辑器节点格式
+ */
+interface EditorNodeTemplate {
+    displayName: string;
+    category: string;
+    type: NodeType;
+    className?: string;
+    [key: string]: any;
+}
+interface EditorNodeData {
+    nodeType?: string;
+    className?: string;
+    variableName?: string;
+    name?: string;
+    [key: string]: any;
+}
+interface EditorNode$1 {
+    id: string;
+    template: EditorNodeTemplate;
+    data: EditorNodeData;
+    position: {
+        x: number;
+        y: number;
+    };
+    children: string[];
+}
+/**
+ * 编辑器连接格式
+ */
+interface EditorConnection$1 {
+    from: string;
+    to: string;
+    fromProperty?: string;
+    toProperty?: string;
+    connectionType: 'node' | 'property';
+}
+/**
+ * 编辑器格式
+ */
+interface EditorFormat {
+    version?: string;
+    metadata?: {
+        name: string;
+        description?: string;
+        createdAt?: string;
+        modifiedAt?: string;
+    };
+    nodes: EditorNode$1[];
+    connections: EditorConnection$1[];
+    blackboard: Record<string, any>;
+    canvasState?: {
+        offset: {
+            x: number;
+            y: number;
+        };
+        scale: number;
+    };
+}
+/**
+ * 编辑器格式转换器
+ *
+ * 将编辑器格式转换为运行时资产格式
+ */
+declare class EditorFormatConverter {
+    /**
+     * 转换编辑器格式为资产格式
+     *
+     * @param editorData 编辑器数据
+     * @param metadata 可选的元数据覆盖
+     * @returns 行为树资产
+     */
+    static toAsset(editorData: EditorFormat, metadata?: Partial<AssetMetadata>): BehaviorTreeAsset;
+    /**
+     * 查找根节点
+     */
+    private static findRootNode;
+    /**
+     * 转换节点列表
+     */
+    private static convertNodes;
+    /**
+     * 转换单个节点
+     */
+    private static convertNode;
+    /**
+     * 转换黑板变量
+     */
+    private static convertBlackboard;
+    /**
+     * 推断黑板变量类型
+     */
+    private static inferBlackboardType;
+    /**
+     * 转换属性绑定
+     */
+    private static convertPropertyBindings;
+    /**
+     * 从资产格式转换回编辑器格式（用于加载）
+     *
+     * @param asset 行为树资产
+     * @returns 编辑器格式数据
+     */
+    static fromAsset(asset: BehaviorTreeAsset): EditorFormat;
+    /**
+     * 从资产格式转换节点
+     */
+    private static convertNodesFromAsset;
+    /**
+     * 推断节点分类
+     */
+    private static inferCategory;
+    /**
+     * 将属性绑定转换为连接
+     */
+    private static convertPropertyBindingsToConnections;
+    /**
+     * 根据children关系构建节点连接
+     */
+    private static buildNodeConnections;
+}
+
+/**
+ * 行为树序列化格式
+ * Behavior tree serialization format
+ */
+type BehaviorTreeSerializationFormat = 'json' | 'binary';
+/**
+ * 序列化选项
+ */
+interface SerializationOptions {
+    /**
+     * 序列化格式
+     */
+    format: BehaviorTreeSerializationFormat;
+    /**
+     * 是否美化JSON输出（仅format='json'时有效）
+     */
+    pretty?: boolean;
+    /**
+     * 是否在序列化前验证资产
+     */
+    validate?: boolean;
+}
+/**
+ * 反序列化选项
+ */
+interface DeserializationOptions {
+    /**
+     * 是否在反序列化后验证资产
+     */
+    validate?: boolean;
+    /**
+     * 是否严格模式（验证失败抛出异常）
+     */
+    strict?: boolean;
+}
+/**
+ * 行为树资产序列化器
+ *
+ * 支持JSON和二进制两种格式
+ */
+declare class BehaviorTreeAssetSerializer {
+    /**
+     * 序列化资产
+     *
+     * @param asset 行为树资产
+     * @param options 序列化选项
+     * @returns 序列化后的数据（字符串或Uint8Array）
+     *
+     * @example
+     * ```typescript
+     * // JSON格式
+     * const jsonData = BehaviorTreeAssetSerializer.serialize(asset, { format: 'json', pretty: true });
+     *
+     * // 二进制格式
+     * const binaryData = BehaviorTreeAssetSerializer.serialize(asset, { format: 'binary' });
+     * ```
+     */
+    static serialize(asset: BehaviorTreeAsset, options?: SerializationOptions): string | Uint8Array;
+    /**
+     * 序列化为JSON格式
+     */
+    private static serializeToJSON;
+    /**
+     * 序列化为二进制格式
+     */
+    private static serializeToBinary;
+    /**
+     * 反序列化资产
+     *
+     * @param data 序列化的数据（字符串或Uint8Array）
+     * @param options 反序列化选项
+     * @returns 行为树资产
+     *
+     * @example
+     * ```typescript
+     * // 从JSON加载
+     * const asset = BehaviorTreeAssetSerializer.deserialize(jsonString);
+     *
+     * // 从二进制加载
+     * const asset = BehaviorTreeAssetSerializer.deserialize(binaryData);
+     * ```
+     */
+    static deserialize(data: string | Uint8Array, options?: DeserializationOptions): BehaviorTreeAsset;
+    /**
+     * 从JSON反序列化
+     */
+    private static deserializeFromJSON;
+    /**
+     * 从二进制反序列化
+     */
+    private static deserializeFromBinary;
+    /**
+     * 检测数据格式
+     *
+     * @param data 序列化的数据
+     * @returns 格式类型
+     */
+    static detectFormat(data: string | Uint8Array): BehaviorTreeSerializationFormat;
+    /**
+     * 获取序列化数据的信息（不完全反序列化）
+     *
+     * @param data 序列化的数据
+     * @returns 资产元信息
+     */
+    static getInfo(data: string | Uint8Array): {
+        format: BehaviorTreeSerializationFormat;
+        name: string;
+        version: string;
+        nodeCount: number;
+        blackboardVariableCount: number;
+        size: number;
+    } | null;
+    /**
+     * 转换格式
+     *
+     * @param data 源数据
+     * @param targetFormat 目标格式
+     * @param pretty 是否美化JSON（仅当目标格式为json时有效）
+     * @returns 转换后的数据
+     *
+     * @example
+     * ```typescript
+     * // JSON转二进制
+     * const binary = BehaviorTreeAssetSerializer.convert(jsonString, 'binary');
+     *
+     * // 二进制转JSON
+     * const json = BehaviorTreeAssetSerializer.convert(binaryData, 'json', true);
+     * ```
+     */
+    static convert(data: string | Uint8Array, targetFormat: BehaviorTreeSerializationFormat, pretty?: boolean): string | Uint8Array;
+    /**
+     * 比较两个资产数据的大小
+     *
+     * @param jsonData JSON格式数据
+     * @param binaryData 二进制格式数据
+     * @returns 压缩率（百分比）
+     */
+    static compareSize(jsonData: string, binaryData: Uint8Array): {
+        jsonSize: number;
+        binarySize: number;
+        compressionRatio: number;
+        savedBytes: number;
+    };
+}
+
+/**
+ * 编辑器节点数据接口
+ */
+interface EditorNode {
+    id: string;
+    template: {
+        type: string;
+        className: string;
+        displayName?: string;
+    };
+    data: Record<string, any>;
+    children?: string[];
+}
+/**
+ * 编辑器连接数据接口
+ */
+interface EditorConnection {
+    from: string;
+    to: string;
+    connectionType: 'node' | 'property';
+    fromProperty?: string;
+    toProperty?: string;
+}
+/**
+ * 编辑器行为树数据接口
+ */
+interface EditorBehaviorTreeData {
+    version?: string;
+    metadata?: {
+        name: string;
+        description?: string;
+        createdAt?: string;
+        modifiedAt?: string;
+    };
+    nodes: EditorNode[];
+    connections?: EditorConnection[];
+    blackboard?: Record<string, any>;
+}
+/**
+ * 编辑器格式到运行时格式的转换器
+ *
+ * 负责将编辑器的 JSON 格式（包含UI信息）转换为运行时的 BehaviorTreeData 格式
+ */
+declare class EditorToBehaviorTreeDataConverter {
+    /**
+     * 将编辑器 JSON 字符串转换为运行时 BehaviorTreeData
+     */
+    static fromEditorJSON(json: string): BehaviorTreeData;
+    /**
+     * 将编辑器数据对象转换为运行时 BehaviorTreeData
+     */
+    static convert(editorData: EditorBehaviorTreeData): BehaviorTreeData;
+    /**
+     * 从连接数据构建属性绑定映射
+     * 处理 connectionType === 'property' 的连接，将黑板变量节点连接到目标节点的属性
+     */
+    private static buildPropertyBindingsMap;
+    /**
+     * 转换单个节点
+     * @param editorNode 编辑器节点数据
+     * @param propertyBindings 从连接中提取的属性绑定（可选）
+     */
+    private static convertNode;
+    /**
+     * 检查是否为不可执行的节点（如黑板变量节点）
+     * 这些节点只在编辑器中使用，不参与运行时执行
+     */
+    private static isNonExecutableNode;
+    /**
+     * 从节点数据中提取实现类型
+     *
+     * 优先级：
+     * 1. template.className（标准方式）
+     * 2. data 中的类型字段（compositeType, actionType 等）
+     * 3. 特殊节点类型的默认值（如 Root）
+     */
+    private static extractImplementationType;
+    /**
+     * 获取节点类型的默认实现
+     * 当无法确定具体实现类型时使用
+     */
+    private static getDefaultImplementationType;
+    /**
+     * 映射节点类型
+     */
+    private static mapNodeType;
+    /**
+     * 提取节点配置（过滤掉内部字段和绑定字段）
+     */
+    private static extractConfig;
+    /**
+     * 提取黑板变量绑定
+     */
+    private static extractBindings;
+    /**
+     * 判断是否为黑板绑定
+     */
+    private static isBinding;
+    /**
+     * 提取黑板绑定的键名
+     */
+    private static extractBindingKey;
+    /**
+     * 提取中止类型（条件装饰器使用）
+     */
+    private static extractAbortType;
+    /**
+     * 生成行为树ID
+     */
+    private static generateTreeId;
+    /**
+     * 将运行时格式转换回编辑器格式（用于双向转换）
+     */
+    static toEditorJSON(treeData: BehaviorTreeData): string;
+    /**
+     * 将运行时 BehaviorTreeData 转换为编辑器格式
+     */
+    static convertToEditor(treeData: BehaviorTreeData): EditorBehaviorTreeData;
+    /**
+     * 将运行时节点转换为编辑器节点
+     */
+    private static convertNodeToEditor;
+}
+
+/**
+ * 全局黑板配置
+ */
+interface GlobalBlackboardConfig {
+    version: string;
+    variables: BlackboardVariable[];
+}
+/**
+ * 全局黑板服务
+ *
+ * 提供所有行为树共享的全局变量存储
+ *
+ * 使用方式：
+ * ```typescript
+ * // 注册服务（在 BehaviorTreePlugin.install 中自动完成）
+ * core.services.registerSingleton(GlobalBlackboardService);
+ *
+ * // 获取服务
+ * const blackboard = core.services.resolve(GlobalBlackboardService);
+ * ```
+ */
+declare class GlobalBlackboardService implements IService {
+    private variables;
+    dispose(): void;
+    /**
+     * 定义全局变量
+     */
+    defineVariable(name: string, type: BlackboardValueType$1, initialValue: any, options?: {
+        readonly?: boolean;
+        description?: string;
+    }): void;
+    /**
+     * 获取全局变量值
+     */
+    getValue<T = any>(name: string): T | undefined;
+    /**
+     * 设置全局变量值
+     */
+    setValue(name: string, value: any, force?: boolean): boolean;
+    /**
+     * 检查全局变量是否存在
+     */
+    hasVariable(name: string): boolean;
+    /**
+     * 删除全局变量
+     */
+    removeVariable(name: string): boolean;
+    /**
+     * 获取所有变量名
+     */
+    getVariableNames(): string[];
+    /**
+     * 获取所有变量
+     */
+    getAllVariables(): BlackboardVariable[];
+    /**
+     * 清空所有全局变量
+     */
+    clear(): void;
+    /**
+     * 批量设置变量
+     */
+    setVariables(values: Record<string, any>): void;
+    /**
+     * 批量获取变量
+     */
+    getVariables(names: string[]): Record<string, any>;
+    /**
+     * 导出配置
+     */
+    exportConfig(): GlobalBlackboardConfig;
+    /**
+     * 导入配置
+     */
+    importConfig(config: GlobalBlackboardConfig): void;
+    /**
+     * 序列化为 JSON
+     */
+    toJSON(): string;
+    /**
+     * 从 JSON 反序列化
+     */
+    static fromJSON(json: string): GlobalBlackboardConfig;
+}
+
+declare enum BlackboardValueType {
+    String = "string",
+    Number = "number",
+    Boolean = "boolean",
+    Vector2 = "vector2",
+    Vector3 = "vector3",
+    Vector4 = "vector4",
+    Quaternion = "quaternion",
+    Color = "color",
+    GameObject = "gameObject",
+    Transform = "transform",
+    Component = "component",
+    AssetReference = "assetReference",
+    Array = "array",
+    Map = "map",
+    Enum = "enum",
+    Struct = "struct",
+    Function = "function",
+    EntityId = "entityId",
+    NodePath = "nodePath",
+    ResourcePath = "resourcePath",
+    AnimationState = "animationState",
+    AudioClip = "audioClip",
+    Material = "material",
+    Texture = "texture"
+}
+interface BlackboardTypeDefinition {
+    type: BlackboardValueType;
+    displayName: string;
+    category: 'basic' | 'math' | 'reference' | 'collection' | 'advanced' | 'game';
+    defaultValue: any;
+    editorComponent?: string;
+    validator?: (value: any) => boolean;
+    converter?: (value: any) => any;
+}
+declare const BlackboardTypes: Record<BlackboardValueType, BlackboardTypeDefinition>;
+
+/**
+ * 行为树执行系统令牌
+ * Behavior tree execution system token
+ */
+declare const BehaviorTreeSystemToken: _esengine_ecs_framework.ServiceToken<BehaviorTreeExecutionSystem>;
+
+export { AbortType, AlwaysFailExecutor, AlwaysSucceedExecutor, type AssetMetadata, type AssetValidationResult, type BehaviorNodeConfigData, type BehaviorNodeData, type BehaviorTreeAsset, BehaviorTreeAssetManager, BehaviorTreeAssetSerializer, BehaviorTreeAssetType, BehaviorTreeAssetValidator, BehaviorTreeBuilder, type BehaviorTreeData, BehaviorTreeExecutionSystem, type BehaviorTreeNodeData, BehaviorTreeRuntimeComponent, type BehaviorTreeSerializationFormat, BehaviorTreeStarter, BehaviorTreeSystemToken, BindingHelper, BlackboardCompare, BlackboardExists, type BlackboardTypeDefinition, BlackboardTypes, BlackboardValueType$1 as BlackboardValueType, type BlackboardVariable, type BlackboardVariableDefinition, CompositeType, ConditionalExecutor, type ConfigFieldDefinition, CooldownExecutor, DecoratorType, type DeserializationOptions, type EditorConnection$1 as EditorConnection, type EditorFormat, EditorFormatConverter, type EditorNode$1 as EditorNode, type EditorNodeData, type EditorNodeTemplate, EditorToBehaviorTreeDataConverter, ExecuteAction, ExecuteCondition, type GlobalBlackboardConfig, GlobalBlackboardService, type IBTAssetManager, type IBehaviorTreeAssetContent, type INodeExecutor, type IServiceExecutor, InverterExecutor, LogAction, ModifyBlackboardValue, type NodeDataJSON, type NodeExecutionContext, NodeExecutorMetadata, NodeExecutorRegistry, type NodeMetadata, NodeMetadataRegistry, NodePropertyType, type NodeRuntimeState, type NodeTemplate, NodeTemplates, NodeType, ParallelExecutor, ParallelSelectorExecutor, type PropertyBinding, type PropertyDefinition, RandomProbability, RandomSelectorExecutor, RandomSequenceExecutor, RepeaterExecutor, RootExecutor, SelectorExecutor, SequenceExecutor, type SerializationOptions, ServiceDecorator, ServiceRegistry, SetBlackboardValue, SubTreeExecutor, TaskStatus, TimeoutExecutor, UntilFailExecutor, UntilSuccessExecutor, WaitAction, createDefaultRuntimeState };