pub struct CommandBuffer { /* private fields */ }
Expand description
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§
Source§impl CommandBuffer
impl CommandBuffer
Sourcepub fn new_with_capacity(world: &World, capacity: usize) -> Self
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.
Sourcepub fn new(world: &World) -> Self
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.
Sourcepub fn write(&mut self, world: &mut World)
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.
Sourcepub fn start_entity(&mut self) -> EntityBuilder<'_, (), ()>
pub fn start_entity(&mut self) -> EntityBuilder<'_, (), ()>
Creates an entity builder for constructing a new entity.
Sourcepub fn exec_mut<F>(&self, f: F)
pub fn exec_mut<F>(&self, f: F)
Executes an arbitrary closure against the mutable world, allowing for queued exclusive access to the world.
Sourcepub fn insert<T, C>(&mut self, tags: T, components: C) -> &[Entity]where
T: 'static + TagSet + TagLayout + for<'a> Filter<ChunksetFilterData<'a>>,
C: 'static + IntoComponentSource,
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.
Sourcepub fn delete(&self, entity: Entity)
pub fn delete(&self, entity: Entity)
Queues the deletion of an entity in the command buffer. This writer calls World::delete
Sourcepub fn add_component<C: Component>(&self, entity: Entity, component: C)
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
Sourcepub fn remove_component<C: Component>(&self, entity: Entity)
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
Sourcepub fn add_tag<T: Tag>(&self, entity: Entity, tag: T)
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
Sourcepub fn remove_tag<T: Tag>(&self, entity: Entity)
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
Trait Implementations§
Source§impl Drop for CommandBuffer
impl Drop for CommandBuffer
impl Send for CommandBuffer
impl Sync for CommandBuffer
Auto Trait Implementations§
impl !Freeze for CommandBuffer
impl !RefUnwindSafe for CommandBuffer
impl Unpin for CommandBuffer
impl !UnwindSafe for CommandBuffer
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
Source§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left
is true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left(&self)
returns true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read more