@esengine/blueprint 4.0.1 → 4.1.0

package/dist/index.d.ts

@@ -2280,4 +2280,239 @@ declare const defaultFragmentRegistry: FragmentRegistry;
  */
 declare function createFragmentRegistry(): IFragmentRegistry;
 
-export { AlwaysFalseCondition, AlwaysTrueCondition, type BlueprintAsset, BlueprintComposer, type BlueprintCompositionAsset, type BlueprintConnection, BlueprintFragment, type BlueprintFragmentAsset, type BlueprintFragmentConfig, type BlueprintMetadata, type BlueprintNode, type BlueprintNodeCategory, type BlueprintNodeTemplate, type BlueprintPin, type BlueprintPinDefinition, type BlueprintPinDirection, type BlueprintPinType, type BlueprintRuntimePin, BlueprintTrigger, BlueprintVM, type BlueprintVariable, CollisionEntityCondition, 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 NodeDefinition, NodeRegistry, NotCondition, RegisterNode, type SlotConnection, StateNameCondition, TimerIdCondition, type TriggerCallback, type TriggerConfig, type TriggerContext, TriggerDispatcher, TriggerRegistry, type TriggerResult, type TriggerType, TriggerTypeCondition, TriggerTypes, type VariableScope, arePinTypesCompatible, cleanupBlueprint, 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, getNodeCategoryColor, getPinTypeColor, initializeBlueprintVM, startBlueprint, stopBlueprint, tickBlueprint, triggerBlueprintEvent, triggerCustomBlueprintEvent, validateBlueprintAsset };
+/**
+ * @zh 蓝图装饰器 - 用于标记可在蓝图中使用的组件、属性和方法
+ * @en Blueprint Decorators - Mark components, properties and methods for blueprint use
+ *
+ * @example
+ * ```typescript
+ * import { BlueprintExpose, BlueprintProperty, BlueprintMethod } from '@esengine/blueprint';
+ *
+ * @ECSComponent('Health')
+ * @BlueprintExpose({ displayName: '生命值组件', category: 'gameplay' })
+ * export class HealthComponent extends Component {
+ *
+ *     @BlueprintProperty({ displayName: '当前生命值', type: 'float' })
+ *     current: number = 100;
+ *
+ *     @BlueprintProperty({ displayName: '最大生命值', type: 'float', readonly: true })
+ *     max: number = 100;
+ *
+ *     @BlueprintMethod({
+ *         displayName: '治疗',
+ *         params: [{ name: 'amount', type: 'float' }]
+ *     })
+ *     heal(amount: number): void {
+ *         this.current = Math.min(this.current + amount, this.max);
+ *     }
+ *
+ *     @BlueprintMethod({
+ *         displayName: '受伤',
+ *         params: [{ name: 'amount', type: 'float' }],
+ *         returnType: 'bool'
+ *     })
+ *     takeDamage(amount: number): boolean {
+ *         this.current -= amount;
+ *         return this.current <= 0;
+ *     }
+ * }
+ * ```
+ */
+
+/**
+ * @zh 参数定义
+ * @en Parameter definition
+ */
+interface BlueprintParamDef {
+    /** @zh 参数名称 @en Parameter name */
+    name: string;
+    /** @zh 显示名称 @en Display name */
+    displayName?: string;
+    /** @zh 引脚类型 @en Pin type */
+    type?: BlueprintPinType;
+    /** @zh 默认值 @en Default value */
+    defaultValue?: unknown;
+}
+/**
+ * @zh 蓝图暴露选项
+ * @en Blueprint expose options
+ */
+interface BlueprintExposeOptions {
+    /** @zh 组件显示名称 @en Component display name */
+    displayName?: string;
+    /** @zh 组件描述 @en Component description */
+    description?: string;
+    /** @zh 组件分类 @en Component category */
+    category?: string;
+    /** @zh 组件颜色 @en Component color */
+    color?: string;
+    /** @zh 组件图标 @en Component icon */
+    icon?: string;
+}
+/**
+ * @zh 蓝图属性选项
+ * @en Blueprint property options
+ */
+interface BlueprintPropertyOptions {
+    /** @zh 属性显示名称 @en Property display name */
+    displayName?: string;
+    /** @zh 属性描述 @en Property description */
+    description?: string;
+    /** @zh 引脚类型 @en Pin type */
+    type?: BlueprintPinType;
+    /** @zh 是否只读（不生成 Set 节点）@en Readonly (no Set node generated) */
+    readonly?: boolean;
+    /** @zh 默认值 @en Default value */
+    defaultValue?: unknown;
+}
+/**
+ * @zh 蓝图方法选项
+ * @en Blueprint method options
+ */
+interface BlueprintMethodOptions {
+    /** @zh 方法显示名称 @en Method display name */
+    displayName?: string;
+    /** @zh 方法描述 @en Method description */
+    description?: string;
+    /** @zh 是否是纯函数（无副作用）@en Is pure function (no side effects) */
+    isPure?: boolean;
+    /** @zh 参数列表 @en Parameter list */
+    params?: BlueprintParamDef[];
+    /** @zh 返回值类型 @en Return type */
+    returnType?: BlueprintPinType;
+}
+/**
+ * @zh 属性元数据
+ * @en Property metadata
+ */
+interface PropertyMetadata {
+    propertyKey: string;
+    displayName: string;
+    description?: string;
+    pinType: BlueprintPinType;
+    readonly: boolean;
+    defaultValue?: unknown;
+}
+/**
+ * @zh 方法元数据
+ * @en Method metadata
+ */
+interface MethodMetadata {
+    methodKey: string;
+    displayName: string;
+    description?: string;
+    isPure: boolean;
+    params: BlueprintParamDef[];
+    returnType: BlueprintPinType;
+}
+/**
+ * @zh 组件蓝图元数据
+ * @en Component blueprint metadata
+ */
+interface ComponentBlueprintMetadata extends BlueprintExposeOptions {
+    componentName: string;
+    properties: PropertyMetadata[];
+    methods: MethodMetadata[];
+}
+/**
+ * @zh 获取所有已注册的蓝图组件
+ * @en Get all registered blueprint components
+ */
+declare function getRegisteredBlueprintComponents(): Map<Function, ComponentBlueprintMetadata>;
+/**
+ * @zh 获取组件的蓝图元数据
+ * @en Get blueprint metadata for a component
+ */
+declare function getBlueprintMetadata(componentClass: Function): ComponentBlueprintMetadata | undefined;
+/**
+ * @zh 清除所有注册的蓝图组件（用于测试）
+ * @en Clear all registered blueprint components (for testing)
+ */
+declare function clearRegisteredComponents(): void;
+/**
+ * @zh 标记组件可在蓝图中使用
+ * @en Mark component as usable in blueprint
+ *
+ * @example
+ * ```typescript
+ * @ECSComponent('Player')
+ * @BlueprintExpose({ displayName: '玩家', category: 'gameplay' })
+ * export class PlayerComponent extends Component { }
+ * ```
+ */
+declare function BlueprintExpose(options?: BlueprintExposeOptions): ClassDecorator;
+/**
+ * @zh 标记属性可在蓝图中访问
+ * @en Mark property as accessible in blueprint
+ *
+ * @example
+ * ```typescript
+ * @BlueprintProperty({ displayName: '生命值', type: 'float' })
+ * health: number = 100;
+ *
+ * @BlueprintProperty({ displayName: '名称', type: 'string', readonly: true })
+ * name: string = 'Player';
+ * ```
+ */
+declare function BlueprintProperty(options?: BlueprintPropertyOptions): PropertyDecorator;
+/**
+ * @zh 标记方法可在蓝图中调用
+ * @en Mark method as callable in blueprint
+ *
+ * @example
+ * ```typescript
+ * @BlueprintMethod({
+ *     displayName: '攻击',
+ *     params: [
+ *         { name: 'target', type: 'entity' },
+ *         { name: 'damage', type: 'float' }
+ *     ],
+ *     returnType: 'bool'
+ * })
+ * attack(target: Entity, damage: number): boolean { }
+ *
+ * @BlueprintMethod({ displayName: '获取速度', isPure: true, returnType: 'float' })
+ * getSpeed(): number { return this.speed; }
+ * ```
+ */
+declare function BlueprintMethod(options?: BlueprintMethodOptions): MethodDecorator;
+/**
+ * @zh 从 TypeScript 类型名推断蓝图引脚类型
+ * @en Infer blueprint pin type from TypeScript type name
+ */
+declare function inferPinType(typeName: string): BlueprintPinType;
+
+/**
+ * @zh 组件节点生成器 - 自动为标记的组件生成蓝图节点
+ * @en Component Node Generator - Auto-generate blueprint nodes for marked components
+ *
+ * @zh 根据 @BlueprintExpose、@BlueprintProperty、@BlueprintMethod 装饰器
+ * 自动生成对应的 Get/Set/Call 节点并注册到 NodeRegistry
+ *
+ * @en Based on @BlueprintExpose, @BlueprintProperty, @BlueprintMethod decorators,
+ * auto-generate corresponding Get/Set/Call nodes and register to NodeRegistry
+ */
+
+/**
+ * @zh 为组件生成所有蓝图节点
+ * @en Generate all blueprint nodes for a component
+ */
+declare function generateComponentNodes(componentClass: Function, metadata: ComponentBlueprintMetadata): void;
+/**
+ * @zh 注册所有已标记的组件节点
+ * @en Register all marked component nodes
+ *
+ * @zh 应该在蓝图系统初始化时调用，会扫描所有使用 @BlueprintExpose 装饰的组件
+ * 并自动生成对应的蓝图节点
+ *
+ * @en Should be called during blueprint system initialization, scans all components
+ * decorated with @BlueprintExpose and auto-generates corresponding blueprint nodes
+ */
+declare function registerAllComponentNodes(): void;
+/**
+ * @zh 手动注册单个组件
+ * @en Manually register a single component
+ */
+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 };