Create a new world.

A world manages all the ECS data and supporting infrastructure. Applications must have at least one world. Entities, component and system handles are local to a world and should not be shared between worlds.

This operation creates a world with all builtin modules loaded.

Get brief description from entity.

Performance warning: a new String object is allocated, along with a new buffer that copies the docs from the original buffer, because Crystal doesn't want to create a String that shares the memory.

Get detailed description from entity.

Performance warning: a new String object is allocated, along with a new buffer that copies the docs from the original buffer, because Crystal doesn't want to create a String that shares the memory.

Get link to external documentation from entity.

Performance warning: a new String object is allocated, along with a new buffer that copies the docs from the original buffer, because Crystal doesn't want to create a String that shares the memory.

Add brief description to entity.

Please ensure that the String is a String literal, or that it is retained somewhere traceable from Crystal, because otherwise the buffer may be garbage-collected, leading to memory corruption.

TODO Some way to enforce this? Maybe with a macro that enforces StringLiteral?

Add detailed description to entity.

Please ensure that the String is a String literal, or that it is retained somewhere traceable from Crystal, because otherwise the buffer may be garbage-collected, leading to memory corruption.

TODO Some way to enforce this? Maybe with a macro that enforces StringLiteral?

Add link to external documentation to entity.

Please ensure that the String is a String literal, or that it is retained somewhere traceable from Crystal, because otherwise the buffer may be garbage-collected, leading to memory corruption.

TODO Some way to enforce this? Maybe with a macro that enforces StringLiteral?

Find or create an entity.

This operation creates a new entity, or modifies an existing one. When a name is set in the ecs_entity_desc_t::name field and ecs_entity_desc_t::entity is not set, the operation will first attempt to find an existing entity by that name. If no entity with that name can be found, it will be created.

If both a name and entity handle are provided, the operation will check if the entity name matches with the provided name. If the names do not match, the function will fail and return 0.

If an id to a non-existing entity is provided, that entity id become alive.

See the documentation of ecs_entity_desc_t for more details.

Delete a world.

This operation deletes the world, and everything it contains.

Convenience wrapper for get_id for when component implements the id method.

Get an immutable pointer to a component.

This operation obtains a const pointer to the requested component. The operation accepts the component entity id.

Get the name of an entity. This will return the name stored in (EcsIdentifier, EcsName).

Performance warning: a new String object is allocated, along with a new buffer that copies the docs from the original buffer, because Crystal doesn't want to create a String that shares the memory.

Get a component that relates a subject entity to an object entity

Convenience wrapper for get for when the entity is a component singleton.

Set the current scope, temporarily.

This operation sets the scope of the current stage to the provided entity. As a result new entities will be created in this scope, and lookups will be relative to the provided scope.

Restore the scope to the old value after the block is done.

Get world info.

Lookup an entity by name.

Returns an entity that matches the specified name. Only looks for entities in the current scope (root if no scope is provided).

Returns the entity with the specified name, or nil if no entity was found.

Progress a world.

This operation progresses the world by running all systems that are both enabled and periodic on their matching entities.

An application can pass a delta_time into the function, which is the time passed since the last frame. This value is passed to systems so they can update entity values proportional to the elapsed time since their last invocation.

When an application passes 0 to delta_time, ecs_progress will automatically measure the time passed since the last frame. If an application does not uses time management, it should pass a non-zero value for delta_time (1.0 is recommended). That way, no time will be wasted measuring the time.

Returns false if ecs_quit has been called, true otherwise.

Signal exit.

This operation signals that the application should quit. It will cause ecs_progress to return false.

Return whether a quit has been signaled.

Convenience wrapper for remove_id for when component implements the id method.

Remove an entity from an entity.

This operation removes a single entity from the type of an entity. Type roles may be used in combination with the added entity. If the entity does not have the entity, this operation will have no side effects.

Remove a component if it relates the subject entity to the object entity.

Convenience wrapper for remove for when the entity is a component singleton.

Convenience wrapper for set_id for when component implements the id method.

Set the value of a component.

This operation allows an application to set the value of a component. The operation is equivalent to calling ecs_get_mut and ecs_modified.

If the provided entity is 0, a new entity will be created.

Set a component that relates a subject entity to an object entity.

Convenience wrapper for set for when the entity is a component singleton.

Get target frames per second (FPS) for application.

See the setter method for more details on how this value is used.

Set target frames per second (FPS) for application.

Setting the target FPS ensures that ecs_progress is not invoked faster than the specified FPS. When enabled, ecs_progress tracks the time passed since the last invocation, and sleeps the remaining time of the frame (if any).

This feature ensures systems are ran at a consistent interval, as well as conserving CPU time by not running systems more often than required.

Note that ecs_progress only sleeps if there is time left in the frame. Both time spent in flecs as time spent outside of flecs are taken into account.