Struct SamplerPool 

pub struct SamplerPool<T: PoolLabel + Component + Clone>(pub T);

A component for building sampler pools.

Sampler pools are bevy_seedling’s primary mechanism for playing multiple sounds at once. SamplerPool allows you to precisely define pools and their routing.

Constructing pools

To construct a pool, you’ll need to provide a PoolLabel.

// Note that you'll need a few additional traits to support `PoolLabel`
#[derive(PoolLabel, Debug, Clone, PartialEq, Eq, Hash)]
struct SimplePool;

fn spawn_pool(mut commands: Commands) {
    commands.spawn(SamplerPool(SimplePool));
}

You can also provide an explicit PoolSize, overriding the DefaultPoolSize resource.

commands.spawn((
    SamplerPool(SimplePool),
    // A pool of exactly 16 samplers that cannot grow
    PoolSize(16..=16),
));

Finally, you can insert arbitrary effects.

#[derive(PoolLabel, Debug, Clone, PartialEq, Eq, Hash)]
struct EffectsPool;

commands.spawn((
    SamplerPool(EffectsPool),
    sample_effects![LowPassNode::default(), SpatialBasicNode::default()],
));

By default, pools will insert a volume node in the root SamplerPool entity and connect all its samplers to it. As a result, you can easily route the entire pool with a single connect call.

let filter = commands.spawn(LowPassNode::default()).id();

commands.spawn(SamplerPool(SimplePool)).connect(filter);

Playing samples in a pool

Once you’ve spawned a pool, playing samples in it is easy! Just spawn your sample players with the label.

#[derive(PoolLabel, Debug, Clone, PartialEq, Eq, Hash)]
struct SimplePool;

fn spawn_pool_and_play(mut commands: Commands, server: Res<AssetServer>) {
    commands.spawn(SamplerPool(SimplePool));

    commands.spawn((SimplePool, SamplePlayer::new(server.load("my_sample.wav"))));
}

Pools with effects will automatically insert SampleEffects into queued SamplePlayers.

#[derive(PoolLabel, Debug, Clone, PartialEq, Eq, Hash)]
struct SpatialPool;

commands.spawn((
    SamplerPool(SpatialPool),
    sample_effects![SpatialBasicNode::default()],
));

// Once spawned, this entity will receive a
// `SampleEffects` pointing to a `SpatialBasicNode`
commands.spawn((SpatialPool, SamplePlayer::new(server.load("my_sample.wav"))));

See SampleEffects for more details.

Architecture

Sampler pools are collections of individual sampler nodes, each of which can play a single sample at a time. When samples are queued up for playback, bevy_seedling will look for the best sampler in the corresponding pool. If a suitable sampler is found, the sample will begin playback, otherwise waiting until a slot opens up. If the time spent waiting exceeds a sample’s SampleQueueLifetime, the sample’s playback is considered complete, and the OnComplete effect is applied.

Each sampler node is routed to a final volume node. For a simple pool:

#[derive(PoolLabel, Debug, Clone, PartialEq, Eq, Hash)]
struct SimplePool;

commands.spawn(SamplerPool(SimplePool));

We end up with a graph like:

┌───────┐┌───────┐┌───────┐┌───────┐
│Sampler││Sampler││Sampler││Sampler│
└┬──────┘└┬──────┘└┬──────┘└┬──────┘
┌▽────────▽────────▽────────▽┐
│Volume                      │
└┬───────────────────────────┘
┌▽──────┐
│MainBus│
└───────┘

If a pool includes effects, these are inserted in series with each sampler. For a pool with spatial processing:

commands.spawn((
    SamplerPool(SpatialPool),
    sample_effects![SpatialBasicNode::default()],
));

We end up with a graph like:

┌───────┐┌───────┐┌───────┐┌───────┐
│Sampler││Sampler││Sampler││Sampler│
└┬──────┘└┬──────┘└┬──────┘└┬──────┘
┌▽──────┐┌▽──────┐┌▽──────┐┌▽──────┐
│Spatial││Spatial││Spatial││Spatial│
└┬──────┘└┬──────┘└┬──────┘└┬──────┘
┌▽────────▽────────▽────────▽┐
│Volume                      │
└┬───────────────────────────┘
┌▽──────┐
│MainBus│
└───────┘

Tuple Fields

0: T

Trait Implementations

impl<T: PoolLabel + Component + Clone> Component for SamplerPool<T>

where Self: Send + Sync + 'static,

Required Components: [PoolMarker], SamplerConfig.

A component’s Required Components are inserted whenever it is inserted. Note that this will also insert the required components of the required components, recursively, in depth-first order.

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

A constant indicating the storage type used for this component.

type Mutability = Immutable

A marker type to assist Bevy with determining if this component is mutable, or immutable. Mutable components will have Component<Mutability = Mutable>, while immutable components will instead have Component<Mutability = Immutable>.

fn register_required_components( _requiree: ComponentId, required_components: &mut RequiredComponentsRegistrator<'_, '_>, )

Registers required components.

fn on_insert() -> Option<ComponentHook>

Gets the on_insert ComponentHook for this Component if one is defined.

fn clone_behavior() -> ComponentCloneBehavior

Called when registering this component, allowing to override clone function (or disable cloning altogether) for this component.

fn relationship_accessor() -> Option<ComponentRelationshipAccessor<Self>>

Returns ComponentRelationshipAccessor required for working with relationships in dynamic contexts.

fn on_add() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_add ComponentHook for this Component if one is defined.

fn on_replace() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_replace ComponentHook for this Component if one is defined.

fn on_remove() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_remove ComponentHook for this Component if one is defined.

fn on_despawn() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_despawn ComponentHook for this Component if one is defined.

fn map_entities<E>(_this: &mut Self, _mapper: &mut E)

where E: EntityMapper,

Maps the entities on this component using the given EntityMapper. This is used to remap entities in contexts like scenes and entity cloning. When deriving Component, this is populated by annotating fields containing entities with #[entities]

impl<T: Debug + PoolLabel + Component + Clone> Debug for SamplerPool<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> FromReflect for SamplerPool<T>

where SamplerPool<T>: Any + Send + Sync, T: TypePath + FromReflect + MaybeTyped + RegisterForReflection + PoolLabel + Component + Clone,

fn from_reflect(reflect: &dyn PartialReflect) -> Option<Self>

Constructs a concrete instance of Self from a reflected value.

fn take_from_reflect( reflect: Box<dyn PartialReflect>, ) -> Result<Self, Box<dyn PartialReflect>>

Attempts to downcast the given value to Self using, constructing the value using from_reflect if that fails.

impl<T> GetTypeRegistration for SamplerPool<T>

where SamplerPool<T>: Any + Send + Sync, T: TypePath + FromReflect + MaybeTyped + RegisterForReflection + PoolLabel + Component + Clone,

fn get_type_registration() -> TypeRegistration

Returns the default TypeRegistration for this type.

fn register_type_dependencies(registry: &mut TypeRegistry)

Registers other types needed by this type.

impl<T> PartialReflect for SamplerPool<T>

where SamplerPool<T>: Any + Send + Sync, T: TypePath + FromReflect + MaybeTyped + RegisterForReflection + PoolLabel + Component + Clone,

fn get_represented_type_info(&self) -> Option<&'static TypeInfo>

Returns the TypeInfo of the type represented by this value.

fn try_apply(&mut self, value: &dyn PartialReflect) -> Result<(), ApplyError>

Tries to apply a reflected value to this value.

fn reflect_kind(&self) -> ReflectKind

Returns a zero-sized enumeration of “kinds” of type.

fn reflect_ref(&self) -> ReflectRef<'_>

Returns an immutable enumeration of “kinds” of type.

fn reflect_mut(&mut self) -> ReflectMut<'_>

Returns a mutable enumeration of “kinds” of type.

fn reflect_owned(self: Box<Self>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn try_into_reflect( self: Box<Self>, ) -> Result<Box<dyn Reflect>, Box<dyn PartialReflect>>

Attempts to cast this type to a boxed, fully-reflected value.

fn try_as_reflect(&self) -> Option<&dyn Reflect>

Attempts to cast this type to a fully-reflected value.

fn try_as_reflect_mut(&mut self) -> Option<&mut dyn Reflect>

Attempts to cast this type to a mutable, fully-reflected value.

fn into_partial_reflect(self: Box<Self>) -> Box<dyn PartialReflect>

Casts this type to a boxed, reflected value.

fn as_partial_reflect(&self) -> &dyn PartialReflect

Casts this type to a reflected value.

fn as_partial_reflect_mut(&mut self) -> &mut dyn PartialReflect

Casts this type to a mutable, reflected value.

fn reflect_partial_eq(&self, value: &dyn PartialReflect) -> Option<bool>

Returns a “partial equality” comparison result.

fn reflect_clone(&self) -> Result<Box<dyn Reflect>, ReflectCloneError>

Attempts to clone Self using reflection.

fn apply(&mut self, value: &(dyn PartialReflect + 'static))

Applies a reflected value to this value.

fn to_dynamic(&self) -> Box<dyn PartialReflect>

Converts this reflected value into its dynamic representation based on its kind.

fn reflect_clone_and_take<T>(&self) -> Result<T, ReflectCloneError>

where T: 'static, Self: Sized + TypePath,

For a type implementing PartialReflect, combines reflect_clone and take in a useful fashion, automatically constructing an appropriate ReflectCloneError if the downcast fails.

fn reflect_hash(&self) -> Option<u64>

Returns a hash of the value (which includes the type).

fn debug(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Debug formatter for the value.

fn is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic type.

impl<T> Reflect for SamplerPool<T>

where SamplerPool<T>: Any + Send + Sync, T: TypePath + FromReflect + MaybeTyped + RegisterForReflection + PoolLabel + Component + Clone,

fn into_any(self: Box<Self>) -> Box<dyn Any>

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &dyn Any

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut dyn Any

Returns the value as a &mut dyn Any.

fn into_reflect(self: Box<Self>) -> Box<dyn Reflect>

Casts this type to a boxed, fully-reflected value.

fn as_reflect(&self) -> &dyn Reflect

Casts this type to a fully-reflected value.

fn as_reflect_mut(&mut self) -> &mut dyn Reflect

Casts this type to a mutable, fully-reflected value.

fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>

Performs a type-checked assignment of a reflected value to this value.

impl<T> TupleStruct for SamplerPool<T>

where SamplerPool<T>: Any + Send + Sync, T: TypePath + FromReflect + MaybeTyped + RegisterForReflection + PoolLabel + Component + Clone,

fn field(&self, index: usize) -> Option<&dyn PartialReflect>

Returns a reference to the value of the field with index index as a &dyn Reflect.

fn field_mut(&mut self, index: usize) -> Option<&mut dyn PartialReflect>

Returns a mutable reference to the value of the field with index index as a &mut dyn Reflect.

fn field_len(&self) -> usize

Returns the number of fields in the tuple struct.

fn iter_fields(&self) -> TupleStructFieldIter<'_>

Returns an iterator over the values of the tuple struct’s fields.

fn to_dynamic_tuple_struct(&self) -> DynamicTupleStruct

Creates a new DynamicTupleStruct from this tuple struct.

fn get_represented_tuple_struct_info(&self) -> Option<&'static TupleStructInfo>

Will return None if TypeInfo is not available.

impl<T> TypePath for SamplerPool<T>

where SamplerPool<T>: Any + Send + Sync, T: TypePath + PoolLabel + Component + Clone,

fn type_path() -> &'static str

Returns the fully qualified path of the underlying type.

fn short_type_path() -> &'static str

Returns a short, pretty-print enabled path to the type.

fn type_ident() -> Option<&'static str>

Returns the name of the type, or None if it is anonymous.

fn crate_name() -> Option<&'static str>

Returns the name of the crate the type is in, or None if it is anonymous.

fn module_path() -> Option<&'static str>

Returns the path to the module the type is in, or None if it is anonymous.

impl<T> Typed for SamplerPool<T>

where SamplerPool<T>: Any + Send + Sync, T: TypePath + FromReflect + MaybeTyped + RegisterForReflection + PoolLabel + Component + Clone,

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.