@cjhd/cj-ecs 1.0.0

package/assets/ecs.ts

@@ -0,0 +1,339 @@
+import { Node } from 'cc';
+import { DEV, EDITOR } from 'cc/env';
+import { EcsComponent } from './ecs/EcsComponent';
+import { EcsSystem } from './ecs/EcsSystem';
+import type { IEcsComponentDirtySink, IEcsExtensionSink, IEcsObservedQuery } from './ecs/EcsDirty';
+import { entityCache } from './lib/EcsCache';
+import { Filter } from './lib/EcsFilter';
+import { ComponentManager, EntityManager, SystemManager } from './lib/EcsManager';
+import { EcsBase, EcsBaseEntity, EcsBaseSystem, IComponent, IECS, IEntity, IEntityUUID, ISingleton, ITypeofComponent, ITypeofEntity, ITypeofSingleton, ITypeofSystem } from './lib/EcsObject';
+
+export class ECS implements IECS {
+    static create(): IECS {
+        return new ECS() as IECS;
+    }
+
+    private entityManager = new EntityManager();
+    private systemManager = new SystemManager();
+    private componentManager = new ComponentManager();
+    private singletons: ISingleton[] = [];
+    private mutationDepth = 0;
+    private dirtyEntities: Map<IEntityUUID, IEntity> = new Map();
+    private dirtySink: IEcsComponentDirtySink | null = null;
+    private observedQuery: IEcsObservedQuery | null = null;
+
+    /**
+     * 查询实体
+     */
+    public query<T extends IEntity>(filter: Filter): T[];
+    public query<T extends IComponent>(filter: Filter, Component: { new(): T }): T[];
+    public query<T>(filter: Filter, Component?: any): T[] {
+        const entities = Filter.query(this.entityManager, this.componentManager, filter);
+        if (!Component) return entities as T[];
+        return entities.map(entity => entity.get(Component as ITypeofComponent)) as T[];
+    }
+
+    /**
+     * 查询实体
+     */
+    public find<T extends IEntity>(filter: Filter): T | null;
+    public find<T extends IComponent>(filter: Filter, Component: { new(): T }): T | null;
+    public find<T>(filter: Filter, Component?: any): T | null {
+        const entity = Filter.find(this.entityManager, this.componentManager, filter);
+        if (!entity) return null;
+        if (!Component) return entity as T;
+        return entity.get(Component as ITypeofComponent) as T;
+    }
+
+    /**
+     * 查询实体是否存在
+     */
+    public exist(filter: Filter) {
+        return !!Filter.find(this.entityManager, this.componentManager, filter);
+    }
+
+    /**
+     * 根据uuid查询实体
+     */
+    public findByUuid(uuid: IEntityUUID) {
+        return this.entityManager.get(uuid);
+    }
+
+    /**
+     * 根据uuid查询实体是否存在
+     */
+    public existByUuid(uuid: IEntityUUID) {
+        return !!this.entityManager.has(uuid);
+    }
+
+    /**
+     * 添加单例组件
+     */
+    public addSingleton<T extends ITypeofSingleton>(param: T): InstanceType<T>;
+    public addSingleton<T extends ISingleton>(param: T): T;
+    public addSingleton(param: ITypeofSingleton | ISingleton) {
+        if (DEV && param.ecsName === 'EcsBase') {
+            console.error('请使用ecsclass修饰', param);
+            return null;
+        }
+        const com = this.singletons.find(com => com.ecsName === param.ecsName);
+        if (com) return com;
+
+        if (param instanceof EcsBase) {
+            this.singletons.push(param);
+            return param;
+        } else {
+            const com = new param();
+            this.singletons.push(com);
+            return com;
+        }
+    }
+
+    /**
+     * 获取单例组件
+     */
+    public getSingleton<T extends ITypeofSingleton>(param: T): InstanceType<T> | null {
+        return this.singletons.find(com => com.ecsName === param.ecsName) as InstanceType<T> || null;
+    }
+
+    /**
+     * 移除单例组件
+     */
+    public removeSingleton<T extends ITypeofSingleton>(param: T): InstanceType<T> | null {
+        const index = this.singletons.findIndex(com => com.ecsName === param.ecsName);
+        if (index >= 0) {
+            return this.singletons.splice(index, 1)[0] as InstanceType<T>;
+        }
+        return null;
+    }
+
+    /**
+     * 创建一个实体
+     */
+    public createEntity<T extends ITypeofEntity>(Entity: T, options?: Node | { node?: Node }): InstanceType<T> {
+        const entity = entityCache.get() || new Entity();
+        EcsBaseEntity.init(entity, this, Node.isNode(options) ? options : options?.node);
+        this.entityManager.add(entity);
+        return entity as InstanceType<T>;
+    }
+
+    /**
+     * 移除一个实体
+     */
+    public removeEntity(entity: IEntity) {
+        const sink = this.dirtySink as IEcsExtensionSink | null;
+        if (sink && sink.onEntityRemoved) {
+            sink.onEntityRemoved(entity);
+        }
+        this.entityManager.remove(entity);
+        if (entity.allowRecycling) {
+            EcsBaseEntity.updateUUID(entity);
+            entityCache.put(entity);
+        }
+    }
+
+    /**
+     * 添加一个组件
+     */
+    public addComponent(entity: IEntity, component: IComponent) {
+        // 先添加组件
+        EcsComponent.bindDirtySink(component as EcsComponent, this.dirtySink);
+        EcsBaseEntity.addComponent(entity, component);
+        this.componentManager.addComponent(component.ecsName, component);
+        const sink = this.dirtySink as IEcsExtensionSink | null;
+        if (sink && sink.onComponentAdded) {
+            sink.onComponentAdded(entity, component);
+        }
+
+        // 再触发系统的监听
+        this.markEntityDirty(entity);
+    }
+
+    /**
+     * 移除一个组件
+     */
+    public removeComponent(component: IComponent) {
+        const entity = component.entity;
+        const componentName = component.ecsName;
+
+        if (entity) {
+            const sink = this.dirtySink as IEcsExtensionSink | null;
+            if (sink && sink.onComponentRemoving) {
+                sink.onComponentRemoving(entity, component);
+            }
+            // 先触发系统的监听
+            EcsComponent.beforeRemove(component as EcsComponent);
+            if (this.mutationDepth === 0) {
+                this.refreshEntitySystems(entity);
+            }
+
+            // 再移除组件
+            EcsBaseEntity.removeComponent(entity, component);
+            if (this.mutationDepth > 0) {
+                this.markEntityDirty(entity);
+            }
+        }
+        this.componentManager.removeComponent(componentName, component);
+    }
+
+    /**
+    * 添加一个系统
+    */
+    public addSystem<T extends ITypeofSystem>(System: T): void {
+        const system = new System(this);
+        this.systemManager.add(system);
+        EcsBaseSystem.onAdd(system);
+
+        // 先添加实体后添加系统的情况，触发系统的监听
+        this.entityManager.each(function (entity) {
+            EcsSystem.matchEntity(system as EcsSystem, entity);
+        });
+    }
+
+    /**
+     * 移除一个系统
+     */
+    public removeSystem<T extends ITypeofSystem>(System: T): void {
+        const system = this.systemManager.remove(System);
+        if (system) EcsBaseSystem.onRemove(system);
+    }
+
+    /**
+     * 清理所有数据
+     */
+    public clear() {
+        this.systemManager.clear();
+        this.entityManager.each((entity) => {
+            const sink = this.dirtySink as IEcsExtensionSink | null;
+            if (sink && sink.onEntityRemoved) {
+                sink.onEntityRemoved(entity);
+            }
+        });
+        this.entityManager.clear();
+        this.componentManager.clear();
+        this.singletons.length = 0;
+        this.mutationDepth = 0;
+        this.dirtyEntities.clear();
+    }
+
+    /**
+     * 安装/卸载 dirty sink。
+     * observed runtime 通过这里接管组件 dirty 通知；传 null 后核心 ECS 仍可独立运行。
+     */
+    public setDirtySink(sink: IEcsComponentDirtySink | null): void {
+        this.dirtySink = sink;
+        this.componentManager.eachUnique((component) => {
+            EcsComponent.bindDirtySink(component as EcsComponent, sink);
+        });
+    }
+
+    /** 获取当前 dirty sink，主要给扩展包链式安装/恢复使用。 */
+    public getDirtySink(): IEcsComponentDirtySink | null {
+        return this.dirtySink;
+    }
+
+    /**
+     * 安装/卸载 observed 查询入口。
+     * 系统内可通过 this.observed 或 ecs.getObservedQuery() 获取 dirty/fieldDirty/index 查询。
+     */
+    public setObservedQuery(query: IEcsObservedQuery | null): void {
+        this.observedQuery = query;
+    }
+
+    /** 获取 observed 查询入口；未安装 observed runtime 时返回 null。 */
+    public getObservedQuery(): IEcsObservedQuery | null {
+        return this.observedQuery;
+    }
+
+    /** 开始批量结构变更，延迟刷新系统 matcher。适合一次性添加/移除多个组件。 */
+    public beginMutation() {
+        this.mutationDepth++;
+    }
+
+    /** 结束批量结构变更，并统一刷新受影响实体的系统 matcher。 */
+    public endMutation() {
+        if (this.mutationDepth <= 0) return;
+        this.mutationDepth--;
+        if (this.mutationDepth > 0) return;
+
+        this.dirtyEntities.forEach((entity) => {
+            this.refreshEntitySystems(entity);
+        });
+        this.dirtyEntities.clear();
+    }
+
+    private markEntityDirty(entity: IEntity) {
+        if (this.mutationDepth > 0) {
+            this.dirtyEntities.set(entity.uuid, entity);
+            return;
+        }
+        this.refreshEntitySystems(entity);
+    }
+
+    private refreshEntitySystems(entity: IEntity) {
+        this.systemManager.each(function (system) {
+            EcsSystem.matchEntity(system as EcsSystem, entity);
+        });
+    }
+
+    private executeSystem(dt: number, args: any[]) {
+        this.systemManager.each(function (system) {
+            EcsBaseSystem.execute(system, dt, args);
+        });
+    }
+    private beforeExecuteSystem(dt: number, args: any[]) {
+        this.systemManager.each(function (system) {
+            EcsBaseSystem.beforeExecute(system, dt, args);
+        });
+    }
+    private afterExecuteSystem(dt: number, args: any[]) {
+        this.systemManager.each(function (system) {
+            EcsBaseSystem.afterExecute(system, dt, args);
+        });
+    }
+
+    private updateSystem(dt: number, args: any[]) {
+        this.systemManager.each(function (system) {
+            EcsBaseSystem.update(system, dt, args);
+        });
+    }
+    private beforeUpdateSystem(dt: number, args: any[]) {
+        this.systemManager.each(function (system) {
+            EcsBaseSystem.beforeUpdate(system, dt, args);
+        });
+    }
+    private afterUpdateSystem(dt: number, args: any[]) {
+        this.systemManager.each(function (system) {
+            EcsBaseSystem.afterUpdate(system, dt, args);
+        });
+    }
+
+    /**
+     * 用于逻辑帧
+     * 执行顺序:
+     * [系统的beforeExecute] -> [系统的execute] ->[系统的afterExecute]
+     */
+    public execute(dt: number, ...args: any[]) {
+        this.beforeExecuteSystem(dt, args);
+        this.executeSystem(dt, args);
+        this.afterExecuteSystem(dt, args);
+    }
+
+    /**
+     * 用于渲染帧
+     * 执行顺序:
+     * [系统的beforeUpdate] -> [系统的update] -> [系统的afterUpdate]
+     */
+    public update(dt: number, ...args: any[]) {
+        this.beforeUpdateSystem(dt, args);
+        this.updateSystem(dt, args);
+        this.afterUpdateSystem(dt, args);
+    }
+}
+
+export const ecs = ECS.create();
+
+if (DEV && !EDITOR) {
+    //@ts-ignore
+    window['ecs'] = ecs;
+}

package/assets/ecs.ts.meta

@@ -0,0 +1,9 @@
+{
+  "ver": "4.0.24",
+  "importer": "typescript",
+  "imported": true,
+  "uuid": "60d3dbb1-44bc-4e65-9cf1-f675847305fc",
+  "files": [],
+  "subMetas": {},
+  "userData": {}
+}

package/assets/lib/EcsCache.ts

@@ -0,0 +1,43 @@
+import { IComponent, IEntity } from './EcsObject';
+
+class Cache<V> {
+    private cache: V[] = [];
+    get() {
+        if (this.cache.length) {
+            return this.cache.pop();
+        }
+        return null;
+    }
+    put(v: V) {
+        this.cache.push(v);
+    }
+    clear() {
+        this.cache.length = 0;
+    }
+}
+/**实体缓存 */
+export const entityCache = new Cache<IEntity>;
+
+class CacheMap<V> {
+    private cache: Map<string, V[]> = new Map();
+    get(k: string) {
+        const array = this.cache.get(k);
+        if (array && array.length) {
+            return array.pop();
+        }
+        return null;
+    }
+    put(k: string, v: V) {
+        const array = this.cache.get(k);
+        if (array) {
+            array.push(v);
+        } else {
+            this.cache.set(k, [v]);
+        }
+    }
+    clear() {
+        this.cache.clear();
+    }
+}
+/**组件缓存 */
+export const componentCache = new CacheMap<IComponent>();

package/assets/lib/EcsCache.ts.meta

@@ -0,0 +1,9 @@
+{
+  "ver": "4.0.24",
+  "importer": "typescript",
+  "imported": true,
+  "uuid": "5a7613ea-530f-443d-817d-f4c2b6a9bc7f",
+  "files": [],
+  "subMetas": {},
+  "userData": {}
+}

package/assets/lib/EcsFilter.ts

@@ -0,0 +1,210 @@
+import { ComponentManager, EntityManager, flagManager } from './EcsManager';
+import { IComponent, IComponentName, IEntity, IFilter, IFlag, ITypeofComponent } from './EcsObject';
+
+/**
+ * 过滤器
+ */
+export class Filter implements IFilter {
+    static check(entity: IEntity, filter: Filter) {
+        const pipeline = filter.pipeline;
+        for (let index = 0, length = pipeline.length; index < length; index++) {
+            if (!pipeline[index](entity)) return false;
+        }
+        return true;
+    }
+
+    static query(entityManager: EntityManager, componentManager: ComponentManager, filter: Filter) {
+        let result: IEntity[] = [];
+        if (!filter) return result;
+
+        const filterComp = (comp: IComponent) => {
+            if (!comp.enabledInHierarchy) return;
+            if (result.indexOf(comp.entity) >= 0) return;
+            result.push(comp.entity);
+        };
+
+        // 优先验证any
+        if (filter.anyList.length !== 0) {
+            filter.anyList.forEach(comName => {
+                componentManager.getComponents(comName)?.forEach(filterComp);
+            });
+            if (result.length === 0) return result;
+        }
+
+        // 其次验证include
+        if (result.length === 0 && filter.include) {
+            componentManager.getComponents(filter.include)?.forEach(filterComp);
+            if (result.length === 0) return result;
+        }
+
+        // 还查询不到，获取所有
+        if (result.length === 0 && !filter.hasSearch && filter.hasExclude) {
+            entityManager.each((entity) => {
+                if (!entity.enabled) return;
+                result.push(entity);
+            });
+        }
+
+        // 没有实体
+        if (result.length === 0) return result;
+
+        return result.filter(entity => this.check(entity, filter));
+    }
+
+    static find(entityManager: EntityManager, componentManager: ComponentManager, filter: Filter) {
+        if (!filter) return null;
+
+        // 优先验证any
+        if (filter.anyList.length) {
+            for (let index = 0, length = filter.anyList.length; index < length; index++) {
+                const comName = filter.anyList[index];
+                const com = componentManager.getComponents(comName)?.find((comp) => {
+                    if (!comp.enabledInHierarchy) return false;
+                    return this.check(comp.entity, filter);
+                });
+                // 只要有任何一个any符合筛选条件，就返回
+                if (com) return com.entity;
+            }
+            return null;
+        }
+
+        let result: IEntity[] = [];
+
+        // 其次验证include
+        if (filter.include) {
+            componentManager.getComponents(filter.include)?.forEach((comp) => {
+                if (!comp.enabledInHierarchy) return;
+                if (result.indexOf(comp.entity) >= 0) return;
+                result.push(comp.entity);
+            });
+            if (result.length === 0) return null;
+        }
+
+        // 获取所有
+        if (result.length === 0 && !filter.hasSearch && filter.hasExclude) {
+            entityManager.each((entity) => {
+                if (!entity.enabled) return;
+                result.push(entity);
+            });
+        }
+
+        if (result.length === 0) return null;
+
+        result = result.filter(entity => this.check(entity, filter));
+
+        return result.length > 0 ? result[0] : null;
+    }
+
+    private anyList: IComponentName[] = [];
+    private include: IComponentName = '';
+    private hasSearch: boolean = false;
+    private hasExclude: boolean = false;
+    private pipeline: ((entity: IEntity) => boolean)[] = [];
+
+    /**
+     * 有这些组件中的任何一个
+     */
+    any(...Comps: ITypeofComponent[]) {
+        this.hasSearch = true;
+        if (Comps.length === 0) return this;
+
+        Comps.forEach(Com => {
+            if (this.anyList.indexOf(Com.ecsName) >= 0) return;
+            this.anyList.push(Com.ecsName);
+        });
+        return this;
+    }
+    /**
+     * 必须包含所有这些组件
+     * 让数量最少的组件作为第一个参数，会获得更好的性能
+     */
+    all(...Comps: ITypeofComponent[]) {
+        this.hasSearch = true;
+        if (Comps.length === 0) return this;
+        if (!this.include) this.include = Comps[0].ecsName;
+
+        let flag: IFlag = null;
+        const componentNames = Comps.map(Com => Com.ecsName);
+        this.pipeline.push(function all(entity: IEntity) {
+            if (!flag) flag = flagManager.getByNames(componentNames);
+            if (!entity.checkFlagAll(flag)) return false;
+            for (let index = 0, length = componentNames.length; index < length; index++) {
+                if (!entity.hasEnabledComponentName(componentNames[index])) return false;
+            }
+            return true;
+        });
+        return this;
+    }
+    /**
+     * 仅仅只有这些组件
+     * 让数量最少的组件作为第一个参数，会获得更好的性能
+     */
+    only(...Comps: ITypeofComponent[]) {
+        this.hasSearch = true;
+        if (Comps.length === 0) return this;
+        if (!this.include) this.include = Comps[0].ecsName;
+
+        let flag: IFlag = null;
+        const componentNames = Comps.map(Com => Com.ecsName);
+        this.pipeline.push(function only(entity: IEntity) {
+            if (!flag) flag = flagManager.getByNames(componentNames);
+            if (!entity.checkFlagOnly(flag)) return false;
+            for (let index = 0, length = componentNames.length; index < length; index++) {
+                if (!entity.hasEnabledComponentName(componentNames[index])) return false;
+            }
+            return true;
+        });
+        return this;
+    }
+    /**
+     * 不能包含其中的任何一个组件
+     */
+    exclude(...Comps: ITypeofComponent[]) {
+        if (Comps.length === 0) return this;
+        this.hasExclude = true;
+
+        let flag: IFlag = null;
+        const componentNames = Comps.map(Com => Com.ecsName);
+        this.pipeline.push(function exclude(entity: IEntity) {
+            if (!flag) flag = flagManager.getByNames(componentNames);
+            if (!entity.checkFlagAny(flag)) return true;
+            for (let index = 0, length = componentNames.length; index < length; index++) {
+                if (entity.hasEnabledComponentName(componentNames[index])) return false;
+            }
+            return true;
+        });
+        return this;
+    }
+}
+
+/**
+ * 过滤条件
+ */
+export const filter: IFilter = {
+    /**
+     * 必须包含所有这些组件
+     * - 让数量最少的组件作为第一个参数，会获得更好的性能
+     */
+    all(...comps: ITypeofComponent[]) {
+        return new Filter().all(...comps);
+    },
+    /**
+     * 有这些组件中的任何一个
+     */
+    any(...comps: ITypeofComponent[]) {
+        return new Filter().any(...comps);
+    },
+    /**
+     * 仅仅只有这些组件
+     * - 让数量最少的组件作为第一个参数，会获得更好的性能
+     */
+    only(...comps: ITypeofComponent[]) {
+        return new Filter().only(...comps);
+    },
+    /**
+     * 不能包含其中的任何一个组件
+     */
+    exclude(...comps: ITypeofComponent[]) {
+        return new Filter().exclude(...comps);
+    }
+};

package/assets/lib/EcsFilter.ts.meta

@@ -0,0 +1,9 @@
+{
+  "ver": "4.0.24",
+  "importer": "typescript",
+  "imported": true,
+  "uuid": "a540f4ff-72e8-4b6e-ab68-56d62e640c28",
+  "files": [],
+  "subMetas": {},
+  "userData": {}
+}