@esengine/ecs-framework 2.1.29 → 2.1.30

package/bin/ECS/Entity.d.ts

@@ -0,0 +1,455 @@
+import { Component } from './Component';
+import { ComponentType } from './Core/ComponentStorage';
+import { EventBus } from './Core/EventBus';
+import { IBigIntLike } from './Utils/BigIntCompatibility';
+interface IScene {
+    readonly name: string;
+    readonly componentStorageManager: import('./Core/ComponentStorage').ComponentStorageManager;
+    readonly querySystem: import('./Core/QuerySystem').QuerySystem;
+    readonly eventSystem: import('./Core/EventSystem').TypeSafeEventSystem;
+    readonly entities: import('./Utils/EntityList').EntityList;
+    addEntity(entity: Entity): Entity;
+    initialize(): void;
+    update(deltaTime: number): void;
+}
+/**
+ * 实体比较器
+ *
+ * 用于比较两个实体的优先级，首先按更新顺序比较，然后按ID比较。
+ */
+export declare class EntityComparer {
+    /**
+     * 比较两个实体
+     *
+     * @param self - 第一个实体
+     * @param other - 第二个实体
+     * @returns 比较结果，负数表示self优先级更高，正数表示other优先级更高，0表示相等
+     */
+    compare(self: Entity, other: Entity): number;
+}
+/**
+ * 游戏实体类
+ *
+ * ECS架构中的实体（Entity），作为组件的容器。
+ * 实体本身不包含游戏逻辑，所有功能都通过组件来实现。
+ * 支持父子关系，可以构建实体层次结构。
+ *
+ * @example
+ * ```typescript
+ * // 创建实体
+ * const entity = new Entity("Player", 1);
+ *
+ * // 添加组件
+ * const healthComponent = entity.addComponent(new HealthComponent(100));
+ *
+ * // 获取组件
+ * const health = entity.getComponent(HealthComponent);
+ *
+ * // 添加位置组件
+ * entity.addComponent(new PositionComponent(100, 200));
+ *
+ * // 添加子实体
+ * const weapon = new Entity("Weapon", 2);
+ * entity.addChild(weapon);
+ * ```
+ */
+export declare class Entity {
+    /**
+     * Entity专用日志器
+     */
+    private static _logger;
+    /**
+     * 实体比较器实例
+     */
+    static entityComparer: EntityComparer;
+    /**
+     * 全局事件总线实例
+     * 用于发射组件相关事件
+     */
+    static eventBus: EventBus | null;
+    /**
+     * 实体名称
+     *
+     * 用于标识和调试的友好名称。
+     */
+    name: string;
+    /**
+     * 实体唯一标识符
+     *
+     * 在场景中唯一的数字标识符。
+     */
+    readonly id: number;
+    /**
+     * 组件集合
+     *
+     * 存储实体拥有的所有组件。
+     */
+    readonly components: Component[];
+    /**
+     * 所属场景引用
+     *
+     * 指向实体所在的场景实例。
+     */
+    scene: IScene | null;
+    /**
+     * 更新间隔
+     *
+     * 控制实体更新的频率，值越大更新越不频繁。
+     */
+    updateInterval: number;
+    /**
+     * 销毁状态标志
+     *
+     * 标记实体是否已被销毁。
+     */
+    _isDestroyed: boolean;
+    /**
+     * 父实体引用
+     *
+     * 指向父级实体，用于构建实体层次结构。
+     */
+    private _parent;
+    /**
+     * 子实体集合
+     *
+     * 存储所有子级实体的数组。
+     */
+    private _children;
+    /**
+     * 激活状态
+     *
+     * 控制实体是否处于激活状态。
+     */
+    private _active;
+    /**
+     * 实体标签
+     *
+     * 用于分类和查询的数字标签。
+     */
+    private _tag;
+    /**
+     * 启用状态
+     *
+     * 控制实体是否启用更新和处理。
+     */
+    private _enabled;
+    /**
+     * 更新顺序
+     *
+     * 控制实体在系统中的更新优先级。
+     */
+    private _updateOrder;
+    /**
+     * 组件位掩码
+     *
+     * 用于快速查询实体拥有的组件类型。
+     */
+    private _componentMask;
+    /**
+     * 组件类型到索引的映射
+     *
+     * 用于快速定位组件在数组中的位置。
+     */
+    private _componentTypeToIndex;
+    /**
+     * 构造函数
+     *
+     * @param name - 实体名称
+     * @param id - 实体唯一标识符
+     */
+    constructor(name: string, id: number);
+    /**
+     * 获取销毁状态
+     *
+     * @returns 如果实体已被销毁则返回true
+     */
+    get isDestroyed(): boolean;
+    /**
+     * 获取父实体
+     *
+     * @returns 父实体，如果没有父实体则返回null
+     */
+    get parent(): Entity | null;
+    /**
+     * 获取子实体数组的只读副本
+     *
+     * @returns 子实体数组的副本
+     */
+    get children(): readonly Entity[];
+    /**
+     * 获取子实体数量
+     *
+     * @returns 子实体的数量
+     */
+    get childCount(): number;
+    /**
+     * 获取活跃状态
+     *
+     * @returns 如果实体处于活跃状态则返回true
+     */
+    get active(): boolean;
+    /**
+     * 设置活跃状态
+     *
+     * 设置实体的活跃状态，会影响子实体的有效活跃状态。
+     *
+     * @param value - 新的活跃状态
+     */
+    set active(value: boolean);
+    /**
+     * 获取实体的有效活跃状态
+     *
+     * 考虑父实体的活跃状态，只有当实体本身和所有父实体都处于活跃状态时才返回true。
+     *
+     * @returns 有效的活跃状态
+     */
+    get activeInHierarchy(): 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(): IBigIntLike;
+    /**
+     * 创建并添加组件
+     *
+     * @param componentType - 组件类型
+     * @param args - 组件构造函数参数
+     * @returns 创建的组件实例
+     */
+    createComponent<T extends Component>(componentType: ComponentType<T>, ...args: unknown[]): T;
+    /**
+     * 内部添加组件方法（不进行重复检查，用于初始化）
+     *
+     * @param component - 要添加的组件实例
+     * @returns 添加的组件实例
+     */
+    private addComponentInternal;
+    /**
+     * 添加组件到实体
+     *
+     * @param component - 要添加的组件实例
+     * @returns 添加的组件实例
+     * @throws {Error} 如果组件类型已存在
+     */
+    addComponent<T extends Component>(component: T): T;
+    /**
+     * 获取指定类型的组件
+     *
+     * @param type - 组件类型
+     * @returns 组件实例或null
+     */
+    getComponent<T extends Component>(type: ComponentType<T>): T | null;
+    /**
+     * 重建组件索引映射
+     */
+    private rebuildComponentIndex;
+    /**
+     * 检查实体是否有指定类型的组件
+     *
+     * @param type - 组件类型
+     * @returns 如果有该组件则返回true
+     */
+    hasComponent<T extends Component>(type: ComponentType<T>): boolean;
+    /**
+     * 获取或创建指定类型的组件
+     *
+     * @param type - 组件类型
+     * @param args - 组件构造函数参数（仅在创建时使用）
+     * @returns 组件实例
+     */
+    getOrCreateComponent<T extends Component>(type: ComponentType<T>, ...args: unknown[]): 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[];
+    /**
+     * 添加子实体
+     *
+     * @param child - 要添加的子实体
+     * @returns 添加的子实体
+     */
+    addChild(child: Entity): Entity;
+    /**
+     * 移除子实体
+     *
+     * @param child - 要移除的子实体
+     * @returns 是否成功移除
+     */
+    removeChild(child: Entity): boolean;
+    /**
+     * 移除所有子实体
+     */
+    removeAllChildren(): void;
+    /**
+     * 根据名称查找子实体
+     *
+     * @param name - 子实体名称
+     * @param recursive - 是否递归查找
+     * @returns 找到的子实体或null
+     */
+    findChild(name: string, recursive?: boolean): Entity | null;
+    /**
+     * 根据标签查找子实体
+     *
+     * @param tag - 标签
+     * @param recursive - 是否递归查找
+     * @returns 找到的子实体数组
+     */
+    findChildrenByTag(tag: number, recursive?: boolean): Entity[];
+    /**
+     * 获取根实体
+     *
+     * @returns 层次结构的根实体
+     */
+    getRoot(): Entity;
+    /**
+     * 检查是否是指定实体的祖先
+     *
+     * @param entity - 要检查的实体
+     * @returns 如果是祖先则返回true
+     */
+    isAncestorOf(entity: Entity): boolean;
+    /**
+     * 检查是否是指定实体的后代
+     *
+     * @param entity - 要检查的实体
+     * @returns 如果是后代则返回true
+     */
+    isDescendantOf(entity: Entity): boolean;
+    /**
+     * 获取层次深度
+     *
+     * @returns 在层次结构中的深度（根实体为0）
+     */
+    getDepth(): number;
+    /**
+     * 遍历所有子实体（深度优先）
+     *
+     * @param callback - 对每个子实体执行的回调函数
+     * @param recursive - 是否递归遍历
+     */
+    forEachChild(callback: (child: Entity, index: number) => void, recursive?: boolean): void;
+    /**
+     * 活跃状态改变时的回调
+     */
+    private onActiveChanged;
+    /**
+     * 更新实体
+     *
+     * 调用所有组件的更新方法，并更新子实体。
+     */
+    update(): void;
+    /**
+     * 销毁实体
+     *
+     * 移除所有组件、子实体并标记为已销毁。
+     */
+    destroy(): void;
+    /**
+     * 比较实体
+     *
+     * @param other - 另一个实体
+     * @returns 比较结果
+     */
+    compareTo(other: Entity): number;
+    /**
+     * 获取实体的字符串表示
+     *
+     * @returns 实体的字符串描述
+     */
+    toString(): string;
+    /**
+     * 获取实体的调试信息（包含组件缓存信息）
+     *
+     * @returns 包含实体详细信息的对象
+     */
+    getDebugInfo(): {
+        name: string;
+        id: number;
+        enabled: boolean;
+        active: boolean;
+        activeInHierarchy: boolean;
+        destroyed: boolean;
+        componentCount: number;
+        componentTypes: string[];
+        componentMask: string;
+        parentId: number | null;
+        childCount: number;
+        childIds: number[];
+        depth: number;
+        indexMappingSize: number;
+    };
+}
+export {};
+//# 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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"}