CocosPlugin/esengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

重构 Component基类违反ECS纯粹性问题

Browse Source
This commit is contained in:
YHH
2025-09-30 22:26:44 +08:00
parent 51debede52
commit 952247def0
8 changed files with 81 additions and 383 deletions
Download Patch File Download Diff File Expand all files Collapse all files

149
packages/core/src/ECS/Component.ts
View File

@@ -1,21 +1,30 @@
import type { IComponent } from '../Types';
import type { Entity } from './Entity';
/**
* 游戏组件基类
*
* ECS架构中的组件（Component），用于实现具体的游戏功能。
* 组件包含数据和行为，可以被添加到实体上以扩展实体的功能。
*
*
* ECS架构中的组件（Component）应该是纯数据容器。
* 所有游戏逻辑应该在 EntitySystem 中实现，而不是在组件内部。
*
* @example
* 推荐做法：纯数据组件
* ```typescript
* class HealthComponent extends Component {
* public health: number = 100;
*
* public takeDamage(damage: number): void {
* this.health -= damage;
* if (this.health <= 0) {
* this.entity.destroy();
* public maxHealth: number = 100;
* }
* ```
*
* @example
* 推荐做法：在 System 中处理逻辑
* ```typescript
* class HealthSystem extends EntitySystem {
* process(entities: Entity[]): void {
* for (const entity of entities) {
* const health = entity.getComponent(HealthComponent);
* if (health && health.health <= 0) {
* entity.destroy();
* }
* }
* }
* }
@@ -24,141 +33,49 @@ import type { Entity } from './Entity';
export abstract class Component implements IComponent {
/**
* 组件ID生成器
*
*
* 用于为每个组件分配唯一的ID。
*/
public static _idGenerator: number = 0;
/**
* 组件唯一标识符
*
*
* 在整个游戏生命周期中唯一的数字ID。
*/
public readonly id: number;
/**
* 组件所属的实体
*
* 指向拥有此组件的实体实例。
*/
public entity!: Entity;
/**
* 组件启用状态
*
* 控制组件是否参与更新循环。
*/
private _enabled: boolean = true;
/**
* 更新顺序
*
* 决定组件在更新循环中的执行顺序。
*
* @see EntitySystem
*/
private _updateOrder: number = 0;
/**
* 创建组件实例
*
*
* 自动分配唯一ID给组件。
*/
constructor() {
this.id = Component._idGenerator++;
}
/**
* 获取组件启用状态
*
* 组件的实际启用状态取决于自身状态和所属实体的状态。
*
* @deprecated 不符合ECS架构规范，建议自己实现DisabledComponent标记组件替代
* @returns 如果组件和所属实体都启用则返回true
*/
public get enabled(): boolean {
return this.entity ? this.entity.enabled && this._enabled : this._enabled;
}
/**
* 设置组件启用状态
*
* 当状态改变时会触发相应的生命周期回调。
*
* @deprecated 不符合ECS架构规范，建议自己实现DisabledComponent标记组件替代
* @param value - 新的启用状态
*/
public set enabled(value: boolean) {
if (this._enabled !== value) {
this._enabled = value;
if (this._enabled) {
this.onEnabled();
} else {
this.onDisabled();
}
}
}
/**
* 获取更新顺序
*
* @deprecated 不符合ECS架构规范，更新顺序应该由EntitySystem管理
* @see EntitySystem
* @returns 组件的更新顺序值
*/
public get updateOrder(): number {
return this._updateOrder;
}
/**
* 设置更新顺序
*
* @deprecated 不符合ECS架构规范，更新顺序应该由EntitySystem管理
* @see EntitySystem
* @param value - 新的更新顺序值
*/
public set updateOrder(value: number) {
this._updateOrder = value;
}
/**
* 组件添加到实体时的回调
*
*
* 当组件被添加到实体时调用，可以在此方法中进行初始化操作。
*
* @remarks
* 这是一个生命周期钩子，用于组件的初始化逻辑。
* 虽然保留此方法，但建议将复杂的初始化逻辑放在 System 中处理。
*/
public onAddedToEntity(): void {
}
/**
* 组件从实体移除时的回调
*
*
* 当组件从实体中移除时调用，可以在此方法中进行清理操作。
*
* @remarks
* 这是一个生命周期钩子，用于组件的清理逻辑。
* 虽然保留此方法，但建议将复杂的清理逻辑放在 System 中处理。
*/
public onRemovedFromEntity(): void {
}
/**
* 组件启用时的回调
*
* 当组件被启用时调用。
*/
public onEnabled(): void {
}
/**
* 组件禁用时的回调
*
* 当组件被禁用时调用。
*/
public onDisabled(): void {
}
/**
* 更新组件
*
* @deprecated 不符合ECS架构规范，建议使用EntitySystem来处理更新逻辑
*/
public update(): void {
}
}

33
packages/core/src/ECS/Entity.ts
View File

@@ -104,12 +104,7 @@ export class Entity {
* 所属场景引用
*/
public scene: IScene | null = null;
/**
* 更新间隔
*/
public updateInterval: number = 1;
/**
* 销毁状态标志
*/
@@ -334,8 +329,6 @@ export class Entity {
const typeId = ComponentRegistry.getBitIndex(componentType);
component.entity = this;
this._componentsByTypeId[typeId] = component;
const denseIndex = this.components.length;
@@ -528,8 +521,6 @@ export class Entity {
component: component
});
}
component.entity = null as any;
// 通知所有相关的QuerySystem组件已变动
Entity.notifyQuerySystems(this);
@@ -568,8 +559,6 @@ export class Entity {
}
component.onRemovedFromEntity();
component.entity = null as any;
}
this.components.length = 0;
@@ -833,26 +822,6 @@ export class Entity {
}
}
/**
* 更新实体
*
* 调用所有组件的更新方法，并更新子实体。
*/
public update(): void {
if (!this.activeInHierarchy || this._isDestroyed) {
return;
}
for (const component of this.components) {
if (component.enabled) {
component.update();
}
}
for (const child of this._children) {
child.update();
}
}
/**
* 销毁实体

9
packages/core/src/ECS/IScene.ts
View File

@@ -152,13 +152,4 @@ export interface ISceneConfig {
* 场景名称
*/
name?: string;
/**
* 调试配置
*/
debug?: boolean;
/**
* 是否启用实体直接更新
* @default false
*/
enableEntityDirectUpdate?: boolean;
}

10
packages/core/src/ECS/Scene.ts
View File

@@ -95,11 +95,6 @@ export class Scene implements IScene {
this.name = config.name;
}
// 配置实体直接更新选项
if (config?.enableEntityDirectUpdate !== undefined) {
this.entities.setEnableEntityDirectUpdate(config.enableEntityDirectUpdate);
}
if (!Entity.eventBus) {
Entity.eventBus = new EventBus(false);
}
@@ -180,16 +175,13 @@ export class Scene implements IScene {
* 更新场景
*/
public update() {
// 更新实体列表
// 更新实体列表（处理延迟操作）
this.entities.updateLists();
// 更新实体处理器
if (this.entityProcessors != null)
this.entityProcessors.update();
// 更新实体
this.entities.update();
// 更新实体处理器后处理
if (this.entityProcessors != null)
this.entityProcessors.lateUpdate();

49
packages/core/src/ECS/Utils/EntityList.ts
View File

@@ -16,10 +16,6 @@ export class EntityList {
// 延迟操作队列
private _entitiesToAdd: Entity[] = [];
private _entitiesToRemove: Entity[] = [];
private _isUpdating = false;
// 是否启用实体直接更新
private _enableEntityDirectUpdate = false;
public get count(): number {
return this.buffer.length;
@@ -30,23 +26,11 @@ export class EntityList {
}
/**
* 设置是否启用实体直接更新
*/
public setEnableEntityDirectUpdate(enabled: boolean): void {
this._enableEntityDirectUpdate = enabled;
}
/**
* 添加实体（立即添加或延迟添加）
* 添加实体
* @param entity 要添加的实体
*/
public add(entity: Entity): void {
if (this._isUpdating) {
// 如果正在更新中，延迟添加
this._entitiesToAdd.push(entity);
} else {
this.addImmediate(entity);
}
this.addImmediate(entity);
}
/**
@@ -67,16 +51,11 @@ export class EntityList {
}
/**
* 移除实体（立即移除或延迟移除）
* 移除实体
* @param entity 要移除的实体
*/
public remove(entity: Entity): void {
if (this._isUpdating) {
// 如果正在更新中，延迟移除
this._entitiesToRemove.push(entity);
} else {
this.removeImmediate(entity);
}
this.removeImmediate(entity);
}
/**
@@ -147,25 +126,11 @@ export class EntityList {
}
/**
* 更新实体列表和实体
* 更新实体列表
*
* 处理延迟操作（添加/删除实体）
*/
public update(): void {
this._isUpdating = true;
try {
// 只有启用实体直接更新时才遍历更新实体
if (this._enableEntityDirectUpdate) {
for (let i = 0; i < this.buffer.length; i++) {
const entity = this.buffer[i];
if (entity.enabled && !entity.isDestroyed) {
entity.update();
}
}
}
} finally {
this._isUpdating = false;
}
// 处理延迟操作
this.updateLists();
}

20
packages/core/src/Types/index.ts
View File

@@ -4,32 +4,20 @@
/**
* 组件接口
*
* 定义组件的基本契约，所有组件都应该实现此接口
*
* 定义组件的基本契约。
* 在 ECS 架构中，组件应该是纯数据容器，不包含业务逻辑。
*/
export interface IComponent {
/** 组件唯一标识符 */
readonly id: number;
/** 组件所属的实体ID */
entityId?: string | number;
/** 组件启用状态 */
enabled: boolean;
/** 更新顺序 */
updateOrder: number;
/** 组件添加到实体时的回调 */
onAddedToEntity(): void;
/** 组件从实体移除时的回调 */
onRemovedFromEntity(): void;
/** 组件启用时的回调 */
onEnabled(): void;
/** 组件禁用时的回调 */
onDisabled(): void;
/**
* 更新组件
* @deprecated 不符合ECS架构规范，建议使用EntitySystem来处理更新逻辑
*/
update(): void;
}
/**