![]() |
Flecs v4.0
A fast entity component system (ECS) for C & C++
|
This guide will help migrating Flecs v3 code bases over to Flecs v4. While the guide attempts to be as complete as possible, v4 is a big release, so some things are inevitably missed. If you see something that you think belongs in the migration guide, feel free to create a PR!
Note that this is not a comprehensive list of things that changed in v4. This document only intends to document the breaking changes between v3 and v4.
The three query implementations in v3 (filter, query, rule) have been merged into a single query API in v4. This means that any usage of filter and rule should now be replaced with query.
Additionally the following things have changed:
ecs_term_id_t is now called ecs_term_ref_t.self, up) are now applied with a bitwise OR mask to ecs_term_ref_t::id.trav field has been moved from ecs_term_ref_t to ecs_term_t.up are provided, the traversal relationship defaults to ChildOf (this used to be IsA).self|up(IsA) for inheritable components.ecs_query_desc_t::instanced member no longer exists. Instancing must be specified with a query flag (.flags = EcsQueryIsInstanced).FLECS_TERM_COUNT_MAX.ecs_query_changed function has been split up into a function that only accepts a query (ecs_query_changed) and one that only accepts an iterator (ecs_iter_changed).ecs_query_skip function has been renamed to ecs_iter_skip.ecs_query_set_group function has been renamed to ecs_iter_set_group.ecs_iter_t::columns array have changed, and may change again in the near future. Applications should not directly depend on it.EcsParent convenience constant is gone, and can now be replaced with just EcsUp.ecs_query_desc_t::group_by_id has been renamed to ecs_query_desc_t::group_byecs_query_desc_t::group_by has been renamed to ecs_query_desc_t::group_by_callbackecs_query_desc_t::order_by_component has been renamed to ecs_query_desc_t::order_byecs_query_desc_t::order_by has been renamed to ecs_query_desc_t::order_by_callbackecs_query_next_table and ecs_query_populate functions have been removed.ecs_query_table_count and ecs_query_empty_table_count functions have been replaced with ecs_query_count, which now returns a struct.ecs_query_t struct is now public, which means that many of the old accessor functions (like ecs_query_get_ctx, ecs_query_get_binding_ctx) are no longer necessary.A before/after example:
C
C++
In v3, a query was always cached. In v4, by default queries are created uncached. There are three conditions under which queries become cached:
order_by, group_by or cascade is usedSystem queries are cached by default (they are always associated with the system entity). See the query manual for more details. The following example shows the difference between creating a cached query in v3 and v4:
C
C++
In C++, the iter iteration function no longer exists, and the signature of the run function has changed. An example:
The query DSL has remained mostly the same but there are a few small changes.
Traversal flags are specified differently in v4:
Component id flags are now specified with lower case:
In v4 the $this variable must be specified with a lower case:
The parent traversal flag has been removed. Because ChildOf is now the default relationship when a traversal flag is specified, it can be replaced with just up:
The $(Relationship) notation was removed from the DSL in v4:
Systems have remained mostly the same. A list of the things that changed:
ecs_readonly_begin got a new multi_threaded parameter (added in 3.2.12)no_readonly has been renamed to immediateObservers have remained mostly the same. A list of the things that changed:
UnSet event no longer exists. OnRemove can in v4 be used instead.EcsIterable component/iterable interface no longer exist. yield_existing is now only supported for builtin events.run callback now behaves like a regular system runner and no longer requires calling ecs_observer_default_run_action. To get the old behavior where run is called before the observer query is evaluated, specify the EcsObserverBypassQuery observer flag.Term iterators have been removed from v4, and have been replaced with the easier to use ecs_each API. An example:
Entities can now be created with names that are numbers, e.g. 1000. Lookups for numbers now result in a regular by name lookup for an entity with the number as name. To lookup an entity with a specific id using the lookup functions, use the # prefix. An example:
C
C++
Additionally, entity name functions have changed:
ecs_get_fullpath is now ecs_get_pathecs_get_path is now ecs_get_path_fromecs_lookup_fullpath is now ecs_lookupecs_lookup_path is now ecs_lookup_fromThese changes got introduced in 3.2.12, but are mentioned here as many users will likely see these changes first when upgrading to v4:
ensure is renamed to make_aliveensure_id is renamed to make_alive_idget_mut in the C++ API is changed from a T* to a T&get_mut is renamed to ensureget_mut function is added that doesn't add the componentThe following changes were made to the new family of functions in the C API:
ecs_new(world, T) got renamed to ecs_new_wecs_new_id got renamed to ecs_newIn v3, ecs_new took into account values set by ecs_set_scope and ecs_set_with. In v4 this is no longer the case, and the ecs_new_w function will only return the entity with the specified component. To get the old behavior that takes into account scope and with, use ecs_entity_init.
The Flecs script syntax changed how components and entities are specified:
For more details, see the Flecs script manual.
In v4, components no longer inherit by default when instantiating a prefab. Instead, components by default override, which is equivalent to how auto overriding worked in v3. To inherit a component, add the (OnInstantiate, Inherit) trait to the component.
The EcsDontInherit v3 trait is equivalent to the (OnInstantiate, DontInherit) v4 trait. The EcsAlwaysOverride v3 trait is now the default in v4. It can also be explicitly specified as (OnInstantiate, Override).
An example:
C
C++
Additionally, the override operation has been renamed to auto_override.
In v4, components can only be disabled if they have the CanToggle trait. An example:
C
C++
In v3, Union relationships where encoded on the entity type with a (Union, Relationship) pair. In v4, union relationships are encoded with a (Relationship, Union) pair.
The API for unions has not changed meaningfully. However, the union storage has changed, which might impact performance (positively or negatively).
The snapshot feature has been removed from v4.
The tree flattening feature (ecs_flatten) has been removed. It will be replaced eventually with a new implementation that addresses the shortcomings of the old feature.
The following addons have been removed/merged with other addons:
FLECS_META_C (merged with FLECS_META)FLECS_PLECS (renamed to FLECS_SCRIPT)FLECS_EXPR (merged with FLECS_SCRIPT)FLECS_PARSER (merged with FLECS_SCRIPT)FLECS_SNAPSHOT (feature got removed)FLECS_RULES (merged with queries)MONITOR (merged with STATS)EcsTag trait has been renamed to EcsPairIsTag.DefaultChildComponent is now a component (was a tag in v3).ecs_set_automerge functionality has been removed from v4.ecs_async_stage_new function has been renamed to ecs_stage_new.ecs_set no longer returns a new entity if 0 is passed (use ecs_insert instead).ecs_set_entity_generation has been renamed to ecs_set_version.ecs_term_copy/ecs_term_move/ecs_term_fini functions have been removed. Terms no longer exist by themselves, and term resources are now owned by the query object.ecs_iter_poly function has been removed. To iterate all entities in the world, now use ecs_get_entities.ecs_field_column has been renamed to ecs_field_column_index.