@esengine/ecs-framework 2.2.21 → 2.3.0

package/bin/ECS/Decorators/index.d.ts

@@ -0,0 +1,7 @@
+export { ECSComponent, ECSSystem, getComponentTypeName, getSystemTypeName, getComponentInstanceTypeName, getSystemInstanceTypeName, getSystemMetadata, getComponentDependencies, COMPONENT_TYPE_NAME, COMPONENT_DEPENDENCIES, SYSTEM_TYPE_NAME } from './TypeDecorators';
+export type { SystemMetadata, ComponentOptions } from './TypeDecorators';
+export { EntityRef, getEntityRefMetadata, hasEntityRef, ENTITY_REF_METADATA } from './EntityRefDecorator';
+export type { EntityRefMetadata } from './EntityRefDecorator';
+export { Property, getPropertyMetadata, hasPropertyMetadata, PROPERTY_METADATA } from './PropertyDecorator';
+export type { PropertyOptions, PropertyType, PropertyControl, PropertyAction, AssetType, EnumOption } from './PropertyDecorator';
+//# sourceMappingURL=index.d.ts.map

package/bin/ECS/Decorators/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ECS/Decorators/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,YAAY,EACZ,SAAS,EACT,oBAAoB,EACpB,iBAAiB,EACjB,4BAA4B,EAC5B,yBAAyB,EACzB,iBAAiB,EACjB,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EACnB,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzE,OAAO,EACH,SAAS,EACT,oBAAoB,EACpB,YAAY,EACZ,mBAAmB,EACtB,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,OAAO,EACH,QAAQ,EACR,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACpB,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC"}

package/bin/ECS/Decorators/index.js

@@ -0,0 +1,4 @@
+export { ECSComponent, ECSSystem, getComponentTypeName, getSystemTypeName, getComponentInstanceTypeName, getSystemInstanceTypeName, getSystemMetadata, getComponentDependencies, COMPONENT_TYPE_NAME, COMPONENT_DEPENDENCIES, SYSTEM_TYPE_NAME } from './TypeDecorators';
+export { EntityRef, getEntityRefMetadata, hasEntityRef, ENTITY_REF_METADATA } from './EntityRefDecorator';
+export { Property, getPropertyMetadata, hasPropertyMetadata, PROPERTY_METADATA } from './PropertyDecorator';
+//# sourceMappingURL=index.js.map

package/bin/ECS/Decorators/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ECS/Decorators/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,YAAY,EACZ,SAAS,EACT,oBAAoB,EACpB,iBAAiB,EACjB,4BAA4B,EAC5B,yBAAyB,EACzB,iBAAiB,EACjB,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EACnB,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EACH,SAAS,EACT,oBAAoB,EACpB,YAAY,EACZ,mBAAmB,EACtB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EACH,QAAQ,EACR,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACpB,MAAM,qBAAqB,CAAC"}

package/bin/ECS/Entity.d.ts

@@ -0,0 +1,415 @@
+import { Component } from './Component';
+import { ComponentType } from './Core/ComponentStorage';
+import { EEntityLifecyclePolicy } from './Core/EntityLifecyclePolicy';
+import { BitMask64Data } from './Utils/BigIntCompatibility';
+import type { IScene } from './IScene';
+/**
+ * 实体比较器
+ *
+ * 用于比较两个实体的优先级，首先按更新顺序比较，然后按ID比较。
+ */
+export declare class EntityComparer {
+    /**
+     * 比较两个实体
+     *
+     * @param self - 第一个实体
+     * @param other - 第二个实体
+     * @returns 比较结果，负数表示self优先级更高，正数表示other优先级更高，0表示相等
+     */
+    compare(self: Entity, other: Entity): number;
+}
+/**
+ * 游戏实体类
+ *
+ * ECS架构中的实体（Entity），作为组件的容器。
+ * 实体本身不包含游戏逻辑，所有功能都通过组件来实现。
+ *
+ * 层级关系通过 HierarchyComponent 和 HierarchySystem 管理，
+ * 而非 Entity 内置属性，符合 ECS 组合原则。
+ *
+ * @example
+ * ```typescript
+ * // 创建实体
+ * const entity = scene.createEntity("Player");
+ *
+ * // 添加组件
+ * const healthComponent = entity.addComponent(new HealthComponent(100));
+ *
+ * // 获取组件
+ * const health = entity.getComponent(HealthComponent);
+ *
+ * // 层级关系使用 HierarchySystem
+ * const hierarchySystem = scene.getSystem(HierarchySystem);
+ * hierarchySystem.setParent(childEntity, parentEntity);
+ * ```
+ */
+export declare class Entity {
+    /**
+     * Entity专用日志器
+     */
+    private static _logger;
+    /**
+     * 实体比较器实例
+     */
+    static entityComparer: EntityComparer;
+    /**
+     * 实体名称
+     */
+    name: string;
+    /**
+     * 实体唯一标识符
+     */
+    readonly id: number;
+    /**
+     * 所属场景引用
+     */
+    scene: IScene | null;
+    /**
+     * 销毁状态标志
+     */
+    private _isDestroyed;
+    /**
+     * 激活状态
+     */
+    private _active;
+    /**
+     * 实体标签
+     */
+    private _tag;
+    /**
+     * 启用状态
+     */
+    private _enabled;
+    /**
+     * 更新顺序
+     */
+    private _updateOrder;
+    /**
+     * 组件位掩码（用于快速 hasComponent 检查）
+     */
+    private _componentMask;
+    /**
+     * 懒加载的组件数组缓存
+     */
+    private _componentCache;
+    /**
+     * 生命周期策略
+     *
+     * Lifecycle policy for scene transitions.
+     */
+    private _lifecyclePolicy;
+    /**
+     * 构造函数
+     *
+     * @param name - 实体名称
+     * @param id - 实体唯一标识符
+     */
+    constructor(name: string, id: number);
+    /**
+     * 获取生命周期策略
+     *
+     * Get lifecycle policy.
+     */
+    get lifecyclePolicy(): EEntityLifecyclePolicy;
+    /**
+     * 检查实体是否为持久化实体
+     *
+     * Check if entity is persistent (survives scene transitions).
+     */
+    get isPersistent(): boolean;
+    /**
+     * 设置实体为持久化（跨场景保留）
+     *
+     * 标记后的实体在场景切换时不会被销毁，会自动迁移到新场景。
+     *
+     * Mark entity as persistent (survives scene transitions).
+     * Persistent entities are automatically migrated to the new scene.
+     *
+     * @returns this，支持链式调用 | Returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * const player = scene.createEntity('Player')
+     *     .setPersistent()
+     *     .addComponent(new PlayerComponent());
+     * ```
+     */
+    setPersistent(): this;
+    /**
+     * 设置实体为场景本地（随场景销毁）
+     *
+     * 将实体恢复为默认行为。
+     *
+     * Mark entity as scene-local (destroyed with scene).
+     * Restores default behavior.
+     *
+     * @returns this，支持链式调用 | Returns this for chaining
+     */
+    setSceneLocal(): this;
+    /**
+     * 获取销毁状态
+     * @returns 如果实体已被销毁则返回true
+     */
+    get isDestroyed(): boolean;
+    /**
+     * 设置销毁状态（内部使用）
+     *
+     * 此方法供Scene和批量操作使用，以提高性能。
+     * 不应在普通业务逻辑中调用，应使用destroy()方法。
+     *
+     * @internal
+     */
+    setDestroyedState(destroyed: boolean): void;
+    /**
+     * 获取组件数组（懒加载）
+     * @returns 只读的组件数组
+     */
+    get components(): readonly Component[];
+    /**
+     * 从存储重建组件缓存
+     */
+    private _rebuildComponentCache;
+    /**
+     * 获取活跃状态
+     *
+     * @returns 如果实体处于活跃状态则返回true
+     */
+    get active(): boolean;
+    /**
+     * 设置活跃状态
+     *
+     * @param value - 新的活跃状态
+     */
+    set active(value: boolean);
+    /**
+     * 获取实体标签
+     *
+     * @returns 实体的数字标签
+     */
+    get tag(): number;
+    /**
+     * 设置实体标签
+     *
+     * @param value - 新的标签值
+     */
+    set tag(value: number);
+    /**
+     * 获取启用状态
+     *
+     * @returns 如果实体已启用则返回true
+     */
+    get enabled(): boolean;
+    /**
+     * 设置启用状态
+     *
+     * @param value - 新的启用状态
+     */
+    set enabled(value: boolean);
+    /**
+     * 获取更新顺序
+     *
+     * @returns 实体的更新顺序值
+     */
+    get updateOrder(): number;
+    /**
+     * 设置更新顺序
+     *
+     * @param value - 新的更新顺序值
+     */
+    set updateOrder(value: number);
+    /**
+     * 获取组件位掩码
+     *
+     * @returns 实体的组件位掩码
+     */
+    get componentMask(): BitMask64Data;
+    /**
+     * 创建并添加组件
+     *
+     * @param componentType - 组件类型构造函数
+     * @param args - 组件构造函数参数
+     * @returns 创建的组件实例
+     *
+     * @example
+     * ```typescript
+     * const position = entity.createComponent(Position, 100, 200);
+     * const health = entity.createComponent(Health, 100);
+     * ```
+     */
+    createComponent<T extends Component>(componentType: ComponentType<T>, ...args: ConstructorParameters<ComponentType<T>>): T;
+    /**
+     * 内部添加组件方法（不进行重复检查，用于初始化）
+     *
+     * @param component - 要添加的组件实例
+     * @returns 添加的组件实例
+     */
+    private addComponentInternal;
+    /**
+     * 通知Scene中的QuerySystem实体组件发生变动
+     *
+     * Notify the QuerySystem in Scene that entity components have changed
+     *
+     * @param changedComponentType 变化的组件类型（可选，用于优化通知） | Changed component type (optional, for optimized notification)
+     */
+    private notifyQuerySystems;
+    /**
+     * 添加组件到实体
+     *
+     * @param component - 要添加的组件实例
+     * @returns 添加的组件实例
+     * @throws {Error} 如果实体已存在该类型的组件
+     *
+     * @example
+     * ```typescript
+     * const position = new Position(100, 200);
+     * entity.addComponent(position);
+     * ```
+     */
+    addComponent<T extends Component>(component: T): T;
+    /**
+     * 获取指定类型的组件
+     *
+     * @param type - 组件类型构造函数
+     * @returns 组件实例，如果不存在则返回null
+     *
+     * @example
+     * ```typescript
+     * const position = entity.getComponent(Position);
+     * if (position) {
+     *     position.x += 10;
+     *     position.y += 20;
+     * }
+     * ```
+     */
+    getComponent<T extends Component>(type: ComponentType<T>): T | null;
+    /**
+     * 检查实体是否拥有指定类型的组件
+     *
+     * @param type - 组件类型构造函数
+     * @returns 如果实体拥有该组件返回true，否则返回false
+     *
+     * @example
+     * ```typescript
+     * if (entity.hasComponent(Position)) {
+     *     const position = entity.getComponent(Position)!;
+     *     position.x += 10;
+     * }
+     * ```
+     */
+    hasComponent<T extends Component>(type: ComponentType<T>): boolean;
+    /**
+     * 获取或创建指定类型的组件
+     *
+     * 如果组件已存在则返回现有组件，否则创建新组件并添加到实体
+     *
+     * @param type - 组件类型构造函数
+     * @param args - 组件构造函数参数（仅在创建新组件时使用）
+     * @returns 组件实例
+     *
+     * @example
+     * ```typescript
+     * // 确保实体拥有Position组件
+     * const position = entity.getOrCreateComponent(Position, 0, 0);
+     * position.x = 100;
+     * ```
+     */
+    getOrCreateComponent<T extends Component>(type: ComponentType<T>, ...args: ConstructorParameters<ComponentType<T>>): T;
+    /**
+     * 移除指定的组件
+     *
+     * @param component - 要移除的组件实例
+     */
+    removeComponent(component: Component): void;
+    /**
+     * 移除指定类型的组件
+     *
+     * @param type - 组件类型
+     * @returns 被移除的组件实例或null
+     */
+    removeComponentByType<T extends Component>(type: ComponentType<T>): T | null;
+    /**
+     * 移除所有组件
+     */
+    removeAllComponents(): void;
+    /**
+     * 批量添加组件
+     *
+     * @param components - 要添加的组件数组
+     * @returns 添加的组件数组
+     */
+    addComponents<T extends Component>(components: T[]): T[];
+    /**
+     * 批量移除组件类型
+     *
+     * @param componentTypes - 要移除的组件类型数组
+     * @returns 被移除的组件数组
+     */
+    removeComponentsByTypes<T extends Component>(componentTypes: ComponentType<T>[]): (T | null)[];
+    /**
+     * 获取所有指定类型的组件
+     *
+     * @param type - 组件类型
+     * @returns 组件实例数组
+     */
+    getComponents<T extends Component>(type: ComponentType<T>): T[];
+    /**
+     * 获取指定基类的组件（支持继承查找）
+     *
+     * 与 getComponent() 不同，此方法使用 instanceof 检查，支持子类查找。
+     * 性能比位掩码查询稍慢，但支持继承层次结构。
+     *
+     * @param baseType - 组件基类类型
+     * @returns 第一个匹配的组件实例，如果不存在则返回 null
+     *
+     * @example
+     * ```typescript
+     * // 查找 CompositeNodeComponent 或其子类
+     * const composite = entity.getComponentByType(CompositeNodeComponent);
+     * if (composite) {
+     *     // composite 可能是 SequenceNode, SelectorNode 等
+     * }
+     * ```
+     */
+    getComponentByType<T extends Component>(baseType: ComponentType<T>): T | null;
+    /**
+     * 活跃状态改变时的回调
+     */
+    private onActiveChanged;
+    /**
+     * 销毁实体
+     *
+     * 移除所有组件并标记为已销毁。
+     * 层级关系的清理由 HierarchySystem 处理。
+     */
+    destroy(): void;
+    /**
+     * 比较实体
+     *
+     * @param other - 另一个实体
+     * @returns 比较结果
+     */
+    compareTo(other: Entity): number;
+    /**
+     * 获取实体的字符串表示
+     *
+     * @returns 实体的字符串描述
+     */
+    toString(): string;
+    /**
+     * 获取实体的调试信息（包含组件缓存信息）
+     *
+     * @returns 包含实体详细信息的对象
+     */
+    getDebugInfo(): {
+        name: string;
+        id: number;
+        enabled: boolean;
+        active: boolean;
+        destroyed: boolean;
+        componentCount: number;
+        componentTypes: string[];
+        componentMask: string;
+        cacheBuilt: boolean;
+    };
+}
+//# sourceMappingURL=Entity.d.ts.map

package/bin/ECS/Entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Entity.d.ts","sourceRoot":"","sources":["../../src/ECS/Entity.ts"],"names":[],"mappings":"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"}