feat(core): 添加持久化实体支持跨场景迁移

实现实体生命周期策略,允许标记实体为持久化,在场景切换时自动迁移到新场景。

主要变更:
- 新增 EEntityLifecyclePolicy 枚举(SceneLocal/Persistent)
- Entity 添加 setPersistent()、setSceneLocal()、isPersistent API
- Scene 添加 findPersistentEntities()、extractPersistentEntities()、receiveMigratedEntities()
- SceneManager.setScene() 自动处理持久化实体迁移
- 添加完整的中英文文档和 21 个测试用例
This commit is contained in:
yhh
2025-12-05 22:46:53 +08:00
parent 3d5fcc1a55
commit 8f9a7d8581
15 changed files with 2158 additions and 5 deletions

View File

@@ -1,5 +1,6 @@
import { Component } from './Component';
import { ComponentRegistry, ComponentType } from './Core/ComponentStorage';
import { EEntityLifecyclePolicy } from './Core/EntityLifecyclePolicy';
import { BitMask64Utils, BitMask64Data } from './Utils/BigIntCompatibility';
import { createLogger } from '../Utils/Logger';
import { getComponentInstanceTypeName, getComponentTypeName } from './Decorators';
@@ -118,6 +119,13 @@ export class Entity {
*/
private _componentCache: Component[] | null = null;
/**
* 生命周期策略
*
* Lifecycle policy for scene transitions.
*/
private _lifecyclePolicy: EEntityLifecyclePolicy = EEntityLifecyclePolicy.SceneLocal;
/**
* 构造函数
*
@@ -129,6 +137,61 @@ export class Entity {
this.id = id;
}
/**
* 获取生命周期策略
*
* Get lifecycle policy.
*/
public get lifecyclePolicy(): EEntityLifecyclePolicy {
return this._lifecyclePolicy;
}
/**
* 检查实体是否为持久化实体
*
* Check if entity is persistent (survives scene transitions).
*/
public get isPersistent(): boolean {
return this._lifecyclePolicy === EEntityLifecyclePolicy.Persistent;
}
/**
* 设置实体为持久化(跨场景保留)
*
* 标记后的实体在场景切换时不会被销毁,会自动迁移到新场景。
*
* Mark entity as persistent (survives scene transitions).
* Persistent entities are automatically migrated to the new scene.
*
* @returns this支持链式调用 | Returns this for chaining
*
* @example
* ```typescript
* const player = scene.createEntity('Player')
* .setPersistent()
* .addComponent(new PlayerComponent());
* ```
*/
public setPersistent(): this {
this._lifecyclePolicy = EEntityLifecyclePolicy.Persistent;
return this;
}
/**
* 设置实体为场景本地(随场景销毁)
*
* 将实体恢复为默认行为。
*
* Mark entity as scene-local (destroyed with scene).
* Restores default behavior.
*
* @returns this支持链式调用 | Returns this for chaining
*/
public setSceneLocal(): this {
this._lifecyclePolicy = EEntityLifecyclePolicy.SceneLocal;
return this;
}
/**
* 获取销毁状态
* @returns 如果实体已被销毁则返回true