@esengine/blueprint 4.3.0 → 4.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -68,6 +68,218 @@ declare function getPinTypeColor(type: BlueprintPinType): string;
68
68
  */
69
69
  declare function arePinTypesCompatible(from: BlueprintPinType, to: BlueprintPinType): boolean;
70
70
 
71
+ /**
72
+ * @zh 蓝图属性 Schema 系统
73
+ * @en Blueprint Property Schema System
74
+ *
75
+ * @zh 提供递归类型定义,支持原始类型、数组、对象、枚举等复杂数据结构
76
+ * @en Provides recursive type definitions supporting primitives, arrays, objects, enums, etc.
77
+ */
78
+
79
+ /**
80
+ * @zh 属性 Schema - 递归定义数据结构
81
+ * @en Property Schema - recursive data structure definition
82
+ */
83
+ type PropertySchema = PrimitiveSchema | ArraySchema | ObjectSchema | EnumSchema | RefSchema;
84
+ /**
85
+ * @zh 原始类型 Schema
86
+ * @en Primitive type schema
87
+ */
88
+ interface PrimitiveSchema {
89
+ type: 'primitive';
90
+ primitive: BlueprintPinType;
91
+ defaultValue?: unknown;
92
+ min?: number;
93
+ max?: number;
94
+ step?: number;
95
+ multiline?: boolean;
96
+ placeholder?: string;
97
+ }
98
+ /**
99
+ * @zh 数组类型 Schema
100
+ * @en Array type schema
101
+ */
102
+ interface ArraySchema {
103
+ type: 'array';
104
+ items: PropertySchema;
105
+ defaultValue?: unknown[];
106
+ minItems?: number;
107
+ maxItems?: number;
108
+ reorderable?: boolean;
109
+ collapsible?: boolean;
110
+ defaultCollapsed?: boolean;
111
+ itemLabel?: string;
112
+ }
113
+ /**
114
+ * @zh 对象类型 Schema
115
+ * @en Object type schema
116
+ */
117
+ interface ObjectSchema {
118
+ type: 'object';
119
+ properties: Record<string, PropertySchema>;
120
+ required?: string[];
121
+ collapsible?: boolean;
122
+ defaultCollapsed?: boolean;
123
+ displayName?: string;
124
+ }
125
+ /**
126
+ * @zh 枚举类型 Schema
127
+ * @en Enum type schema
128
+ */
129
+ interface EnumSchema {
130
+ type: 'enum';
131
+ options: EnumOption[];
132
+ defaultValue?: string | number;
133
+ }
134
+ /**
135
+ * @zh 枚举选项
136
+ * @en Enum option
137
+ */
138
+ interface EnumOption {
139
+ value: string | number;
140
+ label: string;
141
+ description?: string;
142
+ icon?: string;
143
+ }
144
+ /**
145
+ * @zh 引用类型 Schema
146
+ * @en Reference type schema
147
+ *
148
+ * @zh 引用 SchemaRegistry 中已注册的 Schema
149
+ * @en References a schema registered in SchemaRegistry
150
+ */
151
+ interface RefSchema {
152
+ type: 'ref';
153
+ ref: string;
154
+ }
155
+ /**
156
+ * @zh Schema 注册表
157
+ * @en Schema Registry
158
+ *
159
+ * @zh 用于注册和复用常用的 Schema 定义
160
+ * @en Used to register and reuse common Schema definitions
161
+ */
162
+ declare class SchemaRegistry {
163
+ private static schemas;
164
+ /**
165
+ * @zh 注册 Schema
166
+ * @en Register a schema
167
+ */
168
+ static register(id: string, schema: PropertySchema): void;
169
+ /**
170
+ * @zh 获取 Schema
171
+ * @en Get a schema
172
+ */
173
+ static get(id: string): PropertySchema | undefined;
174
+ /**
175
+ * @zh 解析引用,返回实际 Schema
176
+ * @en Resolve reference, return actual schema
177
+ */
178
+ static resolve(schema: PropertySchema): PropertySchema;
179
+ /**
180
+ * @zh 检查 Schema 是否已注册
181
+ * @en Check if schema is registered
182
+ */
183
+ static has(id: string): boolean;
184
+ /**
185
+ * @zh 获取所有已注册的 Schema ID
186
+ * @en Get all registered schema IDs
187
+ */
188
+ static keys(): string[];
189
+ /**
190
+ * @zh 清空注册表
191
+ * @en Clear registry
192
+ */
193
+ static clear(): void;
194
+ }
195
+ /**
196
+ * @zh 获取 Schema 的默认值
197
+ * @en Get default value for a schema
198
+ */
199
+ declare function getSchemaDefaultValue(schema: PropertySchema): unknown;
200
+ /**
201
+ * @zh 获取原始类型的默认值
202
+ * @en Get default value for primitive type
203
+ */
204
+ declare function getPrimitiveDefaultValue(primitive: BlueprintPinType): unknown;
205
+ /**
206
+ * @zh 根据 Schema 获取对应的 PinType
207
+ * @en Get corresponding PinType from Schema
208
+ */
209
+ declare function schemaToPinType(schema: PropertySchema): BlueprintPinType;
210
+ /**
211
+ * @zh 验证数据是否符合 Schema
212
+ * @en Validate data against schema
213
+ */
214
+ declare function validateSchema(schema: PropertySchema, data: unknown, path?: string): ValidationResult;
215
+ /**
216
+ * @zh 验证结果
217
+ * @en Validation result
218
+ */
219
+ interface ValidationResult {
220
+ valid: boolean;
221
+ errors: ValidationError[];
222
+ }
223
+ /**
224
+ * @zh 验证错误
225
+ * @en Validation error
226
+ */
227
+ interface ValidationError {
228
+ path: string;
229
+ message: string;
230
+ expected?: string;
231
+ received?: string;
232
+ }
233
+ /**
234
+ * @zh 深度克隆 Schema
235
+ * @en Deep clone schema
236
+ */
237
+ declare function cloneSchema(schema: PropertySchema): PropertySchema;
238
+ /**
239
+ * @zh 合并两个 ObjectSchema
240
+ * @en Merge two ObjectSchemas
241
+ */
242
+ declare function mergeObjectSchemas(base: ObjectSchema, override: Partial<ObjectSchema>): ObjectSchema;
243
+ /**
244
+ * @zh Schema 构建器
245
+ * @en Schema Builder
246
+ *
247
+ * @example
248
+ * ```typescript
249
+ * const waypointSchema = Schema.object({
250
+ * position: Schema.vector2(),
251
+ * waitTime: Schema.float({ min: 0, defaultValue: 1.0 }),
252
+ * action: Schema.enum([
253
+ * { value: 'idle', label: 'Idle' },
254
+ * { value: 'patrol', label: 'Patrol' }
255
+ * ])
256
+ * });
257
+ *
258
+ * const pathSchema = Schema.array(waypointSchema, {
259
+ * minItems: 2,
260
+ * reorderable: true,
261
+ * itemLabel: 'Point {index1}'
262
+ * });
263
+ * ```
264
+ */
265
+ declare const Schema: {
266
+ bool(options?: Partial<Omit<PrimitiveSchema, "type" | "primitive">>): PrimitiveSchema;
267
+ int(options?: Partial<Omit<PrimitiveSchema, "type" | "primitive">>): PrimitiveSchema;
268
+ float(options?: Partial<Omit<PrimitiveSchema, "type" | "primitive">>): PrimitiveSchema;
269
+ string(options?: Partial<Omit<PrimitiveSchema, "type" | "primitive">>): PrimitiveSchema;
270
+ vector2(options?: Partial<Omit<PrimitiveSchema, "type" | "primitive">>): PrimitiveSchema;
271
+ vector3(options?: Partial<Omit<PrimitiveSchema, "type" | "primitive">>): PrimitiveSchema;
272
+ color(options?: Partial<Omit<PrimitiveSchema, "type" | "primitive">>): PrimitiveSchema;
273
+ entity(options?: Partial<Omit<PrimitiveSchema, "type" | "primitive">>): PrimitiveSchema;
274
+ component(options?: Partial<Omit<PrimitiveSchema, "type" | "primitive">>): PrimitiveSchema;
275
+ object_ref(options?: Partial<Omit<PrimitiveSchema, "type" | "primitive">>): PrimitiveSchema;
276
+ any(options?: Partial<Omit<PrimitiveSchema, "type" | "primitive">>): PrimitiveSchema;
277
+ array(items: PropertySchema, options?: Partial<Omit<ArraySchema, "type" | "items">>): ArraySchema;
278
+ object(properties: Record<string, PropertySchema>, options?: Partial<Omit<ObjectSchema, "type" | "properties">>): ObjectSchema;
279
+ enum(options: EnumOption[], extra?: Partial<Omit<EnumSchema, "type" | "options">>): EnumSchema;
280
+ ref(id: string): RefSchema;
281
+ };
282
+
71
283
  /**
72
284
  * Blueprint Node Types
73
285
  * 蓝图节点类型
@@ -111,6 +323,19 @@ interface BlueprintNodeTemplate {
111
323
  headerColor?: string;
112
324
  /** Node color for visual distinction (节点颜色用于视觉区分) */
113
325
  color?: string;
326
+ /**
327
+ * @zh 节点数据 Schema - 定义节点存储的数据结构
328
+ * @en Node data schema - defines the data structure stored in the node
329
+ *
330
+ * @zh 当定义了 schema 时,节点数据将按照 schema 结构存储和验证
331
+ * @en When schema is defined, node data will be stored and validated according to the schema structure
332
+ */
333
+ schema?: ObjectSchema;
334
+ /**
335
+ * @zh 动态数组路径列表 - 指定哪些数组支持动态增删元素
336
+ * @en Dynamic array paths - specifies which arrays support dynamic add/remove elements
337
+ */
338
+ dynamicArrayPaths?: string[];
114
339
  }
115
340
  /**
116
341
  * Node instance in a blueprint graph
@@ -134,17 +359,26 @@ interface BlueprintNode {
134
359
  /**
135
360
  * Connection between two pins
136
361
  * 两个引脚之间的连接
362
+ *
363
+ * @zh 引脚路径支持数组索引,如 "waypoints[0].position"
364
+ * @en Pin paths support array indices, e.g., "waypoints[0].position"
137
365
  */
138
366
  interface BlueprintConnection {
139
367
  /** Unique connection ID (唯一连接ID) */
140
368
  id: string;
141
369
  /** Source node ID (源节点ID) */
142
370
  fromNodeId: string;
143
- /** Source pin name (源引脚名称) */
371
+ /**
372
+ * @zh 源引脚路径(支持数组索引如 "items[0].value")
373
+ * @en Source pin path (supports array indices like "items[0].value")
374
+ */
144
375
  fromPin: string;
145
376
  /** Target node ID (目标节点ID) */
146
377
  toNodeId: string;
147
- /** Target pin name (目标引脚名称) */
378
+ /**
379
+ * @zh 目标引脚路径(支持数组索引如 "items[0].value")
380
+ * @en Target pin path (supports array indices like "items[0].value")
381
+ */
148
382
  toPin: string;
149
383
  }
150
384
  /**
@@ -228,6 +462,157 @@ declare function createEmptyBlueprint(name: string, includeBeginPlay?: boolean):
228
462
  */
229
463
  declare function validateBlueprintAsset(asset: unknown): asset is BlueprintAsset;
230
464
 
465
+ /**
466
+ * @zh 蓝图路径工具
467
+ * @en Blueprint Path Utilities
468
+ *
469
+ * @zh 用于解析和操作数据路径,支持数组索引和嵌套属性访问
470
+ * @en Used to parse and manipulate data paths, supports array indices and nested property access
471
+ */
472
+ /**
473
+ * @zh 路径部分类型
474
+ * @en Path part type
475
+ */
476
+ type PathPartType = 'property' | 'index' | 'wildcard';
477
+ /**
478
+ * @zh 路径部分
479
+ * @en Path part
480
+ */
481
+ interface PathPart {
482
+ type: PathPartType;
483
+ /** Property name (for 'property' type) */
484
+ name?: string;
485
+ /** Array index (for 'index' type) */
486
+ index?: number;
487
+ }
488
+ /**
489
+ * @zh 端口地址 - 解析后的路径结构
490
+ * @en Port address - parsed path structure
491
+ */
492
+ interface PortAddress {
493
+ /** Base property name (基础属性名) */
494
+ baseName: string;
495
+ /** Array indices [0, 2] represents arr[0][2] (数组索引路径) */
496
+ indices: number[];
497
+ /** Nested property path ['x', 'y'] (嵌套属性路径) */
498
+ subPath: string[];
499
+ /** Original path string (原始路径字符串) */
500
+ original: string;
501
+ }
502
+ /**
503
+ * @zh 解析路径字符串为部分数组
504
+ * @en Parse path string to parts array
505
+ *
506
+ * @example
507
+ * parsePath("waypoints[0].position.x")
508
+ * // => [
509
+ * // { type: 'property', name: 'waypoints' },
510
+ * // { type: 'index', index: 0 },
511
+ * // { type: 'property', name: 'position' },
512
+ * // { type: 'property', name: 'x' }
513
+ * // ]
514
+ */
515
+ declare function parsePath(path: string): PathPart[];
516
+ /**
517
+ * @zh 解析端口路径字符串为 PortAddress
518
+ * @en Parse port path string to PortAddress
519
+ *
520
+ * @example
521
+ * parsePortPath("waypoints[0].position.x")
522
+ * // => { baseName: "waypoints", indices: [0], subPath: ["position", "x"], original: "..." }
523
+ */
524
+ declare function parsePortPath(path: string): PortAddress;
525
+ /**
526
+ * @zh 构建路径字符串
527
+ * @en Build path string from parts
528
+ */
529
+ declare function buildPath(parts: PathPart[]): string;
530
+ /**
531
+ * @zh 从 PortAddress 构建路径字符串
532
+ * @en Build path string from PortAddress
533
+ */
534
+ declare function buildPortPath(address: PortAddress): string;
535
+ /**
536
+ * @zh 根据路径获取数据
537
+ * @en Get data by path
538
+ *
539
+ * @example
540
+ * const data = { waypoints: [{ position: { x: 10, y: 20 } }] };
541
+ * getByPath(data, "waypoints[0].position.x") // => 10
542
+ */
543
+ declare function getByPath(data: unknown, path: string): unknown;
544
+ /**
545
+ * @zh 根据路径设置数据
546
+ * @en Set data by path
547
+ *
548
+ * @example
549
+ * const data = { waypoints: [{ position: { x: 0, y: 0 } }] };
550
+ * setByPath(data, "waypoints[0].position.x", 100);
551
+ * // data.waypoints[0].position.x === 100
552
+ */
553
+ declare function setByPath(data: unknown, path: string, value: unknown): boolean;
554
+ /**
555
+ * @zh 检查路径是否存在
556
+ * @en Check if path exists
557
+ */
558
+ declare function hasPath(data: unknown, path: string): boolean;
559
+ /**
560
+ * @zh 删除路径上的数据
561
+ * @en Delete data at path
562
+ */
563
+ declare function deleteByPath(data: unknown, path: string): boolean;
564
+ /**
565
+ * @zh 数组操作类型
566
+ * @en Array operation type
567
+ */
568
+ type ArrayOperation = 'insert' | 'remove' | 'move';
569
+ /**
570
+ * @zh 当数组元素变化时,更新路径中的索引
571
+ * @en Update indices in path when array elements change
572
+ *
573
+ * @param path - Original path (原始路径)
574
+ * @param arrayPath - Array base path (数组基础路径)
575
+ * @param operation - Operation type (操作类型)
576
+ * @param index - Target index (目标索引)
577
+ * @param toIndex - Move destination (移动目标,仅 move 操作)
578
+ * @returns Updated path or empty string if path becomes invalid (更新后的路径,如果路径失效则返回空字符串)
579
+ */
580
+ declare function updatePathOnArrayChange(path: string, arrayPath: string, operation: ArrayOperation, index: number, toIndex?: number): string;
581
+ /**
582
+ * @zh 展开带通配符的路径
583
+ * @en Expand path with wildcards
584
+ *
585
+ * @example
586
+ * const data = { items: [{ x: 1 }, { x: 2 }, { x: 3 }] };
587
+ * expandWildcardPath("items[*].x", data)
588
+ * // => ["items[0].x", "items[1].x", "items[2].x"]
589
+ */
590
+ declare function expandWildcardPath(path: string, data: unknown): string[];
591
+ /**
592
+ * @zh 检查路径是否包含通配符
593
+ * @en Check if path contains wildcards
594
+ */
595
+ declare function hasWildcard(path: string): boolean;
596
+ /**
597
+ * @zh 获取路径的父路径
598
+ * @en Get parent path
599
+ *
600
+ * @example
601
+ * getParentPath("items[0].position.x") // => "items[0].position"
602
+ * getParentPath("items[0]") // => "items"
603
+ * getParentPath("items") // => ""
604
+ */
605
+ declare function getParentPath(path: string): string;
606
+ /**
607
+ * @zh 获取路径的最后一部分名称
608
+ * @en Get the last part name of path
609
+ *
610
+ * @example
611
+ * getPathLastName("items[0].position.x") // => "x"
612
+ * getPathLastName("items[0]") // => "[0]"
613
+ */
614
+ declare function getPathLastName(path: string): string;
615
+
231
616
  /**
232
617
  * Execution Context - Runtime context for blueprint execution
233
618
  * 执行上下文 - 蓝图执行的运行时上下文
@@ -2333,108 +2718,62 @@ declare function createFragmentRegistry(): IFragmentRegistry;
2333
2718
  /**
2334
2719
  * @zh 蓝图装饰器 - 用于标记可在蓝图中使用的组件、属性和方法
2335
2720
  * @en Blueprint Decorators - Mark components, properties and methods for blueprint use
2336
- *
2337
- * @example
2338
- * ```typescript
2339
- * import { BlueprintExpose, BlueprintProperty, BlueprintMethod } from '@esengine/blueprint';
2340
- *
2341
- * @ECSComponent('Health')
2342
- * @BlueprintExpose({ displayName: '生命值组件', category: 'gameplay' })
2343
- * export class HealthComponent extends Component {
2344
- *
2345
- * @BlueprintProperty({ displayName: '当前生命值', type: 'float' })
2346
- * current: number = 100;
2347
- *
2348
- * @BlueprintProperty({ displayName: '最大生命值', type: 'float', readonly: true })
2349
- * max: number = 100;
2350
- *
2351
- * @BlueprintMethod({
2352
- * displayName: '治疗',
2353
- * params: [{ name: 'amount', type: 'float' }]
2354
- * })
2355
- * heal(amount: number): void {
2356
- * this.current = Math.min(this.current + amount, this.max);
2357
- * }
2358
- *
2359
- * @BlueprintMethod({
2360
- * displayName: '受伤',
2361
- * params: [{ name: 'amount', type: 'float' }],
2362
- * returnType: 'bool'
2363
- * })
2364
- * takeDamage(amount: number): boolean {
2365
- * this.current -= amount;
2366
- * return this.current <= 0;
2367
- * }
2368
- * }
2369
- * ```
2370
2721
  */
2371
2722
 
2372
- /**
2373
- * @zh 参数定义
2374
- * @en Parameter definition
2375
- */
2376
2723
  interface BlueprintParamDef {
2377
- /** @zh 参数名称 @en Parameter name */
2378
2724
  name: string;
2379
- /** @zh 显示名称 @en Display name */
2380
2725
  displayName?: string;
2381
- /** @zh 引脚类型 @en Pin type */
2382
2726
  type?: BlueprintPinType;
2383
- /** @zh 默认值 @en Default value */
2384
2727
  defaultValue?: unknown;
2385
2728
  }
2386
- /**
2387
- * @zh 蓝图暴露选项
2388
- * @en Blueprint expose options
2389
- */
2390
2729
  interface BlueprintExposeOptions {
2391
- /** @zh 组件显示名称 @en Component display name */
2392
2730
  displayName?: string;
2393
- /** @zh 组件描述 @en Component description */
2394
2731
  description?: string;
2395
- /** @zh 组件分类 @en Component category */
2396
2732
  category?: string;
2397
- /** @zh 组件颜色 @en Component color */
2398
2733
  color?: string;
2399
- /** @zh 组件图标 @en Component icon */
2400
2734
  icon?: string;
2401
2735
  }
2402
- /**
2403
- * @zh 蓝图属性选项
2404
- * @en Blueprint property options
2405
- */
2406
2736
  interface BlueprintPropertyOptions {
2407
- /** @zh 属性显示名称 @en Property display name */
2408
2737
  displayName?: string;
2409
- /** @zh 属性描述 @en Property description */
2410
2738
  description?: string;
2411
- /** @zh 引脚类型 @en Pin type */
2412
2739
  type?: BlueprintPinType;
2413
- /** @zh 是否只读(不生成 Set 节点)@en Readonly (no Set node generated) */
2414
2740
  readonly?: boolean;
2415
- /** @zh 默认值 @en Default value */
2416
2741
  defaultValue?: unknown;
2417
2742
  }
2418
- /**
2419
- * @zh 蓝图方法选项
2420
- * @en Blueprint method options
2421
- */
2422
2743
  interface BlueprintMethodOptions {
2423
- /** @zh 方法显示名称 @en Method display name */
2424
2744
  displayName?: string;
2425
- /** @zh 方法描述 @en Method description */
2426
2745
  description?: string;
2427
- /** @zh 是否是纯函数(无副作用)@en Is pure function (no side effects) */
2428
2746
  isPure?: boolean;
2429
- /** @zh 参数列表 @en Parameter list */
2430
2747
  params?: BlueprintParamDef[];
2431
- /** @zh 返回值类型 @en Return type */
2432
2748
  returnType?: BlueprintPinType;
2433
2749
  }
2434
2750
  /**
2435
- * @zh 属性元数据
2436
- * @en Property metadata
2751
+ * @zh 蓝图数组属性选项
2752
+ * @en Blueprint array property options
2753
+ */
2754
+ interface BlueprintArrayOptions {
2755
+ displayName?: string;
2756
+ description?: string;
2757
+ itemSchema: PropertySchema;
2758
+ reorderable?: boolean;
2759
+ collapsible?: boolean;
2760
+ minItems?: number;
2761
+ maxItems?: number;
2762
+ defaultValue?: unknown[];
2763
+ itemLabel?: string;
2764
+ exposeElementPorts?: boolean;
2765
+ portNameTemplate?: string;
2766
+ }
2767
+ /**
2768
+ * @zh 蓝图对象属性选项
2769
+ * @en Blueprint object property options
2437
2770
  */
2771
+ interface BlueprintObjectOptions {
2772
+ displayName?: string;
2773
+ description?: string;
2774
+ properties: Record<string, PropertySchema>;
2775
+ collapsible?: boolean;
2776
+ }
2438
2777
  interface PropertyMetadata {
2439
2778
  propertyKey: string;
2440
2779
  displayName: string;
@@ -2442,11 +2781,11 @@ interface PropertyMetadata {
2442
2781
  pinType: BlueprintPinType;
2443
2782
  readonly: boolean;
2444
2783
  defaultValue?: unknown;
2784
+ schema?: PropertySchema;
2785
+ isDynamicArray?: boolean;
2786
+ exposeElementPorts?: boolean;
2787
+ portNameTemplate?: string;
2445
2788
  }
2446
- /**
2447
- * @zh 方法元数据
2448
- * @en Method metadata
2449
- */
2450
2789
  interface MethodMetadata {
2451
2790
  methodKey: string;
2452
2791
  displayName: string;
@@ -2455,81 +2794,55 @@ interface MethodMetadata {
2455
2794
  params: BlueprintParamDef[];
2456
2795
  returnType: BlueprintPinType;
2457
2796
  }
2458
- /**
2459
- * @zh 组件蓝图元数据
2460
- * @en Component blueprint metadata
2461
- */
2462
2797
  interface ComponentBlueprintMetadata extends BlueprintExposeOptions {
2463
2798
  componentName: string;
2464
2799
  properties: PropertyMetadata[];
2465
2800
  methods: MethodMetadata[];
2466
2801
  }
2467
- /**
2468
- * @zh 获取所有已注册的蓝图组件
2469
- * @en Get all registered blueprint components
2470
- */
2471
2802
  declare function getRegisteredBlueprintComponents(): Map<Function, ComponentBlueprintMetadata>;
2472
- /**
2473
- * @zh 获取组件的蓝图元数据
2474
- * @en Get blueprint metadata for a component
2475
- */
2476
2803
  declare function getBlueprintMetadata(componentClass: Function): ComponentBlueprintMetadata | undefined;
2477
- /**
2478
- * @zh 清除所有注册的蓝图组件(用于测试)
2479
- * @en Clear all registered blueprint components (for testing)
2480
- */
2481
2804
  declare function clearRegisteredComponents(): void;
2482
- /**
2483
- * @zh 标记组件可在蓝图中使用
2484
- * @en Mark component as usable in blueprint
2485
- *
2486
- * @example
2487
- * ```typescript
2488
- * @ECSComponent('Player')
2489
- * @BlueprintExpose({ displayName: '玩家', category: 'gameplay' })
2490
- * export class PlayerComponent extends Component { }
2491
- * ```
2492
- */
2493
2805
  declare function BlueprintExpose(options?: BlueprintExposeOptions): ClassDecorator;
2806
+ declare function BlueprintProperty(options?: BlueprintPropertyOptions): PropertyDecorator;
2494
2807
  /**
2495
- * @zh 标记属性可在蓝图中访问
2496
- * @en Mark property as accessible in blueprint
2808
+ * @zh 标记属性为蓝图数组(支持动态增删、排序)
2809
+ * @en Mark property as blueprint array (supports dynamic add/remove, reorder)
2497
2810
  *
2498
2811
  * @example
2499
2812
  * ```typescript
2500
- * @BlueprintProperty({ displayName: '生命值', type: 'float' })
2501
- * health: number = 100;
2502
- *
2503
- * @BlueprintProperty({ displayName: '名称', type: 'string', readonly: true })
2504
- * name: string = 'Player';
2813
+ * @BlueprintArray({
2814
+ * displayName: '路径点',
2815
+ * itemSchema: Schema.object({
2816
+ * position: Schema.vector2(),
2817
+ * waitTime: Schema.float({ min: 0, defaultValue: 1.0 })
2818
+ * }),
2819
+ * reorderable: true,
2820
+ * exposeElementPorts: true,
2821
+ * portNameTemplate: 'Point {index1}'
2822
+ * })
2823
+ * waypoints: Waypoint[] = [];
2505
2824
  * ```
2506
2825
  */
2507
- declare function BlueprintProperty(options?: BlueprintPropertyOptions): PropertyDecorator;
2826
+ declare function BlueprintArray(options: BlueprintArrayOptions): PropertyDecorator;
2508
2827
  /**
2509
- * @zh 标记方法可在蓝图中调用
2510
- * @en Mark method as callable in blueprint
2828
+ * @zh 标记属性为蓝图对象(支持嵌套结构)
2829
+ * @en Mark property as blueprint object (supports nested structure)
2511
2830
  *
2512
2831
  * @example
2513
2832
  * ```typescript
2514
- * @BlueprintMethod({
2515
- * displayName: '攻击',
2516
- * params: [
2517
- * { name: 'target', type: 'entity' },
2518
- * { name: 'damage', type: 'float' }
2519
- * ],
2520
- * returnType: 'bool'
2833
+ * @BlueprintObject({
2834
+ * displayName: '变换',
2835
+ * properties: {
2836
+ * position: Schema.vector2(),
2837
+ * rotation: Schema.float(),
2838
+ * scale: Schema.vector2({ defaultValue: { x: 1, y: 1 } })
2839
+ * }
2521
2840
  * })
2522
- * attack(target: Entity, damage: number): boolean { }
2523
- *
2524
- * @BlueprintMethod({ displayName: '获取速度', isPure: true, returnType: 'float' })
2525
- * getSpeed(): number { return this.speed; }
2841
+ * transform: Transform;
2526
2842
  * ```
2527
2843
  */
2844
+ declare function BlueprintObject(options: BlueprintObjectOptions): PropertyDecorator;
2528
2845
  declare function BlueprintMethod(options?: BlueprintMethodOptions): MethodDecorator;
2529
- /**
2530
- * @zh 从 TypeScript 类型名推断蓝图引脚类型
2531
- * @en Infer blueprint pin type from TypeScript type name
2532
- */
2533
2846
  declare function inferPinType(typeName: string): BlueprintPinType;
2534
2847
 
2535
2848
  /**
@@ -2633,4 +2946,4 @@ declare function registerComponentNodes(componentClass: Function): void;
2633
2946
  */
2634
2947
  declare function registerComponentClass(typeName: string, componentClass: new () => Component): void;
2635
2948
 
2636
- 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 };
2949
+ export { AlwaysFalseCondition, AlwaysTrueCondition, type ArrayOperation, type ArraySchema, BlueprintArray, type BlueprintArrayOptions, 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, BlueprintObject, type BlueprintObjectOptions, 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 EnumOption, type EnumSchema, 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 ObjectSchema, type PathPart, type PathPartType, type PortAddress, type PrimitiveSchema, type PropertyMetadata, type PropertySchema, type RefSchema, RegisterNode, Schema, SchemaRegistry, type SlotConnection, StateNameCondition, TimerIdCondition, type TriggerCallback, type TriggerConfig, type TriggerContext, TriggerDispatcher, TriggerRegistry, type TriggerResult, type TriggerType, TriggerTypeCondition, TriggerTypes, type ValidationError, type ValidationResult, type VariableScope, arePinTypesCompatible, buildPath, buildPortPath, clearRegisteredComponents, cloneSchema, 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, deleteByPath, expandWildcardPath, fragmentFromAsset, fragmentToAsset, generateComponentNodes, getBlueprintMetadata, getByPath, getNodeCategoryColor, getParentPath, getPathLastName, getPinTypeColor, getPrimitiveDefaultValue, getRegisteredBlueprintComponents, getSchemaDefaultValue, hasPath, hasWildcard, inferPinType, mergeObjectSchemas, parsePath, parsePortPath, registerAllComponentNodes, registerComponentClass, registerComponentNodes, schemaToPinType, setByPath, updatePathOnArrayChange, validateBlueprintAsset, validateSchema };