A fast entity component system (ECS) for C & C++
This is the Flecs v4 beta release! 🎉
You can use this release to familiarize and play around with the new APIs and features before v4 comes out. The biggest difference between v3 and v4 is a new query engine that unifies filters, queries and rules in a single API.
Beta means that the v4 branch now has all the features that the final release will have! The next few weeks will be spent finding bugs, updating documentation, updating the Flecs demo's and on creating a migration guide.
iter
and run
query iteration callbacks have been replaced with a single run
callbackOVERRIDE
is renamed to AUTO_OVERRIDE
This version does not work with the explorer because of a breaking change in the query DSL. To use the explorer with this release, use this URL: https://www.flecs.dev/explorer/v4?remote=true.
The release should be stable enough for experimentation.
The updated goal is to release in June.
Post v4 feedback in this discussion post: https://github.com/SanderMertens/flecs/discussions/1181 or on the Flecs discord server, whichever you prefer!
This is another early preview of the upcoming v4 release! 🎉
You can use this release to familiarize and play around with the new APIs and features before v4 comes out. The biggest difference between v3 and v4 is a new query engine that unifies filters, queries and rules in a single API.
it.field(0)
instead of it.field(1)
)This version does not work with the explorer because of a breaking change in the query DSL. To use the explorer with the alpha, use this URL: https://www.flecs.dev/explorer/v4?remote=true.
The release should be stable enough for experimentation.
// New: a cleaner syntax allows for more natural type descriptions
struct Position {
x = f32
y = f32
}
assembly CheckBox {
prop checked = bool: false
// New: conditional logic!
if $checked {
Image("checked.png") // New: improved anonymous entity notation
} else {
Image("unchecked.png")
}
}
// New: new syntax that improves ergonomics of working with assemblies
CheckBox my_checkbox(checked: true) {
Position: {x: 400, y: 300} // New: a more consistent way to specify components
// Streamlined syntax for creating child entities
Label my_lbl("Hello world") {
Position: {x: 100, y: 0}
}
}
// Old
Item, Player($this:self|up(ContainedBy))
// New
Item, Player($this|self|up ContainedBy)
The updated goal is to release around the end of May, with a beta release coming out in around two weeks.
Post v4 feedback in this discussion post: https://github.com/SanderMertens/flecs/discussions/1181 or on the Flecs discord server, whichever you prefer!
This is an early preview of the upcoming v4 release! 🎉
You can use this release to familiarize and play around with the new APIs and features before v4 comes out. The biggest difference between v3 and v4 is a new query engine that unifies filters, queries and rules in a single API.
// A system with query variables
world.system<Position>("SpaceshipsDockedToPlanet")
.with<SpaceShip>()
.with<DockedTo>("$obj")
.with<Planet>().src("$obj")
.each([](flecs::entity spaceship, Position& p) {
// ...
});
// By default queries are uncached. This is similar to a v3 filter/rule
world.query_builder<Position>()
.with(flecs::ChildOf, "$parent")
.each([](Position& p) {
// ...
});
// Adding .cached() enables caching, which is similar to a v3 query.
// Only the terms that are cacheable will be cached. This allows
// for queries that are partially cached, which is not possible in v3.
auto q = world.query_builder<Position>()
.with(flecs::ChildOf, "$parent")
.cached()
.build();
q.each([](Position& p) {
// ...
});
// Queries can be named. This associates the query with an entity
// with the same name. Queries that are associated with an entity
// are cached. This means that by default all system queries enable
// caching, just like in v3.
auto q = world.query_builder<Position>("Children")
.with(flecs::ChildOf, "$parent")
.build();
q.each([](Position& p) {
// ...
});
// Queries that are associated with an entity need to be explicitly
// destructed. This is the same behavior as `flecs::entity`.
// Queries that are not associated with an entity are cleaned up
// when they go out of scope. This is the same behavior as
// `flecs::world` (RAII).
q.destruct();
flecs::world world_a;
{
// World objects can now be copied. This just creates a handle to
// the existing world, it doesn't create/copy a new world.
flecs::world world_b = world_a;
}
void Move(ecs_iter_t *it) {
Position *p = ecs_field(it, Position, 0); // Field indices now start from 0!
Velocity *v = ecs_field(it, Velocity, 1);
for (int i = 0; i < it->count; i ++) {
p[i].x += v[i].x;
p[i].y += v[i].y;
}
}
The release should be stable enough for experimentation.
There is still a lot that needs to happen before the release. The goal is to release around the end of April, with a higher probability of it being later than earlier.
Post v4 feedback in this discussion post: https://github.com/SanderMertens/flecs/discussions/1181 or on the Flecs discord server, whichever you prefer!
This version includes the following bugfixes:
R(_, _)
and _(_, T)
queries_
) sourceecs_ref_t
could point to invalid component after table recyclingThis version includes the following improvements:
[cpp]
Add missing overloads for delete_with
and remove_all
(thanks @Charlie-83!)[cpp]
Add FLECS_CPP_NO_AUTO_REGISTRATION
flag to disable automatic component registration[cpp]
Add flecs::string::contains
[cpp]
Add support for associating a timer/tick source with a type (thanks @ZeroErrors!)[cpp]
Add missing const
to entity_view
methods (thanks @waywardmonkeys!)[cpp]
Add missing flecs::doc::get/set_color()
functions (thanks @waywardmonkeys!)[cpp]
Mark explicit move ctors/operator= as noexcept
(thanks @waywardmonkeys!)[cpp]
Remove redundant void arg of log function (thanks @waywardmonkeys!)[query-dsl]
Add support for R(A, B || C)
syntax to DSL[query]
Fill out ecs_iter_t.system
when using filters, queries and rules (thanks @BeanCheeseBurrito!)[query]
Improve string conversion of queries with equality operators[rule]
Skip empty ids for R(_, *)
and *(_, T)
queries[json]
Implement serializer for user-friendly JSON format[json]
Add option for serializing query field metadata[rest]
Fix issue where cached REST request would always return code 200[rest]
Add try
parameter that prevents throwing HTTP error when trying out queries[snapshot]
Reduce copies when duplicating tables with non-POD components for snapshots (thanks @ZeroErrors!)[strbuf]
Simplify implementation of ecs_strbuf_t
, improve performance[http]
Improve performance of ecs_http_server_request
[http]
Enable caching of HTTP requests made from C API[log]
Don't mix writing to stderr/stdout in logging output[log]
Make output file used by logging functions configurable[doc]
Fix copy-paste issues with type names (thanks @waywardmonkeys!)[doc]
Fix relationship example by specifying inout (thanks @garrett-is-a-swann!)[doc]
Update Doxygen to v1.10.0 (thanks @ZeroErrors!)[doc]
Enable graphviz dot files in Doxygen (thanks @ZeroErrors!)[doc]
Change defgroup documents to use autobrief (thanks @ZeroErrors!)[doc]
Fix typos (thanks @waywardmonkeys!)[doc]
Fix typos and spelling errors (thanks @ZeroErrors!)[doc]
Fixed documentation link in quickstart addons section (thanks @DJLink!)[doc]
Remove spurious asterisk (thanks @waywardmonkeys!)[doc]
Use @code/@encode (thanks @waywardmonkeys!)[doc]
Fix grouping errors in C docs (thanks @waywardmonkeys!)[doc]
Link function names in doc comments (thanks @waywardmonkeys!)[doc]
Fix ecs_doc_get_name
code samples (thanks @waywardmonkeys!)[doc]
Add tab widget for code snippets (thanks @ZeroErrors!)[doc]
Add Extermination Shock to readme[doc]
Add Hytale to readme[doc]
Improve doc addon docs (thanks @waywardmonkeys!)[doc]
Fix doxygen warnings (thanks @waywardmonkeys!)[doc]
Add missing doc.brief descriptions to flecs entities[doc]
Add C# example snippets to Quickstart, RestApi, System manuals (thanks @BeanCheeseBurrito!)[ci]
Update pages workflow actions (thanks @waywardmonkeys!)[ci]
Add macOS-14 Apple Silicon jobs (thanks @waywardmonkeys!)Benchmark results https://github.com/SanderMertens/ecs_benchmark/tree/4681e8606aa9204b97f6316d3611e9f0d2572852
Known issues: https://github.com/SanderMertens/flecs/issues/844 https://github.com/SanderMertens/flecs/issues/765 https://github.com/SanderMertens/flecs/issues/714 https://github.com/SanderMertens/flecs/issues/620 https://github.com/SanderMertens/flecs/issues/478 https://github.com/SanderMertens/flecs/issues/314
Full Changelog: https://github.com/SanderMertens/flecs/compare/v3.2.10...v3.2.11
up
traversal!⚠️ The next release will merge the filter, rule and query implementations into a single query API, expect breaking changes! ⚠️
This version includes the following bugfixes:
set
commands for new componentson_set
hook was invoked without deferred mode & could be called twiceon_set
hook could get lost||
) expressionsAny
wildcards!
) operators in rulesRel(X, Y, Z)
syntaxThis version includes the following improvements:
[rules]
Implement up
traversal for rules[rules]
Simplify control flow instructions of rule engine[rules]
Add new rule instructions for trivial queries which batches evaluation of multiple terms[rules]
Implement automatic filtering of prefab/disabled entities[rules]
Implement rule instruction reordering to limit evaluation of instructions with only unknown variables[rules]
Improve performance of evaluating queries with exclusive wildcard pairs[rules]
Improve performance of setting data fields for trivial and mixed source queries[meta]
Add new id
primitive type for component ids/pairs[meta]
Use %f
in log statements for doubles instead of %d
[json]
Remove overzealous check on whether it.ptrs
is NULL in iterator serializer[stats]
Remove redundant REST statistics[stats]
Remove less than useful table statistics[stats]
Remove less than useful id statistics[rest]
Reduce log spam from invalid queries from REST API in release mode[meson]
Make compiling hello world example optional (thanks @apache-hb!)[docs]
Fix broken link in REST manual[docs]
Fix C++ module example in manual[docs]
Fix typos in source & documentation (thanks @waywardmonkeys!)[docs]
Doc improvements and formatting (thanks @waywardmonkeys!)[docs]
Remove redundant comment terminators (thanks @waywardmonkeys!)[ci]
Update GitHub actions to actions/checkount@v4
(thanks @waywardmonkeys!)[ci]
Fix new gcc warningsBenchmark results https://github.com/SanderMertens/ecs_benchmark/tree/ab33138f58c7a24cf05f662ac790d7cfbcfbe8e0
Known issues: https://github.com/SanderMertens/flecs/issues/844 https://github.com/SanderMertens/flecs/issues/765 https://github.com/SanderMertens/flecs/issues/714 https://github.com/SanderMertens/flecs/issues/620 https://github.com/SanderMertens/flecs/issues/478 https://github.com/SanderMertens/flecs/issues/314
Full Changelog: https://github.com/SanderMertens/flecs/compare/v3.2.9...v3.2.10
ChildOf($pilot, $cockpit), ChildOf($cockpit, $plane)
can now be rewritten as ChildOf($pilot, $cockpit, $plane)
Turret($this), Health($this.cannon)
window.emit<Resized>({800, 600})
window.enqueue<Resized>({800, 600})
This version includes the following bugfixes:
remove_all
/delete_with
functionsapp_run
OnSet
observer with uninitialized valuesint64_t
values (TODO: correctly handle large uint64_t
values)FLECS_DEBUG
and FLECS_SANITIZE
cursor
API with deserializing into top-level array typesflecs::Override
to C++ API (thanks @BeanCheeseBurrito!)This version includes the following improvements:
[cpp]
Default to InOutNone
when using .with()
in query builder API[cpp]
Enable optional pairs in the C++ query builder (thanks @Thinkofname!)[cpp]
Add array
method to flecs::component
for registering components as array type[cpp]
Add default constructor to flecs::ref
[cpp]
Add flecs::ref::try_ref
method[query-dsl]
Add feature that expands R(A, B, C)
into R(A, B), R(B, C)
[queries]
Add ability to use cascade
in descending order[rules]
Add support for by name lookups relative to query variables ($var.child_name
)[rules]
Don't throw error when comparing variable to *
or _
wildcards[observers]
Add support for entity events[observers]
Add support for enqueueing custom events into command queue[json]
Serialize large integers as strings in JSON serializer[log]
Improve assert performance (thanks @jbarthelmes!)[log]
Enable colors for logging in emcc builds[metrics]
Add ability to track member metrics on pair components[docs]
Fix broken link to meta_c in quickstart[docs]
Fix typo in quickstart[docs]
Fix crash in C++ hooks example[docs]
Fix issue with instancing code example in query manual[docs]
Add STACK_SIZE
parameter to list of emcc parameters in quickstart[docs]
Add game_mechanics/factory
example[docs]
Add more content to FAQ[internals]
Remove record_ptrs
member from table[internals]
Rename flecs::_::invoker*
to flecs::_::delegate*
[internals]
Rename command constants from EcsOp*
to EcsCmd*
[internals]
Reduce complexity of command batching code[ci]
Fix warnings when compiling with -std=gnu2x
[ci]
Fix missing field initializer warning on g++Benchmark results https://github.com/SanderMertens/ecs_benchmark/tree/466a28be07c4ecbc94fa8cccb9dc4a5ba4dabf96
Known issues: https://github.com/SanderMertens/flecs/issues/844 https://github.com/SanderMertens/flecs/issues/765 https://github.com/SanderMertens/flecs/issues/714 https://github.com/SanderMertens/flecs/issues/620 https://github.com/SanderMertens/flecs/issues/478 https://github.com/SanderMertens/flecs/issues/314
Full Changelog: https://github.com/SanderMertens/flecs/compare/v3.2.8...v3.2.9
iterable::find
method that makes it easier to find entities using filters, rules and queries:flecs::query<Position> q = ecs.query<Position>();
flecs::entity result = q.find([](Position& p) {
return p.x == 20;
});
This version includes the following bugfixes:
ecs_pipeline_init
when passing invalid parameterINVALID_PARAMETER
assert in ecs_entity_init
when providing empty separatorflecs::iter::id
each_term
with
statementFLECS_MONITOR
and FLECS_REST
world::id
(thanks @Indra-db!)nullptr
as name to world::use
didn't work correctly (thanks @Indra-db!)world::from_json
NULL
as doc string would not remove doc componentecs_iter_str
This version includes the following improvements:
[cpp]
Add table::get
method for enum types (thanks @Indra-db!)[cpp]
Add iterable::find
method[cpp]
Add parameter to world::lookup
/entity::lookup
to disable/enable recursive searching[cpp]
Remove unnecessary return in entity::modified
(thanks @Indra-db!)[cpp]
Remove redundant component registration from entity::ref
methods (thanks @Indra-db!)[cpp]
Add entity_builder::set_json
[cpp]
Add back world::delta_time
method[meta]
Allow for creating reflection data in deferred, suspended deferred and readonly modes[script]
Add ability to self-reference assembly instance through $this
variable[metrics]
Add ability to create metrics for nested members[alerts]
Add summary counts to AlertsActive
component[cmake]
Add support for building & running tests with cmake (thanks @Naios!)[cmake]
Increase cmake version (thanks @Sororfortuna!)[doc]
Fix typos in examples/documentation (thanks @Rageking8!)[doc]
Documentation corrections (thanks @999pingGG!)[doc]
Improve comments of fwd_declare_component
example[doc]
Add missing argument to pair
function in relationship manual example[doc]
Show how to call target()
in relationship basics example[doc]
Fix incorrect documentation comments in C++ APIBenchmark results https://github.com/SanderMertens/ecs_benchmark/tree/f0c12a99219706c120fd49fe9862749f32f740b5
Known issues: https://github.com/SanderMertens/flecs/issues/1042 https://github.com/SanderMertens/flecs/issues/844 https://github.com/SanderMertens/flecs/issues/765 https://github.com/SanderMertens/flecs/issues/714 https://github.com/SanderMertens/flecs/issues/620 https://github.com/SanderMertens/flecs/issues/478 https://github.com/SanderMertens/flecs/issues/314
Full Changelog: https://github.com/SanderMertens/flecs/compare/v3.2.7...v3.2.8
set
operations are now almost twice as fast in the C++ API 💨// Connect to flecs application
flecs.connect("http://localhost:27750")
// World that stores the joined result of two queries
let w = flecs.world()
.query("SpaceShip, (Dockedto, *)")
.query("Planet, Habitable")
.on_update(() => {
// Access replicated entities
for (let s in w.entities["fleet"]) {
const planet = w.entities[s.pairs.DockedTo];
// Is spaceship docked to a planet?
if (planet.tags.include("Planet") {
// Is planet habitable?
const habitable = planet.tags.include("Habitable") ? "habitable" : "inhabitable";
console.log("SpaceShip " + s.name + " is docked to a " + habitable + " planet!");
}
}
});
This version includes the following bugfixes:
ecs_table_get_column_size
was interpreting column as type indexget
with wildcard idTEXT()
yield_existing
observers weren't always deferredINVALID_COMPONENT_SIZE
assertThis version includes the following improvements:
[c]
Fix inconsistency in naming of get_ctx/set_ctx functions[c]
Add binding_ctx
and ctx_free
/binding_ctx_free
to world[c]
Add ctx
/binding_ctx
to query objects[c]
Add Private
trait to more internal components[c++]
Assert when attempting to create a nested pair id[c++]
Improve performance of deferred C++ set
operations[c++]
Fix issue in filter builder API with pair singletons[timer]
Allow for timer randomization to reduce spikes in pipeline schedule[queries]
Add support for setting $this
variable on query iterators[meta]
Shorten enum constant names by removing name prefix/enum type name prefix[json]
Add ecs_entity_to_json_desc_t::serialize_ids
option[json]
Add ecs_iter_to_json_desc_t::serialize_term_labels
option[json]
Add ecs_iter_to_json_desc_t::serialize_id_labels
option[json]
Remove serialize_meta_ids
option[json]
Add option to serializer to return all queries an entity matches with[json]
Support serialize_id_labels
and serialize_variable_labels
in combination with serialize_table
[json]
Allow for toggling private components in combination with serialize_table
[stats]
Add statistics for sync points[doc]
Fix typo in OS API header[doc]
Fix example in query manual (thanks @jbarthelmes!)[doc]
Fix outdated documentation in query manual and manual[doc]
Fix typo in query manual (thanks @pfeodrippe!)[doc]
Fix documentation for ecs_new_w_pair
in manual[doc]
Fix links in flecs script tutorial[doc]
Fix & improve documentation in main header (thanks @copygirl!)[doc]
Add new C# binding by @BeanCheeseBurrito to README[doc]
Add questions to FAQ on how to debug issues with the explorer[doc]
Remove redundant group_by
callback from group_iter
example[ci]
Suppress new clang warningBenchmark results https://github.com/SanderMertens/ecs_benchmark/tree/563b5476cf13afdeff70fe120ad9d4308da9350b
Breaking changes
Known issues: https://github.com/SanderMertens/flecs/issues/844 https://github.com/SanderMertens/flecs/issues/765 https://github.com/SanderMertens/flecs/issues/714 https://github.com/SanderMertens/flecs/issues/620 https://github.com/SanderMertens/flecs/issues/478 https://github.com/SanderMertens/flecs/issues/314
Full Changelog: https://github.com/SanderMertens/flecs/compare/v3.2.6...v.3.2.7
add
/remove
operations when entity already has the componentThis version includes the following bugfixes:
serialize_alerts
is enabled but module is not importedecs_map_t
macro APIThis version includes the following improvements:
[c]
Fix inconsistencies between column index and type index in table API[c]
Fix naming inconsistencies in table API[cpp]
Fix inconsistencies between column index and type index in flecs::table
API[cpp]
Fix naming inconsistencies in flecs::table
API[cpp]
Add component::member
overload that takes pointer to member (thanks @ZeroErrors!)[cpp]
Add const
to flecs::string::size
and flecs::string::length
(thanks @yuyoyuppe!)[cpp]
Add world::scope(const char*)
method (thanks @sasichkamega!)[meta]
Add support for packed structs (thanks @ZeroErrors!)[meta]
Remove unused size/alignment from EcsMetaType
(thanks @ZeroErrors!)[rest]
Reduce amount of default enabled parameters for REST query endpoint[internals]
Simplify table data structures[internals]
Improve organization and naming of source files[doc]
Add note to FAQ about why (recycled) entity ids can be large[doc]
Add Tempest Rising to README[doc]
Add note on empty entities to cleanup order[ci]
Add msys/mingw builds to CI[ci]
Fix orphaned testsBenchmark results https://github.com/SanderMertens/ecs_benchmark/tree/e66a97d07528be158c1875b7193612904d203ef7
Breaking changes
Known issues: https://github.com/SanderMertens/flecs/issues/844 https://github.com/SanderMertens/flecs/issues/765 https://github.com/SanderMertens/flecs/issues/714 https://github.com/SanderMertens/flecs/issues/620 https://github.com/SanderMertens/flecs/issues/478 https://github.com/SanderMertens/flecs/issues/314
Full Changelog: https://github.com/SanderMertens/flecs/compare/v3.2.5...v3.2.6
This version includes the following bugfixes:
ecs_count
didn't include prefabs and disabled entitiesOVERRIDE
flag in plecs scriptsflecs.monitor
without flecs.meta
removed
argument was not correctly passed by ecs_commit
ecs_commit
wouldn't enter deferred mode while executing the operationecs_iter_t::other_table
would get reset for observers after event propagation.get()
on flecs::table
/flecs::range
from stageifdef
that checked for MSVC
instead of POSIX
(thanks @MilanDierick!)interval
and rate
This version includes the following improvements:
[core]
Remove ability to get entity id array as field with index 0 (thanks @ZeroErrors!)[c]
Add ecs_singleton_set_ptr
(thanks @darkuranium!)[cpp]
Add entity_builder::scope
method that returns world object scoped to entity[cpp]
Add flecs::iter::entities
method (thanks @ZeroErrors!)[cpp]
Add world::run_pipeline<T>
overload (thanks @ZeroErrors!)[cpp]
Add world::target
method (thanks @ZeroErrors!)[cpp]
Add world::get_info
, remove redundant functions (thanks @ZeroErrors!)[pipeline]
Add support for multithreading to ecs_run_pipeline
(thanks @ZeroErrors!)[meta]
Add support for member value ranges[json]
Serialize alerts from children in entity serializer[json]
Add option to serialize incoming relationship edges for entity[alerts]
Add retain_period
to alert configuration[alerts]
Make it possible for alerts to change severity based on a condition[alerts]
Add ability to generate alerts for member values that are out of range[alerts]
Reduce alert detection interval to 0.5 seconds[monitor]
Add WorldSummary
component[expr]
Implement parent()
, name()
and doc_name()
functions in expression parser[http]
Fix unused parameter warning (thanks @MilanDierick!)[doc]
Fix quickstart example[doc]
Fix filenames in documentation comments (thanks @ZeroErrors!)[doc]
Reduce usage of auto
in C++ examples[doc]
Remove redundant functions from C++ examples[doc]
Update C++ examples that used older/more verbose API methods[ci]
Use stricter warning settings to compile code warning free[ci]
Switch asan build to run on Linux, which includes leakage reporting[ci]
Build code on additional compiler versions[cmake]
Add FLECS_STRICT
flag that enables Werror
and stricter warning settingsBenchmark results https://github.com/SanderMertens/ecs_benchmark/tree/8539a8634bc6cc99a61efd5919ffe8f02c6b3478
Breaking changes
ecs_field
no longer returns the entity id array (https://github.com/SanderMertens/flecs/discussions/466#discussioncomment-6425615)ecs_lookup_symbol
function has an additional recursive
argument (https://github.com/SanderMertens/flecs/discussions/466#discussioncomment-6486657)Known issues: https://github.com/SanderMertens/flecs/issues/965 https://github.com/SanderMertens/flecs/issues/844 https://github.com/SanderMertens/flecs/issues/765 https://github.com/SanderMertens/flecs/issues/714 https://github.com/SanderMertens/flecs/issues/620 https://github.com/SanderMertens/flecs/issues/478 https://github.com/SanderMertens/flecs/issues/314
Full Changelog: https://github.com/SanderMertens/flecs/compare/v3.2.4...v3.2.5