添加内部属性标记

2025-11-05 05:45:48 +00:00 · 2025-03-07 16:02:00 +08:00
parent b6551e9bbf
commit 897d618a0b
71 changed files with 909 additions and 220 deletions
--- a/src/ecmodule/Component.ts
+++ b/src/ecmodule/Component.ts
@@ -18,28 +18,28 @@ export abstract class Component extends ObjectBase {
    /** 所属组件管理器 */
    public componentManager: ComponentManager;

-    /** 是否需要销毁 */
+    /** 是否需要销毁 @internal */
    public _needDestroy: boolean;

-    /** 更新ID */
+    /** 更新ID @internal */
    public _updateId: number = -1;

-    /** 是否更新中 */
+    /** 是否更新中 @internal */
    public get _updating(): boolean {
        return this._updateId != -1;
    }

-    /** 生命周期函数 添加到实体 */
+    /** 生命周期函数 添加到实体 @internal */
    public _add(): void {
        this.onAdd();
    }

-    /** 生命周期函数 销毁 */
+    /** 生命周期函数 销毁 @internal */
    public _destroy(): void {
        this.onDestroy();
    }

-    /** 生命周期函数 添加到实体后 在这个函数中可以获取其他组件 */
+    /** 生命周期函数 添加到实体后 在这个函数中可以获取其他组件 @internal */
    public _enter(): void {
        // 自动开启更新
        if (this.needUpdate) {
@@ -48,14 +48,14 @@ export abstract class Component extends ObjectBase {
        this.onEnter();
    }

-    /** 生命周期函数 从实体中移除 */
+    /** 生命周期函数 从实体中移除 @internal */
    public _remove(): void {
        this.stopUpdate();
        this.onRemove();
        this.componentManager._destroyComponent(this);
    }

-    /** 更新 */
+    /** 更新 @internal */
    public _update(dt: number): void {
        this.onUpdate(dt);
    }
--- a/src/ecmodule/ComponentManager.ts
+++ b/src/ecmodule/ComponentManager.ts
@@ -3,18 +3,16 @@ import { ComponentPool } from "./ComponentPool";

 /**
 * 组件更新信息
- *
- * @export
- * @class ComponentUpdate
+ * @internal
 */
 export class ComponentUpdate {
    /** 组件更新类型 */
    public componentType: number;

-    /** 组件更新列表 */
+    /** 组件更新列表 @internal */
    private readonly _components: Component[] = [];

-    /** create constructor */
+    /** create constructor @internal */
    public constructor(componentType: number) {
        this.componentType = componentType;
    }
@@ -22,6 +20,7 @@ export class ComponentUpdate {
    /**
     * 添加要更新的组件
     * @param component 组件
+     * @internal
     */
    public addComponent(component: Component): void {
        this._components.push(component);
@@ -31,6 +30,7 @@ export class ComponentUpdate {
    /**
     * 删除要更新的组件
     * @param {Component} component 组件
+     * @internal
     */
    public removeComponent(component: Component): void {
        const components = this._components;
@@ -52,7 +52,7 @@ export class ComponentUpdate {
        components.pop();
    }

-    /** 更新 */
+    /** 更新 @internal */
    public _update(dt: number): void {
        const components = this._components;
        const componentCount = components.length;
@@ -73,24 +73,28 @@ export class ComponentManager {
    /**
     * 组件池
     * @type {ComponentPool}
+     * @internal
     */
    protected componentPool: ComponentPool;

-    /** 更新组件池 */
+    /** 更新组件池 @internal */
    protected readonly updatingComponents: ComponentUpdate[] = [];
+    /** 组件更新顺序 @internal */
    protected readonly componentUpdateOrderList: number[] = [];

-    /** 新添加的或者新停止更新的组件池 */
+    /** 新添加的或者新停止更新的组件池 @internal */
    private readonly _toUpdateComponents: Component[] = [];
+    /** 新停止更新的组件池 @internal */
    private readonly _toStopComponents: Component[] = [];

-    /** 当前更新的组件类型 */
+    /** 当前更新的组件类型 @internal */
    private _currentUpdateComponentType: number = -1;

    /**
     *Creates an instance of ComponentManager.
     * @param {ComponentPool} componentPool 组件池
     * @param {number[]} componentUpdateOrderList 组件更新顺序
+     * @internal
     */
    constructor(componentPool: ComponentPool, componentUpdateOrderList: number[]) {
        this.componentPool = componentPool;
@@ -101,6 +105,10 @@ export class ComponentManager {
        }
    }

+    /**
+     * 销毁组件管理器
+     * @internal
+     */
    public destroy(): void {
        this.componentPool.clear();
        this.updatingComponents.length = 0;
@@ -114,6 +122,7 @@ export class ComponentManager {
     * @template T
     * @param {string} componentName 组件名
     * @returns {T} 创建的组件
+     * @internal
     */
    public createComponent<T extends Component>(componentName: string): T {
        const component = this.componentPool.get(componentName) as T;
@@ -158,6 +167,7 @@ export class ComponentManager {
    /**
     * 销毁组件（内部使用）
     * @param {Component} component
+     * @internal
     */
    public _destroyComponent(component: Component): void {
        if (!component._updating) {
@@ -168,7 +178,11 @@ export class ComponentManager {
        }
    }

-    /** 更新所有组件（内部使用） */
+    /** 
+     * 更新所有组件（内部使用）
+     * @param {number} dt 时间间隔
+     * @internal
+     */
    public _update(dt: number): void {
        this._updateAllComponents(dt);
        this._currentUpdateComponentType = -1;
@@ -180,6 +194,8 @@ export class ComponentManager {
    /**
     * 添加组件更新顺序，先添加的先更新
     * @param {number} componentType 组件类型
+     * @returns {ComponentManager} 组件管理器
+     * @internal
     */
    private _addComponentUpdateOrder(componentType: number): ComponentManager {
        this.componentUpdateOrderList.push(componentType);
@@ -194,7 +210,11 @@ export class ComponentManager {
        return this;
    }

-    /** 添加组件到组件更新列表 */
+    /** 
+     * 添加组件到组件更新列表
+     * @param {Component} component 组件
+     * @internal
+     */
    private _addComponentToUpdateList(component: Component): void {
        if (component.type >= this.updatingComponents.length || !this.updatingComponents[component.type]) {
            throw new Error(`组件（${component.constructor.name}）没有添加到组件更新列表，请使用addComponentUpdateOrder添加更新`);
@@ -202,12 +222,20 @@ export class ComponentManager {
        this.updatingComponents[component.type].addComponent(component);
    }

-    /** 组件更新列表中删除组件 */
+    /** 
+     * 组件更新列表中删除组件
+     * @param {Component} component 组件
+     * @internal
+     */
    private _removeComponentToUpdateList(component: Component): void {
        this.updatingComponents[component.type].removeComponent(component);
    }

-    /** 更新所有组件 */
+    /** 
+     * 更新所有组件
+     * @param {number} dt 时间间隔
+     * @internal
+     */
    private _updateAllComponents(dt: number): void {
        // 按优先级更新所有组件
        const updateList = this.componentUpdateOrderList;
@@ -221,6 +249,10 @@ export class ComponentManager {
        }
    }

+    /**
+     * 清除停止更新的组件
+     * @internal
+     */
    private _clearStopComponents(): void {
        const toStopComponents = this._toStopComponents;
        const l = toStopComponents.length;
@@ -238,6 +270,10 @@ export class ComponentManager {
        }
    }

+    /**
+     * 添加更新组件
+     * @internal
+     */
    private _addUpdateComponents(): void {
        const toUpdateComponents = this._toUpdateComponents;
        const l = toUpdateComponents.length;
--- a/src/ecmodule/ComponentPool.ts
+++ b/src/ecmodule/ComponentPool.ts
@@ -3,9 +3,11 @@ import { ObjectBase } from "./ObjectBase";
 import { ObjectFactory } from "./ObjectFactory";

 export class ComponentPool {
-    /** 组件对象类型到组件类型转换 */
+    /** 组件对象类型到组件类型转换 @internal */
    private readonly _objectTypeToComponentType: number[] = new Array<number>(128);
+    /** 组件池 @internal */
    private _pools: Map<number, ObjectFactory> = new Map();
+    /** 组件名称到组件对象类型转换 @internal */
    private _nameToObjectType: Map<string, number> = new Map();
    /**
     * 注册组件
@@ -13,6 +15,7 @@ export class ComponentPool {
     * @param {number} componentType 组件类型
     * @param {string} name 组件名称
     * @param {new () => Component} ctor 构造函数
+     * @internal
     */
    public register(componentObjectType: number, componentType: number, name: string, ctor: new () => ObjectBase): void {
        if (this._pools.has(componentObjectType)) {
@@ -28,6 +31,11 @@ export class ComponentPool {
        objectTypeToComponentType[componentObjectType] = componentType;
    }

+    /**
+     * 通过组件名称获取组件对象类型
+     * @param {string} componentName 组件名称
+     * @returns {number} 组件对象类型
+     */
    public getObjectTypeByName(componentName: string): number {
        return this._nameToObjectType.get(componentName);
    }
@@ -36,6 +44,8 @@ export class ComponentPool {
     * 创建组件
     * @param {number} componentName 组件名
     * @returns {T} 创建的组件
+     * @template T
+     * @internal
     */
    public get<T extends Component>(componentName: string): T {
        let objectType = this.getObjectTypeByName(componentName);
@@ -54,6 +64,7 @@ export class ComponentPool {
     * 通过组件对象类型获取组件类名
     * @param {number} componentObjectType 组件类型
     * @returns {string}
+     * @internal
     */
    public className(componentObjectType: number): string {
        const factory = this._pools.get(componentObjectType);
@@ -69,13 +80,17 @@ export class ComponentPool {
     * 回收组件
     * @param {BaseComponent} component 要回收的组件
     * @memberof ComponentPool
+     * @internal
     */
    public recycle(component: Component): void {
        const objectFactory = this._pools.get(component.objectType);
        objectFactory.recycle(component);
    }

-    /** 清理缓存 */
+    /** 
+     * 清理缓存
+     * @internal
+     */
    public clear(): void {
        for (const factory of this._pools.values()) {
            factory._clear();
--- a/src/ecmodule/ECDataHelper.ts
+++ b/src/ecmodule/ECDataHelper.ts
@@ -8,7 +8,7 @@ import { Component } from "./Component";
 * @Description: 
 */
 export class ECDataHelper {
-    /** 组件池 */
+    /** 组件池 @internal */
    public static _componentPool: ComponentPool = new ComponentPool();
    /** 注册所有组件 */
    public static registerComponents(): void {
--- a/src/ecmodule/ECDecorator.ts
+++ b/src/ecmodule/ECDecorator.ts
@@ -9,6 +9,7 @@ import { ObjectHelper } from "../tool/helper/ObjectHelper";


 export namespace _ecdecorator {
+    /** @internal */
    const ECPropMeta = "__ecpropmeta__"

    type ECPropType = "int" | "float" | "string" | "boolean" | "size" | "vec2" | "vec3" | "color" | "asset" | "spriteframe" | "jsonAsset" | "particle" | "animation" | "audio" | "prefab" | "skeleton" | "enum" | "array" | "object" | "entity";
--- a/src/ecmodule/ECManager.ts
+++ b/src/ecmodule/ECManager.ts
@@ -21,9 +21,9 @@ interface IWorldConfig {
 }

 export class ECManager {
-    /** 实体管理器 */
+    /** 实体管理器 @internal */
    private static _worlds: Map<string, IWorldConfig> = new Map();
-    /** 实体配置信息 */
+    /** 实体配置信息 @internal */
    private static _entityList: { [name: string]: Record<string, any> } = {};

    /** 注册所有组件 如果GameEntry因分包导致，组件的代码注册晚于 CocosEntry的 onInit函数, 则需要在合适的时机手动调用此方法 */
@@ -130,6 +130,13 @@ export class ECManager {
        return entity;
    }

+    /**
+     * 添加组件到实体
+     * @param {EntityManager} world 实体管理器
+     * @param {Entity} entity 实体
+     * @param {Record<string, any>} componentsData 组件数据
+     * @internal
+     */
    private static _addComponentToEntity(world: EntityManager, entity: Entity, componentsData: Record<string, any>): void {
        for (const componentName in componentsData) {
            let component = world.createComponent(componentName);
--- a/src/ecmodule/ECType.ts
+++ b/src/ecmodule/ECType.ts
@@ -9,8 +9,11 @@
 */
 import { Stack } from "../tool/DataStruct/Stack";

+/** 实体索引位数 @internal */
 export const EntityIndexBits = 16;
+/** 实体索引掩码 @internal */
 export const EntityIndexMask = (1 << EntityIndexBits) - 1;
+/** 最大实体数量 @internal */
 export const MaxEntityCount = 1 << EntityIndexBits;
 export type EntityId = number;

@@ -18,6 +21,7 @@ export type EntityId = number;
 * 2进制转10进制 (不支持小数和负数)
 * @param {number} bitNumber 二进制数
 * @return {number} 十进制数
+ * @internal
 */
 export function bit2Decimal(bitNumber: number): number {
    let bitString = String(bitNumber);
@@ -34,6 +38,7 @@ export function bit2Decimal(bitNumber: number): number {
 * 10进制转2进制 (不支持小数和负数)
 * @param {number} num 十进制数
 * @return {number} 二进制数
+ * @internal
 */
 export function decimal2Bit(num: number): number {
    let stack = new Stack<number>();
@@ -54,6 +59,8 @@ export function decimal2Bit(num: number): number {
 /**
 * 通过实体id获取实体index
 * @param id 实体id
+ * @return {number} 实体index
+ * @internal
 */
 export function getEntityIndex(id: EntityId): number {
    return id & EntityIndexMask;
@@ -61,7 +68,9 @@ export function getEntityIndex(id: EntityId): number {

 /**
 * 通过实体id获取实体版本
- * @param id
+ * @param id 实体id
+ * @return {number} 实体版本
+ * @internal
 */
 export function getEntityVersion(id: EntityId): number {
    return id >>> EntityIndexBits;
@@ -70,6 +79,8 @@ export function getEntityVersion(id: EntityId): number {
 /**
 * 实体描述
 * @param id 实体id
+ * @return {string} 实体描述
+ * @internal
 */
 export function entityIdString(id: EntityId): string {
    return `${getEntityIndex(id)}:${getEntityVersion(id)}`;
--- a/src/ecmodule/Entity.ts
+++ b/src/ecmodule/Entity.ts
@@ -51,8 +51,8 @@ export class Entity {

    /**
     * 实体被添加到EntityManager
+     * @internal
     */
-    // eslint-disable-next-line @typescript-eslint/naming-convention
    public _add(): void {
        this.active = true;
        for (const component of this.components.values()) {
@@ -62,9 +62,8 @@ export class Entity {

    /**
     * 实体销毁，不要手动调用
-     * @memberof Entity
+     * @internal
     */
-    // eslint-disable-next-line @typescript-eslint/naming-convention
    public _destroy(): void {
        this.removeAllComponents();
        this.tags && this.tags.clear();
--- a/src/ecmodule/EntityManager.ts
+++ b/src/ecmodule/EntityManager.ts
@@ -16,12 +16,14 @@ export class EntityManager {
    /**
     * 单例实体
     * @type {Entity}
+     * @internal
     */
    public readonly insEntity: Entity = new Entity();

    /**
     * 单例实体激活状态
     * @type {boolean}
+     * @internal
     */
    public insActive: boolean = false;

@@ -34,30 +36,32 @@ export class EntityManager {
    /**
     * 普通实体事件容器
     * @type {EventManager}
+     * @internal
     */
    private _eventManager: EventManager;

    /**
     * 单例实体消息监听容器
     * @type {EventManager}
+     * @internal
     */
    private _insEventManager: EventManager;

-    /** 实体池 */
+    /** 实体池 @internal */
    private readonly _entityPool: Entity[] = [];
-    /** tag标记池 */
+    /** tag标记池 @internal */
    private readonly _tagToEntity: Map<number, Set<EntityId>> = new Map<number, Set<EntityId>>();
-    /** 实体回收池 */
+    /** 实体回收池 @internal */
    private _recyclePool: Entity[] = [];
-    /** 实体回收池最大容量 */
+    /** 实体回收池最大容量 @internal */
    private _maxCapacityInPool: number;
-    /** 实体回收版本 */
+    /** 实体回收版本 @internal */
    private _entityVersion: number[] = [];
-    /** 回收实体ID */
+    /** 回收实体ID @internal */
    private _recycleEntityIds: EntityId[] = [];
-    /** 世界是否删除 */
+    /** 世界是否删除 @internal */
    private _isDestroyed: boolean;
-    /** 是否正在更新 */
+    /** 是否正在更新 @internal */
    private _updating: boolean;
    /**
     * 实体池最大容量，回收的多余的实体不会缓存
@@ -67,7 +71,6 @@ export class EntityManager {
     * @param {number} [maxCapacityInPool=128] 实体回收池最大容量
     * @param {number} [preloadEntityCount=32] 预加载Entity数量
     */
-    // eslint-disable-next-line prettier/prettier
    constructor(name: string, componentPool: ComponentPool, componentUpdateOrderList: number[], maxCapacityInPool: number = 128, preloadEntityCount: number = 32) {
        this.name = name;
        if (preloadEntityCount >= MaxEntityCount) {
@@ -90,8 +93,8 @@ export class EntityManager {
     * 添加实体标签（内部使用）
     * @param {EntityId} entityId 实体Id
     * @param {number} tag 标签
+     * @internal
     */
-    // eslint-disable-next-line @typescript-eslint/naming-convention
    public _addEntityTag(entityId: EntityId, tag: number): void {
        this._validateEntityById(entityId);
        let entitiesByTag = this._tagToEntity.get(tag);
@@ -106,8 +109,8 @@ export class EntityManager {
     * 删除实体Tag（内部使用）
     * @param {Entity} entity 实体
     * @param {number} tag 标签
+     * @internal
     */
-    // eslint-disable-next-line @typescript-eslint/naming-convention
    public _removeEntityTag(entity: Entity, tag: number): void {
        this._removeEntityTagById(entity.id, tag);
    }
@@ -116,8 +119,8 @@ export class EntityManager {
     * 通过实体ID删除实体Tag（内部使用）
     * @param {EntityId} entityId 实体Id
     * @param {number} tag 标签
+     * @internal
     */
-    // eslint-disable-next-line @typescript-eslint/naming-convention
    public _removeEntityTagById(entityId: EntityId, tag: number): void {
        this._validateEntityById(entityId);
        const entitiesByTag = this._tagToEntity.get(tag);
@@ -331,6 +334,7 @@ export class EntityManager {
     * @param callback 事件回调
     * @param entityId 实体ID
     * @param once 是否单次事件
+     * @internal
     */
    public _addEvent(eventName: string, callback: (...args: any[]) => void, entity: Entity, once: boolean = false): void {
        if (entity == this.insEntity) {
@@ -347,6 +351,7 @@ export class EntityManager {
     * @param eventName 消息名
     * @param entityId 实体ID
     * @param args 发送参数
+     * @internal
     */
    public _sendEvent(eventName: string, entity: Entity, ...args: any[]): void {
        if (entity == this.insEntity) {
@@ -356,6 +361,13 @@ export class EntityManager {
        this._eventManager && this._eventManager.send(eventName, entity, ...args);
    }

+    /**
+     * 移除消息监听 (内部使用)
+     * @param eventName 消息名
+     * @param entity 实体
+     * @param callback 事件回调
+     * @internal
+     */
    public _removeEvent(eventName: string, entity: Entity, callback?: (...args: any[]) => void): void {
        if (entity == this.insEntity) {
            this._insEventManager && this._insEventManager.remove(eventName, callback, entity);
@@ -364,7 +376,10 @@ export class EntityManager {
        this._eventManager && this._eventManager.remove(eventName, callback, entity);
    }

-    /** 更新 */
+    /**
+     * 更新
+     * @param {number} dt 时间间隔
+     */
    public update(dt: number): void {
        this._updating = true;
        this.componentManager._update(dt);
@@ -374,6 +389,7 @@ export class EntityManager {
    /**
     * 回收Entity
     * @param {Entity} entity 要回收的Entity
+     * @internal
     */
    private _recycleEntity(entity: Entity): void {
        // 回收实体Id
@@ -388,8 +404,8 @@ export class EntityManager {
    /**
     * 销毁实体
     * @param {Entity} entity
+     * @internal
     */
-    // eslint-disable-next-line @typescript-eslint/member-ordering
    private _destroyEntity(entity: Entity): void {
        entity._destroy();
        if (this._recyclePool.length < this._maxCapacityInPool) {
@@ -400,6 +416,7 @@ export class EntityManager {
    /**
     * 实体根据tag添加到tag列表中
     * @param entity
+     * @internal
     */
    private _addEntityToTag(entity: Entity): void {
        const tags = entity.tags;
@@ -412,6 +429,11 @@ export class EntityManager {
        }
    }

+    /**
+     * 验证实体ID是否存在
+     * @param {EntityId} entityId 实体ID
+     * @internal
+     */
    private _validateEntityById(entityId: EntityId): void {
        if (!this.exists(entityId)) {
            throw new Error(`实体（${entityId}）不存在`);
--- a/src/ecmodule/ObjectBase.ts
+++ b/src/ecmodule/ObjectBase.ts
@@ -5,12 +5,12 @@ export class ObjectBase {
    /** 对象类型 */
    public objectType: number;

-    /** 回收 */
+    /** 回收 @internal */
    public _recycle(): void {
        this.recycled = true;
    }

-    /** 重新利用 */
+    /** 重新利用 @internal */
    public _reuse(): void {
        this.recycled = false;
    }
--- a/src/ecmodule/ObjectFactory.ts
+++ b/src/ecmodule/ObjectFactory.ts
@@ -1,5 +1,6 @@
 import { ObjectBase } from "./ObjectBase";

+/** @internal */
 export class ObjectFactory {
    /** 对象类 */
    private _ctor: new () => ObjectBase;