Struct CommandBuffer

Source
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

Source

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.

Source

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.

Source

pub fn world(&self) -> WorldId

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

Source

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.

Source

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

Creates an entity builder for constructing a new entity.

Source

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.

Source

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.

Source

pub fn delete(&self, entity: Entity)

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

Source

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

Source

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

Source

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

Source

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

Source

pub fn len(&self) -> usize

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

Source

pub fn is_empty(&self) -> bool

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

Trait Implementations§

Source§

impl Drop for CommandBuffer

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

impl Send for CommandBuffer

Source§

impl Sync for CommandBuffer

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts 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
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

impl<T> Component for T
where T: Send + Sync + 'static,