Bevy Physics 3d Agent Skill

Bevy 3D physics

When to use

Load this when a Bevy app needs simulated 3D bodies (props, impulses, constraints) before choosing a solver. Pair with bevy-character-movement for player motion that should not be a rigid body.

ECS shape

• Components own velocity, mass, and a sphere radius for props you simulate yourself.
• Resources own gravity.
• Systems integrate on FixedUpdate, then separate overlapping spheres. .chain() runs separation after the step.
• Schedule: the fixed step is the clock. A separate solver plugin can replace the integrator when you need joints and a broadphase. This file does not name that plugin's types. Player locomotion stays on bevy-character-movement.

Ownership

| Need | Bevy shape |

| --- | --- |

| Simulated prop | Body plus Transform, integrated on FixedUpdate |

| Player locomotion | bevy-character-movement, not this integrator |

| Joints and ragdolls | A separate solver plugin once those features are required. This file does not name that plugin's types |

| Layers and masks | A Layer component you define, filtered in the overlap system |

Scope

• Gravity, velocity, and sphere overlap are ordinary components stepped on FixedUpdate.
• Joints, ragdolls, and continuous collision belong to a physics solver you add as a plugin. This skill does not call that plugin's types.

Examples

[package]
name = "physics3d"
version = "0.1.0"
edition = "2021"

[dependencies]
bevy = "0.20"

Integrate velocity under gravity, then push overlapping spheres apart. Both systems write Body and Transform, so they run as one chain.

#[derive(Component)]
struct Body {
    velocity: Vec3,
    mass: f32,
    radius: f32,
}

#[derive(Component)]
struct Layer(u32);

#[derive(Resource)]
struct Gravity(Vec3);

fn integrate(
    time: Res<Time<Fixed>>,
    gravity: Res<Gravity>,
    mut bodies: Query<(&mut Transform, &mut Body)>,
) {
    let dt = time.delta_secs();
    for (mut tf, mut body) in &mut bodies {
        body.velocity += gravity.0 * dt;
        tf.translation += body.velocity * dt;
        if tf.translation.y < body.radius {
            tf.translation.y = body.radius;
            body.velocity.y = body.velocity.y.max(0.0);
        }
    }
}

fn separate(mut bodies: Query<(Entity, &mut Transform, &mut Body, &Layer)>) {
    let mut pairs: Vec<(Entity, Entity)> = Vec::new();
    for (a, tf_a, body_a, layer_a) in &bodies {
        for (b, tf_b, body_b, layer_b) in &bodies {
            if a.index() >= b.index() || layer_a.0 != layer_b.0 {
                continue;
            }
            let min = body_a.radius + body_b.radius;
            if tf_a.translation.distance(tf_b.translation) < min {
                pairs.push((a, b));
            }
        }
    }
    for (a, b) in pairs {
        let Ok([(_, mut tf_a, mut body_a, _), (_, mut tf_b, mut body_b, _)]) =
            bodies.get_many_mut([a, b])
        else {
            continue;
        };
        let delta = tf_b.translation - tf_a.translation;
        let dist = delta.length();
        let min = body_a.radius + body_b.radius;
        if dist >= min || dist == 0.0 {
            continue;
        }
        let normal = delta / dist;
        let push = (min - dist) * 0.5;
        tf_a.translation -= normal * push;
        tf_b.translation += normal * push;
        let rel = (body_b.velocity - body_a.velocity).dot(normal);
        if rel < 0.0 {
            let inv_a = 1.0 / body_a.mass.max(0.001);
            let inv_b = 1.0 / body_b.mass.max(0.001);
            let impulse = -rel / (inv_a + inv_b);
            body_a.velocity -= normal * impulse * inv_a;
            body_b.velocity += normal * impulse * inv_b;
        }
    }
}

pub struct PhysicsPlugin;

impl Plugin for PhysicsPlugin {
    fn build(&self, app: &mut App) {
        app.insert_resource(Gravity(Vec3::new(0.0, -9.8, 0.0)))
            .add_systems(FixedUpdate, (integrate, separate).chain());
    }
}

An impulse adds velocity. Spawn places a crate above the ground plane so the next fixed step can fall.

#[derive(Component)]
struct Body {
    velocity: Vec3,
    mass: f32,
    radius: f32,
}

fn kick(mut bodies: Query<&mut Body>) {
    for mut body in &mut bodies {
        body.velocity += Vec3::new(0.0, 6.0, 2.0);
    }
}

fn spawn_crate(mut commands: Commands) {
    commands.spawn((
        Transform::from_xyz(0.0, 2.0, 0.0),
        Body {
            velocity: Vec3::ZERO,
            mass: 2.0,
            radius: 0.5,
        },
    ));
}

A ray against the ground plane reports the hit point without a physics crate.

fn ray_ground(origin: Vec3, dir: Vec3) -> Option<Vec3> {
    if dir.y >= 0.0 {
        return None;
    }
    let t = -origin.y / dir.y;
    if t < 0.0 {
        return None;
    }
    Some(origin + dir * t)
}

fn aim_at_ground(aimers: Query<&Transform>, mut gizmos: Gizmos) {
    for tf in &aimers {
        let dir = tf.forward().as_vec3();
        if let Some(hit) = ray_ground(tf.translation, dir) {
            gizmos.sphere(hit, 0.1, Color::srgb(1.0, 0.2, 0.2));
        }
    }
}

Expert Knowledge Delta

Target: Bevy 0.20+.

Core ECS types: Component, Resource, Query, Commands, Startup, Update, Fixed / FixedMain (bevy::time), .chain(), Plugin, DefaultPlugins, MinimalPlugins. Messages and observers are an ownership slot. See bevy-events-messaging for their APIs. Systems run in parallel unless .chain() orders the ones that conflict.

Who owns state

| Piece | Owner | Who may mutate | Schedule |

| --- | --- | --- | --- |

| Data on one entity | Component | One system via Query | Update or FixedMain |

| One value for the whole app | Resource | One system | Startup to insert, then the schedule that reads it |

| Spawn | Commands | The spawning system | Startup for the initial world; later schedules for runtime spawn |

| Order that must not race | .chain() | The chained systems only | Same schedule |

| Plugin boundary | Plugin | build registers systems and resources | Before the app runs |

Borrow rule: two systems that both mutably query the same component must be ordered (.chain()) or split so only one writes. Unrelated systems stay parallel. That is the ECS page rule, not a guess at a system-set API.

Decision

| If you need | Do this | Do not |

| --- | --- | --- |

| Per-entity data | Component + Query | A field stored outside a component |

| App-wide config or clock | Resource | Copy the value onto every entity |

| Stable simulation step | FixedMain and the Fixed clock | Tie simulation to raw frame Update |

| Startup spawn | Commands in Startup | Spawn from a render system |

| Cross-system notice that is not shared state | Message or observer slot in bevy-events-messaging | A new event type invented in this file |

| Props under gravity | Body on FixedUpdate | Treating FixedUpdate itself as a solver |

Load references/ecs-ownership.md for the ownership table.

NEVER

• Do not pin /0.20.0/ in docs URLs. WHY: links stay on latest; the 0.20 target is stated once in prose.
• Do not name a third-party solver's types as Bevy APIs. WHY: the bevy feature list has no physics-engine feature.
• Do not pin a solver crate in this skill. Check that crate's own docs before naming its plugin path.
• Do not treat Fixed / FixedMain as a physics engine. WHY: bevy::time documents a clock, not a solver.
• Do not mutably query the same body component from two unordered systems. WHY: systems run in parallel unless .chain() orders them.

Reference

Official links stay on bevy.org. The library pin on bevy-master stays 0.20. The 0.20 feature list has no physics-engine feature.

Official Documentation

• Assets - Official asset catalog. No physics plugin is named from it here.
• Examples - Example tree on the latest branch.
• Quick Start: plugins - Plugin, DefaultPlugins, MinimalPlugins, and third-party add_plugins.
• ECS - Component, Query, and .chain(). Fixed / FixedMain are a clock, not a solver.

Related Skills

Prerequisites

• bevy-master - ECS ownership and the fixed-timestep schedule names.

Complements

• bevy-character-movement - Player locomotion that should not be a rigid body.

Downstream / consumers

• Combat, racing, and shooter skills cover hits, vehicles, and shots.

Master

• bevy-master - Bevy router.