Flecs项目从v3迁移到v4的完整指南

Flecs项目从v3迁移到v4的完整指南

flecs flecs是一个高性能、轻量级的C和C++实体组件系统框架，适用于游戏开发和其他需要组织大量数据和行为的应用。它提供了一种模块化的方式构建复杂应用，并优化了CPU缓存利用率。 项目地址: https://gitcode.com/gh_mirrors/fl/flecs

概述

Flecs是一个高性能的实体组件系统(ECS)框架，在v4版本中进行了重大重构。本文将详细介绍从v3迁移到v4时需要注意的关键变化，帮助开发者顺利完成迁移工作。

查询系统重构

统一查询API

v4版本将v3中的三种查询实现(filter、query、rule)合并为单一的query API。这意味着：

• 所有使用filter和rule的地方都应替换为query
• 查询字段索引现在从0开始(之前从1开始)
• ecs_term_id_t重命名为ecs_term_ref_t

查询语法变化

// v3语法
Gravity(game:self|up(ChildOf))

// v4语法
Gravity(game|self|up ChildOf)

缓存机制变化

v4中查询默认不缓存，需要通过以下方式显式启用缓存：

1. 配置缓存类型
2. 将查询与实体关联
3. 使用order_by、group_by或cascade

系统与观察者

系统变化

• no_readonly重命名为immediate
• ecs_readonly_begin新增multi_threaded参数

观察者变化

• 移除了UnSet事件，使用OnRemove替代
• 移除了EcsIterable组件/接口
• 观察者run回调行为变更

实体操作变更

实体命名

v4允许使用数字作为实体名称，查找方式有所变化：

// v3查找方式
ecs_entity_t e = ecs_lookup(world, "1000");

// v4查找方式
ecs_entity_t e = ecs_lookup(world, "#1000");

实体创建

• ecs_new(world, T) → ecs_new_w
• ecs_new_id → ecs_new
• 移除了ecs_new_entity

继承机制改进

v4中组件默认不再继承，而是覆盖(override)。要启用继承，需为组件添加(OnInstantiate, Inherit)特性。

// v4启用继承示例
world.component<MaxSpeed>().add(flecs::OnInstantiate, flecs::Inherit);

组件禁用机制

v4中只有添加了CanToggle特性的组件才能被禁用：

// v4组件禁用示例
world.component<Position>().add(flecs::CanToggle);
world.entity().set(Position{10, 20}).disable<Position>();

其他重要变更

1. 联合关系：编码方式从(Union, Relationship)改为(Relationship, Union)
2. 快照功能：完全移除
3. 树扁平化：ecs_flatten功能移除
4. 元数据：EcsMetaType重命名为EcsType
5. API重命名：
   • ecs_pair_object → ecs_pair_target
   • ecs_get_context → ecs_get_ctx
   • ecs_set_context → ecs_set_ctx

迁移建议

1. 首先替换所有filter和rule为query
2. 检查所有查询字段索引，从1改为0
3. 更新实体查找和创建方式
4. 检查继承逻辑，必要时添加Inherit特性
5. 更新组件禁用逻辑，添加CanToggle特性
6. 替换所有已重命名的API调用

通过遵循本指南，开发者可以系统性地将项目从Flecs v3迁移到v4，充分利用新版本的改进和优化。

flecs flecs是一个高性能、轻量级的C和C++实体组件系统框架，适用于游戏开发和其他需要组织大量数据和行为的应用。它提供了一种模块化的方式构建复杂应用，并优化了CPU缓存利用率。 项目地址: https://gitcode.com/gh_mirrors/fl/flecs