Struct CommandBuffer

pub struct CommandBuffer { /* private fields */ }

A command buffer used to queue mutable changes to the world from a system. This buffer is automatically flushed and refreshed at the beginning of every frame by Schedule. If Schedule is not used, then the user needs to manually flush it by performing CommandBuffer::write.

This buffer operates as follows: - All commands are queued as trait object of type WorldWritable, to be executed when CommandBuffer:write is called. - Entities are allocated at the time of CommandBuffer:write occuring, being directly allocated from the world and cached internally in the system. This upper cache size can be changed via SystemBuilder::with_command_buffer_size for specific systems, or globally via World::set_command_buffer_size. In the event the cached entity count is exceeded, the cache will be refilled on demand from the world EntityAllocator.

This behavior exists because EntityAllocator is a shared lock within the world, so in order to reduce lock contention with many systems running and adding entities, the CommandBuffer will cache the configured number of entities - reducing contention.

Examples

Inserting an entity using the CommandBuffer:

let mut command_buffer = CommandBuffer::new(&world);
let entity = command_buffer.start_entity().build();

command_buffer.add_component(entity, Position(123.0));
command_buffer.delete(entity);

command_buffer.write(&mut world);

Implementations

impl CommandBuffer

pub fn new_with_capacity(world: &World, capacity: usize) -> Self

Creates a CommandBuffer with a custom capacity of cached Entity’s to be collected every frame. Allocating a command buffer in this manner will override World::set_command_buffer_size and this system will always allocate the custom provide capacity of entities every frame.

This constructor will preallocate the first round of entities needed from the world.

pub fn new(world: &World) -> Self

Creates a CommandBuffer with a custom capacity of cached Entity’s to be collected every frame. Allocating a command buffer in this manner will use the default World::set_command_buffer_size value.

This constructor will preallocate the first round of entities needed from the world.

pub fn world(&self) -> WorldId

Gets the ID of the world this command buffer belongs to.

pub fn write(&mut self, world: &mut World)

Flushes this command buffer, draining all stored commands and writing them to the world.

Command flushes are performed in a FIFO manner, allowing for reliable, linear commands being executed in the order they were provided.

pub fn start_entity(&mut self) -> EntityBuilder<'_, (), ()>

Creates an entity builder for constructing a new entity.

pub fn exec_mut<F>(&self, f: F)

where F: 'static + Fn(&mut World),

Executes an arbitrary closure against the mutable world, allowing for queued exclusive access to the world.

pub fn insert<T, C>(&mut self, tags: T, components: C) -> &[Entity]

where T: 'static + TagSet + TagLayout + for<'a> Filter<ChunksetFilterData<'a>>, C: 'static + IntoComponentSource,

Queues an insertion into the world. This command follows the same syntax as the normal World::insert, returning the entities created for this command.

pub fn delete(&self, entity: Entity)

Queues the deletion of an entity in the command buffer. This writer calls World::delete

pub fn add_component<C: Component>(&self, entity: Entity, component: C)

Queues the addition of a component from an entity in the command buffer. This writer calls World::add_component

pub fn remove_component<C: Component>(&self, entity: Entity)

Queues the removal of a component from an entity in the command buffer. This writer calls World::remove_component

pub fn add_tag<T: Tag>(&self, entity: Entity, tag: T)

Queues the addition of a tag from an entity in the command buffer. This writer calls World::add_tag

pub fn remove_tag<T: Tag>(&self, entity: Entity)

Queues the removal of a tag from an entity in the command buffer. This writer calls World::remove_tag

pub fn len(&self) -> usize

Returns the current number of commands already queued in this CommandBuffer instance.

pub fn is_empty(&self) -> bool

Returns true if this CommandBuffer is currently empty and contains no writers.

Trait Implementations

impl Drop for CommandBuffer

fn drop(&mut self)

Executes the destructor for this type.

impl Send for CommandBuffer

impl Sync for CommandBuffer