[−]Struct acute_ecs::command::CommandBuffer
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) -> CommandBuffer
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) -> CommandBuffer
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),
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
C: 'static + IntoComponentSource,
T: 'static + TagSet + TagLayout + for<'a> Filter<ChunksetFilterData<'a>>,
C: 'static + IntoComponentSource,
T: 'static + TagSet + TagLayout + for<'a> Filter<ChunksetFilterData<'a>>,
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>(&self, entity: Entity, component: C) where
C: Component,
C: Component,
Queues the addition of a component from an entity in the command buffer.
This writer calls World::add_component
pub fn remove_component<C>(&self, entity: Entity) where
C: Component,
C: Component,
Queues the removal of a component from an entity in the command buffer.
This writer calls World::remove_component
pub fn add_tag<T>(&self, entity: Entity, tag: T) where
T: Tag,
T: Tag,
Queues the addition of a tag from an entity in the command buffer.
This writer calls World::add_tag
pub fn remove_tag<T>(&self, entity: Entity) where
T: Tag,
T: Tag,
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
Auto Trait Implementations
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> Component for T where
T: 'static + Send + Sync,
T: 'static + Send + Sync,
impl<T> Downcast for T where
T: Any,
T: Any,
fn into_any(self: Box<T>) -> Box<dyn Any + 'static>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
fn as_any(&self) -> &(dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
impl<T> DowncastSync for T where
T: Send + Sync + Any,
T: Send + Sync + Any,
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> Resource for T where
T: 'static + Send + Sync,
T: 'static + Send + Sync,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,