@cjhd/cj-ecs 1.0.0 → 1.0.1

package/assets/ecs/EcsEntity.d.ts

@@ -0,0 +1,148 @@
+import { Node } from 'cc';
+import { EcsBaseEntity, IComponent, IECS, IEntity, ITypeofComponent } from '../lib/EcsObject';
+import { EcsComponent } from './EcsComponent';
+export declare class EcsEntity extends EcsBaseEntity implements IEntity {
+    /**位运算 */
+    private flag;
+    private instNames;
+    /**组件的名字 => 组件数组 */
+    private instNameToComps;
+    /**组件父类的名字 => 组件数组 */
+    private superNameToComps;
+    private _isValid;
+    /**是否有效 */
+    get isValid(): boolean;
+    private set isValid(value);
+    private _enabled;
+    /**标记是否生效 */
+    get enabled(): boolean;
+    set enabled(value: boolean);
+    /**指定ecs */
+    private _ecs;
+    /**获取对应的ecs */
+    protected get ecs(): IECS;
+    /**节点 */
+    private _node;
+    get node(): Node | null;
+    set node(value: Node | null);
+    /**标记是否已经销毁 */
+    private _isDestroyed;
+    /**
+     * 内部初始化函数
+     */
+    protected innerInit(ecs: IECS, node?: Node | null): void;
+    /**
+     * 添加组件(内部调用)
+     */
+    protected innerAddComponent(com: EcsComponent): void;
+    /**
+     * 移除组件(内部调用)
+     */
+    protected innerRemoveComponent(com: EcsComponent): void;
+    /**
+     * 根据组件名字获取对应的组件数组(先查inst再查询super)
+     */
+    private getCompsByName;
+    /**
+     * 根据组件名字获取对应的组件数组(先查inst再查询super)
+     */
+    private getCompsByName2;
+    /**
+     * 移除当前所有组件
+     */
+    private clear;
+    /**
+     * 销毁
+     */
+    destroy(): boolean;
+    /**添加*/
+    protected onAdd(): void;
+    /**生效*/
+    protected onEnable(): void;
+    /**失效*/
+    protected onDisable(): void;
+    /**移除*/
+    protected onRemove(): void;
+    /**
+     * 检查是否包含全部
+     */
+    checkFlagAll(flag: number[]): boolean;
+    /**
+     * 检查是否包含任一
+     */
+    checkFlagAny(flag: number[]): boolean;
+    /**
+     * 检查是否仅包含全部
+     */
+    checkFlagOnly(flag: number[]): boolean;
+    /**
+     * 根据组件名字检查是否存在启用且有效的组件
+     */
+    hasEnabledComponentName(componentName: string): boolean;
+    /**
+     * 添加相应类型的组件
+     * @see 同add
+     * @param param 类型
+     */
+    addComponent<T extends ITypeofComponent>(param: T | IComponent): InstanceType<T> | null;
+    /**
+     * 添加相应类型的组件
+     * @param param 类型
+     */
+    add<T extends ITypeofComponent>(param: T | IComponent): InstanceType<T> | null;
+    /**
+     * 移除相应类型的第一个组件
+     * @see 同remove
+     * @param param 类型或实例(当组件开启allowMultiple后，需要传入实例)
+     */
+    removeComponent(param: ITypeofComponent | IComponent): boolean;
+    /**
+     * 移除相应类型的第一个组件
+     * @param param 类型或实例(当组件开启allowMultiple后，需要传入实例)
+     */
+    remove(param: ITypeofComponent | IComponent): boolean;
+    /**
+     * 移除相应组件的所有组件
+     * @see 同removeAll
+     * @param Com 类型
+     */
+    removeComponents(Com: ITypeofComponent): boolean;
+    /**
+     * 移除相应组件的所有组件
+     * @param Com 类型
+     */
+    removeAll(Com: ITypeofComponent): boolean;
+    /**
+     * 有没有相应类型的组件
+     * @see 同has
+     * @param Com 类型
+     */
+    hasComponent(Com: ITypeofComponent): boolean;
+    /**
+     * 有没有相应类型的组件
+     * @param Com 类型
+     */
+    has(Com: ITypeofComponent): boolean;
+    /**
+     * 获取相应类型的组件
+     * @see 同get
+     * @param Com 类型
+     */
+    getComponent<T extends ITypeofComponent>(Com: T): InstanceType<T> | null;
+    /**
+     * 获取相应类型的组件
+     * @param Com 类型
+     */
+    get<T extends ITypeofComponent>(Com: T): InstanceType<T> | null;
+    /**
+     * 获取相应类型的组件
+     * @see 同getAll
+     * @param Com 类型
+     */
+    getComponents<T extends ITypeofComponent>(Com: T): InstanceType<T>[];
+    /**
+     * 获取相应类型的组件
+     * @param Com 类型
+     */
+    getAll<T extends ITypeofComponent>(Com: T): InstanceType<T>[];
+}

package/assets/ecs/EcsSingleton.d.ts

@@ -0,0 +1,3 @@
+import { EcsBaseSingleton, ISingleton } from '../lib/EcsObject';
+export declare class EcsSingleton extends EcsBaseSingleton implements ISingleton {
+}

package/assets/ecs/EcsSystem.d.ts

@@ -0,0 +1,96 @@
+import { Node } from 'cc';
+import { EcsBaseSystem, IComponent, IECS, IEntity, IEntityUUID, IFilter, ISystem, ITypeofEntity, ITypeofSingleton } from '../lib/EcsObject';
+import { TimerManager } from '../lib/EcsTimer';
+import { TweenManager } from '../lib/EcsTween';
+import type { IEcsObservedQuery } from './EcsDirty';
+export declare class EcsSystem extends EcsBaseSystem implements ISystem {
+    static matchEntity(system: EcsSystem, entity: IEntity): void;
+    private _ecs;
+    /**获取对应的ecs */
+    protected get ecs(): IECS;
+    /** observed runtime 查询入口。未安装 cj-ecs-observed 时为 null，系统需要自行兜底。 */
+    protected get observed(): IEcsObservedQuery | null;
+    private set ecs(value);
+    /**
+     * Timer管理器
+     * @example
+     * // 创建timer
+     * const timer = new Timer(() => { consoe.log('timer'); });
+     * timer.delay(1);
+     * timer.repeat(10);
+     * // 添加管理
+     * this.timer.add(timer);
+     * // 迭代一次
+     * this.timer.step(dt);
+     */
+    protected timer: TimerManager;
+    /**
+     * Tween管理器
+     * @example
+     * // 创建tween
+     * const tween = new Tween(ECS组件实例);
+     * tween.to(1, ...);
+     * tween.delay(1);
+     * tween.by(1, ...);
+     * // 添加管理
+     * this.tween.add(tween);
+     * // 迭代一次
+     * this.tween.step(dt);
+     */
+    protected tween: TweenManager;
+    /**
+     * 指定ecs
+     */
+    constructor(ecs: IECS);
+    /**添加 */
+    protected onAdd(): void;
+    /**移除 */
+    protected onRemove(): void;
+    /**查询实体 */
+    protected query<T extends IEntity>(filter: IFilter): T[];
+    protected query<T extends IComponent>(filter: IFilter, Component: {
+        new (): T;
+    }): T[];
+    /**查询实体 */
+    protected find<T extends IEntity>(filter: IFilter): T | null;
+    protected find<T extends IComponent>(filter: IFilter, Component: {
+        new (): T;
+    }): T | null;
+    /**是否存在实体 */
+    protected exist(filter: IFilter): boolean;
+    /**遍历当前系统 matcher 命中的实体，避免 query(this.matcher) 每帧分配数组 */
+    protected forEachMatchedEntity<T extends IEntity = IEntity>(handle: (entity: T) => void): void;
+    /**当前系统 matcher 命中的实体数量 */
+    protected get matchedEntityCount(): number;
+    /**创建实体 */
+    protected createEntity<T extends ITypeofEntity>(Entity: T, options?: Node | {
+        node?: Node;
+    }): InstanceType<T>;
+    /**查询实体 */
+    protected findByUuid(uuid: IEntityUUID): IEntity;
+    /**是否存在实体 */
+    protected existByUuid(uuid: IEntityUUID): boolean;
+    /**获取单例组件 */
+    protected getSingleton<T extends ITypeofSingleton>(param: T): InstanceType<T>;
+    /**
+     * 过滤实体
+     * - 配置后才能响应onEntityEnter、onEntityLeave
+     * - 如果query、find、exist方法中的值与matcher中的值相同，则会直接从缓存中获取实体
+     */
+    protected matcher: IFilter | null;
+    /**实体进入系统，会在execute流程最开始调用*/
+    protected onEntityEnter(entity: IEntity): void;
+    /**实体离开系统，会在execute流程最开始调用*/
+    protected onEntityLeave(entity: IEntity): void;
+    private matchEntities;
+    private matchEntity;
+    protected execute(dt?: number, ...args: any[]): void;
+    protected beforeExecute(dt?: number, ...args: any[]): void;
+    protected afterExecute(dt?: number, ...args: any[]): void;
+    protected update(dt?: number, ...args: any[]): void;
+    protected beforeUpdate(dt?: number, ...args: any[]): void;
+    protected afterUpdate(dt?: number, ...args: any[]): void;
+    protected log(...args: any[]): void;
+    protected warn(...args: any[]): void;
+    protected error(...args: any[]): void;
+}

package/assets/ecs.d.ts

@@ -0,0 +1,126 @@
+import { Node } from 'cc';
+import type { IEcsComponentDirtySink, IEcsObservedQuery } from './ecs/EcsDirty';
+import { Filter } from './lib/EcsFilter';
+import { IComponent, IECS, IEntity, IEntityUUID, ISingleton, ITypeofEntity, ITypeofSingleton, ITypeofSystem } from './lib/EcsObject';
+export declare class ECS implements IECS {
+    static create(): IECS;
+    private entityManager;
+    private systemManager;
+    private componentManager;
+    private singletons;
+    private mutationDepth;
+    private dirtyEntities;
+    private dirtySink;
+    private observedQuery;
+    /**
+     * 查询实体
+     */
+    query<T extends IEntity>(filter: Filter): T[];
+    query<T extends IComponent>(filter: Filter, Component: {
+        new (): T;
+    }): T[];
+    /**
+     * 查询实体
+     */
+    find<T extends IEntity>(filter: Filter): T | null;
+    find<T extends IComponent>(filter: Filter, Component: {
+        new (): T;
+    }): T | null;
+    /**
+     * 查询实体是否存在
+     */
+    exist(filter: Filter): boolean;
+    /**
+     * 根据uuid查询实体
+     */
+    findByUuid(uuid: IEntityUUID): IEntity;
+    /**
+     * 根据uuid查询实体是否存在
+     */
+    existByUuid(uuid: IEntityUUID): boolean;
+    /**
+     * 添加单例组件
+     */
+    addSingleton<T extends ITypeofSingleton>(param: T): InstanceType<T>;
+    addSingleton<T extends ISingleton>(param: T): T;
+    /**
+     * 获取单例组件
+     */
+    getSingleton<T extends ITypeofSingleton>(param: T): InstanceType<T> | null;
+    /**
+     * 移除单例组件
+     */
+    removeSingleton<T extends ITypeofSingleton>(param: T): InstanceType<T> | null;
+    /**
+     * 创建一个实体
+     */
+    createEntity<T extends ITypeofEntity>(Entity: T, options?: Node | {
+        node?: Node;
+    }): InstanceType<T>;
+    /**
+     * 移除一个实体
+     */
+    removeEntity(entity: IEntity): void;
+    /**
+     * 添加一个组件
+     */
+    addComponent(entity: IEntity, component: IComponent): void;
+    /**
+     * 移除一个组件
+     */
+    removeComponent(component: IComponent): void;
+    /**
+    * 添加一个系统
+    */
+    addSystem<T extends ITypeofSystem>(System: T): void;
+    /**
+     * 移除一个系统
+     */
+    removeSystem<T extends ITypeofSystem>(System: T): void;
+    /**
+     * 清理所有数据
+     */
+    clear(): void;
+    /**
+     * 安装/卸载 dirty sink。
+     * observed runtime 通过这里接管组件 dirty 通知；传 null 后核心 ECS 仍可独立运行。
+     */
+    setDirtySink(sink: IEcsComponentDirtySink | null): void;
+    /** 获取当前 dirty sink，主要给扩展包链式安装/恢复使用。 */
+    getDirtySink(): IEcsComponentDirtySink | null;
+    /**
+     * 安装/卸载 observed 查询入口。
+     * 系统内可通过 this.observed 或 ecs.getObservedQuery() 获取 dirty/fieldDirty/index 查询。
+     * @param query 查询入口
+     */
+    setObservedQuery(query: IEcsObservedQuery | null): void;
+    /** 获取 observed 查询入口；未安装 observed runtime 时返回 null。
+     * @returns 查询入口
+    */
+    getObservedQuery(): IEcsObservedQuery | null;
+    /** 开始批量结构变更，延迟刷新系统 matcher。适合一次性添加/移除多个组件。 */
+    beginMutation(): void;
+    /** 结束批量结构变更，并统一刷新受影响实体的系统 matcher。 */
+    endMutation(): void;
+    private markEntityDirty;
+    private refreshEntitySystems;
+    private executeSystem;
+    private beforeExecuteSystem;
+    private afterExecuteSystem;
+    private updateSystem;
+    private beforeUpdateSystem;
+    private afterUpdateSystem;
+    /**
+     * 用于逻辑帧
+     * 执行顺序:
+     * [系统的beforeExecute] -> [系统的execute] ->[系统的afterExecute]
+     */
+    execute(dt: number, ...args: any[]): void;
+    /**
+     * 用于渲染帧
+     * 执行顺序:
+     * [系统的beforeUpdate] -> [系统的update] -> [系统的afterUpdate]
+     */
+    update(dt: number, ...args: any[]): void;
+}
+export declare const ecs: IECS;

package/assets/lib/EcsCache.d.ts

@@ -0,0 +1,24 @@
+import { IComponent, IEntity } from './EcsObject';
+/**缓存 */
+declare class Cache<V> {
+    private cache;
+    get(): V;
+    put(v: V): void;
+    clear(): void;
+}
+/**实体缓存 */
+export declare const entityCache: Cache<IEntity>;
+/**缓存映射 */
+declare class CacheMap<V> {
+    /**缓存 */
+    private cache;
+    /**从指定缓存数组中获取并移除元素 */
+    get(k: string): V;
+    /**将元素添加到指定缓存数组中 */
+    put(k: string, v: V): void;
+    /**清空缓存 */
+    clear(): void;
+}
+/**组件缓存 */
+export declare const componentCache: CacheMap<IComponent<IEntity>>;
+export {};

package/assets/lib/EcsFilter.d.ts

@@ -0,0 +1,57 @@
+import { ComponentManager, EntityManager } from './EcsManager';
+import { IEntity, IFilter, ITypeofComponent } from './EcsObject';
+/**
+ * 过滤器
+ */
+export declare class Filter implements IFilter {
+    static check(entity: IEntity, filter: Filter): boolean;
+    /**查询实体
+     * @param entityManager 实体管理器
+     * @param componentManager 组件管理器
+     * @param filter 过滤器
+     * @returns 符合筛选条件的实体数组
+    */
+    static query(entityManager: EntityManager, componentManager: ComponentManager, filter: Filter): IEntity[];
+    /**查询实体
+     * @param entityManager 实体管理器
+     * @param componentManager 组件管理器
+     * @param filter 过滤器
+     * @returns 符合筛选条件的实体
+    */
+    static find(entityManager: EntityManager, componentManager: ComponentManager, filter: Filter): IEntity;
+    private anyList;
+    private include;
+    private hasSearch;
+    private hasExclude;
+    private pipeline;
+    /**
+     * 有这些组件中的任何一个组件
+     * @param Comps 组件类型
+     * @returns this
+     */
+    any(...Comps: ITypeofComponent[]): this;
+    /**
+     * 必须包含所有这些组件
+     * 让数量最少的组件作为第一个参数，会获得更好的性能
+     * @param Comps 组件类型
+     * @returns this
+     */
+    all(...Comps: ITypeofComponent[]): this;
+    /**
+     * 仅仅只有这些组件
+     * 让数量最少的组件作为第一个参数，会获得更好的性能
+     * @param Comps 组件类型
+     * @returns this
+     */
+    only(...Comps: ITypeofComponent[]): this;
+    /**
+     * 不能包含其中的任何一个组件
+     * @param Comps 组件类型
+     * @returns this
+     */
+    exclude(...Comps: ITypeofComponent[]): this;
+}
+/**
+ * 过滤条件
+ */
+export declare const filter: IFilter;

package/assets/lib/EcsManager.d.ts

@@ -0,0 +1,251 @@
+import { EcsBase, IComponent, IComponentName, IEntity, IEntityUUID, IFlag, ISystem, ITypeofSystem } from './EcsObject';
+import { CustomArray } from './EcsUtils';
+/**
+ * 根据名获取类，用于通过组件名字获取组件类
+ */
+export declare function getClassByName(name: IComponentName): typeof EcsBase;
+/**
+ * 类装饰器(组件与单例组件必须使用ecsclass)
+ */
+export declare function ecsclass(className: string): (ctor: any) => any;
+/**
+ * flag位管理器
+*/
+declare class FlagManager {
+    private index;
+    private cache;
+    private cacheAll;
+    /**
+     * 在source中添加flag
+     * @param source
+     * @param flag
+     */
+    addFlag(source: IFlag, flag: IFlag): void;
+    /**
+     * 在source中移除flag
+     * @param source
+     * @param flag
+     */
+    removeFlag(source: IFlag, flag: IFlag): void;
+    /**
+     * 检查是否完全包含
+     * @param source 源
+     * @param sub 子集
+     * @returns 是否完全包含子集
+     */
+    checkFlagAll(source: IFlag, sub: IFlag): boolean;
+    /**
+     * 只包含其中一个即可
+     * @param source 源
+     * @param sub 子集
+     * @returns 是否包含其中一个
+     */
+    checkFlagAny(source: IFlag, sub: IFlag): boolean;
+    /**
+     * 会融合父类的flag位
+     * @param name 组件类型名
+     * @returns 组件类型的flag位数组
+     */
+    getAllByName(name: string): IFlag;
+    /**
+     * 会融合父类的flag位
+     * @param names 组件类型名数组
+     * @param out 输出数组，用于存储融合后的flag位
+     * @returns 输出数组
+     */
+    getAllByNames(names: string[], out: number[]): IFlag;
+    /**
+     * 只计算自身的flag位
+     * @param name 组件类型名
+     * @returns 组件类型的flag位数组
+     */
+    getByName(name: string): IFlag;
+    /**
+     * 只计算自身的flag位
+     * @param names 组件类型名数组
+     * @returns 组件类型的flag位数组
+     */
+    getByNames(names: string[]): IFlag;
+    /**
+     * 获取flag位数量
+     * @returns flag位数量
+     */
+    get bits(): number;
+}
+export declare const flagManager: FlagManager;
+/**
+ * 类管理器
+ */
+declare class ClassManager {
+    /** 组件类数量 */
+    private comClassCount;
+    /** 类名到父类名的映射 */
+    private nameToSuperName;
+    /** 类名到类的映射 */
+    private nameToClass;
+    /**
+     * 获取父类
+     * @param type 类
+     * @returns 父类类型
+     */
+    private getSuper;
+    /**
+     * 添加一个类
+     * @param ctor 类构造函数
+     * @param className 类名
+     */
+    add(ctor: typeof EcsBase, className: string): void;
+    /**
+     * 遍历所有父类名，包括当前类
+     * @param subName 子类名
+     * @param callback 处理函数，用于对每个父类名进行操作
+     */
+    eachSuperName(subName: string, callback: (superName: string) => any): void;
+    /**
+     * 通过类名判断一个是否是另一个的子类
+     * @param subName 子类名
+     * @param superName 父类名
+     * @returns 是否是子类
+     */
+    isChildByName(subName: string, superName: string): boolean;
+    /**
+     * 通过类名获取一个类
+     * @param name 类名
+     * @returns 类
+     */
+    getClassByName(name: string): typeof EcsBase;
+    /**
+     * 获取父类名字
+     * @param name 类名
+     * @returns 父类名
+     */
+    getSuperName(name: string): string;
+    /**
+     * 组件种类数量
+     */
+    get comSize(): number;
+}
+/**类管理器 */
+export declare const classManager: ClassManager;
+/**
+ * 组件管理器
+ */
+export declare class ComponentManager {
+    /** 组件名到组件列表的映射 */
+    private components;
+    /**
+     * 获取或创建组件列表
+     * @param name 组件名
+     * @returns 组件列表
+     */
+    private getOrCreateComps;
+    /**
+     * 添加一个组件名对应的实体
+     * @param comName 组件名
+     * @param comp 组件
+     */
+    addComponent(comName: IComponentName, comp: IComponent): void;
+    /**
+     * 移除一个组件名对应的实体
+     * @param comName 组件名
+     * @param comp 组件
+     */
+    removeComponent(comName: IComponentName, comp: IComponent): void;
+    /**
+     * 根据组件名获取实体列表，可能不存在
+     * @param comName 组件名
+     * @returns 组件列表
+     */
+    getComponents(comName: IComponentName): CustomArray<IComponent<IEntity>>;
+    /**
+     * 清空所有组件
+     */
+    clear(): void;
+    /**
+     * @param callback 处理函数，用于对每个组件进行操作
+     * @returns 输出数组
+     */
+    eachUnique(callback: (component: IComponent) => void): void;
+}
+/**
+ * 实体管理器
+ */
+export declare class EntityManager {
+    /** 实体UUID到实体的映射 */
+    private entities;
+    /**
+     * 检查实体是否存在
+     * @param uuid 实体UUID
+     * @returns 是否存在
+     */
+    has(uuid: IEntityUUID): IEntity;
+    /**
+     * 添加一个实体
+     * @param entity 实体
+     */
+    add(entity: IEntity): void;
+    /**
+     * 移除一个实体
+     * @param entity 实体
+     * @returns 是否成功移除
+     */
+    remove(entity: IEntity): boolean;
+    /**
+     * 根据UUID获取一个实体
+     * @param uuid 实体UUID
+     * @returns 实体
+     */
+    get(uuid: IEntityUUID): IEntity;
+    /**
+     * 获取所有实体
+     * @param out 输出数组，用于存储所有实体
+     * @returns 输出数组
+     */
+    getAll(out: IEntity[]): IEntity[];
+    /**
+     * 遍历所有实体
+     * @param callback 处理函数，用于对每个实体进行操作
+     */
+    each(callback: (value: IEntity) => void): void;
+    /**
+     * 清空所有实体
+     */
+    clear(): void;
+}
+/**
+ * 系统管理器
+ */
+export declare class SystemManager {
+    private systems;
+    /**
+     * 添加一个系统
+     * @param system 系统
+     */
+    add(system: ISystem): void;
+    /**
+     * 根据系统名获取一个系统
+     * @param System 系统类型
+     * @returns 系统
+     */
+    get(System: ITypeofSystem): import("./EcsObject").EcsBaseSystem;
+    /**
+     * 移除一个系统
+     * @param System 系统类型
+     * @returns 是否成功移除
+     */
+    remove(System: ITypeofSystem): import("./EcsObject").EcsBaseSystem;
+    /**
+     * 清空所有系统
+     */
+    clear(): void;
+    /**
+     * 遍历所有系统
+     * @param callback 处理函数，用于对每个系统进行操作
+     */
+    each(callback: (value: ISystem) => void): void;
+    /**
+     * 系统数量
+     */
+    get size(): number;
+}
+export {};