@cjhd/cj-ecs 1.0.0

package/assets/ecs/EcsDirty.ts

@@ -0,0 +1,459 @@
+import type { IComponent, IEntity, ITypeofComponent } from '../lib/EcsObject';
+
+/** Dirty 掩码类型，用于标记组件的脏数据位。 */
+export type EcsDirtyMask = number;
+
+/** Dirty 掩码清空模式，用于指定清空的 dirty 位。 */
+export const EcsDirtyClear = {
+    Matched: 'matched',
+    All: 'all',
+    None: 'none',
+} as const;
+
+export type EcsDirtyClearMode = typeof EcsDirtyClear[keyof typeof EcsDirtyClear];
+
+/**
+ * 业务 DirtyBits 的形状约束。
+ * cj-ecs 只认 number mask，不关心 Transform/Spatial/HealthBar 这些业务语义。
+ */
+export interface IEcsComponentDirtyBits {
+    /** 组件的 dirty mask。 */
+    readonly [name: string]: EcsDirtyMask | unknown;
+}
+
+/**
+ * 业务层 DirtyBits 的辅助基类。
+ *
+ * 用法：
+ * class PositionDirtyBits extends EcsComponentDirtyBitsBase {
+ *     static readonly Transform = this.bit(0);
+ *     static readonly Spatial = this.bit(1);
+ * }
+ *
+ * 注意：这里只提供 bit 运算工具，不维护任何 dirty 队列。
+ */
+export abstract class EcsComponentDirtyBitsBase {
+    static readonly None: EcsDirtyMask = 0;
+
+    /** 定义单个 dirty 位。index 建议保持在 0-30，避免 JS 位运算符号位问题。 
+     * @param index 位索引，从 0 开始。
+     * @returns 单个 dirty 位的 mask。
+    */
+    protected static bit(index: number): EcsDirtyMask {
+        return 1 << index;
+    }
+
+    /** 一次性组合多个 dirty 位，适合定义 AllSync 这类聚合 mask。 
+     * @param indices 位索引列表，从 0 开始。
+     * @returns 多个 dirty 位的 mask。
+    */
+    protected static bits(...indices: number[]): EcsDirtyMask {
+        let mask = 0;
+        for (let index = 0; index < indices.length; index++) {
+            mask |= 1 << indices[index];
+        }
+        return mask;
+    }
+
+    /** 判断 mask 是否包含某个 dirty bit。 
+     * @param mask 目标 mask。
+     * @param bit 要检查的 dirty bit。
+     * @returns 是否包含该 dirty bit。
+    */
+    static has(mask: EcsDirtyMask, bit: EcsDirtyMask): boolean {
+        return (mask & bit) !== 0;
+    }
+
+    /** 给 mask 增加一个或多个 dirty bit。 
+     * @param mask 目标 mask。
+     * @param bit 要增加的 dirty bit。
+     * @returns 新的 mask。
+    */
+    static add(mask: EcsDirtyMask, bit: EcsDirtyMask): EcsDirtyMask {
+        return mask | bit;
+    }
+
+    /** 从 mask 中移除一个或多个 dirty bit。 
+     * @param mask 目标 mask。
+     * @param bit 要移除的 dirty bit。
+     * @returns 新的 mask。
+    */
+    static remove(mask: EcsDirtyMask, bit: EcsDirtyMask): EcsDirtyMask {
+        return mask & ~bit;
+    }
+}
+
+/**
+ * cj-ecs 暴露给扩展包的最小 dirty sink。
+ * 未安装 observed runtime 时，组件只更新本地 dirtyMask/version，不会有队列成本。
+ */
+export interface IEcsComponentDirtySink {
+    /** component.markDirty(mask) 后触发，用于 observed runtime 入队。 
+     * @param component 组件实例。
+     * @param mask 被标记的 dirty mask。
+     * @param oldMask 旧的 dirty mask。
+     * @param newMask 新的 dirty mask。
+    */
+    onComponentDirty(
+        component: IComponent,
+        mask: EcsDirtyMask,
+        oldMask: EcsDirtyMask,
+        newMask: EcsDirtyMask,
+    ): void;
+
+    /** component.clearDirty(mask) 后触发，用于从 observed 队列中清理已消费的 bit。 
+     * @param component 组件实例。
+     * @param mask 被清理的 dirty mask。
+     * @param oldMask 旧的 dirty mask。
+     * @param newMask 新的 dirty mask。
+    */
+    onComponentClearDirty?(
+        component: IComponent,
+        mask: EcsDirtyMask,
+        oldMask: EcsDirtyMask,
+        newMask: EcsDirtyMask,
+    ): void;
+
+    /** 组件被移除时触发，用于清理相关 dirty 状态。 
+     * @param component 组件实例。
+    */
+    onComponentRemoved?(component: IComponent): void;
+    
+    /** 组件启用状态变更时触发，用于处理层级启用逻辑。 
+     * @param component 组件实例。
+     * @param enabledInHierarchy 是否在层级中启用。
+    */
+    onComponentEnabledChanged?(component: IComponent, enabledInHierarchy: boolean): void;
+}
+
+/**
+ * observed 这类扩展包需要同时感知结构变化和 dirty 变化。
+ * 这些 hook 只在安装 sink 后生效，核心 ECS 不持有任何字段索引。
+ */
+export interface IEcsExtensionSink extends IEcsComponentDirtySink {
+    /** 组件被添加到实体时触发，用于初始化相关 dirty 状态。 
+     * @param entity 实体实例。
+     * @param component 组件实例。
+    */
+    onComponentAdded?(entity: IEntity, component: IComponent): void;
+    
+    /** 组件从实体移除时触发，用于清理相关 dirty 状态。 
+     * @param entity 实体实例。
+     * @param component 组件实例。
+    */
+    onComponentRemoving?(entity: IEntity, component: IComponent): void;
+    
+    /** 实体被移除时触发，用于清理相关 dirty 状态。 
+     * @param entity 实体实例。
+    */
+    onEntityRemoved?(entity: IEntity): void;
+}
+
+/** 安装 observed runtime 后挂到 ECS 上的统一查询入口。 */
+export interface IEcsObservedQuery {
+    /** 组件级 dirty 查询：面向系统热路径，例如 Position.Spatial。 */
+    readonly dirty: IEcsComponentDirtyQuery;
+    /** 字段级 dirty 查询：面向网络增量同步、调试、细粒度变化消费。 */
+    readonly fieldDirty: IEcsFieldDirtyQuery;
+    /** 长期字段索引查询：面向“当前满足条件的集合”，例如 queryActive=true。 */
+    readonly index: IEcsIndexedFieldQuery;
+    /** 构造“结构条件 + indexed 字段条件”的组合 matcher。 */
+    indexedMatcher(): IEcsIndexedMatcherBuilder;
+}
+
+/** 组件级 dirty 查询：面向系统热路径，例如 Position.Spatial。 */
+export interface IEcsComponentDirtyQuery {
+    /** 查询某组件某 mask 当前待消费的数量，不分配实体数组。 
+     * @param Comp 组件类型。
+     * @param mask 待查询的 dirty mask。
+     * @returns 待消费数量。
+    */
+    count<T extends ITypeofComponent>(Comp: T, mask: EcsDirtyMask): number;
+
+    /** 只遍历 dirty 集合，不消费队列，适合调试观察或只读统计。 
+     * @param Comp 组件类型。
+     * @param mask 待查询的 dirty mask。
+     * @param handler 遍历处理函数。
+     * @param options 遍历选项。
+    */
+    forEach<T extends ITypeofComponent>(
+        Comp: T,
+        mask: EcsDirtyMask,
+        handler: (entity: IEntity, comp: InstanceType<T>, info: IEcsDirtyVisitInfo) => void,
+        options?: IEcsDirtyVisitOptions,
+    ): void;
+
+    /** 遍历并消费 dirty 集合。 
+     * @param Comp 组件类型。
+     * @param mask 待查询的 dirty mask。
+     * @param handler 遍历处理函数。
+     * @param options 遍历选项。
+     * 默认 clear='matched'，只清本次请求 mask 命中的位；热路径系统通常用这个接口。
+    */
+    drain<T extends ITypeofComponent>(
+        Comp: T,
+        mask: EcsDirtyMask,
+        handler: (entity: IEntity, comp: InstanceType<T>, info: IEcsDirtyVisitInfo) => void,
+        options?: IEcsDirtyDrainOptions,
+    ): number;
+
+    /** 手动清空某组件某 mask 的队列状态，通常用于系统重置或场景切换。 
+     * @param Comp 组件类型。
+     * @param mask 待清空的 dirty mask。
+    */
+    clear<T extends ITypeofComponent>(Comp: T, mask: EcsDirtyMask): void;
+}
+
+/** 字段级 dirty 查询：面向网络增量同步、调试、细粒度变化消费。 */
+export interface IEcsFieldDirtyQuery {
+    count(ref: any): number;
+
+    /** 查询某字段当前待消费的变化数量。 
+     * @param Comp 组件类型。
+     * @param field 待查询的字段名或索引。
+     * @returns 待消费数量。
+    */
+    count<T extends ITypeofComponent>(Comp: T, field: string | number): number;
+
+    forEach(
+        ref: any,
+        handler: (entity: IEntity, comp: any, info: IEcsFieldDirtyVisitInfo) => void,
+        options?: IEcsDirtyVisitOptions,
+    ): void;
+
+    /** 只遍历字段 dirty，不清理队列。 
+     * @param Comp 组件类型。
+     * @param field 待查询的字段名或索引。
+     * @param handler 遍历处理函数。
+     * @param options 遍历选项。
+    */
+    forEach<T extends ITypeofComponent>(
+        Comp: T,
+        field: string | number,
+        handler: (entity: IEntity, comp: InstanceType<T>, info: IEcsFieldDirtyVisitInfo) => void,
+        options?: IEcsDirtyVisitOptions,
+    ): void;
+
+    drain(
+        ref: any,
+        handler: (entity: IEntity, comp: any, info: IEcsFieldDirtyVisitInfo) => void,
+        options?: IEcsDirtyDrainOptions,
+    ): number;
+
+    /** 遍历并消费字段 dirty，适合网络同步写入增量包。 
+     * @param Comp 组件类型。
+     * @param field 待查询的字段名或索引。
+     * @param handler 遍历处理函数。
+     * @param options 遍历选项。
+     * 默认 clear='matched'，只清本次请求 mask 命中的位；热路径系统通常用这个接口。
+    */
+    drain<T extends ITypeofComponent>(
+        Comp: T,
+        field: string | number,
+        handler: (entity: IEntity, comp: InstanceType<T>, info: IEcsFieldDirtyVisitInfo) => void,
+        options?: IEcsDirtyDrainOptions,
+    ): number;
+}
+
+/** 长期字段索引查询：面向“当前满足条件的集合”，例如 queryActive=true。 */
+export interface IEcsIndexedFieldQuery {
+    count(ref: any, condition: IEcsIndexedCondition): number;
+
+    /** 查询当前满足 indexed 条件的组件数量。 
+     * @param Comp 组件类型。
+     * @param field 待查询的字段名或索引。
+     * @param condition 待查询的 indexed 条件。
+     * @returns 待查询数量。
+    */
+    count<T extends ITypeofComponent>(Comp: T, field: string | number, condition: IEcsIndexedCondition): number;
+
+    forEach(
+        ref: any,
+        condition: IEcsIndexedCondition,
+        handler: (entity: IEntity, comp: any, info: IEcsIndexedVisitInfo) => void,
+        options?: IEcsIndexedVisitOptions,
+    ): void;
+
+    /** 遍历当前满足 indexed 条件的集合，不会清理任何 dirty 状态。 
+     * @param Comp 组件类型。
+     * @param field 待查询的字段名或索引。
+     * @param condition 待查询的 indexed 条件。
+     * @param handler 遍历处理函数。
+     * @param options 遍历选项。
+    */
+    forEach<T extends ITypeofComponent>(
+        Comp: T,
+        field: string | number,
+        condition: IEcsIndexedCondition,
+        handler: (entity: IEntity, comp: InstanceType<T>, info: IEcsIndexedVisitInfo) => void,
+        options?: IEcsIndexedVisitOptions,
+    ): void;
+}
+
+/** 长期字段索引查询的上下文信息。 */
+export interface IEcsIndexedMatcher {
+
+    /** 当前满足组合条件的实体数量。 */
+    count(): number;
+
+    /** 遍历命中的实体。forEachEntity 的别名，保留使用习惯。 
+     * @param handler 遍历处理函数。
+     * @param options 遍历选项。
+    */
+    forEach(handler: (entity: IEntity) => void, options?: IEcsIndexedVisitOptions): void;
+
+    /** 遍历命中的实体，内部会从最小 indexed 候选集合开始过滤。 
+     * @param handler 遍历处理函数。
+     * @param options 遍历选项。
+    */
+    forEachEntity(handler: (entity: IEntity) => void, options?: IEcsIndexedVisitOptions): void;
+}
+
+/** 长期字段索引查询的构建器。 */
+export interface IEcsIndexedMatcherBuilder {
+
+    /** 实体必须拥有这些启用组件。 
+     * @param args 启用组件类型列表。
+    */
+    all(...args: ITypeofComponent[]): this;
+
+    /** 实体不能拥有这些启用组件。 
+     * @param args 启用组件类型列表。
+    */
+    exclude(...args: ITypeofComponent[]): this;
+
+    /** indexed 字段必须等于指定值。 
+     * @param Comp 组件类型。
+     * @param field 索引字段名或索引。
+     * @param value 等于值。
+    */
+    whereEq(ref: any, value: unknown): this;
+    whereEq<T extends ITypeofComponent>(Comp: T, field: string | number, value: unknown): this;
+
+    /** flagAny 的别名：字段只要包含任一 mask 位即可。 
+     * @param Comp 组件类型。
+     * @param field 索引字段名或索引。
+     * @param mask 待查询的 mask 位。
+    */
+    whereFlag(ref: any, mask: number): this;
+    whereFlag<T extends ITypeofComponent>(Comp: T, field: string | number, mask: number): this;
+
+    /** flag 字段包含 mask 中任一位即可命中。 
+     * @param Comp 组件类型。
+     * @param field 索引字段名或索引。
+     * @param mask 待查询的 mask 位。
+    */
+    whereFlagAny(ref: any, mask: number): this;
+    whereFlagAny<T extends ITypeofComponent>(Comp: T, field: string | number, mask: number): this;
+
+    /** flag 字段必须包含 mask 中全部位。 
+     * @param Comp 组件类型。
+     * @param field 索引字段名或索引。
+     * @param mask 待查询的 mask 位。
+    */
+    whereFlagAll(ref: any, mask: number): this;
+    whereFlagAll<T extends ITypeofComponent>(Comp: T, field: string | number, mask: number): this;
+
+    /** 构建 matcher。构建后可复用，不需要每帧重新 build。 */
+    build(): IEcsIndexedMatcher;
+}
+
+/** 组件 dirty 访问时的上下文信息。 */
+export interface IEcsDirtyVisitInfo {
+    /** 请求的 dirty mask。 */
+    readonly requestedMask: EcsDirtyMask;
+    /** 实际匹配到的 dirty mask。 */
+    readonly matchedMask: EcsDirtyMask;
+    /** 组件当前完整的 dirty mask。 */
+    readonly componentDirtyMask: EcsDirtyMask;
+    /** 组件的 dirty 版本号。 */
+    readonly dirtyVersion: number;
+    /** 实体的唯一标识。 */
+    readonly entityUuid: number;
+    /** 组件的唯一标识。 */
+    readonly componentUuid: number;
+}
+
+/** 字段级 dirty 访问时的上下文信息。 */
+export interface IEcsFieldDirtyVisitInfo extends IEcsDirtyVisitInfo {
+    /** 发生变化的字段名或索引。 */
+    readonly field: string | number;
+    /** 字段的版本号。 */
+    readonly fieldVersion: number;
+}
+
+/** indexed 字段访问时的上下文信息。 */
+export interface IEcsIndexedVisitInfo {
+    /** 索引字段名或索引。 */
+    readonly field: string | number;
+    /** 实体的唯一标识。 */
+    readonly entityUuid: number;
+    /** 组件的唯一标识。 */
+    readonly componentUuid: number;
+}
+
+/** dirty 访问选项。 */
+export interface IEcsDirtyVisitOptions {
+    /** 是否保证遍历顺序稳定（可能牺牲性能）。 */
+    stable?: boolean;
+    /** 单次遍历的最大数量限制。 */
+    budget?: number;
+}
+
+/** dirty 消费选项。 */
+export interface IEcsDirtyDrainOptions extends IEcsDirtyVisitOptions {
+    /** 清理策略：matched-只清理匹配的位，all-清理全部，none-不清理。 */
+    clear?: EcsDirtyClearMode;
+}
+
+/** indexed 字段访问选项。 */
+export interface IEcsIndexedVisitOptions {
+    /** 是否保证遍历顺序稳定（可能牺牲性能）。 */
+    stable?: boolean;
+    /** 单次遍历的最大数量限制。 */
+    budget?: number;
+}
+
+/** indexed 字段模式常量，避免业务在 @EcsIndexedField({ mode }) 中手写字符串。 */
+export const EcsIndexedFieldMode = {
+    /** 等值索引，适合 boolean、枚举、阵营、类型等离散值。 */
+    Eq: 'eq',
+    /** 位掩码索引，适合 Stunned/Burning/Silence 这类 flags。 */
+    Flag: 'flag',
+} as const;
+
+export type EcsIndexedFieldModeValue = typeof EcsIndexedFieldMode[keyof typeof EcsIndexedFieldMode];
+
+/** indexed 查询条件类型常量，避免业务在 count/forEach 条件里手写字符串。 */
+export const EcsIndexedConditionType = {
+    /** 字段值等于指定值。 */
+    Eq: 'eq',
+    /** flag 字段必须包含 mask 中全部位。 */
+    FlagAll: 'flagAll',
+    /** flag 字段包含 mask 中任意位即可命中。 */
+    FlagAny: 'flagAny',
+} as const;
+
+export type EcsIndexedConditionTypeValue = typeof EcsIndexedConditionType[keyof typeof EcsIndexedConditionType];
+
+/** indexed 字段的查询条件类型。 */
+export type IEcsIndexedCondition =
+    | { type: typeof EcsIndexedConditionType.Eq; value: unknown }        // 字段值等于指定值
+    | { type: typeof EcsIndexedConditionType.FlagAll; mask: number }     // flag 字段必须包含全部 mask 位
+    | { type: typeof EcsIndexedConditionType.FlagAny; mask: number };    // flag 字段包含任一 mask 位即可
+
+/** indexed 查询条件构造器，业务侧优先使用它而不是手写 { type: ... }。 */
+export const EcsIndexedCondition = {
+    /** 创建等值查询条件。 */
+    eq(value: unknown): IEcsIndexedCondition {
+        return { type: EcsIndexedConditionType.Eq, value };
+    },
+    /** 创建 flagAll 查询条件。 */
+    flagAll(mask: number): IEcsIndexedCondition {
+        return { type: EcsIndexedConditionType.FlagAll, mask };
+    },
+    /** 创建 flagAny 查询条件。 */
+    flagAny(mask: number): IEcsIndexedCondition {
+        return { type: EcsIndexedConditionType.FlagAny, mask };
+    },
+} as const;

package/assets/ecs/EcsDirty.ts.meta

@@ -0,0 +1,9 @@
+{
+  "ver": "4.0.24",
+  "importer": "typescript",
+  "imported": true,
+  "uuid": "642c20f8-46f8-4b42-8d6e-3d5a5b85faf9",
+  "files": [],
+  "subMetas": {},
+  "userData": {}
+}