Bundle

A bundle is a typed group of components inserted as a unit. Tuples of components implement Bundle automatically, so most user code never types the word.

The simple case

commands.spawn((Health(100), Position(Vec3::ZERO), Velocity(Vec3::X)));

The tuple (Health, Position, Velocity) is a bundle. spawn adds all three components in one structural change instead of three.

Nested bundles

Bundles compose:

commands.spawn((
    PlayerBundle::default(),
    Transform::default(),
    Visibility::default(),
));

A custom Bundle-deriving struct can hold any number of components plus other bundles.

Custom bundles via derive

use bevy::prelude::*;

#[derive(Bundle, Default)]
struct PlayerBundle {
    health: Health,
    position: Position,
    velocity: Velocity,
}

This was the canonical pattern before required components. New code often uses required components instead:

#[derive(Component, Default)]
#[require(Health, Position, Velocity)]
struct Player;

Spawning Player::default() then auto-inserts the required components. The Bundle derive is still useful when you want a parameterized constructor.

What can be a bundle

• A single component (every Component impls Bundle).
• A tuple of bundles, up to 16 elements.
• A struct deriving Bundle.

A bundle is not a runtime value — it's compiled into a BundleInfo that lists the component IDs.

See also

• Component — what's in a bundle.
• bevy_ecs — crates/bevy_ecs/src/bundle/.