Flecs v4.2.0

Release announcement

https://ajmmertens.medium.com/flecs-4-2-is-out-09435e80fdd1

Release notes

This version includes the following improvements:

• [core] Flush stage commands in ecs_fini
• [core] Detect WebAssembly targets other than Emscripten (thanks @andrewgazelka!)
• [core] Default to Any term for observers without terms
• [core] Rename (OnInstantiate, Override) trait to (OnInstantiate, Copy)
• [core] Add ecs_ref_from_ptr()
• [core] Lock tables for OnAdd/OnRemove hooks and observers
• [core] Only allow DontFragment With targets on DontFragment components
• [core] Reduce overhead of disabling entities
• [core] Optimize performance and memory usage of table graph storage
• [core] Allow changing components of instantiated prefab by clearing stale IsA edges
• [core] Do not silence warnings in user code
• [core] Add Sparse and DontFragment support to ecs_each_id
• [core] Return empty iterator from ecs_children for Wildcard and Any parents
• [core] Rename ecs_is_deferred to ecs_is_stage
• [script] Warn when a script inherits from Prefab instead of declaring a prefab
• [core] Emit ChildOf events for entities created with ecs_new_w_parent
• [core] Remove implicit defer mode from core
• [core] Implement component inheritance as storage feature
• [core] Allow setting cmp/equals hooks on in-use components
• [core] Copy inherited DontFragment components to instantiated prefab children that have no IsA relationship with the prefab child
• [core] Events only propagate down a subtree when an observer with an up term exists for the id
• [core] Observers skip the query engine for tables that cannot match by type and resolve single up(IsA) terms through the base table
• [core] Skip observer maps that hold only up notify observers when forwarding events
• [core] Create named children directly in the table with the name component
• [core] Skip the component index lookup for entities that are not traversable targets
• [core] Extend singleton macros
• [core] Remove ecs_set_with()/ecs_get_with()
• [core] Remove .add, .add_expr and .set members from ecs_entity_init, remove ECS_ENTITY, ECS_PREFAB macros
• [core] Remove SlotOf relationship
• [core] Remove ecs_iter_str()
• [core] Remove behavior where ecs_enable() would disable components of prefab
• [core] Move constraint traits to separate addon
• [core] Move multi-world functionality to FLECS_MULTI_WORLD addon
• [core] Move entity ranges feature to FLECS_ENTITY_RANGES addon
• [core] Move frame functions to new FLECS_FRAME addon
• [core] Move prefab functionality to its own addon
• [core] Calling ensure twice on same component will return same pointer
• [core] Add Relationship trait to relationships
• [core] Remove dependency of core observers on query plans
• [core] DontFragment performance improvements & C++ traits
• [core] Add fast path for (*, *) lookups to flecs_components_get
• [core] Skip non-fragmenting childof cleanup checks when no Parent children exist
• [core] Use lazy table cache index and reduce map operations in table init
• [core] Skip (EcsFlag, target) cleanup lookups when no flag records exist
• [core] Add existence filter to event id records to speed up observer checks
• [core] Use shared component map for tables without low component ids
• [core] Add C++ API, examples, and documentation for the on_validate hook
• [core] Add fast path for single element paths to ecs_lookup
• [core] Avoid copying path elements and redundant hashing in lookup functions
• [core] Optimize path parsing and empty name index check in lookup functions
• [core] Implement on_validate hook
• [core] Pass component pointer from set operation to hooks
• [core] Move disabled/prefab/not queryable tables to end of table cache to reduce branching
• [core] Reduce branching on table emptiness in table cache iterator
• [core] Refactor component index to use more cache efficient datastructures
• [observers] Trigger observers on mixed source events
• [cpp] Rename entity::mut to entity::stage and add default stage overload
• [cpp] Add frame_offset accessor to flecs::iter
• [cpp] Remove remaining implicit defer APIs from C++
• [cpp] Report caller file and line in log functions when std::source_location is available
• [cpp] Iterate DontFragment components when using entity::each()
• [cpp] Add a name argument to the world.pipeline() method
• [cpp] Implement Sparse trait, add sparse get() optimization
• [cpp] Flip argument order of .member method to (&Type::member, "name")
• [queries] Improve performance of cached queries with ChildOf terms
• [queries] Keep only populated query groups in the cache
• [queries] Count a fully cached query from the cache instead of iterating it
• [queries] Gate query plan implementation with new FLECS_QUERY_PLANS addon flag
• [queries] Remove ecs_set_default_query_flags()
• [queries] Gate cached queries behind FLECS_CACHED_QUERIES addon flag
• [queries] Throw error when relationship is queried for as component
• [systems] Make behavior of system builder consistent with query builder
• [systems] Throw locked storage assert when adding with world in immediate system
• [meta] Support more than 31 members in ECS_STRUCT
• [meta] Enable query plans for builds with meta and prefabs (thanks @andrewgazelka!)
• [meta] Make ecs_constant_to_entity accept a type name
• [meta] Add ecs_constant_to_entity function
• [meta] Add member vector to EcsStruct reflection definition
• [meta] Implement functions for generating runtime equals/compare hooks
• [meta] Add reflection support for value types
• [meta] Add map support
• [json] Restore JSON entities through deferred ECS removals
• [http] Decode + into spaces
• [rest] Add readonly option to REST server (thanks @andrewgazelka!)
• [rest] Extend root REST page with API examples
• [rest] Improve error message when using /entity endpoint with dot (.) separators
• [rest] Add small welcome message to root page of REST API
• [rest] Implement support for calling script functions from REST API
• [rest] Throw LOCKED_STORAGE asserts when modifying table in hooks
• [script] Support multiple commands separated by ; in shell and REST API
• [script] Name managed includes relative to including script entity
• [script] Shell navigation, resources, manual improvements
• [script] Support relative paths in script shell commands
• [script] Rename script command addon to script shell
• [script] Rename script event module to script.input
• [script] Add script command addon
• [script] Add on.activate event for click and keyboard activation
• [script] Use '=' for partial component assignments
• [script] Add C API for calling async functions and consuming futures
• [script] Use Parent hierarchy by default for prefab and template scopes
• [script] Add focus API, script events example
• [script] Move mouse event bubbling into event module, add stop_propagation
• [script] Allow async blocks to assign to exported mut variables
• [script] Add shorthand syntax for declaring a template in the scope of an entity
• [script] Evaluate primitive and map declarations during type checking
• [script] Evaluate vector and array declarations during type checking
• [script] Open scope of entity variable instead of converting it to a name
• [script] Add ecs_script_from_scene and ecs_script_save
• [script] Make script dependency matching linear in the number of statements
• [script] Make the script edit path linear in the number of statements
• [script] Add ecs_script_reload to reload a managed script from code or file
• [script] Instantiate base template bodies and inherit mut variables in derived templates
• [script] Allow for passing values to template interface props
• [script] Allow loop entities with children next to templates
• [script] Add vector of templates props
• [script] Allow mut variables to be initialized with instance props
• [script] Add template parent constraint
• [script] Add flecs.script.event module
• [script] Add async blocks, while statement and mut assignment
• [script] Allow interface type as template prop value and use it as default
• [script] Add C++ examples to script manual & add missing C++ APIs
• [script] Improve reactivity section of script manual
• [script] Instantiate templates without props on add
• [script] Add reactivity section to script manual
• [script] Extend support for const caching to regular scripts
• [script] Support explicitly scheduled script template updates
• [script] Add ecs_script_edits_clear and ecs_script_edits_count
• [script] Lenient mode skips member access on dropped variables, unknown component reads, using and function signatures
• [script] Edit template body entities, look up the owning script and print shortest round trip floats
• [script] Source preserving edits API with statement end positions and entity source lookup
• [script] Attach scope on next line to entity statement with kind or props
• [script] Add IR evaluation runtime with per-script selection
• [script] Statements must be separated by a newline or semicolon
• [script] Tasks no longer keep scripts alive, assert when a script with open tasks is freed
• [script] Promote bool to numeric in arithmetic expressions
• [script] Component expressions resolve types declared in the same script
• [script] Implement struct/template inheritance
• [script] Template props no longer create member entities under the template
• [script] Lenient loading drops variables with unresolved types and skips their uses
• [script] Lenient loading ignores unknown components, members, functions and vectors with one warning per name
• [script] Support typed template props without defaults
• [script] Document when the same component may be created in multiple scopes
• [script] Add continue statement for for loops
• [script] Add EcsScriptError tag to managed scripts that fail to evaluate
• [script] Allow equality comparisons on floating point values
• [script] Fold match expressions with constant inputs so exported variables can reference them
• [script] Add mobile constant to flecs.script.platform
• [script] Allow scripts to react to mut vars they declare themselves
• [script] Allow match cases to be terminated by the closing brace
• [script] Type variable and initializer values against the declared type
• [script] Make component refs via entity variables reactive
• [script] Add support for keyed for elements
• [script] Support iterating inline array members in for loops
• [script] Allow indexed expressions in interpolated entity names
• [script] Support format specifiers for integer and string values
• [script] Fine grained reactivity
• [script] Remove support for variables in with statements
• [script] Re-evaluate managed scripts when unresolved references are resolved
• [script] Run managed scripts only after references are resolved
• [script] Track unresolved references in expressions
• [script] Report all unresolved references vs just the first one
• [script] Accept stage for export const/mut variable API
• [script] Support match expressions for typed const variables
• [script] Implement support for has expressions
• [script] Add ecs_mut_var_get_t and ecs_mut_var_set_t
• [script] Remove support for passing variables into a script
• [script] Restrict OneOf pair target lookup to relationship scope
• [script] Remove support for comma operator
• [script] Remove support for entity paths in entity names
• [script] Add support for export mut variables
• [script] Tighten rules around include, using
• [script] Vector literals
• [script] Add support for iterating collections with for
• [script] Async function support
• [script] Add ecs_const_var_get_t() operation
• [script] Remove DefaultChildComponent, implement new struct/enum visitors
• [script] Make variable syntax consistent with function arguments
• [script] Allow using ecs_function_call() and ecs_method_call() from stages
• [script] Implement ecs_function_call() and ecs_method_call()
• [script] Add support for mut variables
• [script] Implement string formatting options
• [script] Support using swizzles for assigning multiple fields inside of initializer
• [script] Defer script reevaluation when world is in deferred mode
• [script] Add new ecs_const_var_modified() function
• [script] Allow to refer to template instance with 'this'
• [script] Add ref tracking for template instances
• [script] Implement monitoring of external component references for managed scripts
• [script] Implement script addon for exposing platform constants to scripts
• [stats] Update memory statistics to match current data structures
• [log] Use int32_t for log level parameters consistently

This version includes the following bugfixes:

• [core] Fix FLECS_NOINLINE and FLECS_ALWAYS_INLINE checking undefined ECS_TARGET_GCC
• [core] Fix ecs_table_clear_entities leaving references to deleted entities
• [core] Remove assert that a Not observer's not_query matches (thanks @simon112!)
• [core] Check that ecs_field isn't used on sparse component fields (thanks @simon112!)
• [core] Fix assert when moving entity with Parent component without value
• [core] Check string buffer growth for overflow and allocation failure (thanks @andrewgazelka!)
• [core] Fix stale row and stale Parent children when OnRemove observers modify siblings
• [core] Fix issues with parent storage
• [core] Fix issue where reparenting to dead non-fragmenting parent would cause child to stay alive
• [core] Fix With trait not working for DontFragment components
• [core] Fix instantiating Exclusive DontFragment pair overwriting instance's own target
• [core] Fix deleting Parent children after their parent when parent is target of other relationships
• [core] Fix deferred remove of overridden components and remove/add command batching
• [core] Fix leak and double free when moving components without move_ctor
• [core] Fix Not term observers reporting all entities in table instead of changed entity
• [core] Fix reachable cache invalidation assert
• [core] Fix crash when deleting parent of disabled IsA base
• [core] Release tree spawner data before deleting non-fragmenting parent (thanks @Keiron-Beadle!)
• [core] Fix assert when deleting scoped components added to builtin entities during world cleanup
• [core] Only suspend defer for non-fragmenting child cleanup when world is deferred
• [core] Invoke on_remove hooks before moving last row in table delete
• [meta] Report an error for non-numeric array sizes in meta descriptors
• [core] Fix deferred ensure() bypassing on_replace hook, use set() in REST
• [core] Don't assert when IsA target has no table in relation search
• [core] Defer ecs_new_w_parent when called on a readonly world
• [core] Construct the name column when creating a named child with ecs_new_w_parent
• [core] Fix parser errors reporting position 1 for scripts larger than 64kb
• [core] Keep ordered children position when a child's parent is restated
• [core] Free stack storage for enqueued event payloads
• [core] Fix multi-term up observer skipping non-fragmenting childof siblings in same table
• [core] Append destination row after invoking remove actions when moving entity
• [core] Prevent int32 overflow when growing a vector
• [core] Free oversized stack allocator allocations when the stack is restored
• [core] Fix duplicate ordered children when converting ChildOf to Parent storage
• [core] Fix out of range assert when prefab child id is outside active entity range
• [core] Fix override of exclusive pair not copying value from prefab
• [core] Fix assert when observer with variable pair term matches removed value pair
• [core] Fix assert on same-table name-index reparent during command batching (thanks @simon112!)
• [core] Fix issue where adding OrderedChildren trait wasn't correctly applied for existing children (thanks @simon112!)
• [core] set_hooks preserves existing cmp/equals hooks and illegal flags
• [core] os_api _n macros parenthesise their count argument
• [queries] Keep explicit self modifier when a cached query is built from finalized terms
• [core] Add refcount to type_info to prevent deleting hooks before component cleanup
• [observers] Fix issue where event propagation doesn't correctly halt after an owned component is found
• [cpp] Fix term_ref_builder::flags overwriting term ref id
• [cpp] Use ECS_CAST in sparse page macros to fix old-style cast warnings
• [cpp] Fix move assignment in query_base (thanks @b-deku!)
• [cpp] Fix crash when module changes scope before parent module registers itself
• [cpp] Fix entities in old module parent getting deleted when module is renamed
• [cpp] Fix is_pair() returning false for value pairs
• [queries] Fix variable not set for ChildOf wildcard term on range with Parent children
• [queries] Fix stale query cache entries for rematched disabled tables and nested table events
• [queries] Fix assert when DontFragment term source is variable set by pair target
• [queries] Don't add table that is marked for deletion to query cache
• [queries] Fix multiple up() terms reading from stale parent for children with Parent component
• [queries] Fix self-reference check reading entity id as variable id (thanks @simon112!)
• [queries] Fix treesup_not dropping rows of tables with non-fragmenting parents
• [queries] Fix leak and assert for ChildOf wildcard target with variable or fixed source
• [queries] Reject tables that miss a required id before evaluating a query for a range
• [queries] Fix MatchPrefab/MatchDisabled flags being ignored by simple queries
• [queries] Fix pair variable check reading entity id as variable id
• [queries] Fix validator rejecting value pair terms with value 0
• [queries] Fix value pair terms not matching in query plans and through IsA traversal
• [queries] Fix crash when evaluating never-populated table with non-fragmenting ChildOf
• [queries] Fix uncached Not up traversal terms for tables with mixed parents
• [queries] Fix cached queries not matching Not up traversal terms through Parent component
• [queries] Fix incorrect OR chain source mismatch error for singleton terms (#2195)
• [pipeline] Fix assert when system reads component it also writes with wildcard
• [meta] Construct appended elements when growing a vector for a type with ctor or dtor hooks
• [meta] Guard array size overflow and free member names on descriptor errors
• [meta] Preserve use_offset when creating member entities
• [meta] Fix use-after-free of member names in cached type serializers
• [meta] Fix uninitialized use_offset in struct members, make size assert portable
• [meta] Compute struct member array size without overflowing int32
• [json] Fix assert on wildcard used as entity in deserializer
• [json] Fix assert on parent that would create cycle in hierarchy
• [json] Fix assert on invalid entity id values in deserializer
• [json] Fix infinite loop on large string in unknown struct member
• [json] Fix stack buffer overflow on member name that exceeds token size
• [json] Fix assert on entity id zero in deserializer
• [json] Fix assert on invalid nested value in unknown component
• [http] Fix crash on request with empty target and encoded characters
• [http] Bound HTTP query parameters (thanks @ShiroKSH!)
• [rest] Fix assert in stats endpoint when stats module is not imported
• [rest] Fix regression where setting .enable_rest = true did not enable REST
• [rest] Fix reply and entity creation when updating a new script
• [script] Fix assert on setting component on entity with invalid id
• [script] Fix assert on struct member with type that has no reflection data
• [script] Fix out of bounds read when printing AST with empty identifier
• [script] Fix assert on entity kind that is a wildcard
• [script] Fix assert on integer used as struct member or enum underlying type
• [script] Fix abort when rerunning script with empty struct that is in use
• [script] Fix crash on invalid escape sequence in expression string
• [script] Fix stack overflow in type visitor for long binary expressions
• [script] Fix issues, cleanup code, simplify parser and runtime
• [script] Fix OR operator for cached ChildOf queries
• [script] Mix Rng seed into generator state so the first draw is well distributed
• [script] Free match case and range bound expressions when cast fails
• [script] Free collection literal and function argument values when cast fails
• [script] Free unary and binary operands when implicit cast fails
• [script] Report error when using [] with component without reflection data
• [script] Reject functions with more parameters than the maximum
• [script] Free interpolated string expression when cast to string fails
• [script] Limit nesting depth of chained else if statements
• [script] Free dotted identifier variable name when expression is freed
• [script] Free existing parameters when redeclaring function or method
• [script] Return 0 from entity lookup method when path is null
• [script] Pop match case frame when case expression fails at runtime
• [script] Report error when an enum or bitmask constant could not be added
• [script] Reject struct members that are of the struct's own type
• [script] Validate that enum underlying type is an integer type
• [script] Report error instead of crashing on include cycle in unmanaged scripts
• [script] Report error instead of aborting when a template instantiates itself
• [script] Don't reassign enum underlying type when it is unchanged
• [script] Validate operator for element type of binary vector operation
• [script] Don't fold binary vector operations
• [script] Fix narrowing of u64 literals reading only the low 32 bits
• [script] Report error for relational operator on string operands
• [script] Fix abort when comparing entities with relational operator
• [script] Report error instead of asserting when indexing a non-collection
• [script] Destruct component eval temporary on set and error paths
• [script] EcsScript move hook releases overwritten row resources
• [script] Fix @tree annotation being ignored for entities created before a template
• [script] Fix crash on NULL string interpolation and on match with float input
• [script] Free owned variable storage regardless of whether the type has a dtor
• [script] Refetch script component after clearing script
• [script] Reject instantiating a template on its own entity
• [script] Fix abort when reading a component from an invalid entity variable
• [script] Report an error when an if condition is not convertible to bool
• [script] Report an error when script evaluation fails without a message
• [script] Fix assert when an annotation is used inside a template body
• [script] Fix assert at world cleanup when a script declares a singleton scope and a template
• [script] Fix member offset for member expression after element expression
• [script] Fix invalid [] error when indexing collection member of struct variable
• [script] Fix parsing identifier value at end of script without newline
• [script] Fix issue with entity to bool conversions, if short-circuiting
• [script] Fix issue in C++ API that prevents fetching const vars of string type
• [script] Fix element access with variable index of type other than i64
• [script] Fix crash when evaluating script twice after failed method call
• [script] Fix binary operand leaking meta cursor into parent expression
• [script] Fix issues with parsing newlines
• [script] Don't add script tag to builtin entities
• [script] Don't invoke opaque handlers when meta cursor has no data
• [script] Fix issues with reporting script errors
• [script] Fix issues where no or incorrect line number was returned
• [script] Fix constant folding of script function arguments
• [script] Fix issue where using statements were not propagated to functions
• [script] Fix issue where prefabs defined in scripts aren't cleared on script update
• [script] Preserve global variables during identifier folding
• [script] Fix crash when template component expr uses this keyword
• [script] Fix crash when updating script while world is deferred
• [script] Fix member and element access on exported const vars in expressions
• [script] Fix variable resolution issue in script templates
• [script] Fix issue where errors from included script were not surfaced
• [script] Don't add redundant (OnInstantiate, Override) trait to template entities
• [script] Warn when reopening a named entity overwrites a component value
• [script] Apply escape sequences to the text fragments of interpolated strings
• [script] Instantiate deferred template add+set once
• [script] Report script error when template is instantiated as its own kind
• [script] Report script error when rng function divides by zero
• [script] Use cursor type for initializer collection mismatch error
• [parser] Fix token stack overflow in expressions with many operators
• [os] Do not pass NULL strings to custom strdup callbacks

Breaking changes

• [cpp] The scoped_world API is removed from the C++ API
• [cpp] The entity_view::child() API is removed from the C++ API
• [cpp] The argument order of the .member method changed to (&Type::member, "name")
• [core] ecs_table_has_flags()/table::has_flags() are replaced with ecs_table_get_flags()/table::get_flags()
• [core] Repeated calls to ensure in deferred mode now return the same storage
• [script] Variable, member and argument type annotations use consistent syntax
• [build] Prefabs, cached queries, query plans, entity ranges, multi-world, frame and constraint features moved to addons
• [script] Major changes to the Flecs Script implementation, including fine grained reactivity
• [core] The (OnInstantiate, Override) trait is renamed to (OnInstantiate, Copy)
• [script] prefab and template scopes in Flecs Script use Parent hierarchies by default
• [core] Implicit defer mode is removed from the core and the C++ API
• [cpp] entity::mut() is renamed to `entity::stage()
• [core] ecs_enable() no longer disables the components of a prefab

New Contributors

• @simon112 made their first contribution in #2171
• @ShiroKSH made their first contribution in #2242
• @Keiron-Beadle made their first contribution in #2297
• @b-deku made their first contribution in #2291
• @andrewgazelka made their first contribution in #2347

Full Changelog: v4.1.6...v4.2.0