Skip to content
Flecs v4.2
flecs.h
Go to the documentation of this file.
1/**
2 * @file flecs.h
3 * @brief Flecs public API.
4 *
5 * This file contains the public API for Flecs.
6 */
7
8#ifndef FLECS_H
9#define FLECS_H
10
11/**
12 * @defgroup c C API
13 *
14 * @{
15 * @}
16 */
17
18/**
19 * @defgroup core Core
20 * @ingroup c
21 * Core ECS functionality (entities, storage, queries).
22 *
23 * @{
24 */
25
26/**
27 * @defgroup options API defines
28 * Defines for customizing compile-time features.
29 *
30 * @{
31 */
32
33/* Flecs version macros */
34#define FLECS_VERSION_MAJOR 4 /**< Flecs major version. */
35#define FLECS_VERSION_MINOR 2 /**< Flecs minor version. */
36#define FLECS_VERSION_PATCH 0 /**< Flecs patch version. */
37
38/** Flecs version. */
39#define FLECS_VERSION FLECS_VERSION_IMPL(\
40 FLECS_VERSION_MAJOR, FLECS_VERSION_MINOR, FLECS_VERSION_PATCH)
41
42/** @def FLECS_CONFIG_HEADER
43 * Allows for including a user-customizable header that specifies compile-time
44 * features. */
45#ifdef FLECS_CONFIG_HEADER
46#include "flecs_config.h"
47#endif
48
49/** @def ecs_float_t
50 * Customizable precision for floating-point operations. */
51#ifndef ecs_float_t
52#define ecs_float_t float
53#endif
54
55/** @def ecs_ftime_t
56 * Customizable precision for scalar time values. Change to double precision for
57 * processes that can run for a long time (e.g., longer than a day). */
58#ifndef ecs_ftime_t
59#define ecs_ftime_t ecs_float_t
60#endif
61
62
63/** @def FLECS_ACCURATE_COUNTERS
64 * Define to ensure that global counters used for statistics (such as the
65 * allocation counters in the OS API) are accurate in multithreaded
66 * applications, at the cost of increased overhead.
67 */
68// #define FLECS_ACCURATE_COUNTERS
69
70/** @def FLECS_DISABLE_COUNTERS
71 * Disables counters used for statistics. Improves performance, but
72 * will prevent some features that rely on statistics from working,
73 * like the statistics pages in the explorer.
74 */
75// #define FLECS_DISABLE_COUNTERS
76
77/* Make sure provided configuration is valid */
78#if defined(FLECS_DEBUG) && defined(FLECS_NDEBUG)
79#warning "invalid configuration: cannot both define FLECS_DEBUG and FLECS_NDEBUG"
80#endif
81#if defined(FLECS_DEBUG) && defined(NDEBUG)
82#warning "invalid configuration: cannot both define FLECS_DEBUG and NDEBUG"
83#endif
84
85/** @def FLECS_DEBUG
86 * Used for input parameter checking and cheap sanity checks. There are lots of
87 * asserts in every part of the code, so this will slow down applications.
88 */
89#if !defined(FLECS_DEBUG) && !defined(FLECS_NDEBUG)
90#if defined(NDEBUG)
91#define FLECS_NDEBUG
92#else
93#define FLECS_DEBUG
94#endif
95#endif
96
97/** @def FLECS_SANITIZE
98 * Enables expensive checks that can detect issues early. Recommended for
99 * running tests or when debugging issues. This will severely slow down code.
100 */
101#ifdef FLECS_SANITIZE
102#ifndef FLECS_DEBUG
103#define FLECS_DEBUG /* If sanitized mode is enabled, so is debug mode */
104#endif
105#endif
106
107/** @def FLECS_DEBUG_INFO
108 * Adds additional debug information to internal data structures. Necessary when
109 * using natvis.
110 */
111#ifdef FLECS_DEBUG
112#ifndef FLECS_DEBUG_INFO
113#define FLECS_DEBUG_INFO
114#endif
115#ifndef FLECS_EXCLUSIVE_ACCESS
116#define FLECS_EXCLUSIVE_ACCESS /* Enable exclusive access checks in debug mode */
117#endif
118#endif
119
120/* Tip: if you see weird behavior that you think might be a bug, make sure to
121 * test with the FLECS_DEBUG or FLECS_SANITIZE flags enabled. There's a good
122 * chance that this gives you more information about the issue! */
123
124/** @def FLECS_SOFT_ASSERT
125 * Define to not abort for recoverable errors, like invalid parameters. An error
126 * is still thrown to the console. This is recommended for when running inside a
127 * third-party runtime, such as the Unreal editor.
128 *
129 * Note that internal sanity checks (ECS_INTERNAL_ERROR) will still abort a
130 * process, as this gives more information than a (likely) subsequent crash.
131 *
132 * When a soft assert occurs, the code will attempt to minimize the number of
133 * side effects of the failed operation, but this may not always be possible.
134 * Even though an application may still be able to continue running after a soft
135 * assert, it should be treated as if in an undefined state.
136 */
137// #define FLECS_SOFT_ASSERT
138
139/** @def FLECS_KEEP_ASSERT
140 * By default, asserts are disabled in release mode, when either FLECS_NDEBUG or
141 * NDEBUG is defined. Defining FLECS_KEEP_ASSERT ensures that asserts are not
142 * disabled. This define can be combined with FLECS_SOFT_ASSERT.
143 */
144// #define FLECS_KEEP_ASSERT
145
146/** @def FLECS_DEFAULT_TO_UNCACHED_QUERIES
147 * When set, this will cause queries with the EcsQueryCacheDefault policy
148 * to default to EcsQueryCacheNone. This can reduce the memory footprint of
149 * applications at the cost of performance. Queries that use features which
150 * require caching, such as group_by and order_by, will still use caching.
151 */
152// #define FLECS_DEFAULT_TO_UNCACHED_QUERIES
153
154/** @def FLECS_CREATE_MEMBER_ENTITIES
155 * By default, Flecs does not create entities for component members when they
156 * are registered with reflection. Define this addon if an application relies
157 * on members being defined as entities. Features that require members to be
158 * defined as entities are:
159 * - Member queries
160 * - Metrics
161 * - Alerts
162 *
163 * Member entities can also be created on a per-type basis by setting
164 * ecs_struct_desc_t::create_member_entities to true.
165 */
166// #define FLECS_CREATE_MEMBER_ENTITIES
167
168/** @def FLECS_CPP_NO_AUTO_REGISTRATION
169 * When set, the C++ API will require that components are registered before they
170 * are used. This is useful in multithreaded applications, where components need
171 * to be registered beforehand, and to catch issues in projects where component
172 * registration is mandatory. Disabling automatic component registration also
173 * slightly improves performance.
174 * The C API is not affected by this feature.
175 */
176// #define FLECS_CPP_NO_AUTO_REGISTRATION
177
178/** @def FLECS_CPP_NO_ENUM_REFLECTION
179 * When set, the C++ API will not attempt to discover and register enum
180 * constants for registered enum components. This will cause C++ APIs that
181 * accept enum constants to not work.
182 * Disabling this feature can significantly improve compile times and reduce
183 * the RAM footprint of an application.
184 */
185// #define FLECS_CPP_NO_ENUM_REFLECTION
186
187/** @def FLECS_NO_ALWAYS_INLINE
188 * When set, this will prevent functions from being annotated with always_inline,
189 * which can improve performance at the cost of increased binary footprint.
190 */
191// #define FLECS_NO_ALWAYS_INLINE
192
193/** @def FLECS_CUSTOM_BUILD
194 * This macro lets you customize which addons to build Flecs with.
195 * Without any addons, Flecs is just a minimal ECS storage, but addons add
196 * features such as systems, scheduling, and reflection. If an addon is disabled,
197 * it is excluded from the build, so that it consumes no resources. By default,
198 * all addons are enabled.
199 *
200 * You can customize a build by either whitelisting or blacklisting addons. To
201 * whitelist addons, first define the FLECS_CUSTOM_BUILD macro, which disables
202 * all addons. You can then manually select the addons you need by defining
203 * their macro, like "FLECS_SYSTEM".
204 *
205 * To blacklist an addon, make sure to *not* define FLECS_CUSTOM_BUILD, and
206 * instead define the addons you don't need by defining FLECS_NO_<addon>, for
207 * example "FLECS_NO_SYSTEM". If there are any addons that depend on the
208 * blacklisted addon, an error will be thrown during the build.
209 *
210 * Note that addons can have dependencies on each other. Addons will
211 * automatically enable their dependencies. To see the list of addons that were
212 * compiled in a build, enable tracing before creating the world by doing:
213 *
214 * @code
215 * ecs_log_set_level(0);
216 * @endcode
217 *
218 * which outputs the full list of addons Flecs was compiled with.
219 */
220// #define FLECS_CUSTOM_BUILD
221
222#ifndef FLECS_CUSTOM_BUILD
223#define FLECS_ALERTS /**< Monitor conditions for errors. */
224#define FLECS_APP /**< Application addon. */
225#define FLECS_CACHED_QUERIES /**< Cached query support. */
226// #define FLECS_C /**< C API convenience macros, always enabled. */
227#define FLECS_CPP /**< C++ API. */
228#define FLECS_CONSTRAINT_TRAITS /**< Component traits that enforce constraints. */
229#define FLECS_DOC /**< Document entities and components. */
230// #define FLECS_EXCLUSIVE_ACCESS /**< Enable exclusive world access checks. */
231#define FLECS_ENTITY_RANGES /**< Create entities in custom id ranges. */
232#define FLECS_FRAME /**< Frame management utilities. */
233// #define FLECS_JOURNAL /**< Journaling addon. */
234#define FLECS_JSON /**< Parsing JSON to/from component values. */
235#define FLECS_HTTP /**< Tiny HTTP server for connecting to remote UI. */
236#define FLECS_LOG /**< When enabled, ECS provides more detailed logs. */
237#define FLECS_META /**< Reflection support. */
238#define FLECS_METRICS /**< Expose component data as statistics. */
239#define FLECS_MODULE /**< Module support. */
240#define FLECS_MULTI_WORLD /**< Support C++ component ids across multiple worlds. */
241#define FLECS_OS_API_IMPL /**< Default implementation for OS API. */
242// #define FLECS_PERF_TRACE /**< Enable performance tracing. */
243#define FLECS_PIPELINE /**< Pipeline support. */
244#define FLECS_PREFAB /**< Prefabs */
245#define FLECS_QUERY_PLANS /**< Query plan support. */
246#define FLECS_REST /**< REST API for querying application data. */
247#define FLECS_PARSER /**< Utilities for script and query DSL parsers. */
248#define FLECS_QUERY_DSL /**< Flecs query DSL parser. */
249#define FLECS_SCRIPT /**< Flecs entity notation language. */
250#define FLECS_SCRIPT_ASYNC /**< Async/await support for Flecs script. */
251// #define FLECS_SCRIPT_MATH /**< Math functions for Flecs script (may require linking with libm). */
252// #define FLECS_SCRIPT_PLATFORM /**< Platform constants for Flecs script. */
253#define FLECS_SCRIPT_INPUT /**< Mouse and keyboard events for Flecs script. */
254#define FLECS_SCRIPT_SHELL /**< Command line interface for interacting with a world. */
255#define FLECS_SYSTEM /**< System support. */
256#define FLECS_STATS /**< Track runtime statistics. */
257#define FLECS_TIMER /**< Timer support. */
258#define FLECS_UNITS /**< Built-in standard units. */
259#endif // ifndef FLECS_CUSTOM_BUILD
260
261#include "flecs/private/addon_defines.h"
262
263/** @def FLECS_LOW_FOOTPRINT
264 * Set a number of constants to values that decrease memory footprint, at the
265 * cost of decreased performance. */
266// #define FLECS_LOW_FOOTPRINT
267#ifdef FLECS_LOW_FOOTPRINT
268#define FLECS_HI_COMPONENT_ID 16
269#define FLECS_HI_ID_RECORD_ID 16
270#define FLECS_ENTITY_PAGE_BITS 6
271#define FLECS_USE_OS_ALLOC
272#define FLECS_DEFAULT_TO_UNCACHED_QUERIES
273#endif
274
275/** @def FLECS_HI_COMPONENT_ID
276 * This constant can be used to balance between performance and memory
277 * utilization. The constant is used in two ways:
278 * - Entity IDs 0..FLECS_HI_COMPONENT_ID are reserved for component IDs.
279 * - Used as the lookup array size in table edges.
280 *
281 * Increasing this value increases the size of the lookup array, which allows
282 * fast table traversal, which improves performance of ECS add/remove
283 * operations. Component IDs that fall outside of this range use a regular map
284 * lookup, which is slower but more memory efficient.
285 *
286 * This value must be set to a power of 2. Setting it to a value that is not a
287 * power of 2 will degrade performance.
288 */
289#ifndef FLECS_HI_COMPONENT_ID
290#define FLECS_HI_COMPONENT_ID 256
291#endif
292
293/** @def FLECS_HI_ID_RECORD_ID
294 * This constant can be used to balance between performance and memory
295 * utilization. The constant is used to determine the size of the component record
296 * lookup array. ID values that fall outside of this range use a regular map
297 * lookup, which is slower but more memory efficient.
298 */
299#ifndef FLECS_HI_ID_RECORD_ID
300#define FLECS_HI_ID_RECORD_ID 1024
301#endif
302
303/** @def FLECS_SPARSE_PAGE_BITS
304 * This constant is used to determine the number of bits of an ID that is used
305 * to determine the page index when used with a sparse set. The number of bits
306 * determines the page size, which is (1 << bits).
307 * Lower values decrease memory utilization, at the cost of more allocations. */
308#ifndef FLECS_SPARSE_PAGE_BITS
309#define FLECS_SPARSE_PAGE_BITS 6
310#endif
311
312/** @def FLECS_ENTITY_PAGE_BITS
313 * Same as FLECS_SPARSE_PAGE_BITS, but for the entity index. */
314#ifndef FLECS_ENTITY_PAGE_BITS
315#define FLECS_ENTITY_PAGE_BITS 10
316#endif
317
318/** @def FLECS_USE_OS_ALLOC
319 * When enabled, Flecs will use the OS allocator provided in the OS API directly
320 * instead of the built-in block allocator. This can decrease memory utilization
321 * as memory will be freed more often, at the cost of decreased performance. */
322// #define FLECS_USE_OS_ALLOC
323
324/** @def FLECS_ID_DESC_MAX
325 * Maximum number of IDs to add in ecs_entity_desc_t / ecs_bulk_desc_t. */
326#ifndef FLECS_ID_DESC_MAX
327#define FLECS_ID_DESC_MAX 32
328#endif
329
330/** @def FLECS_EVENT_DESC_MAX
331 * Maximum number of events in ecs_observer_desc_t. */
332#ifndef FLECS_EVENT_DESC_MAX
333#define FLECS_EVENT_DESC_MAX 8
334#endif
335
336/** @def FLECS_TERM_COUNT_MAX
337 * Maximum number of terms in queries. Should not exceed 64. */
338#ifndef FLECS_TERM_COUNT_MAX
339#define FLECS_TERM_COUNT_MAX 32
340#endif
341
342/** @def FLECS_TERM_ARG_COUNT_MAX
343 * Maximum number of arguments for a term. */
344#ifndef FLECS_TERM_ARG_COUNT_MAX
345#define FLECS_TERM_ARG_COUNT_MAX 16
346#endif
347
348#ifdef FLECS_QUERY_PLANS
349/** @def FLECS_QUERY_VARIABLE_COUNT_MAX
350 * Maximum number of query variables per query. Should not exceed 128. */
351#ifndef FLECS_QUERY_VARIABLE_COUNT_MAX
352#define FLECS_QUERY_VARIABLE_COUNT_MAX 64
353#endif
354#endif
355
356/** @def FLECS_QUERY_SCOPE_NESTING_MAX
357 * Maximum nesting depth of query scopes. */
358#ifndef FLECS_QUERY_SCOPE_NESTING_MAX
359#define FLECS_QUERY_SCOPE_NESTING_MAX 8
360#endif
361
362/** @def FLECS_DAG_DEPTH_MAX
363 * Maximum number of levels in a DAG (acyclic relationship graph). If a graph with a
364 * depth larger than this is encountered, a CYCLE_DETECTED panic is thrown.
365 */
366#ifndef FLECS_DAG_DEPTH_MAX
367#define FLECS_DAG_DEPTH_MAX 128
368#endif
369
370/** @def FLECS_TREE_SPAWNER_DEPTH_CACHE_SIZE
371 * Size of the depth cache in the tree spawner component. Higher values speed up prefab
372 * instantiation for deeper hierarchies, at the cost of slightly more memory.
373 */
374#define FLECS_TREE_SPAWNER_DEPTH_CACHE_SIZE (6)
375
376/** @} */
377
378#include "flecs/private/api_defines.h"
379
380/**
381 * @defgroup core_types Core API Types
382 * Types for core API objects.
383 *
384 * @{
385 */
386
387/** IDs are the things that can be added to an entity.
388 * An ID can be an entity or pair, and can have optional ID flags. */
389typedef uint64_t ecs_id_t;
390
391/** An entity identifier.
392 * Entity IDs consist of a number unique to the entity in the lower 32 bits,
393 * and a counter used to track entity liveliness in the upper 32 bits. When an
394 * ID is recycled, its generation count is increased. This causes recycled IDs
395 * to be very large (>4 billion), which is normal. */
397
398/** A type is a list of (component) IDs.
399 * Types are used to communicate the "type" of an entity. In most type systems, a
400 * typeof operation returns a single type. In ECS, however, an entity can have
401 * multiple components, which is why an ECS type consists of a vector of IDs.
402 *
403 * The component IDs of a type are sorted, which ensures that it doesn't matter
404 * in which order components are added to an entity. For example, if adding
405 * Position then Velocity would result in type [Position, Velocity], first
406 * adding Velocity then Position would also result in type [Position, Velocity].
407 *
408 * Entities are grouped together by type in the ECS storage in tables. The
409 * storage has exactly one table per unique type that is created by the
410 * application that stores all entities and components for that type. This is
411 * also referred to as an archetype.
412 */
413typedef struct {
414 ecs_id_t *array; /**< Array with IDs. */
415 int32_t count; /**< Number of elements in array. */
416} ecs_type_t;
417
418/** A world is the container for all ECS data and supporting features.
419 * Applications can have multiple worlds, though in most cases will only need
420 * one. Worlds are isolated from each other, and can have separate sets of
421 * systems, components, modules, etc.
422 *
423 * If an application has multiple worlds with overlapping components, it is
424 * common (though not strictly required) to use the same component IDs across
425 * worlds, which can be achieved by declaring a global component ID variable.
426 * To do this in the C API, see the entities/fwd_component_decl example. The
427 * C++ API automatically synchronizes component IDs between worlds.
428 *
429 * Component ID conflicts between worlds can occur when a world has already used
430 * an ID for something else. There are a few ways to avoid this:
431 *
432 * - Ensure to register the same components in each world, in the same order.
433 * - Create a dummy world in which all components are preregistered, which
434 * initializes the global ID variables.
435 *
436 * In some use cases, typically when writing tests, multiple worlds are created
437 * and deleted with different components, registered in different order. To
438 * ensure isolation between tests, the C++ API has a `flecs::reset` function
439 * that forces the API to ignore the old component IDs. */
441
442/** A stage enables modification while iterating and from multiple threads. */
444
445/** A table stores entities and components for a specific type. */
447
448/** A term is a single element in a query. */
449typedef struct ecs_term_t ecs_term_t;
450
451/** A query returns entities matching a list of constraints. */
453
454/** An observer is a system that is invoked when an event matches its query.
455 * Observers allow applications to respond to specific events, such as adding or
456 * removing a component. Observers are created by specifying both a query and
457 * a list of event kinds that should be listened for. An example of an observer
458 * that triggers when a Position component is added to an entity (in C++):
459 *
460 * @code
461 * world.observer<Position>()
462 * .event(flecs::OnAdd)
463 * .each([](Position& p) {
464 * // called when Position is added to an entity
465 * });
466 * @endcode
467 *
468 * Observers only trigger when the source of the event matches the full observer
469 * query. For example, an OnAdd observer for Position, Velocity will only
470 * trigger after both components have been added to the entity. */
472
473/** An observable produces events that can be listened for by an observer.
474 * Currently only the world is observable. In the future, queries will become
475 * observable objects as well. */
477
478/** Type used for iterating iterable objects.
479 * Iterators are objects that provide applications with information
480 * about the currently iterated result, and store any state required for the
481 * iteration. */
482typedef struct ecs_iter_t ecs_iter_t;
483
484/** A ref is a fast way to fetch a component for a specific entity.
485 * Refs are a faster alternative to repeatedly calling ecs_get() for the same
486 * entity/component combination. When comparing the performance of getting a ref
487 * to calling ecs_get(), a ref is typically 3-5x faster.
488 *
489 * Refs achieve this performance by caching internal data structures associated
490 * with the entity and component on the ecs_ref_t object that otherwise would
491 * have to be looked up. */
492typedef struct ecs_ref_t ecs_ref_t;
493
494/** Type hooks are callbacks associated with component lifecycle events.
495 * Typical examples of lifecycle events are construction, destruction, copying,
496 * and moving of components. */
498
499/** Type information.
500 * Contains information about a (component) type, such as its size,
501 * alignment, and type hooks. */
503
504/** Information about an entity, like its table and row. */
506
507/** Information about a (component) ID, such as type info and tables with the ID. */
509
510/** A poly object.
511 * A poly (short for polymorph) object is an object that has a variable list of
512 * capabilities, determined by a mixin table. This is the current list of types
513 * in the Flecs API that can be used as an ecs_poly_t:
514 *
515 * - ecs_world_t
516 * - ecs_stage_t
517 * - ecs_query_t
518 *
519 * Functions that accept an ecs_poly_t argument can accept objects of these
520 * types. If the object does not have the requested mixin, the API will throw an
521 * assert.
522 *
523 * The poly/mixin framework enables partially overlapping features to be
524 * implemented once, and enables objects of different types to interact with
525 * each other depending on what mixins they have, rather than their type
526 * (in some ways it's like a mini-ECS). Additionally, each poly object has a
527 * header that enables the API to do sanity checking on the input arguments.
528 */
529typedef void ecs_poly_t;
530
531/** Type that stores poly mixins. */
533
534/** Header for ecs_poly_t objects. */
535typedef struct ecs_header_t {
536 int32_t type; /**< Magic number indicating which type of Flecs object. */
537 int32_t refcount; /**< Refcount, to enable RAII handles. */
538 ecs_mixins_t *mixins; /**< Table with offsets to (optional) mixins. */
540
541/** Opaque type for table record. */
543
544/** @} */
545
546#include "flecs/datastructures/vec.h" /* Vector datatype */
547#include "flecs/datastructures/sparse.h" /* Sparse set */
548#include "flecs/datastructures/block_allocator.h" /* Block allocator */
549#include "flecs/datastructures/stack_allocator.h" /* Stack allocator */
550#include "flecs/datastructures/map.h" /* Map */
551#include "flecs/datastructures/allocator.h" /* Allocator */
552#include "flecs/datastructures/strbuf.h" /* String builder */
553#include "flecs/os_api.h" /* Abstraction for operating system functions */
554
555#ifdef __cplusplus
556extern "C" {
557#endif
558
559/**
560 * @defgroup api_types API types
561 * Public API types.
562 *
563 * @{
564 */
565
566
567/**
568 * @defgroup function_types Function types.
569 * Function callback types.
570 *
571 * @{
572 */
573
574/** Function prototype for runnables (systems, observers).
575 * The run callback overrides the default behavior for iterating through the
576 * results of a runnable object.
577 *
578 * The default runnable iterates the iterator, and calls an iter_action (see
579 * below) for each returned result.
580 *
581 * @param it The iterator to be iterated by the runnable.
582 */
583typedef void (*ecs_run_action_t)(
584 ecs_iter_t *it);
585
586/** Function prototype for iterables.
587 * A system may invoke a callback multiple times, typically once for each
588 * matched table.
589 *
590 * @param it The iterator containing the data for the current match.
591 */
592typedef void (*ecs_iter_action_t)(
593 ecs_iter_t *it);
594
595/** Function prototype for iterating an iterator.
596 * Stored inside initialized iterators. This allows an application to iterate
597 * an iterator without needing to know what created it.
598 *
599 * @param it The iterator to iterate.
600 * @return True if iterator has more results, false if not.
601 */
603 ecs_iter_t *it);
604
605/** Function prototype for freeing an iterator.
606 * Free iterator resources.
607 *
608 * @param it The iterator to free.
609 */
611 ecs_iter_t *it);
612
613/** Callback used for comparing components. */
615 ecs_entity_t e1,
616 const void *ptr1,
617 ecs_entity_t e2,
618 const void *ptr2);
619
620/** Callback used for sorting the entire table of components. */
622 ecs_world_t* world,
623 ecs_table_t* table,
624 ecs_entity_t* entities,
625 void* ptr,
626 int32_t size,
627 int32_t lo,
628 int32_t hi,
629 ecs_order_by_action_t order_by);
630
631/** Callback used for grouping tables in a query. */
632typedef uint64_t (*ecs_group_by_action_t)(
633 ecs_world_t *world,
634 ecs_table_t *table,
635 ecs_id_t group_id,
636 void *ctx);
637
638/** Callback invoked when a query creates a new group. */
639typedef void* (*ecs_group_create_action_t)(
640 ecs_world_t *world,
641 uint64_t group_id,
642 void *group_by_ctx); /* from ecs_query_desc_t */
643
644/** Callback invoked when a query deletes an existing group. */
646 ecs_world_t *world,
647 uint64_t group_id,
648 void *group_ctx, /* return value from ecs_group_create_action_t */
649 void *group_by_ctx); /* from ecs_query_desc_t */
650
651/** Initialization action for modules. */
652typedef void (*ecs_module_action_t)(
653 ecs_world_t *world);
654
655/** Action callback on world exit. */
656typedef void (*ecs_fini_action_t)(
657 ecs_world_t *world,
658 void *ctx);
659
660/** Function to clean up context data. */
661typedef void (*ecs_ctx_free_t)(
662 void *ctx);
663
664/** Callback used for sorting values. */
665typedef int (*ecs_compare_action_t)(
666 const void *ptr1,
667 const void *ptr2);
668
669/** Callback used for hashing values. */
670typedef uint64_t (*ecs_hash_value_action_t)(
671 const void *ptr);
672
673/** Constructor/destructor callback. */
674typedef void (*ecs_xtor_t)(
675 void *ptr,
676 int32_t count,
677 const ecs_type_info_t *type_info);
678
679/** Copy is invoked when a component is copied into another component. */
680typedef void (*ecs_copy_t)(
681 void *dst_ptr,
682 const void *src_ptr,
683 int32_t count,
684 const ecs_type_info_t *type_info);
685
686/** Move is invoked when a component is moved to another component. */
687typedef void (*ecs_move_t)(
688 void *dst_ptr,
689 void *src_ptr,
690 int32_t count,
691 const ecs_type_info_t *type_info);
692
693/** Compare hook to compare component instances. */
694typedef int (*ecs_cmp_t)(
695 const void *a_ptr,
696 const void *b_ptr,
697 const ecs_type_info_t *type_info);
698
699/** Equals operator hook. */
700typedef bool (*ecs_equals_t)(
701 const void *a_ptr,
702 const void *b_ptr,
703 const ecs_type_info_t *type_info);
704
705/** On validate hook. Invoked before on_set/OnSet hooks and observers. When the
706 * hook returns false, the on_set/OnSet hooks and observers are not invoked for
707 * the entity. */
708typedef bool (*ecs_on_validate_t)(
709 ecs_world_t *world,
710 ecs_entity_t entity,
711 void *ptr);
712
713/** Destructor function for poly objects. */
714typedef void (*flecs_poly_dtor_t)(
715 ecs_poly_t *poly);
716
717/** @} */
718
719/**
720 * @defgroup query_types Query descriptor types.
721 * Types used to describe queries.
722 *
723 * @{
724 */
725
726/** Specify read/write access for term. */
727typedef enum ecs_inout_kind_t {
728 EcsInOutDefault, /**< InOut for regular terms, In for shared terms. */
729 EcsInOutNone, /**< Term is neither read nor written. */
730 EcsInOutFilter, /**< Same as InOutNone + prevents term from triggering observers. */
731 EcsInOut, /**< Term is both read and written. */
732 EcsIn, /**< Term is only read. */
733 EcsOut, /**< Term is only written. */
735
736/** Specify operator for term. */
737typedef enum ecs_oper_kind_t {
738 EcsAnd, /**< The term must match. */
739 EcsOr, /**< One of the terms in an or chain must match. */
740 EcsNot, /**< The term must not match. */
741 EcsOptional, /**< The term may match. */
742 EcsAndFrom, /**< Term must match all components from term ID. */
743 EcsOrFrom, /**< Term must match at least one component from term ID. */
744 EcsNotFrom, /**< Term must match none of the components from term ID. */
746
747/** Specify cache policy for query. */
749 EcsQueryCacheDefault, /**< Behavior determined by query creation context. */
750 EcsQueryCacheAuto, /**< Cache query terms that are cacheable. */
751#ifdef FLECS_CACHED_QUERIES
752 EcsQueryCacheAll, /**< Require that all query terms can be cached. */
753#endif
754 EcsQueryCacheNone, /**< No caching. */
756
757/** Term ID flags. */
758
759/** Match on self.
760 * Can be combined with other term flags on the ecs_term_ref_t::id field.
761 * \ingroup queries
762 */
763#define EcsSelf (1llu << 63)
764
765/** Match by traversing upwards.
766 * Can be combined with other term flags on the ecs_term_ref_t::id field.
767 * \ingroup queries
768 */
769#define EcsUp (1llu << 62)
770
771/** Traverse relationship transitively.
772 * Can be combined with other term flags on the ecs_term_ref_t::id field.
773 * \ingroup queries
774 */
775#define EcsTrav (1llu << 61)
776
777/** Sort results breadth-first.
778 * Can be combined with other term flags on the ecs_term_ref_t::id field.
779 * \ingroup queries
780 */
781#define EcsCascade (1llu << 60)
782
783/** Iterate groups in descending order.
784 * Can be combined with other term flags on the ecs_term_ref_t::id field.
785 * \ingroup queries
786 */
787#define EcsDesc (1llu << 59)
788
789/** Term ID is a variable.
790 * Can be combined with other term flags on the ecs_term_ref_t::id field.
791 * \ingroup queries
792 */
793#define EcsIsVariable (1llu << 58)
794
795/** Term ID is an entity.
796 * Can be combined with other term flags on the ecs_term_ref_t::id field.
797 * \ingroup queries
798 */
799#define EcsIsEntity (1llu << 57)
800
801/** Term ID is a name (don't attempt to look up as an entity).
802 * Can be combined with other term flags on the ecs_term_ref_t::id field.
803 * \ingroup queries
804 */
805#define EcsIsName (1llu << 56)
806
807/** All term traversal flags.
808 * Can be combined with other term flags on the ecs_term_ref_t::id field.
809 * \ingroup queries
810 */
811#define EcsTraverseFlags (EcsSelf|EcsUp|EcsTrav|EcsCascade|EcsDesc)
812
813/** All term reference kind flags.
814 * Can be combined with other term flags on the ecs_term_ref_t::id field.
815 * \ingroup queries
816 */
817#define EcsTermRefFlags (EcsTraverseFlags|EcsIsVariable|EcsIsEntity|EcsIsName)
818
819/** Type that describes a reference to an entity or variable in a term. */
820typedef struct ecs_term_ref_t {
821 ecs_entity_t id; /**< Entity ID. If left to 0 and flags do not
822 * specify whether the ID is an entity or a variable,
823 * the ID will be initialized to #EcsThis.
824 * To explicitly set the ID to 0, leave the ID
825 * member to 0 and set #EcsIsEntity in flags. */
826
827 const char *name; /**< Name. This can be either the variable name
828 * (when the #EcsIsVariable flag is set) or an
829 * entity name. When ecs_term_t::move is true,
830 * the API assumes ownership over the string and
831 * will free it when the term is destroyed. */
833
834/** Type that describes a term (single element in a query). */
836 ecs_id_t id; /**< Component ID to be matched by term. Can be
837 * set directly, or will be populated from the
838 * first/second members, which provide more
839 * flexibility. */
840
841 ecs_term_ref_t src; /**< Source of term. */
842 ecs_term_ref_t first; /**< Component or first element of pair. */
843 ecs_term_ref_t second; /**< Second element of pair. */
844
845 ecs_entity_t trav; /**< Relationship to traverse when looking for the
846 * component. The relationship must have
847 * the `Traversable` property. Default is `IsA`. */
848
849 int16_t inout; /**< Access to contents matched by term. */
850 int16_t oper; /**< Operator of term. */
851
852 int8_t field_index; /**< Index of the field for the term in the iterator. */
853 ecs_flags16_t flags_; /**< Flags that help evaluation, set by ecs_query_init(). */
854};
855
856/** Queries are lists of constraints (terms) that match entities.
857 * Created with ecs_query_init().
858 */
860 ecs_header_t hdr; /**< Object header. */
861
862 ecs_term_t *terms; /**< Query terms. */
863 int32_t *sizes; /**< Component sizes. Indexed by field. */
864 ecs_id_t *ids; /**< Component ids. Indexed by field. */
865
866 uint64_t bloom_filter; /**< Bitmask used to quickly discard tables. */
867 ecs_flags32_t flags; /**< Query flags. */
868#ifdef FLECS_QUERY_PLANS
869 int8_t var_count; /**< Number of query variables. */
870#endif
871 int8_t term_count; /**< Number of query terms. */
872 int8_t field_count; /**< Number of fields returned by the query. */
873
874 /** Bitmasks for quick field information lookups. */
875 ecs_termset_t fixed_fields; /**< Fields with a fixed source. */
876 ecs_termset_t var_fields; /**< Fields with non-$this variable source. */
877 ecs_termset_t static_id_fields; /**< Fields with a static (component) id. */
878 ecs_termset_t data_fields; /**< Fields that have data. */
879 ecs_termset_t write_fields; /**< Fields that write data. */
880 ecs_termset_t read_fields; /**< Fields that read data. */
881 ecs_termset_t row_fields; /**< Fields that must be acquired with field_at. */
882 ecs_termset_t shared_readonly_fields; /**< Fields that don't write shared data. */
883 ecs_termset_t set_fields; /**< Fields that will be set. */
884
885 ecs_query_cache_kind_t cache_kind; /**< Caching policy of the query. */
886
887#ifdef FLECS_QUERY_PLANS
888 char **vars; /**< Array with variable names for the iterator. */
889#endif
890
891 void *ctx; /**< User context to pass to callback. */
892 void *binding_ctx; /**< Context to be used for language bindings. */
893
894 ecs_entity_t entity; /**< Entity associated with query (optional). */
895 ecs_world_t *stage; /**< World or stage the query was created with. */
896 ecs_world_t *world; /**< Actual world. */
897
898 int32_t eval_count; /**< Number of times the query is evaluated. */
899};
900
901/** An observer reacts to events matching a query.
902 * Created with ecs_observer_init().
903 */
905 ecs_header_t hdr; /**< Object header. */
906
907 ecs_query_t *query; /**< Observer query. */
908
909 /** Observer events. */
911 int32_t event_count; /**< Number of events. */
912
913 ecs_iter_action_t callback; /**< See ecs_observer_desc_t::callback. */
914 ecs_run_action_t run; /**< See ecs_observer_desc_t::run. */
915
916 void *ctx; /**< Observer context. */
917 void *callback_ctx; /**< Callback language binding context. */
918 void *run_ctx; /**< Run language binding context. */
919
920 ecs_ctx_free_t ctx_free; /**< Callback to free ctx. */
921 ecs_ctx_free_t callback_ctx_free; /**< Callback to free callback_ctx. */
922 ecs_ctx_free_t run_ctx_free; /**< Callback to free run_ctx. */
923
924 ecs_observable_t *observable; /**< Observable for the observer. */
925
926 ecs_world_t *world; /**< The world. */
927 ecs_entity_t entity; /**< Entity associated with the observer. */
928};
929
930/** @} */
931
932/** Type that contains component lifecycle callbacks.
933 *
934 * @ingroup components
935 */
936
937/* Flags that can be used to check which hooks a type has set */
938#define ECS_TYPE_HOOK_CTOR ECS_CAST(ecs_flags32_t, 1 << 0)
939#define ECS_TYPE_HOOK_DTOR ECS_CAST(ecs_flags32_t, 1 << 1)
940#define ECS_TYPE_HOOK_COPY ECS_CAST(ecs_flags32_t, 1 << 2)
941#define ECS_TYPE_HOOK_MOVE ECS_CAST(ecs_flags32_t, 1 << 3)
942#define ECS_TYPE_HOOK_COPY_CTOR ECS_CAST(ecs_flags32_t, 1 << 4)
943#define ECS_TYPE_HOOK_MOVE_CTOR ECS_CAST(ecs_flags32_t, 1 << 5)
944#define ECS_TYPE_HOOK_CTOR_MOVE_DTOR ECS_CAST(ecs_flags32_t, 1 << 6)
945#define ECS_TYPE_HOOK_MOVE_DTOR ECS_CAST(ecs_flags32_t, 1 << 7)
946#define ECS_TYPE_HOOK_CMP ECS_CAST(ecs_flags32_t, 1 << 8)
947#define ECS_TYPE_HOOK_EQUALS ECS_CAST(ecs_flags32_t, 1 << 9)
948
949
950/* Flags that can be used to set/check which hooks of a type are invalid */
951#define ECS_TYPE_HOOK_CTOR_ILLEGAL ECS_CAST(ecs_flags32_t, 1 << 10)
952#define ECS_TYPE_HOOK_DTOR_ILLEGAL ECS_CAST(ecs_flags32_t, 1 << 12)
953#define ECS_TYPE_HOOK_COPY_ILLEGAL ECS_CAST(ecs_flags32_t, 1 << 13)
954#define ECS_TYPE_HOOK_MOVE_ILLEGAL ECS_CAST(ecs_flags32_t, 1 << 14)
955#define ECS_TYPE_HOOK_COPY_CTOR_ILLEGAL ECS_CAST(ecs_flags32_t, 1 << 15)
956#define ECS_TYPE_HOOK_MOVE_CTOR_ILLEGAL ECS_CAST(ecs_flags32_t, 1 << 16)
957#define ECS_TYPE_HOOK_CTOR_MOVE_DTOR_ILLEGAL ECS_CAST(ecs_flags32_t, 1 << 17)
958#define ECS_TYPE_HOOK_MOVE_DTOR_ILLEGAL ECS_CAST(ecs_flags32_t, 1 << 18)
959#define ECS_TYPE_HOOK_CMP_ILLEGAL ECS_CAST(ecs_flags32_t, 1 << 19)
960#define ECS_TYPE_HOOK_EQUALS_ILLEGAL ECS_CAST(ecs_flags32_t, 1 << 20)
961
962/* Internal debug flag that indicates type hooks have been invoked */
963#define ECS_TYPE_HOOK_IN_USE ECS_CAST(ecs_flags32_t, 1 << 21)
964
965
966/* All valid hook flags */
967#define ECS_TYPE_HOOKS (ECS_TYPE_HOOK_CTOR|ECS_TYPE_HOOK_DTOR|\
968 ECS_TYPE_HOOK_COPY|ECS_TYPE_HOOK_MOVE|ECS_TYPE_HOOK_COPY_CTOR|\
969 ECS_TYPE_HOOK_MOVE_CTOR|ECS_TYPE_HOOK_CTOR_MOVE_DTOR|\
970 ECS_TYPE_HOOK_MOVE_DTOR|ECS_TYPE_HOOK_CMP|ECS_TYPE_HOOK_EQUALS)
971
972/* All invalid hook flags */
973#define ECS_TYPE_HOOKS_ILLEGAL (ECS_TYPE_HOOK_CTOR_ILLEGAL|\
974 ECS_TYPE_HOOK_DTOR_ILLEGAL|ECS_TYPE_HOOK_COPY_ILLEGAL|\
975 ECS_TYPE_HOOK_MOVE_ILLEGAL|ECS_TYPE_HOOK_COPY_CTOR_ILLEGAL|\
976 ECS_TYPE_HOOK_MOVE_CTOR_ILLEGAL|ECS_TYPE_HOOK_CTOR_MOVE_DTOR_ILLEGAL|\
977 ECS_TYPE_HOOK_MOVE_DTOR_ILLEGAL|ECS_TYPE_HOOK_CMP_ILLEGAL|\
978 ECS_TYPE_HOOK_EQUALS_ILLEGAL)
980 ecs_xtor_t ctor; /**< ctor. */
981 ecs_xtor_t dtor; /**< dtor. */
982 ecs_copy_t copy; /**< copy assignment. */
983 ecs_move_t move; /**< move assignment. */
984
985 /** Ctor + copy. */
987
988 /** Ctor + move. */
990
991 /** Ctor + move + dtor (or move_ctor + dtor).
992 * This combination is typically used when a component is moved from one
993 * location to a new location, like when it is moved to a new table. If
994 * not set explicitly, it will be derived from other callbacks. */
996
997 /** Move + dtor.
998 * This combination is typically used when a component is moved from one
999 * location to an existing location, like what happens during a remove. If
1000 * not set explicitly, it will be derived from other callbacks. */
1002
1003 /** Compare hook. */
1005
1006 /** Equals hook. */
1008
1009 /** Hook flags.
1010 * Indicates which hooks are set for the type, and which hooks are illegal.
1011 * When an ILLEGAL flag is set when calling ecs_set_hooks(), a hook callback
1012 * will be set that panics when called. */
1013 ecs_flags32_t flags;
1014
1015 /** Callback that is invoked when an instance of a component is added. This
1016 * callback is invoked before observers are invoked. */
1018
1019 /** Callback that is invoked when an instance of the component is set. This
1020 * callback is invoked before observers are invoked, and enables the component
1021 * to respond to changes on itself before others can. */
1023
1024 /** Callback that is invoked when an instance of the component is removed.
1025 * This callback is invoked after the observers are invoked, and before the
1026 * destructor is invoked. */
1028
1029 /** Callback that is invoked with the existing and new value before the
1030 * value is assigned. Invoked after on_add and before on_set. Registering
1031 * an on_replace hook prevents using operations that return a mutable
1032 * pointer to the component, like get_mut(), ensure(), and emplace(). */
1034
1035 /** Callback that is invoked before the on_set/OnSet hooks and observers are
1036 * invoked. When the callback returns false, the on_set/OnSet hooks and
1037 * observers are not invoked for the entity. */
1039
1040 void *ctx; /**< User-defined context. */
1041 void *binding_ctx; /**< Language binding context. */
1042 void *lifecycle_ctx; /**< Component lifecycle context (see meta addon). */
1043
1044 ecs_ctx_free_t ctx_free; /**< Callback to free ctx. */
1045 ecs_ctx_free_t binding_ctx_free; /**< Callback to free binding_ctx. */
1046 ecs_ctx_free_t lifecycle_ctx_free; /**< Callback to free lifecycle_ctx. */
1047};
1048
1049/** Type that contains component information (passed to ctors/dtors/...).
1050 *
1051 * @ingroup components
1052 */
1054 ecs_size_t size; /**< Size of the type. */
1055 ecs_size_t alignment; /**< Alignment of the type. */
1056 ecs_type_hooks_t hooks; /**< Type hooks. */
1057 ecs_entity_t component; /**< Handle to component (do not set). */
1058 const char *name; /**< Type name. */
1059 int32_t refcount; /**< Refcount (do not set). */
1060};
1061
1062#include "flecs/private/api_types.h" /* Supporting API types */
1063#include "flecs/private/api_support.h" /* Supporting API functions */
1064#include "flecs/datastructures/hashmap.h" /* Hashmap */
1065#include "flecs/private/api_internals.h" /* Supporting API functions */
1066
1067/** Value of a dynamic type.
1068 * See the meta addon for functions to create, assign and destruct values. */
1069typedef struct ecs_value_t {
1070 ecs_entity_t type; /**< Type of value. */
1071 void *ptr; /**< Pointer to value. */
1073
1074/** Used with ecs_entity_init().
1075 *
1076 * @ingroup entities
1077 */
1078typedef struct ecs_entity_desc_t {
1079 int32_t _canary; /**< Used for validity testing. Must be 0. */
1080
1081 ecs_entity_t id; /**< Set to modify existing entity (optional). */
1082
1083 ecs_entity_t parent; /**< Parent entity. */
1084
1085 const char *name; /**< Name of the entity. If no entity is provided, an
1086 * entity with this name will be looked up first. When
1087 * an entity is provided, the name will be verified
1088 * with the existing entity. */
1089
1090 const char *sep; /**< Optional custom separator for hierarchical names.
1091 * Leave to NULL for the default ('.') separator. Set to
1092 * an empty string to prevent tokenization of the name. */
1093
1094 const char *root_sep; /**< Optional, used for identifiers relative to the root. */
1095
1096 const char *symbol; /**< Optional entity symbol. A symbol is an unscoped
1097 * identifier that can be used to look up an entity. The
1098 * primary use case for this is to associate the entity
1099 * with a language identifier, such as a type or
1100 * function name, where these identifiers differ from
1101 * the name they are registered with in Flecs. For
1102 * example, C type "EcsPosition" might be registered
1103 * as "flecs.components.transform.Position", with the
1104 * symbol set to "EcsPosition". */
1105
1106 bool use_low_id; /**< When set to true, a low id (typically reserved for
1107 * components) will be used to create the entity, if
1108 * no ID is specified. */
1110
1111/** Used with ecs_bulk_init().
1112 *
1113 * @ingroup entities
1114 */
1115typedef struct ecs_bulk_desc_t {
1116 int32_t _canary; /**< Used for validity testing. Must be 0. */
1117
1118 ecs_entity_t *entities; /**< Entities to bulk insert. Entity IDs provided by
1119 * the application must be empty (cannot
1120 * have components). If no entity IDs are provided, the
1121 * operation will create 'count' new entities. */
1122
1123 int32_t count; /**< Number of entities to create/populate. */
1124
1125 ecs_id_t ids[FLECS_ID_DESC_MAX]; /**< IDs to create the entities with. */
1126
1127 void **data; /**< Array with component data to insert. Each element in
1128 * the array must correspond with an element in the ids
1129 * array. If an element in the ids array is a tag, the
1130 * data array must contain a NULL. An element may be
1131 * set to NULL for a component, in which case the
1132 * component will not be set by the operation. */
1133
1134 ecs_table_t *table; /**< Table to insert the entities into. Should not be set
1135 * at the same time as ids. When 'table' is set at the
1136 * same time as 'data', the elements in the data array
1137 * must correspond with the ids in the table's type. */
1138
1140
1141/** Used with ecs_component_init().
1142 *
1143 * @ingroup components
1144 */
1145typedef struct ecs_component_desc_t {
1146 int32_t _canary; /**< Used for validity testing. Must be 0. */
1147
1148 /** Existing entity to associate with a component (optional). */
1150
1151 /** Parameters for type (size, hooks, ...). */
1154
1155/** Iterator.
1156 * Used for iterating queries. The ecs_iter_t type contains all the information
1157 * that is provided by a query, and contains all the state required for the
1158 * iterator code.
1159 *
1160 * Functions that create iterators accept as first argument the world, and as
1161 * second argument the object they iterate. For example:
1162 *
1163 * @code
1164 * ecs_iter_t it = ecs_query_iter(world, q);
1165 * @endcode
1166 *
1167 * An iterator contains resources that need to be released. By default, this
1168 * is handled by the last call to next() that returns false. When iteration is
1169 * ended before iteration has completed, an application has to manually call
1170 * ecs_iter_fini() to release the iterator resources:
1171 *
1172 * @code
1173 * ecs_iter_t it = ecs_query_iter(world, q);
1174 * while (ecs_query_next(&it)) {
1175 * if (cond) {
1176 * ecs_iter_fini(&it);
1177 * break;
1178 * }
1179 * }
1180 * @endcode
1181 *
1182 * @ingroup queries
1183 */
1185 ecs_world_t *stage;
1186 ecs_world_t *world;
1187
1188 /* Matched data */
1189 int32_t offset; /**< Offset relative to the current table. */
1190 int32_t count; /**< Number of entities to iterate. */
1191 const ecs_entity_t *entities; /**< Entity identifiers. */
1192 void **ptrs; /**< Component pointers. If not set or if it is NULL for a field, use it->trs. */
1193 const ecs_table_record_t **trs; /**< Info on where to find the field in the table. */
1194 const int16_t *columns;
1195 const ecs_size_t *sizes; /**< Component sizes. */
1196 ecs_table_t *table; /**< Current table. */
1197 ecs_table_t *other_table; /**< Previous or next table when adding or removing. */
1198 ecs_id_t *ids; /**< (Component) IDs. */
1199 ecs_entity_t *sources; /**< Entity on which the ID was matched (0 if same as entities). */
1200#ifdef FLECS_QUERY_PLANS
1201 ecs_flags64_t constrained_vars; /**< Bitset that marks constrained variables. */
1202#endif
1203 ecs_termset_t set_fields; /**< Fields that are set. */
1204 ecs_termset_t ref_fields; /**< Bitset with fields that aren't component arrays. */
1205 ecs_termset_t row_fields; /**< Fields that must be obtained with field_at. */
1206 ecs_termset_t up_fields; /**< Bitset with fields matched through up traversal. */
1207
1208 /* Input information */
1209 ecs_entity_t system; /**< The system (if applicable). */
1210 ecs_entity_t event; /**< The event (if applicable). */
1211 ecs_id_t event_id; /**< The (component) ID for the event. */
1212 int32_t event_cur; /**< Unique event ID. Used to dedup observer calls. */
1213
1214 /* Query information */
1215 int8_t field_count; /**< Number of fields in the iterator. */
1216 int8_t term_index; /**< Index of the term that emitted an event.
1217 * This field will be set to the 'index' field
1218 * of an observer term. */
1219 const ecs_query_t *query; /**< Query being evaluated. */
1220
1221 /* Context */
1222 void *param; /**< Param passed to ecs_run(). */
1223 void *ctx; /**< System context. */
1224 void *binding_ctx; /**< System binding context. */
1225 void *callback_ctx; /**< Callback language binding context. */
1226 void *run_ctx; /**< Run language binding context. */
1227
1228 /* Time */
1229 ecs_ftime_t delta_time; /**< Time elapsed since last frame. */
1230 ecs_ftime_t delta_system_time;/**< Time elapsed since last system invocation. */
1231
1232 /* Iterator counters */
1233 int32_t frame_offset; /**< Offset relative to the start of iteration. */
1234
1235 /* Misc */
1236 ecs_flags32_t flags; /**< Iterator flags. */
1237 ecs_entity_t interrupted_by; /**< When set, system execution is interrupted. */
1238 ecs_iter_private_t priv_; /**< Private data. */
1239
1240 /* Chained iterators */
1241 ecs_iter_next_action_t next; /**< Function to progress iterator. */
1242 ecs_iter_action_t callback; /**< Callback of system or observer. */
1243 ecs_iter_fini_action_t fini; /**< Function to clean up iterator resources. */
1244 ecs_iter_t *chain_it; /**< Optional, allows for creating iterator chains. */
1245};
1246
1247
1248/** Query must match prefabs.
1249 * Can be combined with other query flags on the ecs_query_desc_t::flags field.
1250 * \ingroup queries
1251 */
1252#define EcsQueryMatchPrefab (1u << 1u)
1253
1254/** Query must match disabled entities.
1255 * Can be combined with other query flags on the ecs_query_desc_t::flags field.
1256 * \ingroup queries
1257 */
1258#define EcsQueryMatchDisabled (1u << 2u)
1259
1260/** Query must match empty tables.
1261 * Can be combined with other query flags on the ecs_query_desc_t::flags field.
1262 * \ingroup queries
1263 */
1264#define EcsQueryMatchEmptyTables (1u << 3u)
1265
1266/** Query may have unresolved entity identifiers.
1267 * Can be combined with other query flags on the ecs_query_desc_t::flags field.
1268 * \ingroup queries
1269 */
1270#define EcsQueryAllowUnresolvedByName (1u << 6u)
1271
1272/** Query only returns whole tables (ignores toggle or member fields).
1273 * Can be combined with other query flags on the ecs_query_desc_t::flags field.
1274 * \ingroup queries
1275 */
1276#define EcsQueryTableOnly (1u << 7u)
1277
1278/** Enable change detection for a query.
1279 * Can be combined with other query flags on the ecs_query_desc_t::flags field.
1280 *
1281 * Adding this flag makes it possible to use ecs_query_changed() and
1282 * ecs_iter_changed() with the query. Change detection requires the query to be
1283 * cached. If cache_kind is left to the default value, this flag will cause it
1284 * to default to EcsQueryCacheAuto.
1285 *
1286 * \ingroup queries
1287 */
1288#define EcsQueryDetectChanges (1u << 8u)
1289
1290/** Enable ordering for query groups.
1291 * When this flag is set, groups will be iterated in ascending order, with lower
1292 * group ids first and higher group ids afterwards.
1293 *
1294 * This flag is enabled automatically when a query contains cascade terms.
1295 *
1296 * \ingroup queries
1297 */
1298#define EcsQueryGroupByOrdered (1u << 9u)
1299
1300/** Enable descending ordering for query groups.
1301 * When this flag is set in combination with EcsQueryGroupByOrdered, groups will
1302 * be iterated in descending order, with higher group ids first and lower group
1303 * ids afterwards.
1304 *
1305 * This flag is enabled automatically when a query contains cascade|desc terms.
1306 *
1307 * \ingroup queries
1308 */
1309#define EcsQueryGroupByDesc (1u << 10u)
1310
1311#define EcsQueryDontKeepAlive (1u << 21u)
1312
1313
1314/** Used with ecs_query_init().
1315 *
1316 * \ingroup queries
1317 */
1318typedef struct ecs_query_desc_t {
1319 /** Used for validity testing. Must be 0. */
1320 int32_t _canary;
1321
1322 /** Query terms. */
1324
1325 /** Query DSL expression (optional). */
1326 const char *expr;
1327
1328 /** Caching policy of the query. */
1330
1331 /** Flags for enabling query features. */
1332 ecs_flags32_t flags;
1333
1334 /** Callback used for ordering query results. If order_by is 0, the
1335 * pointer provided to the callback will be NULL. If the callback is not
1336 * set, results will not be ordered. */
1338
1339 /** Callback used for ordering query results. Same as order_by_callback,
1340 * but more efficient. */
1342
1343 /** Component to sort on, used together with order_by_callback or
1344 * order_by_table_callback. */
1346
1347 /** Component ID to be used for grouping. Used together with the
1348 * group_by_callback. */
1350
1351 /** Callback used for grouping results. If the callback is not set, results
1352 * will not be grouped. When set, this callback will be used to calculate a
1353 * "rank" for each entity (table) based on its components. This rank is then
1354 * used to sort entities (tables), so that entities (tables) of the same
1355 * rank are "grouped" together when iterated. */
1357
1358 /** Callback that is invoked when a new group is created. The return value of
1359 * the callback is stored as context for a group. */
1361
1362 /** Callback that is invoked when an existing group is deleted. The return
1363 * value of the on_group_create callback is passed as context parameter. */
1365
1366 /** Context to pass to group_by. */
1368
1369 /** Function to free group_by_ctx. */
1371
1372 /** User context to pass to callback. */
1373 void *ctx;
1374
1375 /** Context to be used for language bindings. */
1377
1378 /** Callback to free ctx. */
1380
1381 /** Callback to free binding_ctx. */
1383
1384 /** Entity associated with query (optional). */
1387
1388/** Used with ecs_observer_init().
1389 *
1390 * @ingroup observers
1391 */
1392typedef struct ecs_observer_desc_t {
1393 /** Used for validity testing. Must be 0. */
1394 int32_t _canary;
1395
1396 /** Existing entity to associate with an observer (optional). */
1398
1399 /** Query for observer. */
1401
1402 /** Events to observe (OnAdd, OnRemove, OnSet). */
1404
1405 /** When an observer is created, generate events from existing data. For example,
1406 * #EcsOnAdd `Position` would match all existing instances of `Position`. */
1408
1409 /** Global observers are tied to the lifespan of the world. Creating a
1410 * global observer does not create an entity, and therefore
1411 * ecs_observer_init() will not return an entity handle. */
1413
1414 /** Callback to invoke on an event, invoked when the observer matches. */
1416
1417 /** Callback invoked on an event. When left to NULL, the default runner
1418 * is used, which matches the event with the observer's query, and calls
1419 * 'callback' when it matches.
1420 * A reason to override the run function is to improve performance, if there
1421 * are more efficient ways to test whether an event matches the observer than
1422 * the general-purpose query matcher. */
1424
1425 /** User context to pass to callback. */
1426 void *ctx;
1427
1428 /** Callback to free ctx. */
1430
1431 /** Context associated with callback (for language bindings). */
1433
1434 /** Callback to free callback ctx. */
1436
1437 /** Context associated with run (for language bindings). */
1438 void *run_ctx;
1439
1440 /** Callback to free run ctx. */
1442
1443 /** Used for internal purposes. Do not set. */
1445 int8_t term_index_; /**< Used for internal purposes. Do not set. */
1446 ecs_flags32_t flags_; /**< Used for internal purposes. Do not set. */
1448
1449/** Used with ecs_emit().
1450 *
1451 * @ingroup observers
1452 */
1453typedef struct ecs_event_desc_t {
1454 /** The event ID. Only observers for the specified event will be notified. */
1456
1457 /** Component IDs. Only observers with a matching component ID will be
1458 * notified. Observers are guaranteed to get notified once, even if they
1459 * match more than one ID. */
1461
1462 /** The table for which to notify. */
1464
1465 /** Optional second table to notify. This can be used to communicate the
1466 * previous or next table, in case an entity is moved between tables. */
1468
1469 /** Limit notified entities to ones starting from offset (row) in table. */
1470 int32_t offset;
1471
1472 /** Limit number of notified entities to count. offset+count must be less
1473 * than the total number of entities in the table. If left to 0, it will be
1474 * automatically determined by doing `ecs_table_count(table) - offset`. */
1475 int32_t count;
1476
1477 /** Single-entity alternative to setting table / offset / count. */
1479
1480 /** Optional context.
1481 * The type of the param must be the event, where the event is a component.
1482 * When an event is enqueued, the value of param is copied to a temporary
1483 * storage of the event type. */
1484 void *param;
1485
1486 /** Same as param, but with the guarantee that the value won't be modified.
1487 * When an event with a const parameter is enqueued, the value of the param
1488 * is copied to a temporary storage of the event type. */
1489 const void *const_param;
1490
1491 /** Optional pointer to the value of the component for which the event is
1492 * emitted. May only be set for events that are emitted for a single
1493 * component id and a single entity. If provided, observers will use this
1494 * pointer instead of fetching the component from the table/storage. */
1495 void *set_ptr;
1496
1497 /** Observable (usually the world). */
1499
1500 /** Event flags. */
1501 ecs_flags32_t flags;
1503
1504
1505/**
1506 * @defgroup misc_types Miscellaneous types
1507 * Types used to create entities, observers, queries, and more.
1508 *
1509 * @{
1510 */
1511
1512/** Type with information about the current Flecs build. */
1513typedef struct ecs_build_info_t {
1514 const char *compiler; /**< Compiler used to compile Flecs. */
1515 const char **addons; /**< Addons included in the build. */
1516 const char **flags; /**< Compile-time settings. */
1517 const char *version; /**< Stringified version. */
1518 int16_t version_major; /**< Major Flecs version. */
1519 int16_t version_minor; /**< Minor Flecs version. */
1520 int16_t version_patch; /**< Patch Flecs version. */
1521 bool debug; /**< Is this a debug build? */
1522 bool sanitize; /**< Is this a sanitize build? */
1523 bool perf_trace; /**< Is this a perf tracing build? */
1525
1526/** Type that contains information about the world. */
1527typedef struct ecs_world_info_t {
1528 ecs_entity_t last_component_id; /**< Last issued component entity ID. */
1529
1530 ecs_ftime_t delta_time_raw; /**< Raw delta time (no time scaling). */
1531 ecs_ftime_t delta_time; /**< Time passed to or computed by ecs_progress(). */
1532 ecs_ftime_t time_scale; /**< Time scale applied to delta_time. */
1533 ecs_ftime_t target_fps; /**< Target FPS. */
1534 ecs_ftime_t frame_time_total; /**< Total time spent processing a frame. */
1535 ecs_ftime_t system_time_total; /**< Total time spent in systems. */
1536 ecs_ftime_t emit_time_total; /**< Total time spent notifying observers. */
1537 ecs_ftime_t merge_time_total; /**< Total time spent in merges. */
1538 ecs_ftime_t rematch_time_total; /**< Time spent on query rematching. */
1539 double world_time_total; /**< Time elapsed in simulation. */
1540 double world_time_total_raw; /**< Time elapsed in simulation (no scaling). */
1541
1542 int64_t frame_count_total; /**< Total number of frames. */
1543 int64_t merge_count_total; /**< Total number of merges. */
1544 int64_t eval_comp_monitors_total; /**< Total number of monitor evaluations. */
1545 int64_t rematch_count_total; /**< Total number of rematches. */
1546
1547 int64_t id_create_total; /**< Total number of times a new ID was created. */
1548 int64_t id_delete_total; /**< Total number of times an ID was deleted. */
1549 int64_t table_create_total; /**< Total number of times a table was created. */
1550 int64_t table_delete_total; /**< Total number of times a table was deleted. */
1551 int64_t pipeline_build_count_total; /**< Total number of pipeline builds. */
1552 int64_t systems_ran_total; /**< Total number of systems run. */
1553 int64_t observers_ran_total; /**< Total number of times an observer was invoked. */
1554 int64_t queries_ran_total; /**< Total number of times a query was evaluated. */
1555
1556 int32_t tag_id_count; /**< Number of tag (no data) IDs in the world. */
1557 int32_t component_id_count; /**< Number of component (data) IDs in the world. */
1558 int32_t pair_id_count; /**< Number of pair IDs in the world. */
1559
1560 int32_t table_count; /**< Number of tables. */
1561
1562 uint32_t creation_time; /**< Time when world was created. */
1563
1564 /* -- Command counts -- */
1565 struct {
1566 int64_t add_count; /**< Add commands processed. */
1567 int64_t remove_count; /**< Remove commands processed. */
1568 int64_t delete_count; /**< Delete commands processed. */
1569 int64_t clear_count; /**< Clear commands processed. */
1570 int64_t set_count; /**< Set commands processed. */
1571 int64_t ensure_count; /**< Ensure or emplace commands processed. */
1572 int64_t modified_count; /**< Modified commands processed. */
1573 int64_t discard_count; /**< Commands discarded, happens when the entity is no longer alive when running the command. */
1574 int64_t event_count; /**< Enqueued custom events. */
1575 int64_t other_count; /**< Other commands processed. */
1576 int64_t batched_entity_count; /**< Entities for which commands were batched. */
1577 int64_t batched_command_count; /**< Commands batched. */
1578 } cmd; /**< Command statistics. */
1579
1580 const char *name_prefix; /**< Value set by ecs_set_name_prefix(). Used
1581 * to remove library prefixes of symbol
1582 * names (such as `Ecs`, `ecs_`) when
1583 * registering them as names. */
1585
1586/** Type that contains information about a query group. */
1588 uint64_t id; /**< Group ID. */
1589 int32_t match_count; /**< How often tables have been matched or unmatched. */
1590 int32_t table_count; /**< Number of tables in group. */
1591 void *ctx; /**< Group context, returned by on_group_create. */
1593
1594/** @} */
1595
1596/**
1597 * @defgroup builtin_components Built-in component types.
1598 * Types that represent built-in components.
1599 *
1600 * @{
1601 */
1602
1603/** A (string) identifier. Used as a pair with #EcsName and #EcsSymbol tags. */
1604typedef struct EcsIdentifier {
1605 char *value; /**< Identifier string. */
1606 ecs_size_t length; /**< Length of identifier. */
1607 uint64_t hash; /**< Hash of current value. */
1608 uint64_t index_hash; /**< Hash of existing record in current index. */
1609 ecs_hashmap_t *index; /**< Current index. */
1611
1612/** Component information. */
1613typedef struct EcsComponent {
1614 ecs_size_t size; /**< Component size. */
1615 ecs_size_t alignment; /**< Component alignment. */
1617
1618/** Component for storing a poly object. */
1619typedef struct EcsPoly {
1620 ecs_poly_t *poly; /**< Pointer to poly object. */
1622
1623/** Non-fragmenting ChildOf relationship. */
1624typedef struct EcsParent {
1625 ecs_entity_t value; /**< Parent entity. */
1627
1628/** Component with data to instantiate a non-fragmenting tree. */
1629typedef struct {
1630 const char *child_name; /**< Name of the prefab child. */
1631 ecs_table_t *table; /**< Table in which the child will be stored. */
1632 uint32_t child; /**< Prefab child entity (without generation). */
1633 int32_t parent_index; /**< Index into the children vector. */
1634 bool copy; /**< Copy components instead of inheriting them. */
1636
1637/** Tree spawner data for a single hierarchy depth. */
1638typedef struct {
1639 ecs_vec_t children; /**< vector<ecs_tree_spawner_child_t>. */
1641
1642/** Tree instantiation cache component.
1643 * Tree instantiation cache, indexed by depth. Tables will have a
1644 * (ParentDepth, depth) pair indicating the hierarchy depth. This means that
1645 * for different depths, the tables the children are created in will also be
1646 * different. Caching tables for different depths therefore speeds up
1647 * instantiating trees even when the top-level entity is not at the root.
1648 */
1649typedef struct EcsTreeSpawner {
1650 ecs_tree_spawner_t data[FLECS_TREE_SPAWNER_DEPTH_CACHE_SIZE]; /**< Cache data indexed by depth. */
1652
1653/** @} */
1654/** @} */
1655
1656/* Only include deprecated definitions if deprecated addon is required */
1657#ifdef FLECS_DEPRECATED
1659#endif
1660
1661/**
1662 * @defgroup api_constants API Constants
1663 * Public API constants.
1664 *
1665 * @{
1666 */
1667
1668/**
1669 * @defgroup id_flags Component ID flags.
1670 * ID flags are bits that can be set on an ID (ecs_id_t).
1671 *
1672 * @{
1673 */
1674
1675/** Indicate that the ID is a pair. */
1676FLECS_API extern const ecs_id_t ECS_PAIR;
1677
1678/** Automatically override component when it is inherited. */
1679FLECS_API extern const ecs_id_t ECS_AUTO_OVERRIDE;
1680
1681/** Add a bitset to storage, which allows a component to be enabled or disabled. */
1682FLECS_API extern const ecs_id_t ECS_TOGGLE;
1683
1684/** Indicate that the target of a pair is an integer value. */
1685FLECS_API extern const ecs_id_t ECS_VALUE_PAIR;
1686
1687/** @} */
1688
1689/**
1690 * @defgroup builtin_tags Built-in component IDs.
1691 * @{
1692 */
1693
1694/* Built-in component IDs */
1695
1696/** Component component ID. */
1697FLECS_API extern const ecs_entity_t ecs_id(EcsComponent);
1698
1699/** Identifier component ID. */
1700FLECS_API extern const ecs_entity_t ecs_id(EcsIdentifier);
1701
1702/** Poly component ID. */
1703FLECS_API extern const ecs_entity_t ecs_id(EcsPoly);
1704
1705/** Parent component ID. */
1706FLECS_API extern const ecs_entity_t ecs_id(EcsParent);
1707
1708/** Component with data to instantiate a tree. */
1709FLECS_API extern const ecs_entity_t ecs_id(EcsTreeSpawner);
1710
1711/** Relationship storing the entity's depth in a non-fragmenting hierarchy. */
1712FLECS_API extern const ecs_entity_t EcsParentDepth;
1713
1714/** Tag added to queries. */
1715FLECS_API extern const ecs_entity_t EcsQuery;
1716
1717/** Tag added to observers. */
1718FLECS_API extern const ecs_entity_t EcsObserver;
1719
1720/** Tag added to systems. */
1721FLECS_API extern const ecs_entity_t EcsSystem;
1722
1723/** TickSource component ID. */
1724FLECS_API extern const ecs_entity_t ecs_id(EcsTickSource);
1725
1726/** Pipeline module component IDs. */
1727FLECS_API extern const ecs_entity_t ecs_id(EcsPipelineQuery);
1728
1729/** Timer component ID. */
1730FLECS_API extern const ecs_entity_t ecs_id(EcsTimer);
1731
1732/** RateFilter component ID. */
1733FLECS_API extern const ecs_entity_t ecs_id(EcsRateFilter);
1734
1735/** Root scope for built-in Flecs entities. */
1736FLECS_API extern const ecs_entity_t EcsFlecs;
1737
1738/** Core module scope. */
1739FLECS_API extern const ecs_entity_t EcsFlecsCore;
1740
1741/** Entity associated with world (used for "attaching" components to world). */
1742FLECS_API extern const ecs_entity_t EcsWorld;
1743
1744/** Wildcard entity ("*"). Matches any ID, returns all matches. */
1745FLECS_API extern const ecs_entity_t EcsWildcard;
1746
1747/** Any entity ("_"). Matches any ID, returns only the first. */
1748FLECS_API extern const ecs_entity_t EcsAny;
1749
1750/** This entity. Default source for queries. */
1751FLECS_API extern const ecs_entity_t EcsThis;
1752
1753/** Variable entity ("$"). Used in expressions to prefix variable names. */
1754FLECS_API extern const ecs_entity_t EcsVariable;
1755
1756/** Mark a relationship as transitive.
1757 * Behavior:
1758 *
1759 * @code
1760 * if R(X, Y) and R(Y, Z) then R(X, Z)
1761 * @endcode
1762 */
1763FLECS_API extern const ecs_entity_t EcsTransitive;
1764
1765/** Mark a relationship as reflexive.
1766 * Behavior:
1767 *
1768 * @code
1769 * R(X, X) == true
1770 * @endcode
1771 */
1772FLECS_API extern const ecs_entity_t EcsReflexive;
1773
1774/** Mark component as inheritable.
1775 * This is the opposite of Final. This trait can be used to enforce that queries
1776 * take into account component inheritance before inheritance (IsA)
1777 * relationships are added with the component as the target.
1778 */
1779FLECS_API extern const ecs_entity_t EcsInheritable;
1780
1781/** Relationship that specifies component inheritance behavior. */
1782FLECS_API extern const ecs_entity_t EcsOnInstantiate;
1783
1784/** Relationship that specifies how children of a prefab are instantiated.
1785 * When added to a prefab, the target specifies what happens with the direct
1786 * children of the prefab when it is instantiated:
1787 * - `Copy`: copy children (and their components) to the instance.
1788 * - `Inherit`: create instance children that inherit from (IsA) the prefab
1789 * children.
1790 * - `DontInherit`: don't create children for the instance.
1791 *
1792 * When the trait is not added to a prefab, children created with `ChildOf` are
1793 * copied, and children created with the `Parent` component are inherited. */
1794FLECS_API extern const ecs_entity_t EcsOnInstantiateChildren;
1795
1796#ifdef FLECS_PREFAB
1797/** Copy component on instantiate.
1798 * This will copy the component from the base entity `(IsA target)` to the
1799 * instance. The base component will never be inherited from the prefab. */
1800FLECS_API extern const ecs_entity_t EcsCopy;
1801
1802/** Inherit component on instantiate.
1803 * This will inherit (share) the component from the base entity `(IsA target)`.
1804 * The component can be manually overridden by adding it to the instance. */
1805FLECS_API extern const ecs_entity_t EcsInherit;
1806#endif
1807
1808/** Never inherit component on instantiate.
1809 * This will not copy or share the component from the base entity `(IsA target)`.
1810 * When the component is added to an instance, its value will never be copied
1811 * from the base entity. */
1812FLECS_API extern const ecs_entity_t EcsDontInherit;
1813
1814/** Can be added to a relationship to indicate that the relationship can only occur
1815 * once on an entity. Adding a second instance will replace the first.
1816 *
1817 * Behavior:
1818 *
1819 * @code
1820 * R(X, Y) + R(X, Z) = R(X, Z)
1821 * @endcode
1822 */
1823FLECS_API extern const ecs_entity_t EcsExclusive;
1824
1825/** Mark a relationship as traversable. Traversable relationships may be
1826 * traversed with "up" queries. Traversable relationships are acyclic. */
1827FLECS_API extern const ecs_entity_t EcsTraversable;
1828
1829/** Ensure that a component is always added together with another component.
1830 *
1831 * Behavior:
1832 *
1833 * @code
1834 * If With(R, O) and R(X) then O(X)
1835 * If With(R, O) and R(X, Y) then O(X, Y)
1836 * @endcode
1837 */
1838FLECS_API extern const ecs_entity_t EcsWith;
1839
1840/** Mark a component as toggleable with ecs_enable_id(). */
1841FLECS_API extern const ecs_entity_t EcsCanToggle;
1842
1843/** Can be added to a relationship to indicate that it should never hold data,
1844 * even when it or the relationship target is a component. */
1845FLECS_API extern const ecs_entity_t EcsPairIsTag;
1846
1847/** Tag to indicate name identifier. */
1848FLECS_API extern const ecs_entity_t EcsName;
1849
1850/** Tag to indicate symbol identifier. */
1851FLECS_API extern const ecs_entity_t EcsSymbol;
1852
1853/** Tag to indicate alias identifier. */
1854FLECS_API extern const ecs_entity_t EcsAlias;
1855
1856/** Used to express parent-child relationships. */
1857FLECS_API extern const ecs_entity_t EcsChildOf;
1858
1859/** Used to express inheritance relationships. */
1860FLECS_API extern const ecs_entity_t EcsIsA;
1861
1862/** Used to express dependency relationships. */
1863FLECS_API extern const ecs_entity_t EcsDependsOn;
1864
1865/** Tag that, when added to a parent, ensures stable order of ecs_children() results. */
1866FLECS_API extern const ecs_entity_t EcsOrderedChildren;
1867
1868/** Tag added to module entities. */
1869FLECS_API extern const ecs_entity_t EcsModule;
1870
1871/** Tag added to prefab entities. Any entity with this tag is automatically
1872 * ignored by queries, unless #EcsPrefab is explicitly queried for. */
1873#ifdef FLECS_PREFAB
1874FLECS_API extern const ecs_entity_t EcsPrefab;
1875#endif
1876
1877/** When this tag is added to an entity, it is skipped by queries, unless
1878 * #EcsDisabled is explicitly queried for. */
1879FLECS_API extern const ecs_entity_t EcsDisabled;
1880
1881/** Trait added to entities that should never be returned by queries. Reserved
1882 * for internal entities that have special meaning to the query engine, such as
1883 * #EcsThis, #EcsWildcard, #EcsAny. */
1884FLECS_API extern const ecs_entity_t EcsNotQueryable;
1885
1886/** Event that triggers when an ID is added to an entity. */
1887FLECS_API extern const ecs_entity_t EcsOnAdd;
1888
1889/** Event that triggers when an ID is removed from an entity. */
1890FLECS_API extern const ecs_entity_t EcsOnRemove;
1891
1892/** Event that triggers when a component is set for an entity. */
1893FLECS_API extern const ecs_entity_t EcsOnSet;
1894
1895/** Event that triggers an observer when an entity starts or stops matching a query. */
1896FLECS_API extern const ecs_entity_t EcsMonitor;
1897
1898/** Event that triggers when a table is created. */
1899FLECS_API extern const ecs_entity_t EcsOnTableCreate;
1900
1901/** Event that triggers when a table is deleted. */
1902FLECS_API extern const ecs_entity_t EcsOnTableDelete;
1903
1904/** Relationship used for specifying cleanup behavior. */
1905FLECS_API extern const ecs_entity_t EcsOnDelete;
1906
1907/** Relationship used to define what should happen when a target entity (second
1908 * element of a pair) is deleted. */
1909FLECS_API extern const ecs_entity_t EcsOnDeleteTarget;
1910
1911/** Remove cleanup policy. Must be used as a target in a pair with #EcsOnDelete or
1912 * #EcsOnDeleteTarget. */
1913FLECS_API extern const ecs_entity_t EcsRemove;
1914
1915/** Delete cleanup policy. Must be used as a target in a pair with #EcsOnDelete or
1916 * #EcsOnDeleteTarget. */
1917FLECS_API extern const ecs_entity_t EcsDelete;
1918
1919/** Panic cleanup policy. Must be used as a target in a pair with #EcsOnDelete or
1920 * #EcsOnDeleteTarget. */
1921FLECS_API extern const ecs_entity_t EcsPanic;
1922
1923/** Mark component as sparse. */
1924FLECS_API extern const ecs_entity_t EcsSparse;
1925
1926/** Mark component as non-fragmenting. */
1927FLECS_API extern const ecs_entity_t EcsDontFragment;
1928
1929/** Marker used to indicate `$var == ...` matching in queries. */
1930FLECS_API extern const ecs_entity_t EcsPredEq;
1931
1932/** Marker used to indicate `$var == "name"` matching in queries. */
1933FLECS_API extern const ecs_entity_t EcsPredMatch;
1934
1935/** Marker used to indicate `$var ~= "pattern"` matching in queries. */
1936FLECS_API extern const ecs_entity_t EcsPredLookup;
1937
1938/** Marker used to indicate the start of a scope (`{`) in queries. */
1939FLECS_API extern const ecs_entity_t EcsScopeOpen;
1940
1941/** Marker used to indicate the end of a scope (`}`) in queries. */
1942FLECS_API extern const ecs_entity_t EcsScopeClose;
1943
1944/** Tag used to indicate a query is empty.
1945 * This tag is removed automatically when a query becomes non-empty, and is not
1946 * automatically re-added when it becomes empty.
1947 */
1948FLECS_API extern const ecs_entity_t EcsEmpty;
1949
1950FLECS_API extern const ecs_entity_t ecs_id(EcsPipeline); /**< Pipeline component ID. */
1951FLECS_API extern const ecs_entity_t EcsOnStart; /**< OnStart pipeline phase. */
1952FLECS_API extern const ecs_entity_t EcsPreFrame; /**< PreFrame pipeline phase. */
1953FLECS_API extern const ecs_entity_t EcsOnLoad; /**< OnLoad pipeline phase. */
1954FLECS_API extern const ecs_entity_t EcsPostLoad; /**< PostLoad pipeline phase. */
1955FLECS_API extern const ecs_entity_t EcsPreUpdate; /**< PreUpdate pipeline phase. */
1956FLECS_API extern const ecs_entity_t EcsOnUpdate; /**< OnUpdate pipeline phase. */
1957FLECS_API extern const ecs_entity_t EcsOnValidate; /**< OnValidate pipeline phase. */
1958FLECS_API extern const ecs_entity_t EcsPostUpdate; /**< PostUpdate pipeline phase. */
1959FLECS_API extern const ecs_entity_t EcsPreStore; /**< PreStore pipeline phase. */
1960FLECS_API extern const ecs_entity_t EcsOnStore; /**< OnStore pipeline phase. */
1961FLECS_API extern const ecs_entity_t EcsPostFrame; /**< PostFrame pipeline phase. */
1962FLECS_API extern const ecs_entity_t EcsPhase; /**< Phase pipeline phase. */
1963
1964FLECS_API extern const ecs_entity_t EcsConstant; /**< Tag added to enum or bitmask constants. */
1965
1966/** Value used to quickly check if a component is built-in. This is used to
1967 * filter out tables with built-in components (for example, for ecs_delete()). */
1968#define EcsLastInternalComponentId (ecs_id(EcsTreeSpawner))
1969
1970/** The first user-defined component starts from this ID. IDs up to this number
1971 * are reserved for built-in components. */
1972#define EcsFirstUserComponentId (8)
1973
1974/** The first user-defined entity starts from this ID. IDs up to this number
1975 * are reserved for built-in entities. */
1976#define EcsFirstUserEntityId (FLECS_HI_COMPONENT_ID + 128)
1977
1978/* When visualized, the reserved ID ranges look like this:
1979 * - [1..8]: Built-in components
1980 * - [9..FLECS_HI_COMPONENT_ID]: Low IDs reserved for application components
1981 * - [FLECS_HI_COMPONENT_ID + 1..EcsFirstUserEntityId]: Built-in entities
1982 */
1983
1984/** @} */
1985/** @} */
1986
1987/**
1988 * @defgroup world_api World
1989 * Functions for working with `ecs_world_t`.
1990 *
1991 * @{
1992 */
1993
1994/**
1995 * @defgroup world_creation_deletion Creation & Deletion
1996 * @{
1997 */
1998
1999/** Create a new world.
2000 * This operation automatically imports modules from addons Flecs has been built
2001 * with, except when the module specifies otherwise.
2002 *
2003 * @return A new world.
2004 */
2005FLECS_API
2007
2008/** Create a new world with just the core module.
2009 * Same as ecs_init(), but doesn't import modules from addons. This operation is
2010 * faster than ecs_init() and results in less memory utilization.
2011 *
2012 * @return A new tiny world.
2013 */
2014FLECS_API
2016
2017/** Create a new world with arguments.
2018 * Same as ecs_init(), but allows passing in command-line arguments. Command-line
2019 * arguments are used to:
2020 * - automatically derive the name of the application from argv[0]
2021 *
2022 * @param argc The number of arguments.
2023 * @param argv The argument array.
2024 * @return A new world.
2025 */
2026FLECS_API
2028 int argc,
2029 char *argv[]);
2030
2031/** Delete a world.
2032 * This operation deletes the world, and everything it contains.
2033 *
2034 * @param world The world to delete.
2035 * @return Zero if successful, non-zero if failed.
2036 */
2037FLECS_API
2039 ecs_world_t *world);
2040
2041/** Return whether the world is being deleted.
2042 * This operation can be used in callbacks like type hooks or observers to
2043 * detect if they are invoked while the world is being deleted.
2044 *
2045 * @param world The world.
2046 * @return True if being deleted, false if not.
2047 */
2048FLECS_API
2050 const ecs_world_t *world);
2051
2052/** Register an action to be executed when the world is destroyed.
2053 * Fini actions are typically used when a module needs to clean up before the
2054 * world shuts down.
2055 *
2056 * @param world The world.
2057 * @param action The function to execute.
2058 * @param ctx Userdata to pass to the function.
2059 */
2060FLECS_API
2062 ecs_world_t *world,
2063 ecs_fini_action_t action,
2064 void *ctx);
2065
2066/** Type returned by ecs_get_entities(). */
2067typedef struct ecs_entities_t {
2068 const ecs_entity_t *ids; /**< Array with all entity IDs in the world. */
2069 int32_t count; /**< Total number of entity IDs. */
2070 int32_t alive_count; /**< Number of alive entity IDs. */
2072
2073/** Return entity identifiers in the world.
2074 * This operation returns an array with all entity IDs that exist in the world.
2075 * Note that the returned array will change and may get invalidated as a result
2076 * of entity creation and deletion.
2077 *
2078 * To iterate all alive entity IDs, do:
2079 * @code
2080 * ecs_entities_t entities = ecs_get_entities(world);
2081 * for (int i = 0; i < entities.alive_count; i ++) {
2082 * ecs_entity_t id = entities.ids[i];
2083 * }
2084 * @endcode
2085 *
2086 * To iterate not-alive IDs, do:
2087 * @code
2088 * for (int i = entities.alive_count + 1; i < entities.count; i ++) {
2089 * ecs_entity_t id = entities.ids[i];
2090 * }
2091 * @endcode
2092 *
2093 * The returned array does not need to be freed. Mutating the returned array
2094 * will result in undefined behavior (and likely crashes).
2095 *
2096 * @param world The world.
2097 * @return Struct with entity ID array.
2098 */
2099FLECS_API
2101 const ecs_world_t *world);
2102
2103/** Get flags set on the world.
2104 * This operation returns the internal flags (see api_flags.h) that are
2105 * set on the world.
2106 *
2107 * @param world The world.
2108 * @return Flags set on the world.
2109 */
2110FLECS_API
2112 const ecs_world_t *world);
2113
2114/** @} */
2115
2116/**
2117 * @defgroup commands Commands
2118 * @{
2119 */
2120
2121/** Begin readonly mode.
2122 * This operation puts the world in readonly mode, which disallows mutations on
2123 * the world. Readonly mode exists so that internal mechanisms can implement
2124 * optimizations that assume certain aspects of the world do not change, while also
2125 * providing a mechanism for applications to prevent accidental mutations in,
2126 * for example, multithreaded applications.
2127 *
2128 * Readonly mode is a stronger version of deferred mode. In deferred mode,
2129 * ECS operations such as add, remove, set, delete, etc. are added to a command
2130 * queue to be executed later. In readonly mode, operations that could break
2131 * scheduler logic (such as creating systems, queries) are also disallowed.
2132 *
2133 * Readonly mode itself has a single-threaded and a multithreaded mode. In
2134 * single-threaded mode, certain mutations on the world are still allowed, for
2135 * example:
2136 * - Entity liveliness operations (such as ecs_new(), ecs_make_alive()), so that systems are
2137 * able to create new entities.
2138 * - Implicit component registration, so that it works from systems.
2139 * - Mutations to supporting data structures for the evaluation of uncached
2140 * queries, so that these can be created on the fly.
2141 *
2142 * These mutations are safe in single-threaded applications, but for
2143 * multithreaded applications the world needs to be entirely immutable. For this
2144 * purpose, multithreaded readonly mode exists, which disallows all mutations on
2145 * the world. This means that in multithreaded applications, entity liveliness
2146 * operations, implicit component registration, and on-the-fly query creation
2147 * are not guaranteed to work.
2148 *
2149 * While in readonly mode, applications can still enqueue ECS operations on a
2150 * stage. Stages are managed automatically when using the pipeline addon and
2151 * ecs_progress(), but they can also be configured manually as shown here:
2152 *
2153 * @code
2154 * // Number of stages typically corresponds with number of threads
2155 * ecs_set_stage_count(world, 2);
2156 * ecs_world_t *stage = ecs_get_stage(world, 1);
2157 *
2158 * ecs_readonly_begin(world, false);
2159 * ecs_add(world, e, Tag); // readonly assert
2160 * ecs_add(stage, e, Tag); // OK
2161 * @endcode
2162 *
2163 * When an attempt is made to perform an operation on a world in readonly mode,
2164 * the code will throw an assert saying that the world is in readonly mode.
2165 *
2166 * A call to ecs_readonly_begin() must be followed up with ecs_readonly_end().
2167 * When ecs_readonly_end() is called, all enqueued commands from configured
2168 * stages are merged back into the world. Calls to ecs_readonly_begin() and
2169 * ecs_readonly_end() should always happen from a context where the code has
2170 * exclusive access to the world. The functions themselves are not thread-safe.
2171 *
2172 * @param world The world.
2173 * @param multi_threaded Whether to enable multithreaded readonly mode.
2174 * @return Whether world is in readonly mode.
2175 */
2176FLECS_API
2178 ecs_world_t *world,
2179 bool multi_threaded);
2180
2181/** End readonly mode.
2182 * This operation ends readonly mode, and must be called after
2183 * ecs_readonly_begin(). Operations that were deferred while the world was in
2184 * readonly mode will be flushed.
2185 *
2186 * @param world The world.
2187 */
2188FLECS_API
2190 ecs_world_t *world);
2191
2192/** Merge a stage.
2193 * This will merge all commands enqueued for a stage.
2194 *
2195 * @param stage The stage.
2196 */
2197FLECS_API
2199 ecs_world_t *stage);
2200
2201/** Test whether a world object is a stage.
2202 * Operations on a stage are enqueued until the stage is merged.
2203 *
2204 * @param world The world or stage.
2205 * @return True if stage, false if world.
2206 */
2207FLECS_API
2209 const ecs_world_t *world);
2210
2211/** Configure the world to have N stages.
2212 * This initializes N stages, which allows applications to defer operations to
2213 * multiple isolated defer queues. This is typically used for applications with
2214 * multiple threads, where each thread gets its own queue, and commands are
2215 * merged when threads are synchronized.
2216 *
2217 * Note that the ecs_set_threads() function already creates the appropriate
2218 * number of stages. The ecs_set_stage_count() operation is useful for applications
2219 * that want to manage their own stages and/or threads.
2220 *
2221 * @param world The world.
2222 * @param stages The number of stages.
2223 */
2224FLECS_API
2226 ecs_world_t *world,
2227 int32_t stages);
2228
2229/** Get the number of configured stages.
2230 * Return the number of stages set by ecs_set_stage_count().
2231 *
2232 * @param world The world.
2233 * @return The number of stages used for threading.
2234 */
2235FLECS_API
2237 const ecs_world_t *world);
2238
2239/** Get stage-specific world pointer.
2240 * Flecs threads can safely invoke the API as long as they have a private
2241 * context to write to, also referred to as the stage. This function returns a
2242 * pointer to a stage, disguised as a world pointer.
2243 *
2244 * Note that this function does not create a new world. It simply wraps the
2245 * existing world in a thread-specific context, which the API knows how to
2246 * unwrap. The reason the stage is returned as an ecs_world_t is so that it
2247 * can be passed transparently to the existing API functions, instead of having to
2248 * create a dedicated API for threading.
2249 *
2250 * @param world The world.
2251 * @param stage_id The index of the stage to retrieve.
2252 * @return A thread-specific pointer to the world.
2253 */
2254FLECS_API
2256 const ecs_world_t *world,
2257 int32_t stage_id);
2258
2259/** Test whether the current world is readonly.
2260 * This function allows the code to test whether the currently used world
2261 * is readonly or whether it allows for writing.
2262 *
2263 * @param world A pointer to a stage or the world.
2264 * @return True if the world or stage is readonly.
2265 */
2266FLECS_API
2268 const ecs_world_t *world);
2269
2270/** Create an unmanaged stage.
2271 * Create a stage whose lifecycle is not managed by the world. Must be freed
2272 * with ecs_stage_free().
2273 *
2274 * @param world The world.
2275 * @return The stage.
2276 */
2277FLECS_API
2279 ecs_world_t *world);
2280
2281/** Free an unmanaged stage.
2282 *
2283 * @param stage The stage to free.
2284 */
2285FLECS_API
2287 ecs_world_t *stage);
2288
2289/** Get the stage ID.
2290 * The stage ID can be used by an application to learn about which stage it is
2291 * using, which typically corresponds with the worker thread ID.
2292 *
2293 * @param world The world.
2294 * @return The stage ID.
2295 */
2296FLECS_API
2298 const ecs_world_t *world);
2299
2300/** @} */
2301
2302/**
2303 * @defgroup world_misc Misc
2304 * @{
2305 */
2306
2307/** Set a world context.
2308 * This operation allows an application to register custom data with a world
2309 * that can be accessed anywhere where the application has the world.
2310 *
2311 * @param world The world.
2312 * @param ctx A pointer to a user-defined structure.
2313 * @param ctx_free A function that is invoked with ctx when the world is freed.
2314 */
2315FLECS_API
2317 ecs_world_t *world,
2318 void *ctx,
2319 ecs_ctx_free_t ctx_free);
2320
2321/** Set a world binding context.
2322 * Same as ecs_set_ctx(), but for binding context. A binding context is intended
2323 * specifically for language bindings to store binding-specific data.
2324 *
2325 * @param world The world.
2326 * @param ctx A pointer to a user-defined structure.
2327 * @param ctx_free A function that is invoked with ctx when the world is freed.
2328 */
2329FLECS_API
2331 ecs_world_t *world,
2332 void *ctx,
2333 ecs_ctx_free_t ctx_free);
2334
2335/** Get the world context.
2336 * This operation retrieves a previously set world context.
2337 *
2338 * @param world The world.
2339 * @return The context set with ecs_set_ctx(). If no context was set, the
2340 * function returns NULL.
2341 */
2342FLECS_API
2344 const ecs_world_t *world);
2345
2346/** Get the world binding context.
2347 * This operation retrieves a previously set world binding context.
2348 *
2349 * @param world The world.
2350 * @return The context set with ecs_set_binding_ctx(). If no context was set, the
2351 * function returns NULL.
2352 */
2353FLECS_API
2355 const ecs_world_t *world);
2356
2357/** Get build info.
2358 * Return information about the current Flecs build.
2359 *
2360 * @return A struct with information about the current Flecs build.
2361 */
2362FLECS_API
2364
2365/** Get the world info.
2366 *
2367 * @param world The world.
2368 * @return A pointer to the world info. Valid for as long as the world exists.
2369 */
2370FLECS_API
2372 const ecs_world_t *world);
2373
2374/** Dimension the world for a specified number of entities.
2375 * This operation will preallocate memory in the world for the specified number
2376 * of entities. Specifying a number lower than the current number of entities in
2377 * the world will have no effect.
2378 *
2379 * @param world The world.
2380 * @param entity_count The number of entities to preallocate.
2381 */
2382FLECS_API
2384 ecs_world_t *world,
2385 int32_t entity_count);
2386
2387/** Free unused memory.
2388 * This operation frees allocated memory that is no longer in use by the world.
2389 * Examples of allocations that get cleaned up are:
2390 * - Unused pages in the entity index
2391 * - Component columns
2392 * - Empty tables
2393 *
2394 * Flecs uses allocators internally for speeding up allocations. Allocators are
2395 * not evaluated by this function, which means that the memory reported by the
2396 * OS may not go down. For this reason, this function is most effective when
2397 * combined with FLECS_USE_OS_ALLOC, which disables internal allocators.
2398 *
2399 * @param world The world.
2400 */
2401FLECS_API
2403 ecs_world_t *world);
2404
2405/** Get the largest issued entity ID (not counting generation).
2406 *
2407 * @param world The world.
2408 * @return The largest issued entity ID.
2409 */
2410FLECS_API
2412 const ecs_world_t *world);
2413
2414/** Force aperiodic actions.
2415 * The world may delay certain operations until they are necessary for the
2416 * application to function correctly. This may cause observable side effects
2417 * such as delayed triggering of events, which can be inconvenient when, for
2418 * example, running a test suite.
2419 *
2420 * The flags parameter specifies which aperiodic actions to run. Specify 0 to
2421 * run all actions. Supported flags start with 'EcsAperiodic'. Flags identify
2422 * internal mechanisms and may change unannounced.
2423 *
2424 * @param world The world.
2425 * @param flags The flags specifying which actions to run.
2426 */
2427FLECS_API
2429 ecs_world_t *world,
2430 ecs_flags32_t flags);
2431
2432/** Used with ecs_delete_empty_tables(). */
2434 /** Free table data when generation > clear_generation. */
2436
2437 /** Delete table when generation > delete_generation. */
2439
2440 /** Amount of time operation is allowed to spend. */
2442
2443 /** Table index to start scanning at. The function loops around until it
2444 * reaches this offset again, or until the time budget is exceeded. */
2445 int32_t offset;
2447
2448/** Clean up empty tables.
2449 * This operation cleans up empty tables that meet certain conditions. Having
2450 * large amounts of empty tables does not negatively impact performance of the
2451 * ECS, but can take up considerable amounts of memory, especially in
2452 * applications with many components, and many components per entity.
2453 *
2454 * The generation specifies the minimum number of times this operation has
2455 * to be called before an empty table is cleaned up. If a table becomes
2456 * non-empty, the generation is reset.
2457 *
2458 * The operation allows for both a "clear" generation and a "delete"
2459 * generation. When the clear generation is reached, the table's
2460 * resources are freed (like component arrays) but the table itself is not
2461 * deleted. When the delete generation is reached, the empty table is deleted.
2462 *
2463 * By specifying a non-zero ID, the cleanup logic can be limited to tables with
2464 * a specific (component) ID. The operation will only increase the generation
2465 * count of matching tables.
2466 *
2467 * The min_id_count specifies a lower bound for the number of components a table
2468 * should have. Often the more components a table has, the more specific it is
2469 * and therefore less likely to be reused.
2470 *
2471 * The time budget specifies how long the operation should take at most.
2472 *
2473 * The offset parameter specifies the table index at which to start scanning.
2474 * The function loops around until it reaches this offset again, or until the
2475 * time budget is exceeded.
2476 *
2477 * @param world The world.
2478 * @param desc Configuration parameters.
2479 * @return The index + 1 of the table where the function stopped, or 0 if the
2480 * function scanned all tables. The return value can be used as the
2481 * offset for the next call.
2482 */
2483FLECS_API
2485 ecs_world_t *world,
2486 const ecs_delete_empty_tables_desc_t *desc);
2487
2488/** Get the world from a poly.
2489 *
2490 * @param poly A pointer to a poly object.
2491 * @return The world.
2492 */
2493FLECS_API
2495 const ecs_poly_t *poly);
2496
2497/** Get the entity from a poly.
2498 *
2499 * @param poly A pointer to a poly object.
2500 * @return The entity associated with the poly object.
2501 */
2502FLECS_API
2504 const ecs_poly_t *poly);
2505
2506/** Test if a pointer is of the specified type.
2507 * Usage:
2508 *
2509 * @code
2510 * flecs_poly_is(ptr, ecs_world_t)
2511 * @endcode
2512 *
2513 * This operation only works for poly types.
2514 *
2515 * @param object The object to test.
2516 * @param type The ID of the type.
2517 * @return True if the pointer is of the specified type.
2518 */
2519FLECS_API
2521 const ecs_poly_t *object,
2522 int32_t type);
2523
2524/** Test if a pointer is of the specified type.
2525 * @see flecs_poly_is_()
2526 */
2527#define flecs_poly_is(object, type)\
2528 flecs_poly_is_(object, type##_magic)
2529
2530/** Make a pair ID.
2531 * This function is equivalent to using the ecs_pair() macro, and is added for
2532 * convenience to make it easier for non-C/C++ bindings to work with pairs.
2533 *
2534 * @param first The first element of the pair.
2535 * @param second The target of the pair.
2536 * @return A pair ID.
2537 */
2538FLECS_API
2540 ecs_entity_t first,
2541 ecs_entity_t second);
2542
2543/** Begin exclusive thread access.
2544 * This operation ensures that only the thread from which this operation is
2545 * called can access the world. Attempts to access the world from other threads
2546 * will panic.
2547 *
2548 * ecs_exclusive_access_begin() must be called in pairs with
2549 * ecs_exclusive_access_end(). Calling ecs_exclusive_access_begin() from another
2550 * thread without first calling ecs_exclusive_access_end() will panic.
2551 *
2552 * A thread name can be provided to the function to improve debug messages. The
2553 * function does not copy the thread name, which means the memory for the
2554 * name must remain alive for as long as the thread has exclusive access.
2555 *
2556 * This operation should only be called once per thread. Calling it multiple
2557 * times for the same thread will cause a panic.
2558 *
2559 * Note that this feature only works in builds where asserts are enabled. The
2560 * feature requires the OS API thread_self_ callback to be set.
2561 *
2562 * @param world The world.
2563 * @param thread_name The name of the thread obtaining exclusive access.
2564 */
2565FLECS_API
2567 ecs_world_t *world,
2568 const char *thread_name);
2569
2570/** End exclusive thread access.
2571 * This operation should be called after ecs_exclusive_access_begin(). After
2572 * calling this operation, other threads are no longer prevented from mutating
2573 * the world.
2574 *
2575 * When "lock_world" is set to true, no thread will be able to mutate the world
2576 * until ecs_exclusive_access_begin() is called again. While the world is locked,
2577 * only read-only operations are allowed. For example, ecs_get_id() is allowed,
2578 * but ecs_get_mut_id() is not allowed.
2579 *
2580 * A locked world can be unlocked by calling ecs_exclusive_access_end() again with
2581 * lock_world set to false. Note that this only works for locked worlds. If
2582 * ecs_exclusive_access_end() is called on a world that has exclusive thread
2583 * access from a different thread, a panic will happen.
2584 *
2585 * This operation must be called from the same thread that called
2586 * ecs_exclusive_access_begin(). Calling it from a different thread will cause
2587 * a panic.
2588 *
2589 * @param world The world.
2590 * @param lock_world When true, any mutations on the world will be blocked.
2591 */
2592FLECS_API
2594 ecs_world_t *world,
2595 bool lock_world);
2596
2597/** @} */
2598
2599/** @} */
2600
2601/**
2602 * @defgroup entities Entities
2603 * Functions for working with `ecs_entity_t`.
2604 *
2605 * @{
2606 */
2607
2608/**
2609 * @defgroup creating_entities Creating & Deleting
2610 * Functions for creating and deleting entities.
2611 *
2612 * @{
2613 */
2614
2615/** Create new entity ID.
2616 * This operation returns an unused entity ID. This operation is guaranteed to
2617 * return an empty entity as it does not use values set by ecs_set_scope().
2618 *
2619 * @param world The world.
2620 * @return The new entity ID.
2621 */
2622FLECS_API
2624 ecs_world_t *world);
2625
2626/** Create new low ID.
2627 * This operation returns a new low ID. Entity IDs start after the
2628 * FLECS_HI_COMPONENT_ID constant. This reserves a range of low IDs for things
2629 * like components, and allows parts of the code to optimize operations.
2630 *
2631 * Note that FLECS_HI_COMPONENT_ID does not represent the maximum number of
2632 * components that can be created, only the maximum number of components that
2633 * can take advantage of these optimizations.
2634 *
2635 * This operation is guaranteed to return an empty entity as it does not use
2636 * values set by ecs_set_scope().
2637 *
2638 * This operation does not recycle IDs.
2639 *
2640 * @param world The world.
2641 * @return The new component ID.
2642 */
2643FLECS_API
2645 ecs_world_t *world);
2646
2647/** Create new entity with (component) ID.
2648 * This operation creates a new entity with an optional (component) ID.
2649 *
2650 * @param world The world.
2651 * @param component The component to create the new entity with.
2652 * @return The new entity.
2653 */
2654FLECS_API
2656 ecs_world_t *world,
2657 ecs_id_t component);
2658
2659/** Create new entity in table.
2660 * This operation creates a new entity in the specified table.
2661 *
2662 * @param world The world.
2663 * @param table The table to which to add the new entity.
2664 * @return The new entity.
2665 */
2666FLECS_API
2668 ecs_world_t *world,
2669 ecs_table_t *table);
2670
2671/** Find or create an entity.
2672 * This operation creates a new entity, or modifies an existing one. When a name
2673 * is set in the ecs_entity_desc_t::name field and ecs_entity_desc_t::entity is
2674 * not set, the operation will first attempt to find an existing entity by that
2675 * name. If no entity with that name can be found, it will be created.
2676 *
2677 * If both a name and entity handle are provided, the operation will check if
2678 * the entity name matches with the provided name. If the names do not match,
2679 * the function will fail and return 0.
2680 *
2681 * If an ID to a non-existing entity is provided, that entity ID becomes alive.
2682 *
2683 * See the documentation of ecs_entity_desc_t for more details.
2684 *
2685 * @param world The world.
2686 * @param desc Entity init parameters.
2687 * @return A handle to the new or existing entity, or 0 if failed.
2688 */
2689FLECS_API
2691 ecs_world_t *world,
2692 const ecs_entity_desc_t *desc);
2693
2694/** Create a new entity with a list of component values.
2695 * Values for zero-sized (tag) components are added without setting a value.
2696 *
2697 * This operation is equivalent to creating an entity with ecs_new() followed
2698 * by ecs_set_id() for each provided value.
2699 *
2700 * @param world The world.
2701 * @param values Null-terminated array of component values to set.
2702 * @return A handle to the new entity, or 0 if failed.
2703 */
2704FLECS_API
2706 ecs_world_t *world,
2707 const ecs_value_t *values);
2708
2709/** Bulk create or populate new entities.
2710 * This operation bulk inserts a list of new or predefined entities into a
2711 * single table.
2712 *
2713 * The operation does not take ownership of component arrays provided by the
2714 * application. Components that are non-trivially copyable will be moved into
2715 * the storage.
2716 *
2717 * The operation will emit OnAdd events for each added ID, and OnSet events for
2718 * each component that has been set.
2719 *
2720 * If no entity IDs are provided by the application, the returned array of IDs
2721 * points to an internal data structure, which changes when new entities are
2722 * created or deleted.
2723 *
2724 * If as a result of the operation, observers are invoked that delete
2725 * entities and no entity IDs were provided by the application, the returned
2726 * array of identifiers may be incorrect. To avoid this problem, an application
2727 * can first call ecs_bulk_init() to create empty entities, copy the array to one
2728 * that is owned by the application, and then use this array to populate the
2729 * entities.
2730 *
2731 * @param world The world.
2732 * @param desc Bulk creation parameters.
2733 * @return An array with the list of entity IDs created or populated.
2734 */
2735FLECS_API
2737 ecs_world_t *world,
2738 const ecs_bulk_desc_t *desc);
2739
2740/** Create N new entities.
2741 * This operation is the same as ecs_new_w_id(), but creates N entities
2742 * instead of one.
2743 *
2744 * @param world The world.
2745 * @param component The component to create the entities with.
2746 * @param count The number of entities to create.
2747 * @return An array with the entity IDs of the newly created entities.
2748 */
2749FLECS_API
2751 ecs_world_t *world,
2752 ecs_id_t component,
2753 int32_t count);
2754
2755/** Clone an entity.
2756 * This operation clones the components of one entity into another entity. If
2757 * no destination entity is provided, a new entity will be created. Component
2758 * values are not copied unless copy_value is true.
2759 *
2760 * If the source entity has a name, it will not be copied to the destination
2761 * entity. This is to prevent having two entities with the same name under the
2762 * same parent, which is not allowed.
2763 *
2764 * @param world The world.
2765 * @param dst The entity to copy the components to.
2766 * @param src The entity to copy the components from.
2767 * @param copy_value If true, the value of components will be copied to dst.
2768 * @return The destination entity.
2769 */
2770FLECS_API
2772 ecs_world_t *world,
2773 ecs_entity_t dst,
2774 ecs_entity_t src,
2775 bool copy_value);
2776
2777/** Delete an entity.
2778 * This operation will delete an entity and all of its components. The entity ID
2779 * will be made available for recycling. If the entity passed to ecs_delete() is
2780 * not alive, the operation will have no side effects.
2781 *
2782 * @param world The world.
2783 * @param entity The entity.
2784 */
2785FLECS_API
2787 ecs_world_t *world,
2788 ecs_entity_t entity);
2789
2790/** Delete all entities with the specified component.
2791 * This will delete all entities (tables) that have the specified ID. The
2792 * component may be a wildcard and/or a pair.
2793 *
2794 * @param world The world.
2795 * @param component The component.
2796 */
2797FLECS_API
2799 ecs_world_t *world,
2800 ecs_id_t component);
2801
2802/** Set child order for parent with OrderedChildren.
2803 * If the parent has the OrderedChildren trait, the order of the children
2804 * will be updated to the order in the specified children array. The operation
2805 * will fail if the parent does not have the OrderedChildren trait.
2806 *
2807 * This operation always takes place immediately, and is not deferred. When the
2808 * operation is called from a multithreaded system, it will fail.
2809 *
2810 * The reason for not deferring this operation is that by the time the deferred
2811 * command would be executed, the children of the parent could have been changed
2812 * which would cause the operation to fail.
2813 *
2814 * @param world The world.
2815 * @param parent The parent.
2816 * @param children An array with children.
2817 * @param child_count The number of children in the provided array.
2818 */
2819FLECS_API
2821 ecs_world_t *world,
2822 ecs_entity_t parent,
2823 const ecs_entity_t *children,
2824 int32_t child_count);
2825
2826/** Get ordered children.
2827 * If a parent has the OrderedChildren trait, this operation can be used to
2828 * obtain the array with child entities. If this operation is used on a parent
2829 * that does not have the OrderedChildren trait, it will fail.
2830 *
2831 * @param world The world.
2832 * @param parent The parent.
2833 * @return The array with child entities.
2834 */
2835FLECS_API
2837 const ecs_world_t *world,
2838 ecs_entity_t parent);
2839
2840/** @} */
2841
2842/**
2843 * @defgroup adding_removing Adding & Removing
2844 * Functions for adding and removing components.
2845 *
2846 * @{
2847 */
2848
2849/** Add a (component) ID to an entity.
2850 * This operation adds a single (component) ID to an entity. If the entity
2851 * already has the ID, this operation will have no side effects.
2852 *
2853 * @param world The world.
2854 * @param entity The entity.
2855 * @param component The component ID to add.
2856 */
2857FLECS_API
2859 ecs_world_t *world,
2860 ecs_entity_t entity,
2861 ecs_id_t component);
2862
2863/** Remove a component from an entity.
2864 * This operation removes a single component from an entity. If the entity
2865 * does not have the component, this operation will have no side effects.
2866 *
2867 * @param world The world.
2868 * @param entity The entity.
2869 * @param component The component to remove.
2870 */
2871FLECS_API
2873 ecs_world_t *world,
2874 ecs_entity_t entity,
2875 ecs_id_t component);
2876
2877/** Add an auto override for a component.
2878 * An auto override is a component that is automatically added to an entity when
2879 * it is instantiated from a prefab. Auto overrides are added to the entity that
2880 * is inherited from (usually a prefab). For example:
2881 *
2882 * @code
2883 * ecs_entity_t prefab = ecs_insert(world,
2884 * ecs_value(Position, {10, 20}),
2885 * ecs_value(Mass, {100}));
2886 *
2887 * ecs_auto_override(world, prefab, Position);
2888 *
2889 * ecs_entity_t inst = ecs_new_w_pair(world, EcsIsA, prefab);
2890 * assert(ecs_owns(world, inst, Position)); // true
2891 * assert(ecs_owns(world, inst, Mass)); // false
2892 * @endcode
2893 *
2894 * An auto override is equivalent to a manual override:
2895 *
2896 * @code
2897 * ecs_entity_t prefab = ecs_insert(world,
2898 * ecs_value(Position, {10, 20}),
2899 * ecs_value(Mass, {100}));
2900 *
2901 * ecs_entity_t inst = ecs_new_w_pair(world, EcsIsA, prefab);
2902 * assert(ecs_owns(world, inst, Position)); // false
2903 * ecs_add(world, inst, Position); // manual override
2904 * assert(ecs_owns(world, inst, Position)); // true
2905 * assert(ecs_owns(world, inst, Mass)); // false
2906 * @endcode
2907 *
2908 * This operation is equivalent to manually adding the ID with the AUTO_OVERRIDE
2909 * bit applied:
2910 *
2911 * @code
2912 * ecs_add_id(world, entity, ECS_AUTO_OVERRIDE | id);
2913 * @endcode
2914 *
2915 * When a component is overridden and inherited from a prefab, the value from
2916 * the prefab component is copied to the instance. When the component is not
2917 * inherited from a prefab, it is added to the instance as if using ecs_add_id().
2918 *
2919 * Overriding is the default behavior on prefab instantiation. Auto overriding
2920 * is only useful for components with the `(OnInstantiate, Inherit)` trait.
2921 * When a component has the `(OnInstantiate, DontInherit)` trait and is overridden,
2922 * the component is added, but the value from the prefab will not be copied.
2923 *
2924 * @param world The world.
2925 * @param entity The entity.
2926 * @param component The component to auto override.
2927 */
2928FLECS_API
2930 ecs_world_t *world,
2931 ecs_entity_t entity,
2932 ecs_id_t component);
2933
2934/** Clear all components.
2935 * This operation will remove all components from an entity.
2936 *
2937 * @param world The world.
2938 * @param entity The entity.
2939 */
2940FLECS_API
2942 ecs_world_t *world,
2943 ecs_entity_t entity);
2944
2945/** Remove all instances of the specified component.
2946 * This will remove the specified ID from all entities (tables). The ID may be
2947 * a wildcard and/or a pair.
2948 *
2949 * @param world The world.
2950 * @param component The component.
2951 */
2952FLECS_API
2954 ecs_world_t *world,
2955 ecs_id_t component);
2956
2957/** @} */
2958
2959/**
2960 * @defgroup enabling_disabling Enabling & Disabling
2961 * Functions for enabling/disabling entities and components.
2962 *
2963 * @{
2964 */
2965
2966/** Enable or disable an entity.
2967 * This operation enables or disables an entity by adding or removing the
2968 * #EcsDisabled tag. A disabled entity will not be matched with any systems,
2969 * unless the system explicitly specifies the #EcsDisabled tag.
2970 *
2971 * @param world The world.
2972 * @param entity The entity to enable or disable.
2973 * @param enabled true to enable the entity, false to disable.
2974 */
2975FLECS_API
2977 ecs_world_t *world,
2978 ecs_entity_t entity,
2979 bool enabled);
2980
2981/** Enable or disable a component.
2982 * Enabling or disabling a component does not add or remove a component from an
2983 * entity, but prevents it from being matched with queries. This operation can
2984 * be useful when a component must be temporarily disabled without destroying
2985 * its value. It is also a more performant operation for when an application
2986 * needs to add/remove components at high frequency, as enabling/disabling is
2987 * cheaper than a regular add or remove.
2988 *
2989 * @param world The world.
2990 * @param entity The entity.
2991 * @param component The component to enable/disable.
2992 * @param enable True to enable the component, false to disable.
2993 */
2994FLECS_API
2996 ecs_world_t *world,
2997 ecs_entity_t entity,
2998 ecs_id_t component,
2999 bool enable);
3000
3001/** Test if a component is enabled.
3002 * Test whether a component is currently enabled or disabled. This operation
3003 * will return true when the entity has the component and if it has not been
3004 * disabled by ecs_enable_id().
3005 *
3006 * @param world The world.
3007 * @param entity The entity.
3008 * @param component The component.
3009 * @return True if the component is enabled, otherwise false.
3010 */
3011FLECS_API
3013 const ecs_world_t *world,
3014 ecs_entity_t entity,
3015 ecs_id_t component);
3016
3017/** @} */
3018
3019/**
3020 * @defgroup getting Getting and Setting
3021 * Functions for getting and setting components.
3022 *
3023 * @{
3024 */
3025
3026/** Get an immutable pointer to a component.
3027 * This operation obtains a const pointer to the requested component. The
3028 * operation accepts the component entity ID.
3029 *
3030 * This operation can return inherited components reachable through an `IsA`
3031 * relationship.
3032 *
3033 * @param world The world.
3034 * @param entity The entity.
3035 * @param component The component to get.
3036 * @return The component pointer, NULL if the entity does not have the component.
3037 *
3038 * @see ecs_get_mut_id()
3039 */
3040FLECS_API
3041FLECS_ALWAYS_INLINE const void* ecs_get_id(
3042 const ecs_world_t *world,
3043 ecs_entity_t entity,
3044 ecs_id_t component);
3045
3046/** Get a mutable pointer to a component.
3047 * This operation obtains a mutable pointer to the requested component. The
3048 * operation accepts the component entity ID.
3049 *
3050 * Unlike ecs_get_id(), this operation does not return inherited components.
3051 * This is to prevent errors where an application accidentally resolves an
3052 * inherited component shared with many entities and modifies it, while thinking
3053 * it is modifying an owned component.
3054 *
3055 * @param world The world.
3056 * @param entity The entity.
3057 * @param component The component to get.
3058 * @return The component pointer, NULL if the entity does not have the component.
3059 */
3060FLECS_API
3061FLECS_ALWAYS_INLINE void* ecs_get_mut_id(
3062 const ecs_world_t *world,
3063 ecs_entity_t entity,
3064 ecs_id_t component);
3065
3066/** Get a pointer to a sparse component.
3067 * This operation obtains a pointer to a sparse component, and is a faster
3068 * alternative to using ecs_get_id() and ecs_get_mut_id(). This operation should
3069 * only be used for sparse, non-inheritable components.
3070 *
3071 * @param world The world.
3072 * @param entity The entity.
3073 * @param component The component to get.
3074 * @param size The size of the component type. Must match the size of the component.
3075 * @return The component pointer, NULL if the entity does not have the component.
3076 *
3077 * @see ecs_get_id()
3078 * @see ecs_get_mut_id()
3079 */
3080FLECS_API
3081FLECS_ALWAYS_INLINE void* ecs_get_sparse_id(
3082 const ecs_world_t *world,
3083 ecs_entity_t entity,
3084 ecs_id_t component,
3085 size_t size);
3086
3087/** Ensure an entity has a component and return a pointer.
3088 * This operation returns a mutable pointer to a component. If the entity did
3089 * not yet have the component, it will be added.
3090 *
3091 * @param world The world.
3092 * @param entity The entity.
3093 * @param component The component to get or add.
3094 * @param size The size of the component.
3095 * @return The component pointer.
3096 *
3097 * @see ecs_emplace_id()
3098 */
3099FLECS_API
3101 ecs_world_t *world,
3102 ecs_entity_t entity,
3103 ecs_id_t component,
3104 size_t size);
3105
3106/** Create a component ref.
3107 * A ref is a handle to an entity and component pair, which caches a small amount of
3108 * data to reduce the overhead of repeatedly accessing the component. Use
3109 * ecs_ref_get() to get the component data.
3110 *
3111 * @param world The world.
3112 * @param entity The entity.
3113 * @param component The component to create a ref for.
3114 * @return The reference.
3115 */
3116FLECS_ALWAYS_INLINE FLECS_API
3118 const ecs_world_t *world,
3119 ecs_entity_t entity,
3120 ecs_id_t component);
3121
3122/** Create a component ref from an existing pointer.
3123 * Same as ecs_ref_init_id(), but uses the provided pointer instead of looking
3124 * up the component. This avoids a lookup when the application already has a
3125 * pointer to the component, for example from ecs_get_mut_id().
3126 *
3127 * @param world The world.
3128 * @param entity The entity.
3129 * @param component The component to create a ref for.
3130 * @param ptr Pointer to the component of the entity.
3131 * @return The reference.
3132 */
3133FLECS_API
3135 const ecs_world_t *world,
3136 ecs_entity_t entity,
3137 ecs_id_t component,
3138 void *ptr);
3139
3140/** Get a component from a ref.
3141 * Get a component pointer from a ref. The ref must be created with ecs_ref_init().
3142 * The specified component must match the component with which the ref was
3143 * created.
3144 *
3145 * @param world The world.
3146 * @param ref The ref.
3147 * @param component The component to get.
3148 * @return The component pointer, NULL if the entity does not have the component.
3149 */
3150FLECS_ALWAYS_INLINE FLECS_API
3152 const ecs_world_t *world,
3153 ecs_ref_t *ref,
3154 ecs_id_t component);
3155
3156/** Update a ref.
3157 * Ensure the contents of a ref are up to date. Same as ecs_ref_get_id(), but does not
3158 * return a pointer to the component.
3159 *
3160 * @param world The world.
3161 * @param ref The ref.
3162 * @param component The component the ref was created with.
3163 */
3164FLECS_ALWAYS_INLINE FLECS_API
3166 const ecs_world_t *world,
3167 ecs_ref_t *ref,
3168 ecs_id_t component);
3169
3170/** Signal that the component of a ref has been modified.
3171 * Same as ecs_modified_id(), but uses the data cached by the ref to avoid
3172 * looking up the entity and component. The specified component must match the
3173 * component with which the ref was created.
3174 *
3175 * @param world The world.
3176 * @param ref The ref.
3177 * @param component The component the ref was created with.
3178 *
3179 * @see ecs_modified_id()
3180 */
3181FLECS_API
3183 ecs_world_t *world,
3184 ecs_ref_t *ref,
3185 ecs_id_t component);
3186
3187/** Emplace a component.
3188 * Emplace is similar to ecs_ensure_id() except that the component constructor
3189 * is not invoked for the returned pointer, allowing the component to be
3190 * constructed directly in the storage.
3191 *
3192 * When the `is_new` parameter is not provided, the operation will assert when the
3193 * component already exists. When the `is_new` parameter is provided, it will
3194 * indicate whether the returned storage has been constructed.
3195 *
3196 * When `is_new` indicates that the storage has not yet been constructed, it must
3197 * be constructed by the code invoking this operation. Not constructing the
3198 * component will result in undefined behavior.
3199 *
3200 * @param world The world.
3201 * @param entity The entity.
3202 * @param component The component to get or add.
3203 * @param size The component size.
3204 * @param is_new Whether this is an existing or new component.
3205 * @return The (uninitialized) component pointer.
3206 */
3207FLECS_API
3209 ecs_world_t *world,
3210 ecs_entity_t entity,
3211 ecs_id_t component,
3212 size_t size,
3213 bool *is_new);
3214
3215/** Signal that a component has been modified.
3216 * This operation is usually used after modifying a component value obtained by
3217 * ecs_ensure_id(). The operation will mark the component as dirty, and invoke
3218 * OnSet observers and hooks.
3219 *
3220 * @param world The world.
3221 * @param entity The entity.
3222 * @param component The component that was modified.
3223 */
3224FLECS_API
3226 ecs_world_t *world,
3227 ecs_entity_t entity,
3228 ecs_id_t component);
3229
3230/** Set the value of a component.
3231 * This operation allows an application to set the value of a component. The
3232 * operation is equivalent to calling ecs_ensure_id() followed by
3233 * ecs_modified_id(). The operation will not modify the value of the passed-in
3234 * component. If the component has a copy hook registered, it will be used to
3235 * copy in the component.
3236 *
3237 * If the provided entity is 0, a new entity will be created.
3238 *
3239 * @param world The world.
3240 * @param entity The entity.
3241 * @param component The component to set.
3242 * @param size The size of the pointed-to value.
3243 * @param ptr The pointer to the value.
3244 */
3245FLECS_API
3247 ecs_world_t *world,
3248 ecs_entity_t entity,
3249 ecs_id_t component,
3250 size_t size,
3251 const void *ptr);
3252
3253/** @} */
3254
3255/**
3256 * @defgroup liveliness Entity Liveliness
3257 * Functions for testing and modifying entity liveliness.
3258 *
3259 * @{
3260 */
3261
3262/** Test whether an entity is valid.
3263 * This operation tests whether the entity ID:
3264 * - is not 0
3265 * - has a valid bit pattern
3266 * - is alive (see ecs_is_alive())
3267 *
3268 * If this operation returns true, it is safe to use the entity with
3269 * other operations.
3270 *
3271 * This operation should only be used if an application cannot be sure that an
3272 * entity is initialized with a valid value. In all other cases where an entity
3273 * was initialized with a valid value, but the application wants to check if the
3274 * entity is (still) alive, use ecs_is_alive().
3275 *
3276 * @param world The world.
3277 * @param e The entity.
3278 * @return True if the entity is valid, false if the entity is not valid.
3279 * @see ecs_is_alive()
3280 */
3281FLECS_API
3283 const ecs_world_t *world,
3284 ecs_entity_t e);
3285
3286/** Test whether an entity is alive.
3287 * Entities are alive after they are created, and become not alive when they are
3288 * deleted. Operations that return alive IDs are (amongst others) ecs_new(),
3289 * ecs_new_low_id() and ecs_entity_init(). IDs can be made alive with the
3290 * ecs_make_alive() function.
3291 *
3292 * After an ID is deleted it can be recycled. Recycled IDs are different from
3293 * the original ID in that they have a different generation count. This makes it
3294 * possible for the API to distinguish between the two. An example:
3295 *
3296 * @code
3297 * ecs_entity_t e1 = ecs_new(world);
3298 * ecs_is_alive(world, e1); // true
3299 * ecs_delete(world, e1);
3300 * ecs_is_alive(world, e1); // false
3301 *
3302 * ecs_entity_t e2 = ecs_new(world); // recycles e1
3303 * ecs_is_alive(world, e2); // true
3304 * ecs_is_alive(world, e1); // false
3305 * @endcode
3306 *
3307 * Unlike ecs_is_valid(), this operation will panic if the passed-in entity
3308 * ID is 0 or has an invalid bit pattern.
3309 *
3310 * @param world The world.
3311 * @param e The entity.
3312 * @return True if the entity is alive, false if the entity is not alive.
3313 * @see ecs_is_valid()
3314 */
3315FLECS_API
3317 const ecs_world_t *world,
3318 ecs_entity_t e);
3319
3320/** Remove the generation from an entity ID.
3321 *
3322 * @param e The entity ID.
3323 * @return The entity ID without the generation count.
3324 */
3325FLECS_API
3327 ecs_entity_t e);
3328
3329/** Get an alive identifier.
3330 * In some cases an application may need to work with identifiers from which
3331 * the generation has been stripped. A typical scenario in which this happens is
3332 * when iterating relationships in an entity type.
3333 *
3334 * For example, when obtaining the parent ID from a `ChildOf` relationship, the parent
3335 * (second element of the pair) will have been stored in a 32-bit value, which
3336 * cannot store the entity generation. This function can retrieve the identifier
3337 * with the current generation for that ID.
3338 *
3339 * If the provided identifier is not alive, the function will return 0.
3340 *
3341 * @param world The world.
3342 * @param e The entity for which to obtain the current alive entity ID.
3343 * @return The alive entity ID if there is one, or 0 if the ID is not alive.
3344 */
3345FLECS_API
3347 const ecs_world_t *world,
3348 ecs_entity_t e);
3349
3350/** Ensure an ID is alive.
3351 * This operation ensures that the provided ID is alive. This is useful in
3352 * scenarios where an application has an existing ID that has not been created
3353 * with ecs_new_w() (such as a global constant or an ID from a remote application).
3354 *
3355 * When this operation is successful, it guarantees that the provided ID exists,
3356 * is valid, and is alive.
3357 *
3358 * Before this operation, the ID must either not be alive or have a generation
3359 * that is equal to the passed-in entity.
3360 *
3361 * If the provided ID has a non-zero generation count and the ID does not exist
3362 * in the world, the ID will be created with the specified generation.
3363 *
3364 * If the provided ID is alive and has a generation count that does not match
3365 * the provided ID, the operation will fail.
3366 *
3367 * @param world The world.
3368 * @param entity The entity ID to make alive.
3369 *
3370 * @see ecs_make_alive_id()
3371 */
3372FLECS_API
3374 ecs_world_t *world,
3375 ecs_entity_t entity);
3376
3377/** Same as ecs_make_alive(), but for components.
3378 * An ID can be an entity or a pair, and can contain ID flags. This operation
3379 * ensures that the entity (or entities, for a pair) are alive.
3380 *
3381 * When this operation is successful, it guarantees that the provided ID can be
3382 * used in operations that accept an ID.
3383 *
3384 * Since entities in a pair do not encode their generation IDs, this operation
3385 * will not fail when an entity with non-zero generation count already exists in
3386 * the world.
3387 *
3388 * This is different from ecs_make_alive(), which will fail if attempted with an ID
3389 * that has generation 0 and an entity with a non-zero generation is currently
3390 * alive.
3391 *
3392 * @param world The world.
3393 * @param component The component to make alive.
3394 */
3395FLECS_API
3397 ecs_world_t *world,
3398 ecs_id_t component);
3399
3400/** Test whether an entity exists.
3401 * Similar to ecs_is_alive(), but ignores the entity generation count.
3402 *
3403 * @param world The world.
3404 * @param entity The entity.
3405 * @return True if the entity exists, false if the entity does not exist.
3406 */
3407FLECS_API
3409 const ecs_world_t *world,
3410 ecs_entity_t entity);
3411
3412/** Override the generation of an entity.
3413 * The generation count of an entity is increased each time an entity is deleted
3414 * and is used to test whether an entity ID is alive.
3415 *
3416 * This operation overrides the current generation of an entity with the
3417 * specified generation, which can be useful if an entity is externally managed,
3418 * like for external pools, savefiles, or netcode.
3419 *
3420 * This operation is similar to ecs_make_alive(), except that it will also
3421 * override the generation of an alive entity.
3422 *
3423 * @param world The world.
3424 * @param entity The entity for which to set the generation.
3425 */
3426FLECS_API
3428 ecs_world_t *world,
3429 ecs_entity_t entity);
3430
3431/** Get the generation of an entity.
3432 *
3433 * @param entity The entity for which to get the generation.
3434 * @return The generation of the entity.
3435 */
3436FLECS_API
3438 ecs_entity_t entity);
3439
3440/** @} */
3441
3442/**
3443 * @defgroup entity_info Entity Information.
3444 * Get information from an entity.
3445 *
3446 * @{
3447 */
3448
3449/** Get the type of an entity.
3450 *
3451 * @param world The world.
3452 * @param entity The entity.
3453 * @return The type of the entity, NULL if the entity has no components.
3454 */
3455FLECS_API
3457 const ecs_world_t *world,
3458 ecs_entity_t entity);
3459
3460/** Get the table of an entity.
3461 *
3462 * @param world The world.
3463 * @param entity The entity.
3464 * @return The table of the entity, NULL if the entity has no components or tags.
3465 */
3466FLECS_API
3468 const ecs_world_t *world,
3469 ecs_entity_t entity);
3470
3471/** Convert a type to a string.
3472 * The result of this operation must be freed with ecs_os_free().
3473 *
3474 * @param world The world.
3475 * @param type The type.
3476 * @return The stringified type.
3477 */
3478FLECS_API
3480 const ecs_world_t *world,
3481 const ecs_type_t* type);
3482
3483/** Convert a table to a string.
3484 * Same as `ecs_type_str(world, ecs_table_get_type(table))`. The result of this
3485 * operation must be freed with ecs_os_free().
3486 *
3487 * @param world The world.
3488 * @param table The table.
3489 * @return The stringified table type.
3490 *
3491 * @see ecs_table_get_type()
3492 * @see ecs_type_str()
3493 */
3494FLECS_API
3496 const ecs_world_t *world,
3497 const ecs_table_t *table);
3498
3499/** Convert an entity to a string.
3500 * Same as combining:
3501 * - ecs_get_path(world, entity)
3502 * - ecs_type_str(world, ecs_get_type(world, entity))
3503 *
3504 * The result of this operation must be freed with ecs_os_free().
3505 *
3506 * @param world The world.
3507 * @param entity The entity.
3508 * @return The entity path with stringified type.
3509 *
3510 * @see ecs_get_path()
3511 * @see ecs_type_str()
3512 */
3513FLECS_API
3515 const ecs_world_t *world,
3516 ecs_entity_t entity);
3517
3518/** Test if an entity has a component.
3519 * This operation returns true if the entity has or inherits the component.
3520 *
3521 * @param world The world.
3522 * @param entity The entity.
3523 * @param component The component to test for.
3524 * @return True if the entity has the component, false if not.
3525 *
3526 * @see ecs_owns_id()
3527 */
3528FLECS_API
3529FLECS_ALWAYS_INLINE bool ecs_has_id(
3530 const ecs_world_t *world,
3531 ecs_entity_t entity,
3532 ecs_id_t component);
3533
3534/** Test if an entity owns a component.
3535 * This operation returns true if the entity has the component. The operation
3536 * behaves the same as ecs_has_id(), except that it will return false for
3537 * components that are inherited through an `IsA` relationship.
3538 *
3539 * @param world The world.
3540 * @param entity The entity.
3541 * @param component The component to test for.
3542 * @return True if the entity has the component, false if not.
3543 */
3544FLECS_API
3545FLECS_ALWAYS_INLINE bool ecs_owns_id(
3546 const ecs_world_t *world,
3547 ecs_entity_t entity,
3548 ecs_id_t component);
3549
3550/** Get the target of a relationship.
3551 * This will return a target (second element of a pair) of the entity for the
3552 * specified relationship. The index allows for iterating through the targets,
3553 * if a single entity has multiple targets for the same relationship.
3554 *
3555 * If the index is larger than the total number of instances the entity has for
3556 * the relationship, the operation will return 0.
3557 *
3558 * @param world The world.
3559 * @param entity The entity.
3560 * @param rel The relationship between the entity and the target.
3561 * @param index The index of the relationship instance.
3562 * @return The target for the relationship at the specified index.
3563 */
3564FLECS_API
3566 const ecs_world_t *world,
3567 ecs_entity_t entity,
3568 ecs_entity_t rel,
3569 int32_t index);
3570
3571/** Get the parent (target of the `ChildOf` relationship) for an entity.
3572 * This operation is the same as calling:
3573 *
3574 * @code
3575 * ecs_get_target(world, entity, EcsChildOf, 0);
3576 * @endcode
3577 *
3578 * @param world The world.
3579 * @param entity The entity.
3580 * @return The parent of the entity, 0 if the entity has no parent.
3581 *
3582 * @see ecs_get_target()
3583 */
3584FLECS_API
3586 const ecs_world_t *world,
3587 ecs_entity_t entity);
3588
3589/** Create child with Parent component.
3590 * This creates or returns an existing child for the specified parent. If a new
3591 * child is created, the Parent component is used to create the parent
3592 * relationship.
3593 *
3594 * If a child entity already exists with the specified name, it will be
3595 * returned.
3596 *
3597 * @param world The world.
3598 * @param parent The parent for which to create the child.
3599 * @param name The name with which to create the entity (may be NULL).
3600 * @return A new or existing child entity.
3601 */
3602FLECS_API
3604 ecs_world_t *world,
3605 ecs_entity_t parent,
3606 const char *name);
3607
3608/** Get the target of a relationship for a given component.
3609 * This operation returns the first entity that has the provided component by
3610 * following the relationship. If the entity itself has the component then it
3611 * will be returned. If the component cannot be found on the entity or by
3612 * following the relationship, the operation will return 0.
3613 *
3614 * This operation can be used to look up, for example, which prefab is providing
3615 * a component by specifying the `IsA` relationship:
3616 *
3617 * @code
3618 * // Is Position provided by the entity or one of its base entities?
3619 * ecs_get_target_for_id(world, entity, EcsIsA, ecs_id(Position))
3620 * @endcode
3621 *
3622 * @param world The world.
3623 * @param entity The entity.
3624 * @param rel The relationship to follow.
3625 * @param component The component to look up.
3626 * @return The entity for which the target has been found.
3627 */
3628FLECS_API
3630 const ecs_world_t *world,
3631 ecs_entity_t entity,
3632 ecs_entity_t rel,
3633 ecs_id_t component);
3634
3635/** Return the depth for an entity in the tree for the specified relationship.
3636 * Depth is determined by counting the number of targets encountered while
3637 * traversing up the relationship tree for `rel`. Only acyclic relationships are
3638 * supported.
3639 *
3640 * @param world The world.
3641 * @param entity The entity.
3642 * @param rel The relationship.
3643 * @return The depth of the entity in the tree.
3644 */
3645FLECS_API
3647 const ecs_world_t *world,
3648 ecs_entity_t entity,
3649 ecs_entity_t rel);
3650
3651/** Count entities that have the specified ID.
3652 * Return the number of entities that have the specified ID.
3653 *
3654 * @param world The world.
3655 * @param entity The ID to search for.
3656 * @return The number of entities that have the ID.
3657 */
3658FLECS_API
3660 const ecs_world_t *world,
3661 ecs_id_t entity);
3662
3663/** @} */
3664
3665
3666/**
3667 * @defgroup paths Entity Names
3668 * Functions for working with entity names and paths.
3669 *
3670 * @{
3671 */
3672
3673/** Get the name of an entity.
3674 * This will return the name stored in `(EcsIdentifier, EcsName)`.
3675 *
3676 * @param world The world.
3677 * @param entity The entity.
3678 * @return The name of the entity, NULL if the entity has no name.
3679 *
3680 * @see ecs_set_name()
3681 */
3682FLECS_API
3683const char* ecs_get_name(
3684 const ecs_world_t *world,
3685 ecs_entity_t entity);
3686
3687/** Get the symbol of an entity.
3688 * This will return the symbol stored in `(EcsIdentifier, EcsSymbol)`.
3689 *
3690 * @param world The world.
3691 * @param entity The entity.
3692 * @return The symbol of the entity, NULL if the entity has no symbol.
3693 *
3694 * @see ecs_set_symbol()
3695 */
3696FLECS_API
3697const char* ecs_get_symbol(
3698 const ecs_world_t *world,
3699 ecs_entity_t entity);
3700
3701/** Set the name of an entity.
3702 * This will set or overwrite the name of an entity. If no entity is provided,
3703 * a new entity will be created.
3704 *
3705 * The name is stored in `(EcsIdentifier, EcsName)`.
3706 *
3707 * @param world The world.
3708 * @param entity The entity.
3709 * @param name The name.
3710 * @return The provided entity, or a new entity if 0 was provided.
3711 *
3712 * @see ecs_get_name()
3713 */
3714FLECS_API
3716 ecs_world_t *world,
3717 ecs_entity_t entity,
3718 const char *name);
3719
3720/** Set the symbol of an entity.
3721 * This will set or overwrite the symbol of an entity. If no entity is provided,
3722 * a new entity will be created.
3723 *
3724 * The symbol is stored in `(EcsIdentifier, EcsSymbol)`.
3725 *
3726 * @param world The world.
3727 * @param entity The entity.
3728 * @param symbol The symbol.
3729 * @return The provided entity, or a new entity if 0 was provided.
3730 *
3731 * @see ecs_get_symbol()
3732 */
3733FLECS_API
3735 ecs_world_t *world,
3736 ecs_entity_t entity,
3737 const char *symbol);
3738
3739/** Set an alias for an entity.
3740 * An entity can be looked up using its alias from the root scope without
3741 * providing the fully qualified name of its parent. An entity can only have
3742 * a single alias.
3743 *
3744 * The alias is stored in `(EcsIdentifier, EcsAlias)`.
3745 *
3746 * @param world The world.
3747 * @param entity The entity.
3748 * @param alias The alias.
3749 */
3750FLECS_API
3752 ecs_world_t *world,
3753 ecs_entity_t entity,
3754 const char *alias);
3755
3756/** Look up an entity by its path.
3757 * This operation is equivalent to calling:
3758 *
3759 * @code
3760 * ecs_lookup_path_w_sep(world, 0, path, ".", NULL, true);
3761 * @endcode
3762 *
3763 * @param world The world.
3764 * @param path The entity path.
3765 * @return The entity with the specified path, or 0 if no entity was found.
3766 *
3767 * @see ecs_lookup_child()
3768 * @see ecs_lookup_path_w_sep()
3769 * @see ecs_lookup_symbol()
3770 */
3771FLECS_API
3773 const ecs_world_t *world,
3774 const char *path);
3775
3776/** Look up a child entity by name.
3777 * Return an entity that matches the specified name. Only look for entities in
3778 * the provided parent. If no parent is provided, look in the current scope
3779 * (root if no scope is provided).
3780 *
3781 * @param world The world.
3782 * @param parent The parent for which to look up the child.
3783 * @param name The entity name.
3784 * @return The entity with the specified name, or 0 if no entity was found.
3785 *
3786 * @see ecs_lookup()
3787 * @see ecs_lookup_path_w_sep()
3788 * @see ecs_lookup_symbol()
3789 */
3790FLECS_API
3792 const ecs_world_t *world,
3793 ecs_entity_t parent,
3794 const char *name);
3795
3796/** Look up an entity from a path.
3797 * Look up an entity from a provided path, relative to the provided parent. The
3798 * operation will use the provided separator to tokenize the path expression. If
3799 * the provided path contains the prefix, the search will start from the root.
3800 *
3801 * If the entity is not found in the provided parent, the operation will
3802 * continue to search in the parent of the parent, until the root is reached. If
3803 * the entity is still not found, the lookup will search in the `flecs.core`
3804 * scope. If the entity is not found there either, the function returns 0.
3805 *
3806 * @param world The world.
3807 * @param parent The entity from which to resolve the path.
3808 * @param path The path to resolve.
3809 * @param sep The path separator.
3810 * @param prefix The path prefix.
3811 * @param recursive Recursively traverse up the tree until the entity is found.
3812 * @return The entity if found, else 0.
3813 *
3814 * @see ecs_lookup()
3815 * @see ecs_lookup_child()
3816 * @see ecs_lookup_symbol()
3817 */
3818FLECS_API
3820 const ecs_world_t *world,
3821 ecs_entity_t parent,
3822 const char *path,
3823 const char *sep,
3824 const char *prefix,
3825 bool recursive);
3826
3827/** Look up an entity by its symbol name.
3828 * This looks up an entity by the symbol stored in `(EcsIdentifier, EcsSymbol)`. The
3829 * operation does not take into account hierarchies.
3830 *
3831 * This operation can be useful to resolve, for example, a type by its C
3832 * identifier, which does not include the Flecs namespacing.
3833 *
3834 * @param world The world.
3835 * @param symbol The symbol.
3836 * @param lookup_as_path If not found as a symbol, look up as path.
3837 * @param recursive If looking up as path, recursively traverse up the tree.
3838 * @return The entity if found, else 0.
3839 *
3840 * @see ecs_lookup()
3841 * @see ecs_lookup_child()
3842 * @see ecs_lookup_path_w_sep()
3843 */
3844FLECS_API
3846 const ecs_world_t *world,
3847 const char *symbol,
3848 bool lookup_as_path,
3849 bool recursive);
3850
3851/** Get a path identifier for an entity.
3852 * This operation creates a path that contains the names of the entities from
3853 * the specified parent to the provided entity, separated by the provided
3854 * separator. If no parent is provided, the path will be relative to the root. If
3855 * a prefix is provided, the path will be prefixed by the prefix.
3856 *
3857 * If the parent is equal to the provided child, the operation will return an
3858 * empty string. If a non-zero component is provided, the path will be created by
3859 * looking for parents with that component.
3860 *
3861 * The returned path should be freed by the application.
3862 *
3863 * @param world The world.
3864 * @param parent The entity from which to create the path.
3865 * @param child The entity to which to create the path.
3866 * @param sep The separator to use between path elements.
3867 * @param prefix The initial character to use for root elements.
3868 * @return The relative entity path.
3869 *
3870 * @see ecs_get_path_w_sep_buf()
3871 */
3872FLECS_API
3874 const ecs_world_t *world,
3875 ecs_entity_t parent,
3876 ecs_entity_t child,
3877 const char *sep,
3878 const char *prefix);
3879
3880/** Write a path identifier to a buffer.
3881 * Same as ecs_get_path_w_sep(), but writes the result to an `ecs_strbuf_t`.
3882 *
3883 * @param world The world.
3884 * @param parent The entity from which to create the path.
3885 * @param child The entity to which to create the path.
3886 * @param sep The separator to use between path elements.
3887 * @param prefix The initial character to use for root elements.
3888 * @param buf The buffer to write to.
3889 * @param escape Whether to escape separator characters in names.
3890 *
3891 * @see ecs_get_path_w_sep()
3892 */
3893FLECS_API
3895 const ecs_world_t *world,
3896 ecs_entity_t parent,
3897 ecs_entity_t child,
3898 const char *sep,
3899 const char *prefix,
3900 ecs_strbuf_t *buf,
3901 bool escape);
3902
3903/** Find or create an entity from a path.
3904 * This operation will find or create an entity from a path, and will create any
3905 * intermediate entities if required. If the entity already exists, no entities
3906 * will be created.
3907 *
3908 * If the path starts with the prefix, then the entity will be created from the
3909 * root scope.
3910 *
3911 * @param world The world.
3912 * @param parent The entity relative to which the entity should be created.
3913 * @param path The path to create the entity for.
3914 * @param sep The separator used in the path.
3915 * @param prefix The prefix used in the path.
3916 * @return The entity.
3917 */
3918FLECS_API
3920 ecs_world_t *world,
3921 ecs_entity_t parent,
3922 const char *path,
3923 const char *sep,
3924 const char *prefix);
3925
3926/** Add a specified path to an entity.
3927 * This operation is similar to ecs_new_from_path(), but will instead add the path
3928 * to an existing entity.
3929 *
3930 * If an entity already exists for the path, it will be returned instead.
3931 *
3932 * @param world The world.
3933 * @param entity The entity to which to add the path.
3934 * @param parent The entity relative to which the entity should be created.
3935 * @param path The path to create the entity for.
3936 * @param sep The separator used in the path.
3937 * @param prefix The prefix used in the path.
3938 * @return The entity.
3939 */
3940FLECS_API
3942 ecs_world_t *world,
3943 ecs_entity_t entity,
3944 ecs_entity_t parent,
3945 const char *path,
3946 const char *sep,
3947 const char *prefix);
3948
3949/** Set the current scope.
3950 * This operation sets the scope of the current stage to the provided entity.
3951 * As a result, new entities will be created in this scope, and lookups will be
3952 * relative to the provided scope.
3953 *
3954 * It is considered good practice to restore the scope to the old value.
3955 *
3956 * @param world The world.
3957 * @param scope The entity to use as scope.
3958 * @return The previous scope.
3959 *
3960 * @see ecs_get_scope()
3961 */
3962FLECS_API
3964 ecs_world_t *world,
3965 ecs_entity_t scope);
3966
3967/** Get the current scope.
3968 * Get the scope set by ecs_set_scope(). If no scope is set, this operation will
3969 * return 0.
3970 *
3971 * @param world The world.
3972 * @return The current scope.
3973 */
3974FLECS_API
3976 const ecs_world_t *world);
3977
3978/** Set a name prefix for newly created entities.
3979 * This is a utility that lets C modules use prefixed names for C types and
3980 * C functions, while using names for the entity names that do not have the
3981 * prefix. The name prefix is currently only used by `ECS_COMPONENT`.
3982 *
3983 * @param world The world.
3984 * @param prefix The name prefix to use.
3985 * @return The previous prefix.
3986 */
3987FLECS_API
3989 ecs_world_t *world,
3990 const char *prefix);
3991
3992/** Set the search path for lookup operations.
3993 * This operation accepts an array of entity IDs that will be used as search
3994 * scopes by lookup operations. The operation returns the current search path.
3995 * It is good practice to restore the old search path.
3996 *
3997 * The search path will be evaluated starting from the last element.
3998 *
3999 * The default search path includes `flecs.core`. When a custom search path is
4000 * provided, it overwrites the existing search path. Operations that rely on
4001 * looking up names from `flecs.core` without providing the namespace may fail if
4002 * the custom search path does not include `flecs.core` (`EcsFlecsCore`).
4003 *
4004 * The search path array is not copied into managed memory. The application must
4005 * ensure that the provided array is valid for as long as it is used as the
4006 * search path.
4007 *
4008 * The provided array must be terminated with a 0 element. This enables an
4009 * application to push or pop elements to an existing array without invoking the
4010 * ecs_set_lookup_path() operation again.
4011 *
4012 * @param world The world.
4013 * @param lookup_path 0-terminated array with entity IDs for the lookup path.
4014 * @return The current lookup path array.
4015 *
4016 * @see ecs_get_lookup_path()
4017 */
4018FLECS_API
4020 ecs_world_t *world,
4021 const ecs_entity_t *lookup_path);
4022
4023/** Get the current lookup path.
4024 * Return the value set by ecs_set_lookup_path().
4025 *
4026 * @param world The world.
4027 * @return The current lookup path.
4028 */
4029FLECS_API
4031 const ecs_world_t *world);
4032
4033/** @} */
4034
4035/** @} */
4036
4037/**
4038 * @defgroup components Components
4039 * Functions for registering and working with components.
4040 *
4041 * @{
4042 */
4043
4044/** Find or create a component.
4045 * This operation creates a new component, or finds an existing one. The find or
4046 * create behavior is the same as ecs_entity_init().
4047 *
4048 * When an existing component is found, the size and alignment are verified with
4049 * the provided values. If the values do not match, the operation will fail.
4050 *
4051 * See the documentation of ecs_component_desc_t for more details.
4052 *
4053 * @param world The world.
4054 * @param desc Component init parameters.
4055 * @return A handle to the new or existing component, or 0 if failed.
4056 */
4057FLECS_API
4059 ecs_world_t *world,
4060 const ecs_component_desc_t *desc);
4061
4062/** Get the type info for a component.
4063 * This function returns the type information for a component. The component can
4064 * be a regular component or a pair. For the rules on how type information is
4065 * determined based on a component ID, see ecs_get_typeid().
4066 *
4067 * @param world The world.
4068 * @param component The component.
4069 * @return The type information of the component ID.
4070 */
4071FLECS_API
4073 const ecs_world_t *world,
4074 ecs_id_t component);
4075
4076/** Register hooks for a component.
4077 * Hooks allow for the execution of user code when components are constructed,
4078 * copied, moved, destructed, added, removed, or set. Hooks can be assigned
4079 * as long as a component has not yet been used (added to an entity).
4080 *
4081 * The hooks that are currently set can be accessed with ecs_get_type_info().
4082 *
4083 * @param world The world.
4084 * @param component The component for which to register the actions.
4085 * @param hooks The type that contains the component actions.
4086 */
4087FLECS_API
4089 ecs_world_t *world,
4090 ecs_entity_t component,
4091 const ecs_type_hooks_t *hooks);
4092
4093/** Get hooks for a component.
4094 *
4095 * @param world The world.
4096 * @param component The component for which to retrieve the hooks.
4097 * @return The hooks for the component, or NULL if not registered.
4098 */
4099FLECS_API
4101 const ecs_world_t *world,
4102 ecs_entity_t component);
4103
4104/** @} */
4105
4106/**
4107 * @defgroup ids IDs
4108 * Functions for working with `ecs_id_t`.
4109 *
4110 * @{
4111 */
4112
4113/** Return whether a specified component is a tag.
4114 * This operation returns whether the specified component is a tag (a component
4115 * without data or size).
4116 *
4117 * An ID is a tag when:
4118 * - it is an entity without the `EcsComponent` component
4119 * - it has an `EcsComponent` with size member set to 0
4120 * - it is a pair where both elements are a tag
4121 * - it is a pair where the first element has the #EcsPairIsTag tag
4122 *
4123 * @param world The world.
4124 * @param component The component.
4125 * @return Whether the provided ID is a tag.
4126 */
4127FLECS_API
4129 const ecs_world_t *world,
4130 ecs_id_t component);
4131
4132/** Return whether a specified component is in use.
4133 * This operation returns whether a component is in use in the world. A
4134 * component is in use if it has been added to one or more tables.
4135 *
4136 * @param world The world.
4137 * @param component The component.
4138 * @return Whether the component is in use.
4139 */
4140FLECS_API
4142 const ecs_world_t *world,
4143 ecs_id_t component);
4144
4145/** Get the type for a component.
4146 * This operation returns the type for a component ID, if the ID is associated
4147 * with a type. For a regular component with a non-zero size (an entity with the
4148 * EcsComponent component), the operation will return the component ID itself.
4149 *
4150 * For an entity that does not have the EcsComponent component, or with an
4151 * EcsComponent value with size 0, the operation will return 0.
4152 *
4153 * For a pair ID, the operation will return the type associated with the pair, by
4154 * applying the following queries in order:
4155 * - The first pair element is returned if it is a component.
4156 * - 0 is returned if the relationship entity has the Tag property.
4157 * - The second pair element is returned if it is a component.
4158 * - 0 is returned.
4159 *
4160 * @param world The world.
4161 * @param component The component.
4162 * @return The type of the component.
4163 */
4164FLECS_API
4166 const ecs_world_t *world,
4167 ecs_id_t component);
4168
4169/** Utility to match a component with a pattern.
4170 * This operation returns true if the provided pattern matches the provided
4171 * component. The pattern may contain a wildcard (or wildcards, when a pair).
4172 *
4173 * @param component The component.
4174 * @param pattern The pattern to compare with.
4175 * @return Whether the ID matches the pattern.
4176 */
4177FLECS_API
4179 ecs_id_t component,
4180 ecs_id_t pattern);
4181
4182/** Utility to check if a component is a pair.
4183 *
4184 * @param component The component.
4185 * @return True if the component is a pair.
4186 */
4187FLECS_API
4189 ecs_id_t component);
4190
4191/** Utility to check if a component is a wildcard.
4192 *
4193 * @param component The component.
4194 * @return True if the component is a wildcard or a pair containing a wildcard.
4195 */
4196FLECS_API
4198 ecs_id_t component);
4199
4200/** Utility to check if a component is an any wildcard.
4201 *
4202 * @param component The component.
4203 * @return True if the component is an any wildcard or a pair containing an any wildcard.
4204 */
4206 ecs_id_t component);
4207
4208/** Utility to check if an ID is valid.
4209 * A valid ID is an ID that can be added to an entity. Invalid IDs are:
4210 * - IDs that contain wildcards
4211 * - IDs that contain invalid entities
4212 * - IDs that are 0 or contain 0 entities
4213 *
4214 * Note that the same rules apply to removing from an entity, with the exception
4215 * of wildcards.
4216 *
4217 * @param world The world.
4218 * @param component The component.
4219 * @return True if the ID is valid.
4220 */
4221FLECS_API
4223 const ecs_world_t *world,
4224 ecs_id_t component);
4225
4226/** Get flags associated with an ID.
4227 * This operation returns the internal flags (see api_flags.h) that are
4228 * associated with the provided ID.
4229 *
4230 * @param world The world.
4231 * @param component The component.
4232 * @return The flags associated with the ID, or 0 if the ID is not in use.
4233 */
4234FLECS_API
4235ecs_flags32_t ecs_id_get_flags(
4236 const ecs_world_t *world,
4237 ecs_id_t component);
4238
4239/** Convert a component flag to a string.
4240 * This operation converts a component flag to a string. Possible outputs are:
4241 *
4242 * - PAIR
4243 * - TOGGLE
4244 * - AUTO_OVERRIDE
4245 *
4246 * @param component_flags The component flag.
4247 * @return The ID flag string, or NULL if no valid ID is provided.
4248 */
4249FLECS_API
4251 uint64_t component_flags);
4252
4253/** Convert a component ID to a string.
4254 * This operation converts the provided component ID to a string. It can output
4255 * strings of the following formats:
4256 *
4257 * - "ComponentName"
4258 * - "FLAG|ComponentName"
4259 * - "(Relationship, Target)"
4260 * - "FLAG|(Relationship, Target)"
4261 *
4262 * The PAIR flag is never added to the string.
4263 *
4264 * @param world The world.
4265 * @param component The component to convert to a string.
4266 * @return The component converted to a string.
4267 */
4268FLECS_API
4270 const ecs_world_t *world,
4271 ecs_id_t component);
4272
4273/** Write a component string to a buffer.
4274 * Same as ecs_id_str(), but writes the result to ecs_strbuf_t.
4275 *
4276 * @param world The world.
4277 * @param component The component to convert to a string.
4278 * @param buf The buffer to write to.
4279 */
4280FLECS_API
4282 const ecs_world_t *world,
4283 ecs_id_t component,
4284 ecs_strbuf_t *buf);
4285
4286/** Convert a string to a component.
4287 * This operation is the reverse of ecs_id_str(). The FLECS_SCRIPT addon
4288 * is required for this operation to work.
4289 *
4290 * @param world The world.
4291 * @param expr The string to convert to an ID.
4292 * @return The ID, or 0 if the string could not be converted.
4293 */
4294FLECS_API
4296 const ecs_world_t *world,
4297 const char *expr);
4298
4299/** @} */
4300
4301/**
4302 * @defgroup queries Queries
4303 * @brief Functions for working with `ecs_term_t` and `ecs_query_t`.
4304 * @{
4305 */
4306
4307/** Test whether a term ref is set.
4308 * A term ref is a reference to an entity, component, or variable for one of the
4309 * three parts of a term (src, first, second).
4310 *
4311 * @param ref The term ref.
4312 * @return True when set, false when not set.
4313 */
4314FLECS_API
4316 const ecs_term_ref_t *ref);
4317
4318/** Test whether a term is set.
4319 * This operation can be used to test whether a term has been initialized with
4320 * values or whether it is empty.
4321 *
4322 * An application generally does not need to invoke this operation. It is useful
4323 * when initializing a 0-initialized array of terms (like in ecs_query_desc_t), as
4324 * this operation can be used to find the last initialized element.
4325 *
4326 * @param term The term.
4327 * @return True when set, false when not set.
4328 */
4329FLECS_API
4331 const ecs_term_t *term);
4332
4333/** Is a term matched on the $this variable.
4334 * This operation checks whether a term is matched on the $this variable, which
4335 * is the default source for queries.
4336 *
4337 * A term has a $this source when:
4338 * - ecs_term_t::src::id is EcsThis
4339 * - ecs_term_t::src::flags is EcsIsVariable
4340 *
4341 * If ecs_term_t::src is not populated, it will be automatically initialized to
4342 * the $this source for the created query.
4343 *
4344 * @param term The term.
4345 * @return True if the term matches $this, false if not.
4346 */
4347FLECS_API
4349 const ecs_term_t *term);
4350
4351/** Is a term matched on a 0 source.
4352 * This operation checks whether a term is matched on a 0 source. A 0 source is
4353 * a term that isn't matched against anything, and can be used just to pass
4354 * (component) IDs to a query iterator.
4355 *
4356 * A term has a 0 source when:
4357 * - ecs_term_t::src::id is 0
4358 * - ecs_term_t::src::flags has EcsIsEntity set
4359 *
4360 * @param term The term.
4361 * @return True if the term has a 0 source, false if not.
4362 */
4363FLECS_API
4365 const ecs_term_t *term);
4366
4367/** Convert a term to a string expression.
4368 * Convert a term to a string expression. The resulting expression is equivalent
4369 * to the same term, with the exception of And and Or operators.
4370 *
4371 * @param world The world.
4372 * @param term The term.
4373 * @return The term converted to a string.
4374 */
4375FLECS_API
4377 const ecs_world_t *world,
4378 const ecs_term_t *term);
4379
4380/** Convert a query to a string expression.
4381 * Convert a query to a string expression. The resulting expression can be
4382 * parsed to create the same query.
4383 *
4384 * @param query The query.
4385 * @return The query converted to a string.
4386 */
4387FLECS_API
4389 const ecs_query_t *query);
4390
4391/** @} */
4392
4393/**
4394 * @defgroup each_iter Each iterator
4395 * @brief Find all entities that have a single (component) ID.
4396 * @{
4397 */
4398
4399/** Iterate all entities with a specified (component ID).
4400 * This returns an iterator that yields all entities with a single specified
4401 * component. This is a much lighter-weight operation than creating and
4402 * iterating a query.
4403 *
4404 * Usage:
4405 * @code
4406 * ecs_iter_t it = ecs_each(world, Player);
4407 * while (ecs_each_next(&it)) {
4408 * for (int i = 0; i < it.count; i ++) {
4409 * // Iterate as usual.
4410 * }
4411 * }
4412 * @endcode
4413 *
4414 * If the specified ID is a component, it is possible to access the component
4415 * pointer with ecs_field() just like with regular queries:
4416 *
4417 * @code
4418 * ecs_iter_t it = ecs_each(world, Position);
4419 * while (ecs_each_next(&it)) {
4420 * Position *p = ecs_field(&it, Position, 0);
4421 * for (int i = 0; i < it.count; i ++) {
4422 * // Iterate as usual.
4423 * }
4424 * }
4425 * @endcode
4426 *
4427 * @param world The world.
4428 * @param component The component to iterate.
4429 * @return An iterator that iterates all entities with the (component) ID.
4430 */
4431FLECS_API
4433 const ecs_world_t *world,
4434 ecs_id_t component);
4435
4436/** Progress an iterator created with ecs_each_id().
4437 *
4438 * @param it The iterator.
4439 * @return True if the iterator has more results, false if not.
4440 */
4441FLECS_API
4443 ecs_iter_t *it);
4444
4445/** Iterate children of a parent.
4446 * This operation is usually equivalent to doing:
4447 * @code
4448 * ecs_iter_t it = ecs_each_id(world, ecs_pair(EcsChildOf, parent));
4449 * @endcode
4450 *
4451 * The only exception is when the parent has the EcsOrderedChildren trait, in
4452 * which case this operation will return a single result with the ordered
4453 * child entity IDs.
4454 *
4455 * This operation is equivalent to doing:
4456 *
4457 * @code
4458 * ecs_children_w_rel(world, EcsChildOf, parent);
4459 * @endcode
4460 *
4461 * @param world The world.
4462 * @param parent The parent.
4463 * @return An iterator that iterates all children of the parent.
4464 *
4465 * @see ecs_each_id()
4466 */
4467FLECS_API
4468FLECS_ALWAYS_INLINE ecs_iter_t ecs_children(
4469 const ecs_world_t *world,
4470 ecs_entity_t parent);
4471
4472/** Same as ecs_children(), but with a custom relationship argument.
4473 *
4474 * @param world The world.
4475 * @param relationship The relationship.
4476 * @param parent The parent.
4477 * @return An iterator that iterates all children of the parent.
4478 */
4479FLECS_API
4480FLECS_ALWAYS_INLINE ecs_iter_t ecs_children_w_rel(
4481 const ecs_world_t *world,
4482 ecs_entity_t relationship,
4483 ecs_entity_t parent);
4484
4485/** Progress an iterator created with ecs_children().
4486 *
4487 * @param it The iterator.
4488 * @return True if the iterator has more results, false if not.
4489 */
4490FLECS_API
4492 ecs_iter_t *it);
4493
4494/** @} */
4495
4496/**
4497 * @defgroup queries Queries
4498 * Functions for working with `ecs_query_t`.
4499 *
4500 * @{
4501 */
4502
4503/** Create a query.
4504 * If the descriptor specifies an existing entity, the entity must not already
4505 * be associated with a query. To replace an existing query on an entity, use
4506 * ecs_query_update().
4507 *
4508 * @param world The world.
4509 * @param desc The descriptor (see ecs_query_desc_t).
4510 * @return The query.
4511 */
4512FLECS_API
4514 ecs_world_t *world,
4515 const ecs_query_desc_t *desc);
4516
4517/** Replace the query on an existing entity.
4518 * Removes the query currently attached to the entity and creates a new one
4519 * from the descriptor. Any handles to the previous query become invalid; use
4520 * the returned handle for subsequent iteration.
4521 *
4522 * @param world The world.
4523 * @param entity The entity that holds the query to replace.
4524 * @param desc The descriptor (see ecs_query_desc_t).
4525 * @return The new query, or NULL if the operation failed.
4526 */
4527FLECS_API
4529 ecs_world_t *world,
4530 ecs_entity_t entity,
4531 const ecs_query_desc_t *desc);
4532
4533/** Delete a query.
4534 *
4535 * @param query The query.
4536 */
4537FLECS_API
4539 ecs_query_t *query);
4540
4541#ifdef FLECS_QUERY_PLANS
4542
4543/** Find a variable index.
4544 * This operation looks up the index of a variable in the query. This index can
4545 * be used in operations like ecs_iter_set_var() and ecs_iter_get_var().
4546 *
4547 * @param query The query.
4548 * @param name The variable name.
4549 * @return The variable index.
4550 */
4551FLECS_API
4553 const ecs_query_t *query,
4554 const char *name);
4555
4556/** Get the variable name.
4557 * This operation returns the variable name for an index.
4558 *
4559 * @param query The query.
4560 * @param var_id The variable index.
4561 * @return The variable name.
4562 */
4563FLECS_API
4565 const ecs_query_t *query,
4566 int32_t var_id);
4567
4568/** Test if a variable is an entity.
4569 * Internally, the query engine has entity variables and table variables. When
4570 * iterating through query variables (by using ecs_query_t::var_count) only
4571 * the values for entity variables are accessible. This operation enables an
4572 * application to check if a variable is an entity variable.
4573 *
4574 * @param query The query.
4575 * @param var_id The variable ID.
4576 * @return Whether the variable is an entity variable.
4577 */
4578FLECS_API
4580 const ecs_query_t *query,
4581 int32_t var_id);
4582
4583#endif // FLECS_QUERY_PLANS
4584
4585/** Create a query iterator.
4586 * Use an iterator to iterate through the entities that match a query. Queries
4587 * can return multiple results, and have to be iterated by repeatedly calling
4588 * ecs_query_next() until the operation returns false.
4589 *
4590 * Depending on the query, a single result can contain an entire table, a range
4591 * of entities in a table, or a single entity. Iteration code has an inner and
4592 * an outer loop. The outer loop loops through the query results, and typically
4593 * corresponds with a table. The inner loop iterates entities in the result.
4594 *
4595 * Example:
4596 * @code
4597 * ecs_iter_t it = ecs_query_iter(world, q);
4598 *
4599 * while (ecs_query_next(&it)) {
4600 * Position *p = ecs_field(&it, Position, 0);
4601 * Velocity *v = ecs_field(&it, Velocity, 1);
4602 *
4603 * for (int i = 0; i < it.count; i ++) {
4604 * p[i].x += v[i].x;
4605 * p[i].y += v[i].y;
4606 * }
4607 * }
4608 * @endcode
4609 *
4610 * If query iteration is stopped without the last call to ecs_query_next()
4611 * returning false, iterator resources need to be cleaned up explicitly
4612 * with ecs_iter_fini().
4613 *
4614 * Example:
4615 * @code
4616 * ecs_iter_t it = ecs_query_iter(world, q);
4617 *
4618 * while (ecs_query_next(&it)) {
4619 * if (!ecs_field_is_set(&it, 0)) {
4620 * ecs_iter_fini(&it); // Free iterator resources
4621 * break;
4622 * }
4623 *
4624 * for (int i = 0; i < it.count; i ++) {
4625 * // ...
4626 * }
4627 * }
4628 * @endcode
4629 *
4630 * @param world The world.
4631 * @param query The query.
4632 * @return An iterator.
4633 *
4634 * @see ecs_query_next()
4635 */
4636FLECS_API
4638 const ecs_world_t *world,
4639 const ecs_query_t *query);
4640
4641/** Progress a query iterator.
4642 *
4643 * @param it The iterator.
4644 * @return True if the iterator has more results, false if not.
4645 *
4646 * @see ecs_query_iter()
4647 */
4648FLECS_API
4650 ecs_iter_t *it);
4651
4652/** Match an entity with a query.
4653 * This operation matches an entity with a query and returns the result of the
4654 * match in the "it" out parameter. An application should free the iterator
4655 * resources with ecs_iter_fini() if this function returns true.
4656 *
4657 * Usage:
4658 * @code
4659 * ecs_iter_t it;
4660 * if (ecs_query_has(q, e, &it)) {
4661 * ecs_iter_fini(&it);
4662 * }
4663 * @endcode
4664 *
4665 * @param query The query.
4666 * @param entity The entity to match.
4667 * @param it The iterator with matched data.
4668 * @return True if entity matches the query, false if not.
4669 */
4670FLECS_API
4672 const ecs_query_t *query,
4673 ecs_entity_t entity,
4674 ecs_iter_t *it);
4675
4676/** Match a table with a query.
4677 * This operation matches a table with a query and returns the result of the
4678 * match in the "it" out parameter. An application should free the iterator
4679 * resources with ecs_iter_fini() if this function returns true.
4680 *
4681 * Usage:
4682 * @code
4683 * ecs_iter_t it;
4684 * if (ecs_query_has_table(q, t, &it)) {
4685 * ecs_iter_fini(&it);
4686 * }
4687 * @endcode
4688 *
4689 * @param query The query.
4690 * @param table The table to match.
4691 * @param it The iterator with matched data.
4692 * @return True if table matches the query, false if not.
4693 */
4694FLECS_API
4696 const ecs_query_t *query,
4697 ecs_table_t *table,
4698 ecs_iter_t *it);
4699
4700/** Match a range with a query.
4701 * This operation matches a range with a query and returns the result of the
4702 * match in the "it" out parameter. An application should free the iterator
4703 * resources with ecs_iter_fini() if this function returns true.
4704 *
4705 * The entire range must match the query for the operation to return true.
4706 *
4707 * Usage:
4708 * @code
4709 * ecs_table_range_t range = {
4710 * .table = table,
4711 * .offset = 1,
4712 * .count = 2
4713 * };
4714 *
4715 * ecs_iter_t it;
4716 * if (ecs_query_has_range(q, &range, &it)) {
4717 * ecs_iter_fini(&it);
4718 * }
4719 * @endcode
4720 *
4721 * @param query The query.
4722 * @param range The range to match.
4723 * @param it The iterator with matched data.
4724 * @return True if range matches the query, false if not.
4725 */
4726FLECS_API
4728 const ecs_query_t *query,
4729 ecs_table_range_t *range,
4730 ecs_iter_t *it);
4731
4732#ifdef FLECS_CACHED_QUERIES
4733
4734/** Return how often a match event happened for a cached query.
4735 * This operation can be used to determine whether the query cache has been
4736 * updated with new tables.
4737 *
4738 * @param query The query.
4739 * @return The number of match events that happened.
4740 */
4741FLECS_API
4743 const ecs_query_t *query);
4744
4745/** Event emitted when a table needs to be revalidated for a query cache.
4746 * The event is enqueued when an observer detects that the components that are
4747 * matched through relationship traversal changed for a table, and is handled
4748 * when the command queue is flushed. The event payload is of type
4749 * ecs_query_cache_revalidate_t. */
4750FLECS_API extern const ecs_entity_t EcsOnQueryCacheRevalidate;
4751
4752/** Payload for EcsOnQueryCacheRevalidate event. */
4754 ecs_entity_t query; /**< Query for which to revalidate table. */
4755 uint64_t table_id; /**< Id of table to revalidate. */
4757
4758#endif // FLECS_CACHED_QUERIES
4759
4760#ifdef FLECS_QUERY_PLANS
4761
4762/** Convert a query to a string.
4763 * This will convert the query program to a string, which can aid in debugging
4764 * the behavior of a query.
4765 *
4766 * The returned string must be freed with ecs_os_free().
4767 *
4768 * @param query The query.
4769 * @return The query plan.
4770 */
4771FLECS_API
4773 const ecs_query_t *query);
4774
4775/** Convert a query to a string with a profile.
4776 * To use this, you must set the EcsIterProfile flag on an iterator before
4777 * starting iteration:
4778 *
4779 * @code
4780 * it.flags |= EcsIterProfile;
4781 * @endcode
4782 *
4783 * The returned string must be freed with ecs_os_free().
4784 *
4785 * @param query The query.
4786 * @param it The iterator with profile data.
4787 * @return The query plan with profile data.
4788 */
4789FLECS_API
4791 const ecs_query_t *query,
4792 const ecs_iter_t *it);
4793
4794/** Same as ecs_query_plan(), but includes the plan for populating the cache (if any).
4795 *
4796 * @param query The query.
4797 * @return The query plan.
4798 */
4799FLECS_API
4801 const ecs_query_t *query);
4802
4803/** Populate variables from a key-value string.
4804 * Convenience function to set query variables from a key-value string separated
4805 * by commas. The string must have the following format:
4806 *
4807 * @code
4808 * var_a: value, var_b: value
4809 * @endcode
4810 *
4811 * The key-value list may optionally be enclosed in parentheses.
4812 *
4813 * This function uses the script addon.
4814 *
4815 * @param query The query.
4816 * @param it The iterator for which to set the variables.
4817 * @param expr The key-value expression.
4818 * @return A pointer to the next character after the last parsed one.
4819 */
4820FLECS_API
4822 ecs_query_t *query,
4823 ecs_iter_t *it,
4824 const char *expr);
4825
4826#endif // FLECS_QUERY_PLANS
4827
4828#ifdef FLECS_CACHED_QUERIES
4829/** Return whether the query data changed since the last iteration.
4830 * The operation will return true after:
4831 * - new entities have been matched
4832 * - new tables have been matched or unmatched
4833 * - matched entities were deleted
4834 * - matched components were changed
4835 *
4836 * The operation will not return true after a write-only (EcsOut) or filter
4837 * (EcsInOutFilter) term has changed, when a term is not matched with the
4838 * current table ($this source) or for tag terms.
4839 *
4840 * The changed state of a table is reset after it is iterated. If an iterator was
4841 * not iterated until completion, tables may still be marked as changed.
4842 *
4843 * To check the changed state of the current iterator result, use
4844 * ecs_iter_changed().
4845 *
4846 * @param query The query.
4847 * @return True if entities changed, otherwise false.
4848 *
4849 * @see ecs_iter_changed()
4850 */
4851FLECS_API
4853 ecs_query_t *query);
4854#endif
4855
4856/** Get the query object.
4857 * Return the query object. Can be used to access various information about
4858 * the query.
4859 *
4860 * @param world The world.
4861 * @param query The query.
4862 * @return The query object.
4863 */
4864FLECS_API
4866 const ecs_world_t *world,
4867 ecs_entity_t query);
4868
4869#ifdef FLECS_CACHED_QUERIES
4870/** Skip a table while iterating.
4871 * This operation lets the query iterator know that a table was skipped while
4872 * iterating. A skipped table will not reset its changed state, and the query
4873 * will not update the dirty flags of the table for its out fields.
4874 *
4875 * Only valid iterators must be provided (next() has to be called at least once
4876 * and must return true), and the iterator must be a query iterator.
4877 *
4878 * @param it The iterator result to skip.
4879 */
4880FLECS_API
4882 ecs_iter_t *it);
4883
4884/** Set the group to iterate for a query iterator.
4885 * This operation limits the results returned by the query to only the selected
4886 * group ID. The query must have a group_by function, and the iterator must
4887 * be a query iterator.
4888 *
4889 * Groups are sets of tables that are stored together in the query cache based
4890 * on a group ID, which is calculated per table by the group_by function. To
4891 * iterate a group, an iterator only needs to know the first and last cache node
4892 * for that group, which can both be found in a fast O(1) operation.
4893 *
4894 * As a result, group iteration is one of the most efficient mechanisms to
4895 * filter out large numbers of entities, even if those entities are distributed
4896 * across many tables. This makes it a good fit for things like dividing up
4897 * a world into cells, and only iterating cells close to a player.
4898 *
4899 * The group to iterate must be set before the first call to ecs_query_next(). No
4900 * operations that can add or remove components should be invoked between calling
4901 * ecs_iter_set_group() and ecs_query_next().
4902 *
4903 * @param it The query iterator.
4904 * @param group_id The group to iterate.
4905 */
4906FLECS_API
4908 ecs_iter_t *it,
4909 uint64_t group_id);
4910
4911/** Return the map with query groups.
4912 * This map can be used to iterate the active group identifiers of a query. The
4913 * payload of the map is opaque. The map can be used as follows:
4914 *
4915 * @code
4916 * const ecs_map_t *keys = ecs_query_get_groups(q);
4917 * ecs_map_iter_t kit = ecs_map_iter(keys);
4918 * while (ecs_map_next(&kit)) {
4919 * uint64_t group_id = ecs_map_key(&kit);
4920 *
4921 * // Iterate query for group
4922 * ecs_iter_t it = ecs_query_iter(world, q);
4923 * ecs_iter_set_group(&it, group_id);
4924 * while (ecs_query_next(&it)) {
4925 * // Iterate as usual
4926 * }
4927 * }
4928 * @endcode
4929 *
4930 * This operation is not valid for queries that do not use group_by. The
4931 * returned map pointer will remain valid for as long as the query exists.
4932 *
4933 * @param query The query.
4934 * @return The map with query groups.
4935 */
4936FLECS_API
4937const ecs_map_t* ecs_query_get_groups(
4938 const ecs_query_t *query);
4939
4940/** Get the context of a query group.
4941 * This operation returns the context of a query group as returned by the
4942 * on_group_create callback.
4943 *
4944 * @param query The query.
4945 * @param group_id The group for which to obtain the context.
4946 * @return The group context, NULL if the group doesn't exist.
4947 */
4948FLECS_API
4950 const ecs_query_t *query,
4951 uint64_t group_id);
4952
4953/** Get information about a query group.
4954 * This operation returns information about a query group, including the group
4955 * context returned by the on_group_create callback.
4956 *
4957 * @param query The query.
4958 * @param group_id The group for which to obtain the group info.
4959 * @return The group info, NULL if the group doesn't exist.
4960 */
4961FLECS_API
4963 const ecs_query_t *query,
4964 uint64_t group_id);
4965
4966#endif // FLECS_CACHED_QUERIES
4967
4968/** Struct returned by ecs_query_count(). */
4969typedef struct ecs_query_count_t {
4970 int32_t results; /**< Number of results returned by the query. */
4971 int32_t entities; /**< Number of entities returned by the query. */
4972 int32_t tables; /**< Number of tables returned by the query. Only set for
4973 * queries for which the table count can be reliably
4974 * determined. */
4976
4977/** Return the number of entities and results the query matches with.
4978 * Only entities matching the $this variable as source are counted.
4979 *
4980 * @param query The query.
4981 * @return The number of matched entities.
4982 */
4983FLECS_API
4985 const ecs_query_t *query);
4986
4987/** Test whether a query returns one or more results.
4988 *
4989 * @param query The query.
4990 * @return True if query matches anything, false if not.
4991 */
4992FLECS_API
4994 const ecs_query_t *query);
4995
4996#ifdef FLECS_CACHED_QUERIES
4997
4998/** Get the query used to populate the cache.
4999 * This operation returns the query that is used to populate the query cache.
5000 * For queries that can be entirely cached, the returned query will be
5001 * equivalent to the query passed to ecs_query_init().
5002 *
5003 * @param query The query.
5004 * @return The query used to populate the cache, NULL if query is not cached.
5005 */
5006FLECS_API
5008 const ecs_query_t *query);
5009
5010#endif // FLECS_CACHED_QUERIES
5011
5012/** @} */
5013
5014/**
5015 * @defgroup observers Observers
5016 * Functions for working with events and observers.
5017 *
5018 * @{
5019 */
5020
5021/** Send an event.
5022 * This sends an event to matching observers and is the mechanism used by Flecs
5023 * itself to send `OnAdd`, `OnRemove`, etc. events.
5024 *
5025 * Applications can use this function to send custom events, where a custom
5026 * event can be any regular entity.
5027 *
5028 * Applications should not send built-in Flecs events, as this may violate
5029 * assumptions the code makes about the conditions under which those events are
5030 * sent.
5031 *
5032 * Observers are invoked synchronously. It is therefore safe to use stack-based
5033 * data as event context, which can be set in the "param" member.
5034 *
5035 * @param world The world.
5036 * @param desc The event parameters.
5037 *
5038 * @see ecs_enqueue()
5039 */
5040FLECS_API
5042 ecs_world_t *world,
5043 ecs_event_desc_t *desc);
5044
5045/** Enqueue an event.
5046 * @param world The world.
5047 * @param desc The event parameters.
5048 */
5049FLECS_API
5051 ecs_world_t *world,
5052 ecs_event_desc_t *desc);
5053
5054/** Create an observer.
5055 * Observers can subscribe for one or more terms. An observer only triggers
5056 * when the source of the event meets all terms.
5057 *
5058 * If the descriptor specifies an existing entity, the entity must not already
5059 * be associated with an observer. To modify an existing observer, use
5060 * ecs_observer_update().
5061 *
5062 * See the documentation for ecs_observer_desc_t for more details.
5063 *
5064 * @param world The world.
5065 * @param desc The observer creation parameters.
5066 * @return The observer, or 0 if the operation failed.
5067 */
5068FLECS_API
5070 ecs_world_t *world,
5071 const ecs_observer_desc_t *desc);
5072
5073/** Update an existing observer.
5074 * Updates the configuration of an observer that was previously created with
5075 * ecs_observer_init(). Only fields in desc that are set to a non-default
5076 * value will be applied; fields left at their default value preserve the
5077 * existing configuration of the observer.
5078 *
5079 * The query and events fields of the descriptor are not used by this function;
5080 * the observer query and event subscriptions cannot be modified after
5081 * creation.
5082 *
5083 * @param world The world.
5084 * @param observer The observer to update.
5085 * @param desc The observer descriptor.
5086 * @return The observer entity, or 0 if the operation failed.
5087 */
5088FLECS_API
5090 ecs_world_t *world,
5091 ecs_entity_t observer,
5092 const ecs_observer_desc_t *desc);
5093
5094/** Get the observer object.
5095 * Return the observer object. Can be used to access various information about
5096 * the observer, like the query and context.
5097 *
5098 * @param world The world.
5099 * @param observer The observer.
5100 * @return The observer object.
5101 */
5102FLECS_API
5104 const ecs_world_t *world,
5105 ecs_entity_t observer);
5106
5107/** @} */
5108
5109/**
5110 * @defgroup iterator Iterators
5111 * Functions for working with `ecs_iter_t`.
5112 *
5113 * @{
5114 */
5115
5116/** Progress any iterator.
5117 * This operation is useful in combination with iterators for which it is not
5118 * known what created them. Example use cases are functions that should accept
5119 * any kind of iterator (such as serializers) or iterators created from poly
5120 * objects.
5121 *
5122 * This operation is slightly slower than using a type-specific iterator (e.g.,
5123 * ecs_query_next(), ecs_each_next()), as it has to call a function pointer, which
5124 * introduces a level of indirection.
5125 *
5126 * @param it The iterator.
5127 * @return True if iterator has more results, false if not.
5128 */
5129FLECS_API
5131 ecs_iter_t *it);
5132
5133/** Clean up iterator resources.
5134 * This operation cleans up any resources associated with the iterator.
5135 *
5136 * This operation should only be used when an iterator is not iterated until
5137 * completion (next() has not yet returned false). When an iterator is iterated
5138 * until completion, resources are automatically freed.
5139 *
5140 * @param it The iterator.
5141 */
5142FLECS_API
5144 ecs_iter_t *it);
5145
5146/** Count the number of matched entities in a query.
5147 * This operation returns the number of matched entities. If a query contains no
5148 * matched entities but still yields results (e.g., it has no terms with $this
5149 * sources), the operation will return 0.
5150 *
5151 * To determine the number of matched entities, the operation iterates the
5152 * iterator until it yields no more results.
5153 *
5154 * @param it The iterator.
5155 * @return The number of matched entities.
5156 */
5157FLECS_API
5159 ecs_iter_t *it);
5160
5161/** Test if an iterator is true.
5162 * This operation will return true if the iterator returns at least one result.
5163 * This is especially useful in combination with fact-checking queries (see the
5164 * queries addon).
5165 *
5166 * The operation requires a valid iterator. After the operation is invoked, the
5167 * application should no longer invoke next() on the iterator and should treat it
5168 * as if the iterator is iterated until completion.
5169 *
5170 * @param it The iterator.
5171 * @return True if the iterator returns at least one result.
5172 */
5173FLECS_API
5175 ecs_iter_t *it);
5176
5177/** Get the first matching entity from an iterator.
5178 * After this operation, the application should treat the iterator as if it has
5179 * been iterated until completion.
5180 *
5181 * @param it The iterator.
5182 * @return The first matching entity, or 0 if no entities were matched.
5183 */
5184FLECS_API
5186 ecs_iter_t *it);
5187
5188/** Set the value for an iterator variable.
5189 * This constrains the iterator to return only results for which the variable
5190 * equals the specified value. The default value for all variables is
5191 * EcsWildcard, which means the variable can assume any value.
5192 *
5193 * Example:
5194 *
5195 * @code
5196 * // Query that matches Position
5197 * ecs_query_t *q = ecs_query(world, {
5198 * .terms = {{ ecs_id(Position) }}
5199 * });
5200 *
5201 * // Constrain $this so the query only matches entity e
5202 * ecs_iter_t it = ecs_query_iter(world, q);
5203 * ecs_iter_set_var(&it, 0, e);
5204 *
5205 * while (ecs_query_next(&it)) {
5206 * for (int i = 0; i < it.count; i ++) {
5207 * // iterate as usual
5208 * }
5209 * }
5210 * @endcode
5211 *
5212 * The variable must be initialized after creating the iterator and before the
5213 * first call to next().
5214 * Without FLECS_QUERY_PLANS, only variable 0 ($this) can be set.
5215 *
5216 * @param it The iterator.
5217 * @param var_id The variable index.
5218 * @param entity The entity variable value.
5219 *
5220 * @see ecs_iter_set_var_as_range()
5221 * @see ecs_iter_set_var_as_table()
5222 */
5223FLECS_API
5225 ecs_iter_t *it,
5226 int32_t var_id,
5227 ecs_entity_t entity);
5228
5229/** Same as ecs_iter_set_var(), but for a table.
5230 * This constrains the variable to all entities in a table.
5231 *
5232 * @param it The iterator.
5233 * @param var_id The variable index.
5234 * @param table The table variable value.
5235 *
5236 * @see ecs_iter_set_var()
5237 * @see ecs_iter_set_var_as_range()
5238 */
5239FLECS_API
5241 ecs_iter_t *it,
5242 int32_t var_id,
5243 const ecs_table_t *table);
5244
5245/** Same as ecs_iter_set_var(), but for a range of entities.
5246 * This constrains the variable to a range of entities in a table.
5247 *
5248 * @param it The iterator.
5249 * @param var_id The variable index.
5250 * @param range The range variable value.
5251 *
5252 * @see ecs_iter_set_var()
5253 * @see ecs_iter_set_var_as_table()
5254 */
5255FLECS_API
5257 ecs_iter_t *it,
5258 int32_t var_id,
5259 const ecs_table_range_t *range);
5260
5261#ifdef FLECS_QUERY_PLANS
5262
5263/** Get the value of an iterator variable as an entity.
5264 * A variable can be interpreted as an entity if it is set to an entity, or if it
5265 * is set to a table range with count 1.
5266 *
5267 * This operation can only be invoked on valid iterators. The variable index
5268 * must be smaller than the total number of variables provided by the iterator
5269 * (as returned by ecs_iter_get_var_count()).
5270 *
5271 * @param it The iterator.
5272 * @param var_id The variable index.
5273 * @return The variable value.
5274 */
5275FLECS_API
5277 ecs_iter_t *it,
5278 int32_t var_id);
5279
5280/** Get the variable name.
5281 *
5282 * @param it The iterator.
5283 * @param var_id The variable index.
5284 * @return The variable name.
5285 */
5286FLECS_API
5288 const ecs_iter_t *it,
5289 int32_t var_id);
5290
5291/** Get the number of variables.
5292 *
5293 * @param it The iterator.
5294 * @return The number of variables.
5295 */
5296FLECS_API
5298 const ecs_iter_t *it);
5299
5300/** Get the variable array.
5301 *
5302 * @param it The iterator.
5303 * @return The variable array (if any).
5304 */
5305FLECS_API
5307 const ecs_iter_t *it);
5308
5309/** Get the value of an iterator variable as a table.
5310 * A variable can be interpreted as a table if it is set as a table range with
5311 * both offset and count set to 0, or if offset is 0 and count matches the
5312 * number of elements in the table.
5313 *
5314 * This operation can only be invoked on valid iterators. The variable index
5315 * must be smaller than the total number of variables provided by the iterator
5316 * (as returned by ecs_iter_get_var_count()).
5317 *
5318 * @param it The iterator.
5319 * @param var_id The variable index.
5320 * @return The variable value.
5321 */
5322FLECS_API
5324 ecs_iter_t *it,
5325 int32_t var_id);
5326
5327/** Get the value of an iterator variable as a table range.
5328 * A value can be interpreted as a table range if it is set as a table range, or if
5329 * it is set to an entity with a non-empty type (the entity must have at least
5330 * one component, tag, or relationship in its type).
5331 *
5332 * This operation can only be invoked on valid iterators. The variable index
5333 * must be smaller than the total number of variables provided by the iterator
5334 * (as returned by ecs_iter_get_var_count()).
5335 *
5336 * @param it The iterator.
5337 * @param var_id The variable index.
5338 * @return The variable value.
5339 */
5340FLECS_API
5342 ecs_iter_t *it,
5343 int32_t var_id);
5344
5345/** Return whether a variable is constrained.
5346 * This operation returns true for variables set by one of the ecs_iter_set_var*
5347 * operations.
5348 *
5349 * A constrained variable is guaranteed not to change values while results are
5350 * being iterated.
5351 *
5352 * @param it The iterator.
5353 * @param var_id The variable index.
5354 * @return Whether the variable is constrained to a specified value.
5355 */
5356FLECS_API
5358 ecs_iter_t *it,
5359 int32_t var_id);
5360
5361#endif // FLECS_QUERY_PLANS
5362
5363#ifdef FLECS_CACHED_QUERIES
5364
5365/** Return the group ID for the currently iterated result.
5366 * This operation returns the group ID for queries that use group_by. If this
5367 * operation is called on an iterator that is not iterating a query that uses
5368 * group_by, it will fail.
5369 *
5370 * For queries that use cascade, this operation will return the hierarchy depth
5371 * of the currently iterated result.
5372 *
5373 * @param it The iterator.
5374 * @return The group ID of the currently iterated result.
5375 */
5376FLECS_API
5378 const ecs_iter_t *it);
5379
5380/** Return whether the current iterator result has changed.
5381 * This operation must be used in combination with a query that supports change
5382 * detection (e.g., is cached). The operation returns whether the currently
5383 * iterated result has changed since the last time it was iterated by the query.
5384 *
5385 * Change detection works on a per-table basis. Changes to individual entities
5386 * cannot be detected this way.
5387 *
5388 * @param it The iterator.
5389 * @return True if the result changed, false if it didn't.
5390 */
5391FLECS_API
5393 ecs_iter_t *it);
5394#endif
5395
5396/** Create a paged iterator.
5397 * Paged iterators limit the results to those starting from 'offset', and will
5398 * return at most 'limit' results.
5399 *
5400 * The iterator must be iterated with ecs_page_next().
5401 *
5402 * A paged iterator acts as a passthrough for data exposed by the parent
5403 * iterator, so that any data provided by the parent will also be provided by
5404 * the paged iterator.
5405 *
5406 * @param it The source iterator.
5407 * @param offset The number of entities to skip.
5408 * @param limit The maximum number of entities to iterate.
5409 * @return A page iterator.
5410 */
5411FLECS_API
5413 const ecs_iter_t *it,
5414 int32_t offset,
5415 int32_t limit);
5416
5417/** Progress a paged iterator.
5418 * Progress an iterator created by ecs_page_iter().
5419 *
5420 * @param it The iterator.
5421 * @return True if the iterator has more results, false if not.
5422 */
5423FLECS_API
5425 ecs_iter_t *it);
5426
5427/** Create a worker iterator.
5428 * Worker iterators can be used to equally divide the number of matched entities
5429 * across N resources (usually threads). Each resource will process the total
5430 * number of matched entities divided by 'count'.
5431 *
5432 * Entities are distributed across resources such that the distribution is
5433 * stable between queries. Two queries that match the same table are guaranteed
5434 * to match the same entities in that table.
5435 *
5436 * The iterator must be iterated with ecs_worker_next().
5437 *
5438 * A worker iterator acts as a passthrough for data exposed by the parent
5439 * iterator, so that any data provided by the parent will also be provided by
5440 * the worker iterator.
5441 *
5442 * @param it The source iterator.
5443 * @param index The index of the current resource.
5444 * @param count The total number of resources to divide entities between.
5445 * @return A worker iterator.
5446 */
5447FLECS_API
5449 const ecs_iter_t *it,
5450 int32_t index,
5451 int32_t count);
5452
5453/** Progress a worker iterator.
5454 * Progress an iterator created by ecs_worker_iter().
5455 *
5456 * @param it The iterator.
5457 * @return True if the iterator has more results, false if not.
5458 */
5459FLECS_API
5461 ecs_iter_t *it);
5462
5463/** Get data for a field.
5464 * This operation retrieves a pointer to an array of data that belongs to the
5465 * term in the query. The index refers to the location of the term in the query,
5466 * and starts counting from zero.
5467 *
5468 * For example, the query `"Position, Velocity"` will return the `Position` array
5469 * for index 0, and the `Velocity` array for index 1.
5470 *
5471 * When the specified field is not owned by the entity, this function returns a
5472 * pointer instead of an array. This happens when the source of a field is not
5473 * the entity being iterated, such as a shared component (from a prefab), a
5474 * component from a parent, or another entity. The ecs_field_is_self() operation
5475 * can be used to test dynamically if a field is owned.
5476 *
5477 * When a field contains a sparse component, use the ecs_field_at() function. When
5478 * a field is guaranteed to be set and owned, the ecs_field_self() function can be
5479 * used. ecs_field_self() has slightly better performance, and provides stricter
5480 * validity checking.
5481 *
5482 * The provided size must be either 0 or must match the size of the type
5483 * of the returned array. If the size does not match, the operation may assert.
5484 * The size can be dynamically obtained with ecs_field_size().
5485 *
5486 * An example:
5487 *
5488 * @code
5489 * while (ecs_query_next(&it)) {
5490 * Position *p = ecs_field(&it, Position, 0);
5491 * Velocity *v = ecs_field(&it, Velocity, 1);
5492 * for (int32_t i = 0; i < it.count; i ++) {
5493 * p[i].x += v[i].x;
5494 * p[i].y += v[i].y;
5495 * }
5496 * }
5497 * @endcode
5498 *
5499 * @param it The iterator.
5500 * @param size The size of the field type.
5501 * @param index The index of the field.
5502 * @return A pointer to the data of the field.
5503 */
5504FLECS_API
5506 const ecs_iter_t *it,
5507 size_t size,
5508 int8_t index);
5509
5510/** Get data for a field matched through component inheritance.
5511 * This operation is like ecs_field_w_size(), but is used when a field is
5512 * matched on a component that is derived from the queried (base) type. Because
5513 * the stored (derived) component can be larger than the requested (base) type,
5514 * the returned pointer must be iterated with the stride returned by
5515 * ecs_field_stride().
5516 *
5517 * @param it The iterator.
5518 * @param size The size of the field type.
5519 * @param index The index of the field.
5520 * @return A pointer to the data of the field.
5521 */
5522FLECS_API
5524 const ecs_iter_t *it,
5525 size_t size,
5526 int8_t index);
5527
5528/** Get data for a field at a specified row.
5529 * This operation should be used instead of ecs_field_w_size() for sparse
5530 * component fields. This operation should be called for each returned row in a
5531 * result. In the following example, the Velocity component is sparse:
5532 *
5533 * @code
5534 * while (ecs_query_next(&it)) {
5535 * Position *p = ecs_field(&it, Position, 0);
5536 * for (int32_t i = 0; i < it.count; i ++) {
5537 * Velocity *v = ecs_field_at(&it, Velocity, 1, i);
5538 * p[i].x += v->x;
5539 * p[i].y += v->y;
5540 * }
5541 * }
5542 * @endcode
5543 *
5544 * @param it The iterator.
5545 * @param size The size of the field type.
5546 * @param index The index of the field.
5547 * @param row The row to get data for.
5548 * @return A pointer to the data of the field.
5549 */
5550FLECS_API
5552 const ecs_iter_t *it,
5553 size_t size,
5554 int8_t index,
5555 int32_t row);
5556
5557/** Test whether the field is read-only.
5558 * This operation returns whether the field is read-only. Read-only fields are
5559 * annotated with [in], or are added as a const type in the C++ API.
5560 *
5561 * @param it The iterator.
5562 * @param index The index of the field in the iterator.
5563 * @return Whether the field is read-only.
5564 */
5565FLECS_API
5567 const ecs_iter_t *it,
5568 int8_t index);
5569
5570/** Test whether the field is write-only.
5571 * This operation returns whether this is a write-only field. Write-only terms are
5572 * annotated with [out].
5573 *
5574 * Serializers are not required to serialize the values of a write-only field.
5575 *
5576 * @param it The iterator.
5577 * @param index The index of the field in the iterator.
5578 * @return Whether the field is write-only.
5579 */
5580FLECS_API
5582 const ecs_iter_t *it,
5583 int8_t index);
5584
5585/** Test whether a field is set.
5586 *
5587 * @param it The iterator.
5588 * @param index The index of the field in the iterator.
5589 * @return Whether the field is set.
5590 */
5591FLECS_API
5593 const ecs_iter_t *it,
5594 int8_t index);
5595
5596/** Return the ID matched for a field.
5597 *
5598 * @param it The iterator.
5599 * @param index The index of the field in the iterator.
5600 * @return The ID matched for the field.
5601 */
5602FLECS_API
5604 const ecs_iter_t *it,
5605 int8_t index);
5606
5607/** Return the index of a matched table column.
5608 * This function only returns column indices for fields that have been matched
5609 * on the $this variable. Fields matched on other tables will return -1.
5610 *
5611 * @param it The iterator.
5612 * @param index The index of the field in the iterator.
5613 * @return The index of the matched column, -1 if not matched.
5614 */
5615FLECS_API
5617 const ecs_iter_t *it,
5618 int8_t index);
5619
5620/** Return the field source.
5621 * The field source is the entity on which the field was matched.
5622 *
5623 * @param it The iterator.
5624 * @param index The index of the field in the iterator.
5625 * @return The source for the field.
5626 */
5627FLECS_API
5629 const ecs_iter_t *it,
5630 int8_t index);
5631
5632/** Return the field type size.
5633 * Returns the type size of the field. Returns 0 if the field has no data.
5634 *
5635 * @param it The iterator.
5636 * @param index The index of the field in the iterator.
5637 * @return The type size for the field.
5638 */
5639FLECS_API
5641 const ecs_iter_t *it,
5642 int8_t index);
5643
5644/** Return the field storage stride.
5645 * Like ecs_field_size(), but for a field matched through component inheritance
5646 * returns the size of the stored (derived) component.
5647 *
5648 * @param it The iterator.
5649 * @param index The index of the field in the iterator.
5650 * @return The storage stride for the field.
5651 */
5652FLECS_API
5654 const ecs_iter_t *it,
5655 int8_t index);
5656
5657/** Test whether the field is matched on self.
5658 * This operation returns whether the field is matched on the currently iterated
5659 * entity. This function will return false when the field is owned by another
5660 * entity, such as a parent or a prefab.
5661 *
5662 * When this operation returns false, the field must be accessed as a single
5663 * value instead of an array. Fields for which this operation returns true
5664 * return arrays with it->count values.
5665 *
5666 * @param it The iterator.
5667 * @param index The index of the field in the iterator.
5668 * @return Whether the field is matched on self.
5669 */
5670FLECS_API
5672 const ecs_iter_t *it,
5673 int8_t index);
5674
5675/** @} */
5676
5677/**
5678 * @defgroup tables Tables
5679 * Functions for working with `ecs_table_t`.
5680 *
5681 * @{
5682 */
5683
5684/** Get the type for a table.
5685 * The table type is a vector that contains all component, tag, and pair IDs.
5686 *
5687 * @param table The table.
5688 * @return The type of the table.
5689 */
5690FLECS_API
5692 const ecs_table_t *table);
5693
5694/** Get the type index for a component.
5695 * This operation returns the index for a component in the table's type.
5696 *
5697 * @param world The world.
5698 * @param table The table.
5699 * @param component The component.
5700 * @return The index of the component in the table type, or -1 if not found.
5701 *
5702 * @see ecs_table_has_id()
5703 */
5704FLECS_API
5706 const ecs_world_t *world,
5707 const ecs_table_t *table,
5708 ecs_id_t component);
5709
5710/** Get the column index for a component.
5711 * This operation returns the column index for a component in the table's type.
5712 * If the component doesn't have data (it is a tag), the function will return -1.
5713 *
5714 * @param world The world.
5715 * @param table The table.
5716 * @param component The component.
5717 * @return The column index of the component ID, or -1 if not found or not a component.
5718 */
5719FLECS_API
5721 const ecs_world_t *world,
5722 const ecs_table_t *table,
5723 ecs_id_t component);
5724
5725/** Return the number of columns in a table.
5726 * Similar to `ecs_table_get_type(table)->count`, except that the column count
5727 * only counts the number of components in a table.
5728 *
5729 * @param table The table.
5730 * @return The number of columns in the table.
5731 */
5732FLECS_API
5734 const ecs_table_t *table);
5735
5736/** Convert a type index to a column index.
5737 * Tables have an array of columns for each component in the table. This array
5738 * does not include elements for tags, which means that the index for a
5739 * component in the table type is not necessarily the same as the index in the
5740 * column array. This operation converts from an index in the table type to an
5741 * index in the column array.
5742 *
5743 * @param table The table.
5744 * @param index The index in the table type.
5745 * @return The index in the table column array.
5746 *
5747 * @see ecs_table_column_to_type_index()
5748 */
5749FLECS_API
5751 const ecs_table_t *table,
5752 int32_t index);
5753
5754/** Convert a column index to a type index.
5755 * Same as ecs_table_type_to_column_index(), but converts from an index in the
5756 * column array to an index in the table type.
5757 *
5758 * @param table The table.
5759 * @param index The column index.
5760 * @return The index in the table type.
5761 */
5762FLECS_API
5764 const ecs_table_t *table,
5765 int32_t index);
5766
5767/** Get a column from a table by column index.
5768 * This operation returns the component array for the provided index.
5769 *
5770 * @param table The table.
5771 * @param index The column index.
5772 * @param offset The index of the first row to return (0 for entire column).
5773 * @return The component array, or NULL if the index is not a component.
5774 */
5775FLECS_API
5777 const ecs_table_t *table,
5778 int32_t index,
5779 int32_t offset);
5780
5781/** Get a column from a table by component.
5782 * This operation returns the component array for the provided component.
5783 *
5784 * @param world The world.
5785 * @param table The table.
5786 * @param component The component for the column.
5787 * @param offset The index of the first row to return (0 for entire column).
5788 * @return The component array, or NULL if the component is not found.
5789 */
5790FLECS_API
5792 const ecs_world_t *world,
5793 const ecs_table_t *table,
5794 ecs_id_t component,
5795 int32_t offset);
5796
5797/** Get the column size from a table.
5798 * This operation returns the component size for the provided index.
5799 *
5800 * @param table The table.
5801 * @param index The column index.
5802 * @return The component size, or 0 if the index is not a component.
5803 */
5804FLECS_API
5806 const ecs_table_t *table,
5807 int32_t index);
5808
5809/** Return the number of entities in the table.
5810 * This operation returns the number of entities in the table.
5811 *
5812 * @param table The table.
5813 * @return The number of entities in the table.
5814 */
5815FLECS_API
5817 const ecs_table_t *table);
5818
5819/** Return the allocated size of the table.
5820 * This operation returns the number of elements allocated in the table
5821 * per column.
5822 *
5823 * @param table The table.
5824 * @return The number of allocated elements in the table.
5825 */
5826FLECS_API
5828 const ecs_table_t *table);
5829
5830/** Return the array with entity IDs for the table.
5831 * The size of the returned array is the result of ecs_table_count().
5832 *
5833 * @param table The table.
5834 * @return The array with entity IDs for the table.
5835 */
5836FLECS_API
5838 const ecs_table_t *table);
5839
5840/** Test if a table has a component.
5841 * Same as `ecs_table_get_type_index(world, table, component) != -1`.
5842 *
5843 * @param world The world.
5844 * @param table The table.
5845 * @param component The component.
5846 * @return True if the table has the component ID, false if the table doesn't.
5847 *
5848 * @see ecs_table_get_type_index()
5849 */
5850FLECS_API
5852 const ecs_world_t *world,
5853 const ecs_table_t *table,
5854 ecs_id_t component);
5855
5856/** Get the relationship target for a table.
5857 *
5858 * @param world The world.
5859 * @param table The table.
5860 * @param relationship The relationship for which to obtain the target.
5861 * @param index The index, in case the table has multiple instances of the relationship.
5862 * @return The requested relationship target.
5863 *
5864 * @see ecs_get_target()
5865 */
5866FLECS_API
5868 const ecs_world_t *world,
5869 const ecs_table_t *table,
5870 ecs_entity_t relationship,
5871 int32_t index);
5872
5873/** Return the depth for a table in the tree for the specified relationship.
5874 * Depth is determined by counting the number of targets encountered while
5875 * traversing up the relationship tree. Only acyclic relationships are
5876 * supported.
5877 *
5878 * @param world The world.
5879 * @param table The table.
5880 * @param rel The relationship.
5881 * @return The depth of the table in the tree.
5882 */
5883FLECS_API
5885 const ecs_world_t *world,
5886 const ecs_table_t *table,
5887 ecs_entity_t rel);
5888
5889/** Get the table that has all components of the current table plus the specified ID.
5890 * If the provided table already has the provided ID, the operation will return
5891 * the provided table.
5892 *
5893 * @param world The world.
5894 * @param table The table.
5895 * @param component The component to add.
5896 * @return The resulting table.
5897 */
5898FLECS_API
5900 ecs_world_t *world,
5901 ecs_table_t *table,
5902 ecs_id_t component);
5903
5904/** Find a table from an ID array.
5905 * This operation finds or creates a table with the specified array of
5906 * (component) IDs. The IDs in the array must be sorted, and it may not contain
5907 * duplicate elements.
5908 *
5909 * @param world The world.
5910 * @param ids The ID array.
5911 * @param id_count The number of elements in the ID array.
5912 * @return The table with the specified (component) IDs.
5913 */
5914FLECS_API
5916 ecs_world_t *world,
5917 const ecs_id_t *ids,
5918 int32_t id_count);
5919
5920/** Get the table that has all components of the current table minus the specified component.
5921 * If the provided table doesn't have the provided component, the operation will
5922 * return the provided table.
5923 *
5924 * @param world The world.
5925 * @param table The table.
5926 * @param component The component to remove.
5927 * @return The resulting table.
5928 */
5929FLECS_API
5931 ecs_world_t *world,
5932 ecs_table_t *table,
5933 ecs_id_t component);
5934
5935/** Lock a table.
5936 * When a table is locked, modifications to it will throw an assert. When the
5937 * table is locked recursively, it will take an equal amount of unlock
5938 * operations to actually unlock the table.
5939 *
5940 * Table locks can be used to build safe iterators where it is guaranteed that
5941 * the contents of a table are not modified while it is being iterated.
5942 *
5943 * The operation only works when called on the world, and has no side effects
5944 * when called on a stage. The assumption is that when called on a stage,
5945 * operations are deferred already.
5946 *
5947 * @param world The world.
5948 * @param table The table to lock.
5949 */
5950FLECS_API
5952 ecs_world_t *world,
5953 ecs_table_t *table);
5954
5955/** Unlock a table.
5956 * Must be called after calling ecs_table_lock().
5957 *
5958 * @param world The world.
5959 * @param table The table to unlock.
5960 */
5961FLECS_API
5963 ecs_world_t *world,
5964 ecs_table_t *table);
5965
5966/** Check if a table is locked.
5967 * Can be used to check whether an operation that modifies the table would
5968 * run into a table lock assert.
5969 *
5970 * @param table The table.
5971 * @return True if the table is locked, false if not (or if table is NULL).
5972 */
5973FLECS_API
5975 const ecs_table_t *table);
5976
5977/** Test a table for flags.
5978 * Test if a table has all of the provided flags. See
5979 * include/flecs/private/api_flags.h for a list of table flags that can be used
5980 * with this function.
5981 *
5982 * @param table The table.
5983 * @param flags The flags to test for.
5984 * @return Whether the specified flags are set for the table.
5985 */
5986FLECS_API
5988 ecs_table_t *table,
5989 ecs_flags32_t flags);
5990
5991/** Check if a table has traversable entities.
5992 * Traversable entities are entities that are used as a target in a pair with a
5993 * relationship that has the Traversable trait.
5994 *
5995 * @param table The table.
5996 * @return Whether the table has traversable entities.
5997 */
5998FLECS_API
6000 const ecs_table_t *table);
6001
6002/** Swap two elements inside the table.
6003 * This is useful for implementing custom
6004 * table sorting algorithms.
6005 *
6006 * @param world The world.
6007 * @param table The table to swap elements in.
6008 * @param row_1 The table element to swap with row_2.
6009 * @param row_2 The table element to swap with row_1.
6010 */
6011FLECS_API
6013 ecs_world_t* world,
6014 ecs_table_t* table,
6015 int32_t row_1,
6016 int32_t row_2);
6017
6018/** Search for a component in a table type.
6019 * This operation returns the index of the first occurrence of the component in the
6020 * table type. The component may be a pair or a wildcard.
6021 *
6022 * When component_out is provided, the function will assign it with the found
6023 * component. The found component may be different from the provided component
6024 * if it is a wildcard.
6025 *
6026 * This is a constant-time operation.
6027 *
6028 * @param world The world.
6029 * @param table The table.
6030 * @param component The component to search for.
6031 * @param component_out If provided, it will be set to the found component (optional).
6032 * @return The index of the ID in the table type.
6033 *
6034 * @see ecs_search_offset()
6035 * @see ecs_search_relation()
6036 */
6037FLECS_API
6039 const ecs_world_t *world,
6040 const ecs_table_t *table,
6041 ecs_id_t component,
6042 ecs_id_t *component_out);
6043
6044/** Search for a component in a table type starting from an offset.
6045 * This operation is the same as ecs_search(), but starts searching from an offset
6046 * in the table type.
6047 *
6048 * This operation is typically called in a loop where the resulting index is
6049 * used in the next iteration as offset:
6050 *
6051 * @code
6052 * int32_t index = -1;
6053 * while ((index = ecs_search_offset(world, table, index + 1, id, NULL)) != -1) {
6054 * // do stuff
6055 * }
6056 * @endcode
6057 *
6058 * Depending on how the operation is used, it is either linear or constant time.
6059 * When the ID has the form `(id)` or `(rel, *)` and the operation is invoked as
6060 * in the above example, it is guaranteed to be constant time.
6061 *
6062 * If the provided component has the form `(*, tgt)`, the operation takes linear
6063 * time. The reason for this is that IDs for a target are not packed together,
6064 * as they are sorted relationship-first.
6065 *
6066 * If the component at the offset does not match the provided ID, the operation
6067 * will do a linear search to find a matching ID.
6068 *
6069 * @param world The world.
6070 * @param table The table.
6071 * @param offset The offset from where to start searching.
6072 * @param component The component to search for.
6073 * @param component_out If provided, it will be set to the found component (optional).
6074 * @return The index of the ID in the table type.
6075 *
6076 * @see ecs_search()
6077 * @see ecs_search_relation()
6078 */
6079FLECS_API
6081 const ecs_world_t *world,
6082 const ecs_table_t *table,
6083 int32_t offset,
6084 ecs_id_t component,
6085 ecs_id_t *component_out);
6086
6087/** Search for a component or relationship ID in a table type starting from an offset.
6088 * This operation is the same as ecs_search_offset(), but has the additional
6089 * capability of traversing relationships to find a component. For example, if
6090 * an application wants to find a component for either the provided table or a
6091 * prefab (using the `IsA` relationship) of that table, it could use the operation
6092 * like this:
6093 *
6094 * @code
6095 * int32_t index = ecs_search_relation(
6096 * world, // the world
6097 * table, // the table
6098 * 0, // offset 0
6099 * ecs_id(Position), // the component ID
6100 * EcsIsA, // the relationship to traverse
6101 * EcsSelf|EcsUp, // search self and up
6102 * NULL, // (optional) entity on which component was found
6103 * NULL, // (optional) found component ID
6104 * NULL); // internal type with information about matched ID
6105 * @endcode
6106 *
6107 * The operation searches depth-first. If a table type has 2 `IsA` relationships, the
6108 * operation will first search the `IsA` tree of the first relationship.
6109 *
6110 * When choosing between ecs_search(), ecs_search_offset(), and ecs_search_relation(),
6111 * the simpler the function, the better its performance.
6112 *
6113 * @param world The world.
6114 * @param table The table.
6115 * @param offset The offset from where to start searching.
6116 * @param component The component to search for.
6117 * @param rel The relationship to traverse (optional).
6118 * @param flags Whether to search EcsSelf and/or EcsUp.
6119 * @param tgt_out If provided, it will be set to the matched entity.
6120 * @param component_out If provided, it will be set to the found component (optional).
6121 * @param tr_out The internal datatype.
6122 * @return The index of the component in the table type.
6123 *
6124 * @see ecs_search()
6125 * @see ecs_search_offset()
6126 */
6127FLECS_API
6129 const ecs_world_t *world,
6130 const ecs_table_t *table,
6131 int32_t offset,
6132 ecs_id_t component,
6133 ecs_entity_t rel,
6134 ecs_flags64_t flags, /* EcsSelf and/or EcsUp */
6135 ecs_entity_t *tgt_out,
6136 ecs_id_t *component_out,
6137 struct ecs_table_record_t **tr_out);
6138
6139/** Search for a component ID by following a relationship, starting from an entity.
6140 * This operation is the same as ecs_search_relation(), but starts the search
6141 * from an entity rather than a table.
6142 *
6143 * @param world The world.
6144 * @param entity The entity from which to begin the search.
6145 * @param id The component ID to search for.
6146 * @param rel The relationship to follow.
6147 * @param self If true, also search components on the entity itself.
6148 * @param cr Optional component record for the component ID.
6149 * @param tgt_out Out parameter for the target entity.
6150 * @param id_out Out parameter for the found component ID.
6151 * @param tr_out Out parameter for the table record.
6152 * @return The index of the component ID in the entity's type, or -1 if not found.
6153 */
6154FLECS_API
6156 const ecs_world_t *world,
6157 ecs_entity_t entity,
6158 ecs_id_t id,
6159 ecs_entity_t rel,
6160 bool self,
6162 ecs_entity_t *tgt_out,
6163 ecs_id_t *id_out,
6164 struct ecs_table_record_t **tr_out);
6165
6166/** Delete all entities in a table. The entities are deleted as with
6167 * ecs_delete(), which cleans up relationships and children that refer to them.
6168 * Does not deallocate table memory, unless the cleanup deletes the table (for
6169 * example when the table has a pair with one of its own entities as target).
6170 * Retaining table memory can be efficient when planning to refill the table
6171 * with operations like ecs_bulk_init().
6172 *
6173 * @param world The world.
6174 * @param table The table to clear.
6175 */
6176FLECS_API
6178 ecs_world_t* world,
6179 ecs_table_t* table);
6180
6181/** @} */
6182
6183/** @} */
6184
6185/**
6186 * @defgroup c_addons Addons
6187 * @ingroup c
6188 * C APIs for addons.
6189 *
6190 * @{
6191 * @}
6192 */
6193
6194#include "flecs/addons/flecs_c.h"
6195
6196#ifdef __cplusplus
6197}
6198#endif
6199
6200#include "flecs/private/addons.h"
6201
6202#if defined(ECS_TARGET_CLANG)
6203#pragma clang diagnostic pop
6204#elif defined(ECS_TARGET_GNU)
6205#pragma GCC diagnostic pop
6206#elif defined(ECS_TARGET_MSVC)
6207#pragma warning(pop)
6208#endif
6209
6210#endif
The deprecated addon contains deprecated operations.
Extends the core API with convenience macros for C applications.
void ecs_remove_id(ecs_world_t *world, ecs_entity_t entity, ecs_id_t component)
Remove a component from an entity.
void ecs_auto_override_id(ecs_world_t *world, ecs_entity_t entity, ecs_id_t component)
Add an auto override for a component.
void ecs_remove_all(ecs_world_t *world, ecs_id_t component)
Remove all instances of the specified component.
void ecs_clear(ecs_world_t *world, ecs_entity_t entity)
Clear all components.
void ecs_add_id(ecs_world_t *world, ecs_entity_t entity, ecs_id_t component)
Add a (component) ID to an entity.
const ecs_entity_t EcsScopeClose
Marker used to indicate the end of a scope (}) in queries.
const ecs_entity_t EcsOnRemove
Event that triggers when an ID is removed from an entity.
const ecs_entity_t EcsThis
This entity.
const ecs_entity_t EcsWildcard
Wildcard entity ("*").
const ecs_entity_t EcsName
Tag to indicate name identifier.
const ecs_entity_t EcsAlias
Tag to indicate alias identifier.
const ecs_entity_t EcsOnSet
Event that triggers when a component is set for an entity.
const ecs_entity_t EcsReflexive
Mark a relationship as reflexive.
const ecs_entity_t EcsEmpty
Tag used to indicate a query is empty.
const ecs_entity_t EcsOnTableDelete
Event that triggers when a table is deleted.
const ecs_entity_t EcsOnTableCreate
Event that triggers when a table is created.
const ecs_entity_t EcsObserver
Tag added to observers.
const ecs_entity_t EcsQuery
Tag added to queries.
const ecs_entity_t EcsOnStart
OnStart pipeline phase.
const ecs_entity_t EcsNotQueryable
Trait added to entities that should never be returned by queries.
const ecs_entity_t EcsOnStore
OnStore pipeline phase.
const ecs_entity_t EcsOrderedChildren
Tag that, when added to a parent, ensures stable order of ecs_children() results.
const ecs_entity_t EcsDontFragment
Mark component as non-fragmenting.
const ecs_entity_t EcsTraversable
Mark a relationship as traversable.
const ecs_entity_t EcsPredLookup
Marker used to indicate $var ~= "pattern" matching in queries.
const ecs_entity_t EcsPreStore
PreStore pipeline phase.
const ecs_entity_t EcsOnLoad
OnLoad pipeline phase.
const ecs_entity_t EcsIsA
Used to express inheritance relationships.
const ecs_entity_t EcsExclusive
Can be added to a relationship to indicate that the relationship can only occur once on an entity.
const ecs_entity_t EcsSymbol
Tag to indicate symbol identifier.
const ecs_entity_t EcsDependsOn
Used to express dependency relationships.
const ecs_entity_t EcsTransitive
Mark a relationship as transitive.
const ecs_entity_t EcsDelete
Delete cleanup policy.
const ecs_entity_t EcsChildOf
Used to express parent-child relationships.
const ecs_entity_t EcsFlecsCore
Core module scope.
const ecs_entity_t EcsMonitor
Event that triggers an observer when an entity starts or stops matching a query.
const ecs_entity_t EcsCanToggle
Mark a component as toggleable with ecs_enable_id().
const ecs_entity_t EcsPredEq
Marker used to indicate $var == ... matching in queries.
const ecs_entity_t EcsOnInstantiateChildren
Relationship that specifies how children of a prefab are instantiated.
const ecs_entity_t EcsPhase
Phase pipeline phase.
const ecs_entity_t EcsWorld
Entity associated with world (used for "attaching" components to world).
const ecs_entity_t EcsScopeOpen
Marker used to indicate the start of a scope ({) in queries.
const ecs_entity_t EcsPostUpdate
PostUpdate pipeline phase.
const ecs_entity_t EcsOnValidate
OnValidate pipeline phase.
const ecs_entity_t EcsRemove
Remove cleanup policy.
const ecs_entity_t EcsCopy
Copy component on instantiate.
const ecs_entity_t EcsPredMatch
Marker used to indicate $var == "name" matching in queries.
const ecs_entity_t EcsInherit
Inherit component on instantiate.
const ecs_entity_t EcsModule
Tag added to module entities.
const ecs_entity_t EcsSparse
Mark component as sparse.
const ecs_entity_t EcsPreUpdate
PreUpdate pipeline phase.
const ecs_entity_t EcsOnAdd
Event that triggers when an ID is added to an entity.
const ecs_entity_t EcsPrefab
Tag added to prefab entities.
const ecs_entity_t EcsOnInstantiate
Relationship that specifies component inheritance behavior.
const ecs_entity_t EcsPostFrame
PostFrame pipeline phase.
const ecs_entity_t EcsInheritable
Mark component as inheritable.
const ecs_entity_t EcsAny
Any entity ("_").
const ecs_entity_t EcsParentDepth
Relationship storing the entity's depth in a non-fragmenting hierarchy.
const ecs_entity_t EcsWith
Ensure that a component is always added together with another component.
const ecs_entity_t EcsPostLoad
PostLoad pipeline phase.
const ecs_entity_t EcsOnDelete
Relationship used for specifying cleanup behavior.
const ecs_entity_t EcsOnDeleteTarget
Relationship used to define what should happen when a target entity (second element of a pair) is del...
const ecs_entity_t EcsPreFrame
PreFrame pipeline phase.
const ecs_entity_t EcsFlecs
Root scope for built-in Flecs entities.
const ecs_entity_t EcsSystem
Tag added to systems.
const ecs_entity_t EcsOnUpdate
OnUpdate pipeline phase.
const ecs_entity_t EcsDisabled
When this tag is added to an entity, it is skipped by queries, unless EcsDisabled is explicitly queri...
const ecs_entity_t EcsDontInherit
Never inherit component on instantiate.
const ecs_entity_t EcsPairIsTag
Can be added to a relationship to indicate that it should never hold data, even when it or the relati...
const ecs_entity_t EcsPanic
Panic cleanup policy.
const ecs_entity_t EcsVariable
Variable entity ("$").
const ecs_entity_t EcsConstant
Tag added to enum or bitmask constants.
FLECS_API const ecs_entity_t ecs_id(EcsDocDescription)
Component ID for EcsDocDescription.
ecs_world_t * ecs_stage_new(ecs_world_t *world)
Create an unmanaged stage.
bool ecs_readonly_begin(ecs_world_t *world, bool multi_threaded)
Begin readonly mode.
void ecs_stage_free(ecs_world_t *stage)
Free an unmanaged stage.
bool ecs_is_stage(const ecs_world_t *world)
Test whether a world object is a stage.
void ecs_merge(ecs_world_t *stage)
Merge a stage.
int32_t ecs_stage_get_id(const ecs_world_t *world)
Get the stage ID.
bool ecs_stage_is_readonly(const ecs_world_t *world)
Test whether the current world is readonly.
int32_t ecs_get_stage_count(const ecs_world_t *world)
Get the number of configured stages.
ecs_world_t * ecs_get_stage(const ecs_world_t *world, int32_t stage_id)
Get stage-specific world pointer.
void ecs_set_stage_count(ecs_world_t *world, int32_t stages)
Configure the world to have N stages.
void ecs_readonly_end(ecs_world_t *world)
End readonly mode.
const ecs_type_hooks_t * ecs_get_hooks_id(const ecs_world_t *world, ecs_entity_t component)
Get hooks for a component.
ecs_entity_t ecs_component_init(ecs_world_t *world, const ecs_component_desc_t *desc)
Find or create a component.
const ecs_type_info_t * ecs_get_type_info(const ecs_world_t *world, ecs_id_t component)
Get the type info for a component.
void ecs_set_hooks_id(ecs_world_t *world, ecs_entity_t component, const ecs_type_hooks_t *hooks)
Register hooks for a component.
struct ecs_component_record_t ecs_component_record_t
Information about a (component) ID, such as type info and tables with the ID.
Definition flecs.h:508
struct ecs_stage_t ecs_stage_t
A stage enables modification while iterating and from multiple threads.
Definition flecs.h:443
struct ecs_ref_t ecs_ref_t
A ref is a fast way to fetch a component for a specific entity.
Definition flecs.h:492
ecs_id_t ecs_entity_t
An entity identifier.
Definition flecs.h:396
struct ecs_table_record_t ecs_table_record_t
Opaque type for table record.
Definition flecs.h:542
struct ecs_world_t ecs_world_t
A world is the container for all ECS data and supporting features.
Definition flecs.h:440
struct ecs_mixins_t ecs_mixins_t
Type that stores poly mixins.
Definition flecs.h:532
uint64_t ecs_id_t
IDs are the things that can be added to an entity.
Definition flecs.h:389
struct ecs_observable_t ecs_observable_t
An observable produces events that can be listened for by an observer.
Definition flecs.h:476
struct ecs_record_t ecs_record_t
Information about an entity, like its table and row.
Definition flecs.h:505
struct ecs_table_t ecs_table_t
A table stores entities and components for a specific type.
Definition flecs.h:446
void ecs_poly_t
A poly object.
Definition flecs.h:529
ecs_entity_t ecs_new_low_id(ecs_world_t *world)
Create new low ID.
void ecs_set_child_order(ecs_world_t *world, ecs_entity_t parent, const ecs_entity_t *children, int32_t child_count)
Set child order for parent with OrderedChildren.
const ecs_entity_t * ecs_bulk_init(ecs_world_t *world, const ecs_bulk_desc_t *desc)
Bulk create or populate new entities.
ecs_entity_t ecs_insert_w_values(ecs_world_t *world, const ecs_value_t *values)
Create a new entity with a list of component values.
ecs_entity_t ecs_clone(ecs_world_t *world, ecs_entity_t dst, ecs_entity_t src, bool copy_value)
Clone an entity.
ecs_entity_t ecs_new(ecs_world_t *world)
Create new entity ID.
ecs_entity_t ecs_entity_init(ecs_world_t *world, const ecs_entity_desc_t *desc)
Find or create an entity.
void ecs_delete(ecs_world_t *world, ecs_entity_t entity)
Delete an entity.
void ecs_delete_with(ecs_world_t *world, ecs_id_t component)
Delete all entities with the specified component.
ecs_entity_t ecs_new_w_id(ecs_world_t *world, ecs_id_t component)
Create new entity with (component) ID.
ecs_entity_t ecs_new_w_table(ecs_world_t *world, ecs_table_t *table)
Create new entity in table.
const ecs_entity_t * ecs_bulk_new_w_id(ecs_world_t *world, ecs_id_t component, int32_t count)
Create N new entities.
ecs_entities_t ecs_get_ordered_children(const ecs_world_t *world, ecs_entity_t parent)
Get ordered children.
bool ecs_children_next(ecs_iter_t *it)
Progress an iterator created with ecs_children().
ecs_iter_t ecs_each_id(const ecs_world_t *world, ecs_id_t component)
Iterate all entities with a specified (component ID).
bool ecs_each_next(ecs_iter_t *it)
Progress an iterator created with ecs_each_id().
ecs_iter_t ecs_children(const ecs_world_t *world, ecs_entity_t parent)
Iterate children of a parent.
ecs_iter_t ecs_children_w_rel(const ecs_world_t *world, ecs_entity_t relationship, ecs_entity_t parent)
Same as ecs_children(), but with a custom relationship argument.
void ecs_enable_id(ecs_world_t *world, ecs_entity_t entity, ecs_id_t component, bool enable)
Enable or disable a component.
bool ecs_is_enabled_id(const ecs_world_t *world, ecs_entity_t entity, ecs_id_t component)
Test if a component is enabled.
void ecs_enable(ecs_world_t *world, ecs_entity_t entity, bool enabled)
Enable or disable an entity.
char * ecs_entity_str(const ecs_world_t *world, ecs_entity_t entity)
Convert an entity to a string.
ecs_entity_t ecs_get_target(const ecs_world_t *world, ecs_entity_t entity, ecs_entity_t rel, int32_t index)
Get the target of a relationship.
ecs_entity_t ecs_get_parent(const ecs_world_t *world, ecs_entity_t entity)
Get the parent (target of the ChildOf relationship) for an entity.
ecs_entity_t ecs_get_target_for_id(const ecs_world_t *world, ecs_entity_t entity, ecs_entity_t rel, ecs_id_t component)
Get the target of a relationship for a given component.
const ecs_type_t * ecs_get_type(const ecs_world_t *world, ecs_entity_t entity)
Get the type of an entity.
bool ecs_owns_id(const ecs_world_t *world, ecs_entity_t entity, ecs_id_t component)
Test if an entity owns a component.
char * ecs_type_str(const ecs_world_t *world, const ecs_type_t *type)
Convert a type to a string.
char * ecs_table_str(const ecs_world_t *world, const ecs_table_t *table)
Convert a table to a string.
int32_t ecs_count_id(const ecs_world_t *world, ecs_id_t entity)
Count entities that have the specified ID.
int32_t ecs_get_depth(const ecs_world_t *world, ecs_entity_t entity, ecs_entity_t rel)
Return the depth for an entity in the tree for the specified relationship.
ecs_table_t * ecs_get_table(const ecs_world_t *world, ecs_entity_t entity)
Get the table of an entity.
ecs_entity_t ecs_new_w_parent(ecs_world_t *world, ecs_entity_t parent, const char *name)
Create child with Parent component.
bool ecs_has_id(const ecs_world_t *world, ecs_entity_t entity, ecs_id_t component)
Test if an entity has a component.
void(*) ecs_ctx_free_t(void *ctx)
Function to clean up context data.
Definition flecs.h:661
uint64_t(*) ecs_group_by_action_t(ecs_world_t *world, ecs_table_t *table, ecs_id_t group_id, void *ctx)
Callback used for grouping tables in a query.
Definition flecs.h:632
void(*) ecs_copy_t(void *dst_ptr, const void *src_ptr, int32_t count, const ecs_type_info_t *type_info)
Copy is invoked when a component is copied into another component.
Definition flecs.h:680
void(*) ecs_xtor_t(void *ptr, int32_t count, const ecs_type_info_t *type_info)
Constructor/destructor callback.
Definition flecs.h:674
void(*) ecs_group_delete_action_t(ecs_world_t *world, uint64_t group_id, void *group_ctx, void *group_by_ctx)
Callback invoked when a query deletes an existing group.
Definition flecs.h:645
void(*) ecs_module_action_t(ecs_world_t *world)
Initialization action for modules.
Definition flecs.h:652
void(*) ecs_iter_fini_action_t(ecs_iter_t *it)
Function prototype for freeing an iterator.
Definition flecs.h:610
void(*) ecs_iter_action_t(ecs_iter_t *it)
Function prototype for iterables.
Definition flecs.h:592
void *(*) ecs_group_create_action_t(ecs_world_t *world, uint64_t group_id, void *group_by_ctx)
Callback invoked when a query creates a new group.
Definition flecs.h:639
void(*) ecs_sort_table_action_t(ecs_world_t *world, ecs_table_t *table, ecs_entity_t *entities, void *ptr, int32_t size, int32_t lo, int32_t hi, ecs_order_by_action_t order_by)
Callback used for sorting the entire table of components.
Definition flecs.h:621
uint64_t(*) ecs_hash_value_action_t(const void *ptr)
Callback used for hashing values.
Definition flecs.h:670
int(*) ecs_order_by_action_t(ecs_entity_t e1, const void *ptr1, ecs_entity_t e2, const void *ptr2)
Callback used for comparing components.
Definition flecs.h:614
void(*) ecs_run_action_t(ecs_iter_t *it)
Function prototype for runnables (systems, observers).
Definition flecs.h:583
void(*) ecs_move_t(void *dst_ptr, void *src_ptr, int32_t count, const ecs_type_info_t *type_info)
Move is invoked when a component is moved to another component.
Definition flecs.h:687
void(*) flecs_poly_dtor_t(ecs_poly_t *poly)
Destructor function for poly objects.
Definition flecs.h:714
void(*) ecs_fini_action_t(ecs_world_t *world, void *ctx)
Action callback on world exit.
Definition flecs.h:656
bool(*) ecs_equals_t(const void *a_ptr, const void *b_ptr, const ecs_type_info_t *type_info)
Equals operator hook.
Definition flecs.h:700
int(*) ecs_cmp_t(const void *a_ptr, const void *b_ptr, const ecs_type_info_t *type_info)
Compare hook to compare component instances.
Definition flecs.h:694
bool(*) ecs_iter_next_action_t(ecs_iter_t *it)
Function prototype for iterating an iterator.
Definition flecs.h:602
int(*) ecs_compare_action_t(const void *ptr1, const void *ptr2)
Callback used for sorting values.
Definition flecs.h:665
bool(*) ecs_on_validate_t(ecs_world_t *world, ecs_entity_t entity, void *ptr)
On validate hook.
Definition flecs.h:708
void * ecs_ref_get_id(const ecs_world_t *world, ecs_ref_t *ref, ecs_id_t component)
Get a component from a ref.
void ecs_ref_modified_id(ecs_world_t *world, ecs_ref_t *ref, ecs_id_t component)
Signal that the component of a ref has been modified.
void * ecs_emplace_id(ecs_world_t *world, ecs_entity_t entity, ecs_id_t component, size_t size, bool *is_new)
Emplace a component.
void ecs_ref_update(const ecs_world_t *world, ecs_ref_t *ref, ecs_id_t component)
Update a ref.
const void * ecs_get_id(const ecs_world_t *world, ecs_entity_t entity, ecs_id_t component)
Get an immutable pointer to a component.
void ecs_modified_id(ecs_world_t *world, ecs_entity_t entity, ecs_id_t component)
Signal that a component has been modified.
ecs_ref_t ecs_ref_init_id(const ecs_world_t *world, ecs_entity_t entity, ecs_id_t component)
Create a component ref.
ecs_ref_t ecs_ref_from_ptr(const ecs_world_t *world, ecs_entity_t entity, ecs_id_t component, void *ptr)
Create a component ref from an existing pointer.
void * ecs_get_mut_id(const ecs_world_t *world, ecs_entity_t entity, ecs_id_t component)
Get a mutable pointer to a component.
void * ecs_ensure_id(ecs_world_t *world, ecs_entity_t entity, ecs_id_t component, size_t size)
Ensure an entity has a component and return a pointer.
void ecs_set_id(ecs_world_t *world, ecs_entity_t entity, ecs_id_t component, size_t size, const void *ptr)
Set the value of a component.
void * ecs_get_sparse_id(const ecs_world_t *world, ecs_entity_t entity, ecs_id_t component, size_t size)
Get a pointer to a sparse component.
const ecs_id_t ECS_PAIR
Indicate that the ID is a pair.
const ecs_id_t ECS_AUTO_OVERRIDE
Automatically override component when it is inherited.
const ecs_id_t ECS_TOGGLE
Add a bitset to storage, which allows a component to be enabled or disabled.
const ecs_id_t ECS_VALUE_PAIR
Indicate that the target of a pair is an integer value.
char * ecs_id_str(const ecs_world_t *world, ecs_id_t component)
Convert a component ID to a string.
bool ecs_id_is_tag(const ecs_world_t *world, ecs_id_t component)
Return whether a specified component is a tag.
ecs_flags32_t ecs_id_get_flags(const ecs_world_t *world, ecs_id_t component)
Get flags associated with an ID.
bool ecs_id_is_valid(const ecs_world_t *world, ecs_id_t component)
Utility to check if an ID is valid.
const char * ecs_id_flag_str(uint64_t component_flags)
Convert a component flag to a string.
bool ecs_id_in_use(const ecs_world_t *world, ecs_id_t component)
Return whether a specified component is in use.
bool ecs_id_match(ecs_id_t component, ecs_id_t pattern)
Utility to match a component with a pattern.
void ecs_id_str_buf(const ecs_world_t *world, ecs_id_t component, ecs_strbuf_t *buf)
Write a component string to a buffer.
bool ecs_id_is_pair(ecs_id_t component)
Utility to check if a component is a pair.
ecs_entity_t ecs_get_typeid(const ecs_world_t *world, ecs_id_t component)
Get the type for a component.
ecs_id_t ecs_id_from_str(const ecs_world_t *world, const char *expr)
Convert a string to a component.
bool ecs_id_is_wildcard(ecs_id_t component)
Utility to check if a component is a wildcard.
bool ecs_id_is_any(ecs_id_t component)
Utility to check if a component is an any wildcard.
ecs_entity_t ecs_field_src(const ecs_iter_t *it, int8_t index)
Return the field source.
bool ecs_iter_changed(ecs_iter_t *it)
Return whether the current iterator result has changed.
bool ecs_field_is_writeonly(const ecs_iter_t *it, int8_t index)
Test whether the field is write-only.
ecs_var_t * ecs_iter_get_vars(const ecs_iter_t *it)
Get the variable array.
bool ecs_field_is_readonly(const ecs_iter_t *it, int8_t index)
Test whether the field is read-only.
const char * ecs_iter_get_var_name(const ecs_iter_t *it, int32_t var_id)
Get the variable name.
ecs_iter_t ecs_worker_iter(const ecs_iter_t *it, int32_t index, int32_t count)
Create a worker iterator.
bool ecs_iter_is_true(ecs_iter_t *it)
Test if an iterator is true.
void ecs_iter_fini(ecs_iter_t *it)
Clean up iterator resources.
size_t ecs_field_stride(const ecs_iter_t *it, int8_t index)
Return the field storage stride.
bool ecs_iter_var_is_constrained(ecs_iter_t *it, int32_t var_id)
Return whether a variable is constrained.
ecs_iter_t ecs_page_iter(const ecs_iter_t *it, int32_t offset, int32_t limit)
Create a paged iterator.
int32_t ecs_iter_get_var_count(const ecs_iter_t *it)
Get the number of variables.
void * ecs_field_at_w_size(const ecs_iter_t *it, size_t size, int8_t index, int32_t row)
Get data for a field at a specified row.
void * ecs_base_field_w_size(const ecs_iter_t *it, size_t size, int8_t index)
Get data for a field matched through component inheritance.
ecs_id_t ecs_field_id(const ecs_iter_t *it, int8_t index)
Return the ID matched for a field.
bool ecs_field_is_set(const ecs_iter_t *it, int8_t index)
Test whether a field is set.
void ecs_iter_set_var(ecs_iter_t *it, int32_t var_id, ecs_entity_t entity)
Set the value for an iterator variable.
bool ecs_field_is_self(const ecs_iter_t *it, int8_t index)
Test whether the field is matched on self.
bool ecs_iter_next(ecs_iter_t *it)
Progress any iterator.
ecs_entity_t ecs_iter_get_var(ecs_iter_t *it, int32_t var_id)
Get the value of an iterator variable as an entity.
bool ecs_worker_next(ecs_iter_t *it)
Progress a worker iterator.
ecs_entity_t ecs_iter_first(ecs_iter_t *it)
Get the first matching entity from an iterator.
int32_t ecs_field_column(const ecs_iter_t *it, int8_t index)
Return the index of a matched table column.
uint64_t ecs_iter_get_group(const ecs_iter_t *it)
Return the group ID for the currently iterated result.
void ecs_iter_set_var_as_table(ecs_iter_t *it, int32_t var_id, const ecs_table_t *table)
Same as ecs_iter_set_var(), but for a table.
ecs_table_t * ecs_iter_get_var_as_table(ecs_iter_t *it, int32_t var_id)
Get the value of an iterator variable as a table.
void * ecs_field_w_size(const ecs_iter_t *it, size_t size, int8_t index)
Get data for a field.
int32_t ecs_iter_count(ecs_iter_t *it)
Count the number of matched entities in a query.
bool ecs_page_next(ecs_iter_t *it)
Progress a paged iterator.
void ecs_iter_set_var_as_range(ecs_iter_t *it, int32_t var_id, const ecs_table_range_t *range)
Same as ecs_iter_set_var(), but for a range of entities.
size_t ecs_field_size(const ecs_iter_t *it, int8_t index)
Return the field type size.
ecs_table_range_t ecs_iter_get_var_as_range(ecs_iter_t *it, int32_t var_id)
Get the value of an iterator variable as a table range.
ecs_id_t ecs_strip_generation(ecs_entity_t e)
Remove the generation from an entity ID.
void ecs_make_alive_id(ecs_world_t *world, ecs_id_t component)
Same as ecs_make_alive(), but for components.
bool ecs_is_valid(const ecs_world_t *world, ecs_entity_t e)
Test whether an entity is valid.
void ecs_make_alive(ecs_world_t *world, ecs_entity_t entity)
Ensure an ID is alive.
ecs_entity_t ecs_get_alive(const ecs_world_t *world, ecs_entity_t e)
Get an alive identifier.
uint32_t ecs_get_version(ecs_entity_t entity)
Get the generation of an entity.
bool ecs_exists(const ecs_world_t *world, ecs_entity_t entity)
Test whether an entity exists.
bool ecs_is_alive(const ecs_world_t *world, ecs_entity_t e)
Test whether an entity is alive.
void ecs_set_version(ecs_world_t *world, ecs_entity_t entity)
Override the generation of an entity.
ecs_entity_t ecs_observer_update(ecs_world_t *world, ecs_entity_t observer, const ecs_observer_desc_t *desc)
Update an existing observer.
void ecs_emit(ecs_world_t *world, ecs_event_desc_t *desc)
Send an event.
void ecs_enqueue(ecs_world_t *world, ecs_event_desc_t *desc)
Enqueue an event.
ecs_entity_t ecs_observer_init(ecs_world_t *world, const ecs_observer_desc_t *desc)
Create an observer.
const ecs_observer_t * ecs_observer_get(const ecs_world_t *world, ecs_entity_t observer)
Get the observer object.
#define FLECS_EVENT_DESC_MAX
Maximum number of events in ecs_observer_desc_t.
Definition flecs.h:333
#define ecs_ftime_t
Customizable precision for scalar time values.
Definition flecs.h:59
#define FLECS_ID_DESC_MAX
Maximum number of IDs to add in ecs_entity_desc_t / ecs_bulk_desc_t.
Definition flecs.h:327
#define FLECS_TERM_COUNT_MAX
Maximum number of terms in queries.
Definition flecs.h:339
#define FLECS_TREE_SPAWNER_DEPTH_CACHE_SIZE
Size of the depth cache in the tree spawner component.
Definition flecs.h:374
char * ecs_get_path_w_sep(const ecs_world_t *world, ecs_entity_t parent, ecs_entity_t child, const char *sep, const char *prefix)
Get a path identifier for an entity.
ecs_entity_t ecs_new_from_path_w_sep(ecs_world_t *world, ecs_entity_t parent, const char *path, const char *sep, const char *prefix)
Find or create an entity from a path.
ecs_entity_t ecs_lookup_symbol(const ecs_world_t *world, const char *symbol, bool lookup_as_path, bool recursive)
Look up an entity by its symbol name.
void ecs_set_alias(ecs_world_t *world, ecs_entity_t entity, const char *alias)
Set an alias for an entity.
ecs_entity_t ecs_lookup(const ecs_world_t *world, const char *path)
Look up an entity by its path.
ecs_entity_t ecs_get_scope(const ecs_world_t *world)
Get the current scope.
void ecs_get_path_w_sep_buf(const ecs_world_t *world, ecs_entity_t parent, ecs_entity_t child, const char *sep, const char *prefix, ecs_strbuf_t *buf, bool escape)
Write a path identifier to a buffer.
ecs_entity_t * ecs_set_lookup_path(ecs_world_t *world, const ecs_entity_t *lookup_path)
Set the search path for lookup operations.
ecs_entity_t ecs_set_name(ecs_world_t *world, ecs_entity_t entity, const char *name)
Set the name of an entity.
const char * ecs_get_symbol(const ecs_world_t *world, ecs_entity_t entity)
Get the symbol of an entity.
ecs_entity_t ecs_lookup_path_w_sep(const ecs_world_t *world, ecs_entity_t parent, const char *path, const char *sep, const char *prefix, bool recursive)
Look up an entity from a path.
ecs_entity_t ecs_set_symbol(ecs_world_t *world, ecs_entity_t entity, const char *symbol)
Set the symbol of an entity.
ecs_entity_t ecs_lookup_child(const ecs_world_t *world, ecs_entity_t parent, const char *name)
Look up a child entity by name.
const char * ecs_get_name(const ecs_world_t *world, ecs_entity_t entity)
Get the name of an entity.
ecs_entity_t ecs_add_path_w_sep(ecs_world_t *world, ecs_entity_t entity, ecs_entity_t parent, const char *path, const char *sep, const char *prefix)
Add a specified path to an entity.
ecs_entity_t * ecs_get_lookup_path(const ecs_world_t *world)
Get the current lookup path.
ecs_entity_t ecs_set_scope(ecs_world_t *world, ecs_entity_t scope)
Set the current scope.
const char * ecs_set_name_prefix(ecs_world_t *world, const char *prefix)
Set a name prefix for newly created entities.
void ecs_iter_skip(ecs_iter_t *it)
Skip a table while iterating.
bool ecs_query_has_table(const ecs_query_t *query, ecs_table_t *table, ecs_iter_t *it)
Match a table with a query.
void ecs_iter_set_group(ecs_iter_t *it, uint64_t group_id)
Set the group to iterate for a query iterator.
const ecs_query_t * ecs_query_get(const ecs_world_t *world, ecs_entity_t query)
Get the query object.
bool ecs_query_next(ecs_iter_t *it)
Progress a query iterator.
const ecs_query_group_info_t * ecs_query_get_group_info(const ecs_query_t *query, uint64_t group_id)
Get information about a query group.
ecs_query_t * ecs_query_update(ecs_world_t *world, ecs_entity_t entity, const ecs_query_desc_t *desc)
Replace the query on an existing entity.
bool ecs_query_is_true(const ecs_query_t *query)
Test whether a query returns one or more results.
char * ecs_term_str(const ecs_world_t *world, const ecs_term_t *term)
Convert a term to a string expression.
bool ecs_query_has_range(const ecs_query_t *query, ecs_table_range_t *range, ecs_iter_t *it)
Match a range with a query.
int32_t ecs_query_find_var(const ecs_query_t *query, const char *name)
Find a variable index.
void ecs_query_fini(ecs_query_t *query)
Delete a query.
bool ecs_query_has(const ecs_query_t *query, ecs_entity_t entity, ecs_iter_t *it)
Match an entity with a query.
char * ecs_query_plan_w_profile(const ecs_query_t *query, const ecs_iter_t *it)
Convert a query to a string with a profile.
const char * ecs_query_args_parse(ecs_query_t *query, ecs_iter_t *it, const char *expr)
Populate variables from a key-value string.
int32_t ecs_query_match_count(const ecs_query_t *query)
Return how often a match event happened for a cached query.
char * ecs_query_plan(const ecs_query_t *query)
Convert a query to a string.
ecs_iter_t ecs_query_iter(const ecs_world_t *world, const ecs_query_t *query)
Create a query iterator.
char * ecs_query_str(const ecs_query_t *query)
Convert a query to a string expression.
bool ecs_query_var_is_entity(const ecs_query_t *query, int32_t var_id)
Test if a variable is an entity.
ecs_query_t * ecs_query_init(ecs_world_t *world, const ecs_query_desc_t *desc)
Create a query.
bool ecs_query_changed(ecs_query_t *query)
Return whether the query data changed since the last iteration.
const char * ecs_query_var_name(const ecs_query_t *query, int32_t var_id)
Get the variable name.
bool ecs_term_match_this(const ecs_term_t *term)
Is a term matched on the $this variable.
const ecs_entity_t EcsOnQueryCacheRevalidate
Event emitted when a table needs to be revalidated for a query cache.
char * ecs_query_plans(const ecs_query_t *query)
Same as ecs_query_plan(), but includes the plan for populating the cache (if any).
void * ecs_query_get_group_ctx(const ecs_query_t *query, uint64_t group_id)
Get the context of a query group.
ecs_query_count_t ecs_query_count(const ecs_query_t *query)
Return the number of entities and results the query matches with.
const ecs_map_t * ecs_query_get_groups(const ecs_query_t *query)
Return the map with query groups.
bool ecs_term_is_initialized(const ecs_term_t *term)
Test whether a term is set.
bool ecs_term_ref_is_set(const ecs_term_ref_t *ref)
Test whether a term ref is set.
bool ecs_term_match_0(const ecs_term_t *term)
Is a term matched on a 0 source.
const ecs_query_t * ecs_query_get_cache_query(const ecs_query_t *query)
Get the query used to populate the cache.
ecs_query_cache_kind_t
Specify cache policy for query.
Definition flecs.h:748
ecs_inout_kind_t
Specify read/write access for term.
Definition flecs.h:727
ecs_oper_kind_t
Specify operator for term.
Definition flecs.h:737
@ EcsQueryCacheAll
Require that all query terms can be cached.
Definition flecs.h:752
@ EcsQueryCacheDefault
Behavior determined by query creation context.
Definition flecs.h:749
@ EcsQueryCacheNone
No caching.
Definition flecs.h:754
@ EcsQueryCacheAuto
Cache query terms that are cacheable.
Definition flecs.h:750
@ EcsOut
Term is only written.
Definition flecs.h:733
@ EcsInOut
Term is both read and written.
Definition flecs.h:731
@ EcsInOutFilter
Same as InOutNone + prevents term from triggering observers.
Definition flecs.h:730
@ EcsInOutDefault
InOut for regular terms, In for shared terms.
Definition flecs.h:728
@ EcsInOutNone
Term is neither read nor written.
Definition flecs.h:729
@ EcsIn
Term is only read.
Definition flecs.h:732
@ EcsNot
The term must not match.
Definition flecs.h:740
@ EcsOptional
The term may match.
Definition flecs.h:741
@ EcsOr
One of the terms in an or chain must match.
Definition flecs.h:739
@ EcsOrFrom
Term must match at least one component from term ID.
Definition flecs.h:743
@ EcsAnd
The term must match.
Definition flecs.h:738
@ EcsNotFrom
Term must match none of the components from term ID.
Definition flecs.h:744
@ EcsAndFrom
Term must match all components from term ID.
Definition flecs.h:742
ecs_table_t * ecs_table_add_id(ecs_world_t *world, ecs_table_t *table, ecs_id_t component)
Get the table that has all components of the current table plus the specified ID.
int32_t ecs_search_offset(const ecs_world_t *world, const ecs_table_t *table, int32_t offset, ecs_id_t component, ecs_id_t *component_out)
Search for a component in a table type starting from an offset.
ecs_table_t * ecs_table_remove_id(ecs_world_t *world, ecs_table_t *table, ecs_id_t component)
Get the table that has all components of the current table minus the specified component.
const ecs_type_t * ecs_table_get_type(const ecs_table_t *table)
Get the type for a table.
int32_t ecs_table_get_column_index(const ecs_world_t *world, const ecs_table_t *table, ecs_id_t component)
Get the column index for a component.
int32_t ecs_search_relation_for_entity(const ecs_world_t *world, ecs_entity_t entity, ecs_id_t id, ecs_entity_t rel, bool self, ecs_component_record_t *cr, ecs_entity_t *tgt_out, ecs_id_t *id_out, struct ecs_table_record_t **tr_out)
Search for a component ID by following a relationship, starting from an entity.
bool ecs_table_is_locked(const ecs_table_t *table)
Check if a table is locked.
void * ecs_table_get_id(const ecs_world_t *world, const ecs_table_t *table, ecs_id_t component, int32_t offset)
Get a column from a table by component.
int32_t ecs_table_size(const ecs_table_t *table)
Return the allocated size of the table.
bool ecs_table_has_flags(ecs_table_t *table, ecs_flags32_t flags)
Test a table for flags.
int32_t ecs_table_column_to_type_index(const ecs_table_t *table, int32_t index)
Convert a column index to a type index.
int32_t ecs_table_column_count(const ecs_table_t *table)
Return the number of columns in a table.
int32_t ecs_search_relation(const ecs_world_t *world, const ecs_table_t *table, int32_t offset, ecs_id_t component, ecs_entity_t rel, ecs_flags64_t flags, ecs_entity_t *tgt_out, ecs_id_t *component_out, struct ecs_table_record_t **tr_out)
Search for a component or relationship ID in a table type starting from an offset.
void * ecs_table_get_column(const ecs_table_t *table, int32_t index, int32_t offset)
Get a column from a table by column index.
int32_t ecs_search(const ecs_world_t *world, const ecs_table_t *table, ecs_id_t component, ecs_id_t *component_out)
Search for a component in a table type.
ecs_entity_t ecs_table_get_target(const ecs_world_t *world, const ecs_table_t *table, ecs_entity_t relationship, int32_t index)
Get the relationship target for a table.
int32_t ecs_table_count(const ecs_table_t *table)
Return the number of entities in the table.
const ecs_entity_t * ecs_table_entities(const ecs_table_t *table)
Return the array with entity IDs for the table.
void ecs_table_unlock(ecs_world_t *world, ecs_table_t *table)
Unlock a table.
bool ecs_table_has_traversable(const ecs_table_t *table)
Check if a table has traversable entities.
int32_t ecs_table_get_depth(const ecs_world_t *world, const ecs_table_t *table, ecs_entity_t rel)
Return the depth for a table in the tree for the specified relationship.
bool ecs_table_has_id(const ecs_world_t *world, const ecs_table_t *table, ecs_id_t component)
Test if a table has a component.
void ecs_table_swap_rows(ecs_world_t *world, ecs_table_t *table, int32_t row_1, int32_t row_2)
Swap two elements inside the table.
void ecs_table_lock(ecs_world_t *world, ecs_table_t *table)
Lock a table.
ecs_table_t * ecs_table_find(ecs_world_t *world, const ecs_id_t *ids, int32_t id_count)
Find a table from an ID array.
size_t ecs_table_get_column_size(const ecs_table_t *table, int32_t index)
Get the column size from a table.
int32_t ecs_table_get_type_index(const ecs_world_t *world, const ecs_table_t *table, ecs_id_t component)
Get the type index for a component.
void ecs_table_clear_entities(ecs_world_t *world, ecs_table_t *table)
Delete all entities in a table.
int32_t ecs_table_type_to_column_index(const ecs_table_t *table, int32_t index)
Convert a type index to a column index.
void ecs_atfini(ecs_world_t *world, ecs_fini_action_t action, void *ctx)
Register an action to be executed when the world is destroyed.
bool ecs_is_fini(const ecs_world_t *world)
Return whether the world is being deleted.
int ecs_fini(ecs_world_t *world)
Delete a world.
ecs_flags32_t ecs_world_get_flags(const ecs_world_t *world)
Get flags set on the world.
ecs_world_t * ecs_mini(void)
Create a new world with just the core module.
ecs_world_t * ecs_init(void)
Create a new world.
ecs_world_t * ecs_init_w_args(int argc, char *argv[])
Create a new world with arguments.
ecs_entities_t ecs_get_entities(const ecs_world_t *world)
Return entity identifiers in the world.
ecs_entity_t ecs_get_entity(const ecs_poly_t *poly)
Get the entity from a poly.
ecs_id_t ecs_make_pair(ecs_entity_t first, ecs_entity_t second)
Make a pair ID.
const ecs_build_info_t * ecs_get_build_info(void)
Get build info.
bool flecs_poly_is_(const ecs_poly_t *object, int32_t type)
Test if a pointer is of the specified type.
ecs_entity_t ecs_get_max_id(const ecs_world_t *world)
Get the largest issued entity ID (not counting generation).
void ecs_run_aperiodic(ecs_world_t *world, ecs_flags32_t flags)
Force aperiodic actions.
void * ecs_get_binding_ctx(const ecs_world_t *world)
Get the world binding context.
void ecs_shrink(ecs_world_t *world)
Free unused memory.
void ecs_dim(ecs_world_t *world, int32_t entity_count)
Dimension the world for a specified number of entities.
const ecs_world_info_t * ecs_get_world_info(const ecs_world_t *world)
Get the world info.
const ecs_world_t * ecs_get_world(const ecs_poly_t *poly)
Get the world from a poly.
void ecs_set_ctx(ecs_world_t *world, void *ctx, ecs_ctx_free_t ctx_free)
Set a world context.
void ecs_exclusive_access_begin(ecs_world_t *world, const char *thread_name)
Begin exclusive thread access.
int32_t ecs_delete_empty_tables(ecs_world_t *world, const ecs_delete_empty_tables_desc_t *desc)
Clean up empty tables.
void ecs_set_binding_ctx(ecs_world_t *world, void *ctx, ecs_ctx_free_t ctx_free)
Set a world binding context.
void ecs_exclusive_access_end(ecs_world_t *world, bool lock_world)
End exclusive thread access.
void * ecs_get_ctx(const ecs_world_t *world)
Get the world context.
Operating system abstraction API.
Component information.
Definition flecs.h:1613
ecs_size_t size
Component size.
Definition flecs.h:1614
ecs_size_t alignment
Component alignment.
Definition flecs.h:1615
A (string) identifier.
Definition flecs.h:1604
ecs_size_t length
Length of identifier.
Definition flecs.h:1606
char * value
Identifier string.
Definition flecs.h:1605
ecs_hashmap_t * index
Current index.
Definition flecs.h:1609
uint64_t hash
Hash of current value.
Definition flecs.h:1607
uint64_t index_hash
Hash of existing record in current index.
Definition flecs.h:1608
Non-fragmenting ChildOf relationship.
Definition flecs.h:1624
ecs_entity_t value
Parent entity.
Definition flecs.h:1625
Component for storing a poly object.
Definition flecs.h:1619
ecs_poly_t * poly
Pointer to poly object.
Definition flecs.h:1620
Apply a rate filter to a tick source.
Definition timer.h:45
Component used to provide a tick source to systems.
Definition system.h:32
Component used for one-shot and interval timer functionality.
Definition timer.h:35
Tree instantiation cache component.
Definition flecs.h:1649
ecs_tree_spawner_t data[(6)]
Cache data indexed by depth.
Definition flecs.h:1650
Type with information about the current Flecs build.
Definition flecs.h:1513
const char ** flags
Compile-time settings.
Definition flecs.h:1516
int16_t version_major
Major Flecs version.
Definition flecs.h:1518
const char ** addons
Addons included in the build.
Definition flecs.h:1515
const char * version
Stringified version.
Definition flecs.h:1517
const char * compiler
Compiler used to compile Flecs.
Definition flecs.h:1514
bool sanitize
Is this a sanitize build?
Definition flecs.h:1522
bool perf_trace
Is this a perf tracing build?
Definition flecs.h:1523
int16_t version_minor
Minor Flecs version.
Definition flecs.h:1519
bool debug
Is this a debug build?
Definition flecs.h:1521
int16_t version_patch
Patch Flecs version.
Definition flecs.h:1520
Used with ecs_bulk_init().
Definition flecs.h:1115
ecs_id_t ids[32]
IDs to create the entities with.
Definition flecs.h:1125
void ** data
Array with component data to insert.
Definition flecs.h:1127
int32_t count
Number of entities to create/populate.
Definition flecs.h:1123
int32_t _canary
Used for validity testing.
Definition flecs.h:1116
ecs_entity_t * entities
Entities to bulk insert.
Definition flecs.h:1118
ecs_table_t * table
Table to insert the entities into.
Definition flecs.h:1134
Used with ecs_component_init().
Definition flecs.h:1145
int32_t _canary
Used for validity testing.
Definition flecs.h:1146
ecs_type_info_t type
Parameters for type (size, hooks, ...).
Definition flecs.h:1152
ecs_entity_t entity
Existing entity to associate with a component (optional).
Definition flecs.h:1149
Used with ecs_delete_empty_tables().
Definition flecs.h:2433
uint16_t delete_generation
Delete table when generation > delete_generation.
Definition flecs.h:2438
double time_budget_seconds
Amount of time operation is allowed to spend.
Definition flecs.h:2441
uint16_t clear_generation
Free table data when generation > clear_generation.
Definition flecs.h:2435
int32_t offset
Table index to start scanning at.
Definition flecs.h:2445
Type returned by ecs_get_entities().
Definition flecs.h:2067
int32_t alive_count
Number of alive entity IDs.
Definition flecs.h:2070
int32_t count
Total number of entity IDs.
Definition flecs.h:2069
const ecs_entity_t * ids
Array with all entity IDs in the world.
Definition flecs.h:2068
Used with ecs_entity_init().
Definition flecs.h:1078
const char * sep
Optional custom separator for hierarchical names.
Definition flecs.h:1090
const char * root_sep
Optional, used for identifiers relative to the root.
Definition flecs.h:1094
const char * name
Name of the entity.
Definition flecs.h:1085
bool use_low_id
When set to true, a low id (typically reserved for components) will be used to create the entity,...
Definition flecs.h:1106
const char * symbol
Optional entity symbol.
Definition flecs.h:1096
int32_t _canary
Used for validity testing.
Definition flecs.h:1079
ecs_entity_t id
Set to modify existing entity (optional).
Definition flecs.h:1081
ecs_entity_t parent
Parent entity.
Definition flecs.h:1083
Used with ecs_emit().
Definition flecs.h:1453
ecs_entity_t entity
Single-entity alternative to setting table / offset / count.
Definition flecs.h:1478
const void * const_param
Same as param, but with the guarantee that the value won't be modified.
Definition flecs.h:1489
ecs_table_t * table
The table for which to notify.
Definition flecs.h:1463
int32_t count
Limit number of notified entities to count.
Definition flecs.h:1475
ecs_table_t * other_table
Optional second table to notify.
Definition flecs.h:1467
int32_t offset
Limit notified entities to ones starting from offset (row) in table.
Definition flecs.h:1470
const ecs_type_t * ids
Component IDs.
Definition flecs.h:1460
void * set_ptr
Optional pointer to the value of the component for which the event is emitted.
Definition flecs.h:1495
ecs_poly_t * observable
Observable (usually the world).
Definition flecs.h:1498
ecs_entity_t event
The event ID.
Definition flecs.h:1455
ecs_flags32_t flags
Event flags.
Definition flecs.h:1501
void * param
Optional context.
Definition flecs.h:1484
Header for ecs_poly_t objects.
Definition flecs.h:535
int32_t type
Magic number indicating which type of Flecs object.
Definition flecs.h:536
int32_t refcount
Refcount, to enable RAII handles.
Definition flecs.h:537
ecs_mixins_t * mixins
Table with offsets to (optional) mixins.
Definition flecs.h:538
Iterator.
Definition flecs.h:1184
void * param
Param passed to ecs_run().
Definition flecs.h:1222
ecs_entity_t event
The event (if applicable).
Definition flecs.h:1210
int32_t frame_offset
Offset relative to the start of iteration.
Definition flecs.h:1233
ecs_flags32_t ref_fields
Bitset with fields that aren't component arrays.
Definition flecs.h:1204
ecs_entity_t interrupted_by
When set, system execution is interrupted.
Definition flecs.h:1237
ecs_flags32_t flags
Iterator flags.
Definition flecs.h:1236
ecs_iter_t * chain_it
Optional, allows for creating iterator chains.
Definition flecs.h:1244
void * ctx
System context.
Definition flecs.h:1223
void * run_ctx
Run language binding context.
Definition flecs.h:1226
ecs_table_t * table
Current table.
Definition flecs.h:1196
int32_t offset
Offset relative to the current table.
Definition flecs.h:1189
ecs_id_t event_id
The (component) ID for the event.
Definition flecs.h:1211
ecs_iter_fini_action_t fini
Function to clean up iterator resources.
Definition flecs.h:1243
ecs_iter_private_t priv_
Private data.
Definition flecs.h:1238
void * callback_ctx
Callback language binding context.
Definition flecs.h:1225
ecs_entity_t * sources
Entity on which the ID was matched (0 if same as entities).
Definition flecs.h:1199
void * binding_ctx
System binding context.
Definition flecs.h:1224
ecs_flags32_t row_fields
Fields that must be obtained with field_at.
Definition flecs.h:1205
float delta_system_time
Time elapsed since last system invocation.
Definition flecs.h:1230
const ecs_query_t * query
Query being evaluated.
Definition flecs.h:1219
int8_t term_index
Index of the term that emitted an event.
Definition flecs.h:1216
ecs_entity_t system
The system (if applicable).
Definition flecs.h:1209
ecs_flags32_t set_fields
Fields that are set.
Definition flecs.h:1203
const ecs_size_t * sizes
Component sizes.
Definition flecs.h:1195
float delta_time
Time elapsed since last frame.
Definition flecs.h:1229
ecs_flags32_t up_fields
Bitset with fields matched through up traversal.
Definition flecs.h:1206
ecs_iter_action_t callback
Callback of system or observer.
Definition flecs.h:1242
int8_t field_count
Number of fields in the iterator.
Definition flecs.h:1215
ecs_table_t * other_table
Previous or next table when adding or removing.
Definition flecs.h:1197
int32_t event_cur
Unique event ID.
Definition flecs.h:1212
const ecs_table_record_t ** trs
Info on where to find the field in the table.
Definition flecs.h:1193
int32_t count
Number of entities to iterate.
Definition flecs.h:1190
void ** ptrs
Component pointers.
Definition flecs.h:1192
ecs_iter_next_action_t next
Function to progress iterator.
Definition flecs.h:1241
const ecs_entity_t * entities
Entity identifiers.
Definition flecs.h:1191
ecs_id_t * ids
(Component) IDs.
Definition flecs.h:1198
ecs_flags64_t constrained_vars
Bitset that marks constrained variables.
Definition flecs.h:1201
Used with ecs_observer_init().
Definition flecs.h:1392
ecs_ctx_free_t run_ctx_free
Callback to free run ctx.
Definition flecs.h:1441
ecs_ctx_free_t ctx_free
Callback to free ctx.
Definition flecs.h:1429
void * run_ctx
Context associated with run (for language bindings).
Definition flecs.h:1438
ecs_entity_t entity
Existing entity to associate with an observer (optional).
Definition flecs.h:1397
int32_t * last_event_id
Used for internal purposes.
Definition flecs.h:1444
void * callback_ctx
Context associated with callback (for language bindings).
Definition flecs.h:1432
void * ctx
User context to pass to callback.
Definition flecs.h:1426
ecs_query_desc_t query
Query for observer.
Definition flecs.h:1400
ecs_flags32_t flags_
Used for internal purposes.
Definition flecs.h:1446
ecs_ctx_free_t callback_ctx_free
Callback to free callback ctx.
Definition flecs.h:1435
int8_t term_index_
Used for internal purposes.
Definition flecs.h:1445
bool global_observer
Global observers are tied to the lifespan of the world.
Definition flecs.h:1412
ecs_iter_action_t callback
Callback to invoke on an event, invoked when the observer matches.
Definition flecs.h:1415
bool yield_existing
When an observer is created, generate events from existing data.
Definition flecs.h:1407
ecs_run_action_t run
Callback invoked on an event.
Definition flecs.h:1423
ecs_entity_t events[8]
Events to observe (OnAdd, OnRemove, OnSet).
Definition flecs.h:1403
int32_t _canary
Used for validity testing.
Definition flecs.h:1394
An observer reacts to events matching a query.
Definition flecs.h:904
int32_t event_count
Number of events.
Definition flecs.h:911
ecs_iter_action_t callback
See ecs_observer_desc_t::callback.
Definition flecs.h:913
ecs_entity_t entity
Entity associated with the observer.
Definition flecs.h:927
ecs_observable_t * observable
Observable for the observer.
Definition flecs.h:924
ecs_run_action_t run
See ecs_observer_desc_t::run.
Definition flecs.h:914
ecs_header_t hdr
Object header.
Definition flecs.h:905
ecs_ctx_free_t ctx_free
Callback to free ctx.
Definition flecs.h:920
ecs_entity_t events[8]
Observer events.
Definition flecs.h:910
void * run_ctx
Run language binding context.
Definition flecs.h:918
ecs_world_t * world
The world.
Definition flecs.h:926
ecs_ctx_free_t run_ctx_free
Callback to free run_ctx.
Definition flecs.h:922
void * callback_ctx
Callback language binding context.
Definition flecs.h:917
void * ctx
Observer context.
Definition flecs.h:916
ecs_ctx_free_t callback_ctx_free
Callback to free callback_ctx.
Definition flecs.h:921
ecs_query_t * query
Observer query.
Definition flecs.h:907
Payload for EcsOnQueryCacheRevalidate event.
Definition flecs.h:4753
ecs_entity_t query
Query for which to revalidate table.
Definition flecs.h:4754
uint64_t table_id
Id of table to revalidate.
Definition flecs.h:4755
Struct returned by ecs_query_count().
Definition flecs.h:4969
int32_t entities
Number of entities returned by the query.
Definition flecs.h:4971
int32_t results
Number of results returned by the query.
Definition flecs.h:4970
int32_t tables
Number of tables returned by the query.
Definition flecs.h:4972
Used with ecs_query_init().
Definition flecs.h:1318
ecs_ctx_free_t ctx_free
Callback to free ctx.
Definition flecs.h:1379
ecs_id_t group_by
Component ID to be used for grouping.
Definition flecs.h:1349
ecs_term_t terms[32]
Query terms.
Definition flecs.h:1323
int32_t _canary
Used for validity testing.
Definition flecs.h:1320
void * ctx
User context to pass to callback.
Definition flecs.h:1373
ecs_ctx_free_t group_by_ctx_free
Function to free group_by_ctx.
Definition flecs.h:1370
void * group_by_ctx
Context to pass to group_by.
Definition flecs.h:1367
void * binding_ctx
Context to be used for language bindings.
Definition flecs.h:1376
ecs_entity_t order_by
Component to sort on, used together with order_by_callback or order_by_table_callback.
Definition flecs.h:1345
ecs_order_by_action_t order_by_callback
Callback used for ordering query results.
Definition flecs.h:1337
ecs_group_create_action_t on_group_create
Callback that is invoked when a new group is created.
Definition flecs.h:1360
ecs_entity_t entity
Entity associated with query (optional).
Definition flecs.h:1385
ecs_ctx_free_t binding_ctx_free
Callback to free binding_ctx.
Definition flecs.h:1382
ecs_group_by_action_t group_by_callback
Callback used for grouping results.
Definition flecs.h:1356
ecs_group_delete_action_t on_group_delete
Callback that is invoked when an existing group is deleted.
Definition flecs.h:1364
ecs_sort_table_action_t order_by_table_callback
Callback used for ordering query results.
Definition flecs.h:1341
ecs_flags32_t flags
Flags for enabling query features.
Definition flecs.h:1332
ecs_query_cache_kind_t cache_kind
Caching policy of the query.
Definition flecs.h:1329
const char * expr
Query DSL expression (optional).
Definition flecs.h:1326
Type that contains information about a query group.
Definition flecs.h:1587
int32_t table_count
Number of tables in group.
Definition flecs.h:1590
void * ctx
Group context, returned by on_group_create.
Definition flecs.h:1591
uint64_t id
Group ID.
Definition flecs.h:1588
int32_t match_count
How often tables have been matched or unmatched.
Definition flecs.h:1589
Queries are lists of constraints (terms) that match entities.
Definition flecs.h:859
ecs_flags32_t row_fields
Fields that must be acquired with field_at.
Definition flecs.h:881
ecs_flags32_t data_fields
Fields that have data.
Definition flecs.h:878
ecs_flags32_t read_fields
Fields that read data.
Definition flecs.h:880
ecs_header_t hdr
Object header.
Definition flecs.h:860
int8_t var_count
Number of query variables.
Definition flecs.h:869
ecs_flags32_t fixed_fields
Bitmasks for quick field information lookups.
Definition flecs.h:875
ecs_flags32_t var_fields
Fields with non-$this variable source.
Definition flecs.h:876
ecs_flags32_t write_fields
Fields that write data.
Definition flecs.h:879
int32_t eval_count
Number of times the query is evaluated.
Definition flecs.h:898
ecs_world_t * world
Actual world.
Definition flecs.h:896
ecs_flags32_t static_id_fields
Fields with a static (component) id.
Definition flecs.h:877
uint64_t bloom_filter
Bitmask used to quickly discard tables.
Definition flecs.h:866
ecs_flags32_t set_fields
Fields that will be set.
Definition flecs.h:883
ecs_entity_t entity
Entity associated with query (optional).
Definition flecs.h:894
void * ctx
User context to pass to callback.
Definition flecs.h:891
int32_t * sizes
Component sizes.
Definition flecs.h:863
ecs_id_t * ids
Component ids.
Definition flecs.h:864
ecs_flags32_t shared_readonly_fields
Fields that don't write shared data.
Definition flecs.h:882
ecs_term_t * terms
Query terms.
Definition flecs.h:862
ecs_query_cache_kind_t cache_kind
Caching policy of the query.
Definition flecs.h:885
int8_t term_count
Number of query terms.
Definition flecs.h:871
char ** vars
Array with variable names for the iterator.
Definition flecs.h:888
ecs_world_t * stage
World or stage the query was created with.
Definition flecs.h:895
int8_t field_count
Number of fields returned by the query.
Definition flecs.h:872
ecs_flags32_t flags
Query flags.
Definition flecs.h:867
void * binding_ctx
Context to be used for language bindings.
Definition flecs.h:892
Type that describes a reference to an entity or variable in a term.
Definition flecs.h:820
const char * name
Name.
Definition flecs.h:827
ecs_entity_t id
Entity ID.
Definition flecs.h:821
Type that describes a term (single element in a query).
Definition flecs.h:835
ecs_term_ref_t src
Source of term.
Definition flecs.h:841
int8_t field_index
Index of the field for the term in the iterator.
Definition flecs.h:852
ecs_id_t id
Component ID to be matched by term.
Definition flecs.h:836
int16_t oper
Operator of term.
Definition flecs.h:850
ecs_term_ref_t second
Second element of pair.
Definition flecs.h:843
ecs_flags16_t flags_
Flags that help evaluation, set by ecs_query_init().
Definition flecs.h:853
ecs_entity_t trav
Relationship to traverse when looking for the component.
Definition flecs.h:845
int16_t inout
Access to contents matched by term.
Definition flecs.h:849
ecs_term_ref_t first
Component or first element of pair.
Definition flecs.h:842
Component with data to instantiate a non-fragmenting tree.
Definition flecs.h:1629
uint32_t child
Prefab child entity (without generation).
Definition flecs.h:1632
int32_t parent_index
Index into the children vector.
Definition flecs.h:1633
const char * child_name
Name of the prefab child.
Definition flecs.h:1630
ecs_table_t * table
Table in which the child will be stored.
Definition flecs.h:1631
bool copy
Copy components instead of inheriting them.
Definition flecs.h:1634
Tree spawner data for a single hierarchy depth.
Definition flecs.h:1638
ecs_vec_t children
vector<ecs_tree_spawner_child_t>.
Definition flecs.h:1639
ecs_copy_t copy_ctor
Ctor + copy.
Definition flecs.h:986
void * lifecycle_ctx
Component lifecycle context (see meta addon).
Definition flecs.h:1042
void * ctx
User-defined context.
Definition flecs.h:1040
ecs_iter_action_t on_remove
Callback that is invoked when an instance of the component is removed.
Definition flecs.h:1027
void * binding_ctx
Language binding context.
Definition flecs.h:1041
ecs_move_t move_dtor
Move + dtor.
Definition flecs.h:1001
ecs_flags32_t flags
Hook flags.
Definition flecs.h:1013
ecs_cmp_t cmp
Compare hook.
Definition flecs.h:1004
ecs_copy_t copy
copy assignment.
Definition flecs.h:982
ecs_ctx_free_t lifecycle_ctx_free
Callback to free lifecycle_ctx.
Definition flecs.h:1046
ecs_on_validate_t on_validate
Callback that is invoked before the on_set/OnSet hooks and observers are invoked.
Definition flecs.h:1038
ecs_iter_action_t on_set
Callback that is invoked when an instance of the component is set.
Definition flecs.h:1022
ecs_move_t move
move assignment.
Definition flecs.h:983
ecs_xtor_t ctor
ctor.
Definition flecs.h:980
ecs_iter_action_t on_replace
Callback that is invoked with the existing and new value before the value is assigned.
Definition flecs.h:1033
ecs_ctx_free_t ctx_free
Callback to free ctx.
Definition flecs.h:1044
ecs_iter_action_t on_add
Callback that is invoked when an instance of a component is added.
Definition flecs.h:1017
ecs_ctx_free_t binding_ctx_free
Callback to free binding_ctx.
Definition flecs.h:1045
ecs_move_t move_ctor
Ctor + move.
Definition flecs.h:989
ecs_equals_t equals
Equals hook.
Definition flecs.h:1007
ecs_move_t ctor_move_dtor
Ctor + move + dtor (or move_ctor + dtor).
Definition flecs.h:995
ecs_xtor_t dtor
dtor.
Definition flecs.h:981
Type that contains component information (passed to ctors/dtors/...).
Definition flecs.h:1053
ecs_size_t alignment
Alignment of the type.
Definition flecs.h:1055
ecs_size_t size
Size of the type.
Definition flecs.h:1054
const char * name
Type name.
Definition flecs.h:1058
ecs_entity_t component
Handle to component (do not set).
Definition flecs.h:1057
ecs_type_hooks_t hooks
Type hooks.
Definition flecs.h:1056
int32_t refcount
Refcount (do not set).
Definition flecs.h:1059
A type is a list of (component) IDs.
Definition flecs.h:413
ecs_id_t * array
Array with IDs.
Definition flecs.h:414
int32_t count
Number of elements in array.
Definition flecs.h:415
Value of a dynamic type.
Definition flecs.h:1069
void * ptr
Pointer to value.
Definition flecs.h:1071
ecs_entity_t type
Type of value.
Definition flecs.h:1070
int64_t event_count
Enqueued custom events.
int64_t remove_count
Remove commands processed.
int64_t add_count
Add commands processed.
int64_t modified_count
Modified commands processed.
int64_t clear_count
Clear commands processed.
int64_t ensure_count
Ensure or emplace commands processed.
int64_t delete_count
Delete commands processed.
int64_t other_count
Other commands processed.
int64_t batched_entity_count
Entities for which commands were batched.
int64_t discard_count
Commands discarded, happens when the entity is no longer alive when running the command.
int64_t batched_command_count
Commands batched.
int64_t set_count
Set commands processed.
Type that contains information about the world.
Definition flecs.h:1527
int64_t observers_ran_total
Total number of times an observer was invoked.
Definition flecs.h:1553
float delta_time
Time passed to or computed by ecs_progress().
Definition flecs.h:1531
int64_t systems_ran_total
Total number of systems run.
Definition flecs.h:1552
double world_time_total
Time elapsed in simulation.
Definition flecs.h:1539
int32_t tag_id_count
Number of tag (no data) IDs in the world.
Definition flecs.h:1556
int32_t component_id_count
Number of component (data) IDs in the world.
Definition flecs.h:1557
int64_t pipeline_build_count_total
Total number of pipeline builds.
Definition flecs.h:1551
int64_t eval_comp_monitors_total
Total number of monitor evaluations.
Definition flecs.h:1544
int32_t table_count
Number of tables.
Definition flecs.h:1560
float delta_time_raw
Raw delta time (no time scaling).
Definition flecs.h:1530
float frame_time_total
Total time spent processing a frame.
Definition flecs.h:1534
int64_t table_create_total
Total number of times a table was created.
Definition flecs.h:1549
float system_time_total
Total time spent in systems.
Definition flecs.h:1535
int64_t id_delete_total
Total number of times an ID was deleted.
Definition flecs.h:1548
struct ecs_world_info_t::@354013130002221015352342176135321160002353227336 cmd
Command statistics.
float merge_time_total
Total time spent in merges.
Definition flecs.h:1537
ecs_entity_t last_component_id
Last issued component entity ID.
Definition flecs.h:1528
int64_t frame_count_total
Total number of frames.
Definition flecs.h:1542
int64_t merge_count_total
Total number of merges.
Definition flecs.h:1543
int64_t table_delete_total
Total number of times a table was deleted.
Definition flecs.h:1550
int64_t queries_ran_total
Total number of times a query was evaluated.
Definition flecs.h:1554
int64_t rematch_count_total
Total number of rematches.
Definition flecs.h:1545
int64_t id_create_total
Total number of times a new ID was created.
Definition flecs.h:1547
float time_scale
Time scale applied to delta_time.
Definition flecs.h:1532
int32_t pair_id_count
Number of pair IDs in the world.
Definition flecs.h:1558
float rematch_time_total
Time spent on query rematching.
Definition flecs.h:1538
float target_fps
Target FPS.
Definition flecs.h:1533
double world_time_total_raw
Time elapsed in simulation (no scaling).
Definition flecs.h:1540
float emit_time_total
Total time spent notifying observers.
Definition flecs.h:1536
uint32_t creation_time
Time when world was created.
Definition flecs.h:1562
const char * name_prefix
Value set by ecs_set_name_prefix().
Definition flecs.h:1580