@esengine/blueprint 4.1.0 → 4.3.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Entity, IScene } from '@esengine/ecs-framework';
+import { Entity, IScene, Component, EntitySystem } from '@esengine/ecs-framework';
 
 /**
  * Blueprint Pin Types
@@ -218,10 +218,10 @@ interface BlueprintAsset {
     connections: BlueprintConnection[];
 }
 /**
- * Creates an empty blueprint asset
- * 创建空的蓝图资产
+ * Creates an empty blueprint asset with default Event Begin Play node
+ * 创建带有默认 Event Begin Play 节点的空蓝图资产
  */
-declare function createEmptyBlueprint(name: string): BlueprintAsset;
+declare function createEmptyBlueprint(name: string, includeBeginPlay?: boolean): BlueprintAsset;
 /**
  * Validates a blueprint asset structure
  * 验证蓝图资产结构
@@ -285,6 +285,8 @@ declare class ExecutionContext {
     private _localVariables;
     /** Global variables (shared) (全局变量，共享) */
     private static _globalVariables;
+    /** Component class registry (组件类注册表) */
+    private static _componentRegistry;
     /** Node output cache for current execution (当前执行的节点输出缓存) */
     private _outputCache;
     /** Connection lookup by target (按目标的连接查找) */
@@ -353,6 +355,29 @@ declare class ExecutionContext {
      * 清除全局变量（用于场景重置）
      */
     static clearGlobalVariables(): void;
+    /**
+     * Get a component class by name
+     * 通过名称获取组件类
+     *
+     * @zh 首先检查 @BlueprintExpose 装饰的组件，然后检查手动注册的组件
+     * @en First checks @BlueprintExpose decorated components, then manually registered ones
+     */
+    getComponentClass(typeName: string): (new () => Component) | undefined;
+    /**
+     * Register a component class for dynamic creation
+     * 注册组件类以支持动态创建
+     */
+    static registerComponentClass(typeName: string, componentClass: new () => Component): void;
+    /**
+     * Unregister a component class
+     * 取消注册组件类
+     */
+    static unregisterComponentClass(typeName: string): void;
+    /**
+     * Get all registered component classes
+     * 获取所有已注册的组件类
+     */
+    static getRegisteredComponentClasses(): Map<string, new () => Component>;
 }
 
 /**
@@ -552,101 +577,126 @@ declare class BlueprintVM {
 }
 
 /**
- * Blueprint Component - Attaches a blueprint to an entity
- * 蓝图组件 - 将蓝图附加到实体
+ * @zh 蓝图组件 - 将蓝图附加到实体
+ * @en Blueprint Component - Attaches a blueprint to an entity
  */
 
 /**
- * Component interface for ECS integration
- * 用于 ECS 集成的组件接口
+ * @zh 蓝图组件，用于将可视化脚本附加到 ECS 实体
+ * @en Blueprint component for attaching visual scripts to ECS entities
+ *
+ * @example
+ * ```typescript
+ * const entity = scene.createEntity('Player');
+ * const blueprint = new BlueprintComponent();
+ * blueprint.blueprintAsset = await loadBlueprintAsset('player.bp');
+ * blueprint.autoStart = true;
+ * entity.addComponent(blueprint);
+ * ```
  */
-interface IBlueprintComponent {
-    /** Entity ID this component belongs to (此组件所属的实体ID) */
-    entityId: number | null;
-    /** Blueprint asset reference (蓝图资产引用) */
+declare class BlueprintComponent extends Component {
+    /**
+     * @zh 蓝图资产引用
+     * @en Blueprint asset reference
+     */
     blueprintAsset: BlueprintAsset | null;
-    /** Blueprint asset path for serialization (用于序列化的蓝图资产路径) */
+    /**
+     * @zh 用于序列化的蓝图资产路径
+     * @en Blueprint asset path for serialization
+     */
     blueprintPath: string;
-    /** Auto-start execution when entity is created (实体创建时自动开始执行) */
+    /**
+     * @zh 实体创建时自动开始执行
+     * @en Auto-start execution when entity is created
+     */
     autoStart: boolean;
-    /** Enable debug mode for VM (启用 VM 调试模式) */
+    /**
+     * @zh 启用 VM 调试模式
+     * @en Enable debug mode for VM
+     */
     debug: boolean;
-    /** Runtime VM instance (运行时 VM 实例) */
+    /**
+     * @zh 运行时 VM 实例
+     * @en Runtime VM instance
+     */
     vm: BlueprintVM | null;
-    /** Whether the blueprint has started (蓝图是否已启动) */
+    /**
+     * @zh 蓝图是否已启动
+     * @en Whether the blueprint has started
+     */
     isStarted: boolean;
+    /**
+     * @zh 初始化蓝图 VM
+     * @en Initialize blueprint VM
+     */
+    initialize(entity: Entity, scene: IScene): void;
+    /**
+     * @zh 开始执行蓝图
+     * @en Start blueprint execution
+     */
+    start(): void;
+    /**
+     * @zh 停止执行蓝图
+     * @en Stop blueprint execution
+     */
+    stop(): void;
+    /**
+     * @zh 更新蓝图
+     * @en Update blueprint
+     */
+    tick(deltaTime: number): void;
+    /**
+     * @zh 清理蓝图资源
+     * @en Cleanup blueprint resources
+     */
+    cleanup(): void;
 }
-/**
- * Creates a blueprint component data object
- * 创建蓝图组件数据对象
- */
-declare function createBlueprintComponentData(): IBlueprintComponent;
-/**
- * Initialize the VM for a blueprint component
- * 为蓝图组件初始化 VM
- */
-declare function initializeBlueprintVM(component: IBlueprintComponent, entity: Entity, scene: IScene): void;
-/**
- * Start blueprint execution
- * 开始蓝图执行
- */
-declare function startBlueprint(component: IBlueprintComponent): void;
-/**
- * Stop blueprint execution
- * 停止蓝图执行
- */
-declare function stopBlueprint(component: IBlueprintComponent): void;
-/**
- * Update blueprint execution
- * 更新蓝图执行
- */
-declare function tickBlueprint(component: IBlueprintComponent, deltaTime: number): void;
-/**
- * Clean up blueprint resources
- * 清理蓝图资源
- */
-declare function cleanupBlueprint(component: IBlueprintComponent): void;
 
 /**
- * Blueprint Execution System - Manages blueprint lifecycle and execution
- * 蓝图执行系统 - 管理蓝图生命周期和执行
+ * @zh 蓝图系统 - 处理所有带有 BlueprintComponent 的实体
+ * @en Blueprint System - Processes all entities with BlueprintComponent
  */
 
 /**
- * Blueprint system interface for engine integration
- * 用于引擎集成的蓝图系统接口
- */
-interface IBlueprintSystem {
-    /** Process entities with blueprint components (处理带有蓝图组件的实体) */
-    process(entities: IBlueprintEntity[], deltaTime: number): void;
-    /** Called when entity is added to system (实体添加到系统时调用) */
-    onEntityAdded(entity: IBlueprintEntity): void;
-    /** Called when entity is removed from system (实体从系统移除时调用) */
-    onEntityRemoved(entity: IBlueprintEntity): void;
-}
-/**
- * Entity with blueprint component
- * 带有蓝图组件的实体
+ * @zh 蓝图执行系统
+ * @en Blueprint execution system
+ *
+ * @zh 自动处理所有带有 BlueprintComponent 的实体，管理蓝图的初始化、执行和清理
+ * @en Automatically processes all entities with BlueprintComponent, manages blueprint initialization, execution and cleanup
+ *
+ * @example
+ * ```typescript
+ * import { BlueprintSystem } from '@esengine/blueprint';
+ *
+ * // 添加到场景
+ * scene.addSystem(new BlueprintSystem());
+ *
+ * // 为实体添加蓝图
+ * const entity = scene.createEntity('Player');
+ * const blueprint = new BlueprintComponent();
+ * blueprint.blueprintAsset = await loadBlueprintAsset('player.bp');
+ * entity.addComponent(blueprint);
+ * ```
  */
-interface IBlueprintEntity extends Entity {
-    /** Blueprint component data (蓝图组件数据) */
-    blueprintComponent: IBlueprintComponent;
+declare class BlueprintSystem extends EntitySystem {
+    private _componentsRegistered;
+    constructor();
+    /**
+     * @zh 系统初始化时注册所有组件节点
+     * @en Register all component nodes when system initializes
+     */
+    protected onInitialize(): void;
+    /**
+     * @zh 处理所有带有蓝图组件的实体
+     * @en Process all entities with blueprint components
+     */
+    protected process(entities: readonly Entity[]): void;
+    /**
+     * @zh 实体移除时清理蓝图资源
+     * @en Cleanup blueprint resources when entity is removed
+     */
+    protected onRemoved(entity: Entity): void;
 }
-/**
- * Creates a blueprint execution system
- * 创建蓝图执行系统
- */
-declare function createBlueprintSystem(scene: IScene): IBlueprintSystem;
-/**
- * Utility to manually trigger blueprint events
- * 手动触发蓝图事件的工具
- */
-declare function triggerBlueprintEvent(entity: IBlueprintEntity, eventType: string, data?: Record<string, unknown>): void;
-/**
- * Utility to trigger custom events by name
- * 按名称触发自定义事件的工具
- */
-declare function triggerCustomBlueprintEvent(entity: IBlueprintEntity, eventName: string, data?: Record<string, unknown>): void;
 
 /**
  * @zh 蓝图触发器类型定义
@@ -2515,4 +2565,72 @@ declare function registerAllComponentNodes(): void;
  */
 declare function registerComponentNodes(componentClass: Function): void;
 
-export { AlwaysFalseCondition, AlwaysTrueCondition, type BlueprintAsset, BlueprintComposer, type BlueprintCompositionAsset, type BlueprintConnection, BlueprintExpose, type BlueprintExposeOptions, BlueprintFragment, type BlueprintFragmentAsset, type BlueprintFragmentConfig, type BlueprintMetadata, BlueprintMethod, type BlueprintMethodOptions, type BlueprintNode, type BlueprintNodeCategory, type BlueprintNodeTemplate, type BlueprintParamDef, type BlueprintPin, type BlueprintPinDefinition, type BlueprintPinDirection, type BlueprintPinType, BlueprintProperty, type BlueprintPropertyOptions, type BlueprintRuntimePin, BlueprintTrigger, BlueprintVM, type BlueprintVariable, CollisionEntityCondition, type ComponentBlueprintMetadata, CompositeCondition, type CompositionError, type CompositionValidationResult, type CompositionWarning, ConditionBuilder, type ConditionLogic, CustomEventCondition, type DispatchResult, EntityIdCondition, EntityTriggerManager, type EventType, ExecutionContext, type ExecutionResult, type ExposedPin, type FragmentFilter, FragmentRegistry, type FragmentSlot, FunctionCondition, type IBlueprintComponent, type IBlueprintComposer, type IBlueprintEntity, type IBlueprintFragment, type IBlueprintSystem, type IBlueprintTrigger, type ICollisionTriggerContext, type ICustomTriggerContext, type IEntityTriggerManager, type IFragmentRegistry, type IInputTriggerContext, type IMessageTriggerContext, type INodeExecutor, type IStateTriggerContext, type ITickTriggerContext, type ITimerTriggerContext, type ITriggerCondition, type ITriggerContext, type ITriggerDispatcher, type ITriggerRegistry, InputActionCondition, MessageNameCondition, type MethodMetadata, type NodeDefinition, NodeRegistry, NotCondition, type PropertyMetadata, RegisterNode, type SlotConnection, StateNameCondition, TimerIdCondition, type TriggerCallback, type TriggerConfig, type TriggerContext, TriggerDispatcher, TriggerRegistry, type TriggerResult, type TriggerType, TriggerTypeCondition, TriggerTypes, type VariableScope, arePinTypesCompatible, cleanupBlueprint, clearRegisteredComponents, condition, createBlueprintComponentData, createBlueprintSystem, createCollisionContext, createCollisionTrigger, createComposer, createCustomContext, createCustomTrigger, createEmptyBlueprint, createEntityTriggerManager, createExposedPin, createFragment, createFragmentRegistry, createInputContext, createInputTrigger, createMessageContext, createMessageTrigger, createStateContext, createStateEnterTrigger, createStateExitTrigger, createTickContext, createTickTrigger, createTimerContext, createTimerTrigger, createTrigger, createTriggerDispatcher, defaultFragmentRegistry, fragmentFromAsset, fragmentToAsset, generateComponentNodes, getBlueprintMetadata, getNodeCategoryColor, getPinTypeColor, getRegisteredBlueprintComponents, inferPinType, initializeBlueprintVM, registerAllComponentNodes, registerComponentNodes, startBlueprint, stopBlueprint, tickBlueprint, triggerBlueprintEvent, triggerCustomBlueprintEvent, validateBlueprintAsset };
+/**
+ * @esengine/blueprint - Visual scripting system for ECS Framework
+ *
+ * @zh 蓝图可视化脚本系统 - 与 ECS 框架深度集成
+ * @en Visual scripting system - Deep integration with ECS framework
+ *
+ * @zh 此包提供完整的可视化脚本功能：
+ * - 内置 ECS 操作节点（Entity、Component、Flow）
+ * - 组件自动节点生成（使用装饰器标记）
+ * - 运行时蓝图执行
+ *
+ * @en This package provides complete visual scripting features:
+ * - Built-in ECS operation nodes (Entity, Component, Flow)
+ * - Auto component node generation (using decorators)
+ * - Runtime blueprint execution
+ *
+ * @example 基础使用 | Basic Usage:
+ * ```typescript
+ * import { BlueprintSystem, BlueprintComponent } from '@esengine/blueprint';
+ * import { Scene, Core } from '@esengine/ecs-framework';
+ *
+ * // 创建场景并添加蓝图系统
+ * const scene = new Scene();
+ * scene.addSystem(new BlueprintSystem());
+ * Core.setScene(scene);
+ *
+ * // 为实体添加蓝图
+ * const entity = scene.createEntity('Player');
+ * const blueprint = new BlueprintComponent();
+ * blueprint.blueprintAsset = await loadBlueprintAsset('player.bp');
+ * entity.addComponent(blueprint);
+ * ```
+ *
+ * @example 标记组件 | Mark Components:
+ * ```typescript
+ * import { BlueprintExpose, BlueprintProperty, BlueprintMethod } from '@esengine/blueprint';
+ * import { Component, ECSComponent } from '@esengine/ecs-framework';
+ *
+ * @ECSComponent('Health')
+ * @BlueprintExpose({ displayName: '生命值' })
+ * export class HealthComponent extends Component {
+ *     @BlueprintProperty({ displayName: '当前生命值' })
+ *     current: number = 100;
+ *
+ *     @BlueprintMethod({ displayName: '治疗' })
+ *     heal(amount: number): void {
+ *         this.current += amount;
+ *     }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * @zh 注册组件类以支持在蓝图中动态创建
+ * @en Register a component class for dynamic creation in blueprints
+ *
+ * @example
+ * ```typescript
+ * import { registerComponentClass } from '@esengine/blueprint';
+ * import { MyComponent } from './MyComponent';
+ *
+ * registerComponentClass('MyComponent', MyComponent);
+ * ```
+ */
+declare function registerComponentClass(typeName: string, componentClass: new () => Component): void;
+
+export { AlwaysFalseCondition, AlwaysTrueCondition, type BlueprintAsset, BlueprintComponent, BlueprintComposer, type BlueprintCompositionAsset, type BlueprintConnection, BlueprintExpose, type BlueprintExposeOptions, BlueprintFragment, type BlueprintFragmentAsset, type BlueprintFragmentConfig, type BlueprintMetadata, BlueprintMethod, type BlueprintMethodOptions, type BlueprintNode, type BlueprintNodeCategory, type BlueprintNodeTemplate, type BlueprintParamDef, type BlueprintPin, type BlueprintPinDefinition, type BlueprintPinDirection, type BlueprintPinType, BlueprintProperty, type BlueprintPropertyOptions, type BlueprintRuntimePin, BlueprintSystem, BlueprintTrigger, BlueprintVM, type BlueprintVariable, CollisionEntityCondition, type ComponentBlueprintMetadata, CompositeCondition, type CompositionError, type CompositionValidationResult, type CompositionWarning, ConditionBuilder, type ConditionLogic, CustomEventCondition, type DispatchResult, EntityIdCondition, EntityTriggerManager, type EventType, ExecutionContext, type ExecutionResult, type ExposedPin, type FragmentFilter, FragmentRegistry, type FragmentSlot, FunctionCondition, type IBlueprintComposer, type IBlueprintFragment, type IBlueprintTrigger, type ICollisionTriggerContext, type ICustomTriggerContext, type IEntityTriggerManager, type IFragmentRegistry, type IInputTriggerContext, type IMessageTriggerContext, type INodeExecutor, type IStateTriggerContext, type ITickTriggerContext, type ITimerTriggerContext, type ITriggerCondition, type ITriggerContext, type ITriggerDispatcher, type ITriggerRegistry, InputActionCondition, MessageNameCondition, type MethodMetadata, type NodeDefinition, NodeRegistry, NotCondition, type PropertyMetadata, RegisterNode, type SlotConnection, StateNameCondition, TimerIdCondition, type TriggerCallback, type TriggerConfig, type TriggerContext, TriggerDispatcher, TriggerRegistry, type TriggerResult, type TriggerType, TriggerTypeCondition, TriggerTypes, type VariableScope, arePinTypesCompatible, clearRegisteredComponents, condition, createCollisionContext, createCollisionTrigger, createComposer, createCustomContext, createCustomTrigger, createEmptyBlueprint, createEntityTriggerManager, createExposedPin, createFragment, createFragmentRegistry, createInputContext, createInputTrigger, createMessageContext, createMessageTrigger, createStateContext, createStateEnterTrigger, createStateExitTrigger, createTickContext, createTickTrigger, createTimerContext, createTimerTrigger, createTrigger, createTriggerDispatcher, defaultFragmentRegistry, fragmentFromAsset, fragmentToAsset, generateComponentNodes, getBlueprintMetadata, getNodeCategoryColor, getPinTypeColor, getRegisteredBlueprintComponents, inferPinType, registerAllComponentNodes, registerComponentClass, registerComponentNodes, validateBlueprintAsset };