feat(core): 添加持久化实体支持跨场景迁移
实现实体生命周期策略,允许标记实体为持久化,在场景切换时自动迁移到新场景。 主要变更: - 新增 EEntityLifecyclePolicy 枚举(SceneLocal/Persistent) - Entity 添加 setPersistent()、setSceneLocal()、isPersistent API - Scene 添加 findPersistentEntities()、extractPersistentEntities()、receiveMigratedEntities() - SceneManager.setScene() 自动处理持久化实体迁移 - 添加完整的中英文文档和 21 个测试用例
This commit is contained in:
@@ -819,6 +819,81 @@ export class Scene implements IScene {
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* 查找所有持久化实体
|
||||
*
|
||||
* Find all persistent entities in this scene.
|
||||
*
|
||||
* @returns 持久化实体数组 | Array of persistent entities
|
||||
*/
|
||||
public findPersistentEntities(): Entity[] {
|
||||
return this.entities.buffer.filter(entity => entity.isPersistent);
|
||||
}
|
||||
|
||||
/**
|
||||
* 提取持久化实体(从场景中分离但不销毁)
|
||||
*
|
||||
* 用于场景切换时收集需要迁移的实体。
|
||||
*
|
||||
* Extract persistent entities (detach from scene without destroying).
|
||||
* Used during scene transitions to collect entities for migration.
|
||||
*
|
||||
* @returns 被提取的持久化实体数组 | Array of extracted persistent entities
|
||||
*
|
||||
* @internal
|
||||
*/
|
||||
public extractPersistentEntities(): Entity[] {
|
||||
const persistentEntities = this.findPersistentEntities();
|
||||
|
||||
for (const entity of persistentEntities) {
|
||||
// 从实体列表移除
|
||||
this.entities.remove(entity);
|
||||
|
||||
// 从查询系统移除
|
||||
this.querySystem.removeEntity(entity);
|
||||
|
||||
// 清除场景引用(但保留组件数据)
|
||||
entity.scene = null;
|
||||
}
|
||||
|
||||
return persistentEntities;
|
||||
}
|
||||
|
||||
/**
|
||||
* 接收迁移的实体
|
||||
*
|
||||
* 将从其他场景迁移来的实体添加到当前场景。
|
||||
*
|
||||
* Receive migrated entities from another scene.
|
||||
*
|
||||
* @param entities 要接收的实体数组 | Entities to receive
|
||||
*
|
||||
* @internal
|
||||
*/
|
||||
public receiveMigratedEntities(entities: Entity[]): void {
|
||||
for (const entity of entities) {
|
||||
// 设置新场景引用
|
||||
entity.scene = this;
|
||||
|
||||
// 添加到实体列表
|
||||
this.entities.add(entity);
|
||||
|
||||
// 添加到查询系统
|
||||
this.querySystem.addEntity(entity);
|
||||
|
||||
// 重新注册组件到新场景的存储
|
||||
for (const component of entity.components) {
|
||||
this.componentStorageManager.addComponent(entity.id, component);
|
||||
this.referenceTracker?.registerEntityScene(entity.id, this);
|
||||
}
|
||||
}
|
||||
|
||||
// 清除系统缓存
|
||||
if (entities.length > 0) {
|
||||
this.clearSystemEntityCaches();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 根据名称查找实体(别名方法)
|
||||
*
|
||||
|
||||
Reference in New Issue
Block a user