Trait valence::ecs::prelude::Bundle

pub unsafe trait Bundle: DynamicBundle + Send + Sync + 'static { }
Expand description

The Bundle trait enables insertion and removal of Components from an entity.

Implementors of the Bundle trait are called ‘bundles’.

Each bundle represents a static set of Component types. Currently, bundles can only contain one of each Component, and will panic once initialised if this is not met.

Insertion

The primary use for bundles is to add a useful collection of components to an entity.

Adding a value of bundle to an entity will add the components from the set it represents to the entity. The values of these components are taken from the bundle. If an entity already had one of these components, the entity’s original component value will be overwritten.

Importantly, bundles are only their constituent set of components. You should not use bundles as a unit of behavior. The behavior of your app can only be considered in terms of components, as systems, which drive the behavior of a bevy application, operate on combinations of components.

This rule is also important because multiple bundles may contain the same component type, calculated in different ways — adding both of these bundles to one entity would create incoherent behavior. This would be unexpected if bundles were treated as an abstraction boundary, as the abstraction would be unmaintainable for these cases. For example, both Camera3dBundle and Camera2dBundle contain the CameraRenderGraph component, but specifying different render graphs to use. If the bundles were both added to the same entity, only one of these two bundles would work.

For this reason, there is intentionally no Query to match whether an entity contains the components of a bundle. Queries should instead only select the components they logically operate on.

Removal

Bundles are also used when removing components from an entity.

Removing a bundle from an entity will remove any of its components attached to the entity from the entity. That is, if the entity does not have all the components of the bundle, those which are present will be removed.

Implementors

Every type which implements Component also implements Bundle, since Component types can be added to or removed from an entity.

Additionally, Tuples of bundles are also Bundle (with up to 15 bundles). These bundles contain the items of the ‘inner’ bundles. This is a convenient shorthand which is primarily used when spawning entities. For example, spawning an entity using the bundle (SpriteBundle {...}, PlayerMarker) will spawn an entity with components required for a 2d sprite, and the PlayerMarker component.

unit, otherwise known as (), is a Bundle containing no components (since it can also be considered as the empty tuple). This can be useful for spawning large numbers of empty entities using World::spawn_batch.

Tuple bundles can be nested, which can be used to create an anonymous bundle with more than 15 items. However, in most cases where this is required, the derive macro Bundle should be used instead. The derived Bundle implementation contains the items of its fields, which all must implement Bundle. As explained above, this includes any Component type, and other derived bundles.

If you want to add PhantomData to your Bundle you have to mark it with #[bundle(ignore)].

use bevy_ecs::{component::Component, bundle::Bundle};

#[derive(Component)]
struct XPosition(i32);
#[derive(Component)]
struct YPosition(i32);

#[derive(Bundle)]
struct PositionBundle {
    // A bundle can contain components
    x: XPosition,
    y: YPosition,
}

// You have to implement `Default` for ignored field types in bundle structs.
#[derive(Default)]
struct Other(f32);

#[derive(Bundle)]
struct NamedPointBundle<T: Send + Sync + 'static> {
    // Or other bundles
    a: PositionBundle,
    // In addition to more components
    z: PointName,

    // when you need to use `PhantomData` you have to mark it as ignored
    #[bundle(ignore)]
    _phantom_data: PhantomData<T>
}

#[derive(Component)]
struct PointName(String);

Safety

Manual implementations of this trait are unsupported. That is, there is no safe way to implement this trait, and you must not do so. If you want a type to implement Bundle, you must use derive@Bundle.

Object Safety§

This trait is not object safe.

Implementations on Foreign Types§

§

impl Bundle for ()

source§

impl Bundle for BossBarBundle

source§

impl Bundle for PlayerListEntryBundle

source§

impl Bundle for ObjectiveBundle

source§

impl Bundle for WeatherBundle

source§

impl Bundle for WorldBorderBundle

§

impl<B0> Bundle for (B0,)
where B0: Bundle,

§

impl<B0, B1> Bundle for (B0, B1)
where B0: Bundle, B1: Bundle,

§

impl<B0, B1, B2> Bundle for (B0, B1, B2)
where B0: Bundle, B1: Bundle, B2: Bundle,

§

impl<B0, B1, B2, B3> Bundle for (B0, B1, B2, B3)
where B0: Bundle, B1: Bundle, B2: Bundle, B3: Bundle,

§

impl<B0, B1, B2, B3, B4> Bundle for (B0, B1, B2, B3, B4)
where B0: Bundle, B1: Bundle, B2: Bundle, B3: Bundle, B4: Bundle,

§

impl<B0, B1, B2, B3, B4, B5> Bundle for (B0, B1, B2, B3, B4, B5)
where B0: Bundle, B1: Bundle, B2: Bundle, B3: Bundle, B4: Bundle, B5: Bundle,

§

impl<B0, B1, B2, B3, B4, B5, B6> Bundle for (B0, B1, B2, B3, B4, B5, B6)
where B0: Bundle, B1: Bundle, B2: Bundle, B3: Bundle, B4: Bundle, B5: Bundle, B6: Bundle,

§

impl<B0, B1, B2, B3, B4, B5, B6, B7> Bundle for (B0, B1, B2, B3, B4, B5, B6, B7)
where B0: Bundle, B1: Bundle, B2: Bundle, B3: Bundle, B4: Bundle, B5: Bundle, B6: Bundle, B7: Bundle,

§

impl<B0, B1, B2, B3, B4, B5, B6, B7, B8> Bundle for (B0, B1, B2, B3, B4, B5, B6, B7, B8)
where B0: Bundle, B1: Bundle, B2: Bundle, B3: Bundle, B4: Bundle, B5: Bundle, B6: Bundle, B7: Bundle, B8: Bundle,

§

impl<B0, B1, B2, B3, B4, B5, B6, B7, B8, B9> Bundle for (B0, B1, B2, B3, B4, B5, B6, B7, B8, B9)
where B0: Bundle, B1: Bundle, B2: Bundle, B3: Bundle, B4: Bundle, B5: Bundle, B6: Bundle, B7: Bundle, B8: Bundle, B9: Bundle,

§

impl<B0, B1, B2, B3, B4, B5, B6, B7, B8, B9, B10> Bundle for (B0, B1, B2, B3, B4, B5, B6, B7, B8, B9, B10)
where B0: Bundle, B1: Bundle, B2: Bundle, B3: Bundle, B4: Bundle, B5: Bundle, B6: Bundle, B7: Bundle, B8: Bundle, B9: Bundle, B10: Bundle,

§

impl<B0, B1, B2, B3, B4, B5, B6, B7, B8, B9, B10, B11> Bundle for (B0, B1, B2, B3, B4, B5, B6, B7, B8, B9, B10, B11)
where B0: Bundle, B1: Bundle, B2: Bundle, B3: Bundle, B4: Bundle, B5: Bundle, B6: Bundle, B7: Bundle, B8: Bundle, B9: Bundle, B10: Bundle, B11: Bundle,

§

impl<B0, B1, B2, B3, B4, B5, B6, B7, B8, B9, B10, B11, B12> Bundle for (B0, B1, B2, B3, B4, B5, B6, B7, B8, B9, B10, B11, B12)
where B0: Bundle, B1: Bundle, B2: Bundle, B3: Bundle, B4: Bundle, B5: Bundle, B6: Bundle, B7: Bundle, B8: Bundle, B9: Bundle, B10: Bundle, B11: Bundle, B12: Bundle,

§

impl<B0, B1, B2, B3, B4, B5, B6, B7, B8, B9, B10, B11, B12, B13> Bundle for (B0, B1, B2, B3, B4, B5, B6, B7, B8, B9, B10, B11, B12, B13)
where B0: Bundle, B1: Bundle, B2: Bundle, B3: Bundle, B4: Bundle, B5: Bundle, B6: Bundle, B7: Bundle, B8: Bundle, B9: Bundle, B10: Bundle, B11: Bundle, B12: Bundle, B13: Bundle,

§

impl<B0, B1, B2, B3, B4, B5, B6, B7, B8, B9, B10, B11, B12, B13, B14> Bundle for (B0, B1, B2, B3, B4, B5, B6, B7, B8, B9, B10, B11, B12, B13, B14)
where B0: Bundle, B1: Bundle, B2: Bundle, B3: Bundle, B4: Bundle, B5: Bundle, B6: Bundle, B7: Bundle, B8: Bundle, B9: Bundle, B10: Bundle, B11: Bundle, B12: Bundle, B13: Bundle, B14: Bundle,

Implementors§

source§

impl Bundle for ClientBundle

source§

impl Bundle for AllayEntityBundle

source§

impl Bundle for AreaEffectCloudEntityBundle

source§

impl Bundle for ArmorStandEntityBundle

source§

impl Bundle for ArrowEntityBundle

source§

impl Bundle for AxolotlEntityBundle

source§

impl Bundle for BatEntityBundle

source§

impl Bundle for BeeEntityBundle

source§

impl Bundle for BlazeEntityBundle

source§

impl Bundle for BlockDisplayEntityBundle

source§

impl Bundle for BoatEntityBundle

source§

impl Bundle for CamelEntityBundle

source§

impl Bundle for CatEntityBundle

source§

impl Bundle for CaveSpiderEntityBundle

source§

impl Bundle for ChestBoatEntityBundle

source§

impl Bundle for ChestMinecartEntityBundle

source§

impl Bundle for ChickenEntityBundle

source§

impl Bundle for CodEntityBundle

source§

impl Bundle for CommandBlockMinecartEntityBundle

source§

impl Bundle for CowEntityBundle

source§

impl Bundle for CreeperEntityBundle

source§

impl Bundle for DolphinEntityBundle

source§

impl Bundle for DonkeyEntityBundle

source§

impl Bundle for DragonFireballEntityBundle

source§

impl Bundle for DrownedEntityBundle

source§

impl Bundle for EggEntityBundle

source§

impl Bundle for ElderGuardianEntityBundle

source§

impl Bundle for EndCrystalEntityBundle

source§

impl Bundle for EnderDragonEntityBundle

source§

impl Bundle for EnderPearlEntityBundle

source§

impl Bundle for EndermanEntityBundle

source§

impl Bundle for EndermiteEntityBundle

source§

impl Bundle for EvokerEntityBundle

source§

impl Bundle for EvokerFangsEntityBundle

source§

impl Bundle for ExperienceBottleEntityBundle

source§

impl Bundle for ExperienceOrbEntityBundle

source§

impl Bundle for EyeOfEnderEntityBundle

source§

impl Bundle for FallingBlockEntityBundle

source§

impl Bundle for FireballEntityBundle

source§

impl Bundle for FireworkRocketEntityBundle

source§

impl Bundle for FishingBobberEntityBundle

source§

impl Bundle for FoxEntityBundle

source§

impl Bundle for FrogEntityBundle

source§

impl Bundle for FurnaceMinecartEntityBundle

source§

impl Bundle for GhastEntityBundle

source§

impl Bundle for GiantEntityBundle

source§

impl Bundle for GlowItemFrameEntityBundle

source§

impl Bundle for GlowSquidEntityBundle

source§

impl Bundle for GoatEntityBundle

source§

impl Bundle for GuardianEntityBundle

source§

impl Bundle for HoglinEntityBundle

source§

impl Bundle for HopperMinecartEntityBundle

source§

impl Bundle for HorseEntityBundle

source§

impl Bundle for HuskEntityBundle

source§

impl Bundle for IllusionerEntityBundle

source§

impl Bundle for InteractionEntityBundle

source§

impl Bundle for IronGolemEntityBundle

source§

impl Bundle for ItemEntityBundle

source§

impl Bundle for ItemDisplayEntityBundle

source§

impl Bundle for ItemFrameEntityBundle

source§

impl Bundle for LeashKnotEntityBundle

source§

impl Bundle for LightningEntityBundle

source§

impl Bundle for LlamaEntityBundle

source§

impl Bundle for LlamaSpitEntityBundle

source§

impl Bundle for MagmaCubeEntityBundle

source§

impl Bundle for MarkerEntityBundle

source§

impl Bundle for MinecartEntityBundle

source§

impl Bundle for MooshroomEntityBundle

source§

impl Bundle for MuleEntityBundle

source§

impl Bundle for OcelotEntityBundle

source§

impl Bundle for PaintingEntityBundle

source§

impl Bundle for PandaEntityBundle

source§

impl Bundle for ParrotEntityBundle

source§

impl Bundle for PhantomEntityBundle

source§

impl Bundle for PigEntityBundle

source§

impl Bundle for PiglinEntityBundle

source§

impl Bundle for PiglinBruteEntityBundle

source§

impl Bundle for PillagerEntityBundle

source§

impl Bundle for PlayerEntityBundle

source§

impl Bundle for PolarBearEntityBundle

source§

impl Bundle for PotionEntityBundle

source§

impl Bundle for PufferfishEntityBundle

source§

impl Bundle for RabbitEntityBundle

source§

impl Bundle for RavagerEntityBundle

source§

impl Bundle for SalmonEntityBundle

source§

impl Bundle for SheepEntityBundle

source§

impl Bundle for ShulkerEntityBundle

source§

impl Bundle for ShulkerBulletEntityBundle

source§

impl Bundle for SilverfishEntityBundle

source§

impl Bundle for SkeletonEntityBundle

source§

impl Bundle for SkeletonHorseEntityBundle

source§

impl Bundle for SlimeEntityBundle

source§

impl Bundle for SmallFireballEntityBundle

source§

impl Bundle for SnifferEntityBundle

source§

impl Bundle for SnowGolemEntityBundle

source§

impl Bundle for SnowballEntityBundle

source§

impl Bundle for SpawnerMinecartEntityBundle

source§

impl Bundle for SpectralArrowEntityBundle

source§

impl Bundle for SpiderEntityBundle

source§

impl Bundle for SquidEntityBundle

source§

impl Bundle for StrayEntityBundle

source§

impl Bundle for StriderEntityBundle

source§

impl Bundle for TadpoleEntityBundle

source§

impl Bundle for TextDisplayEntityBundle

source§

impl Bundle for TntEntityBundle

source§

impl Bundle for TntMinecartEntityBundle

source§

impl Bundle for TraderLlamaEntityBundle

source§

impl Bundle for TridentEntityBundle

source§

impl Bundle for TropicalFishEntityBundle

source§

impl Bundle for TurtleEntityBundle

source§

impl Bundle for VexEntityBundle

source§

impl Bundle for VillagerEntityBundle

source§

impl Bundle for VindicatorEntityBundle

source§

impl Bundle for WanderingTraderEntityBundle

source§

impl Bundle for WardenEntityBundle

source§

impl Bundle for WitchEntityBundle

source§

impl Bundle for WitherEntityBundle

source§

impl Bundle for WitherSkeletonEntityBundle

source§

impl Bundle for WitherSkullEntityBundle

source§

impl Bundle for WolfEntityBundle

source§

impl Bundle for ZoglinEntityBundle

source§

impl Bundle for ZombieEntityBundle

source§

impl Bundle for ZombieHorseEntityBundle

source§

impl Bundle for ZombieVillagerEntityBundle

source§

impl Bundle for ZombifiedPiglinEntityBundle

source§

impl Bundle for AdvancementBundle

source§

impl Bundle for LayerBundle

§

impl<C> Bundle for C
where C: Component,