Struct Forces

pub struct Forces { /* private fields */ }

A helper QueryData for applying forces, impulses, and accelerations to dynamic rigid bodies.

For constant forces that persist across time steps, consider using components like ConstantForce instead.

See the module-level documentation for more general information about forces in Avian.

Usage

To use Forces, add it to a Query (without & or &mut), and use the associated methods to apply forces, impulses, and accelerations to the rigid bodies.

fn apply_forces(mut query: Query<Forces>) {
    for mut forces in &mut query {
        // Apply a force of 10 N in the positive Y direction to the entity.
        forces.apply_force(Vec2::new(0.0, 10.0));
    }
}

The force is applied continuously during the physics step, and cleared automatically after the step is complete.

By default, applying forces to sleeping bodies will wake them up. If this is not desired, the non_waking method can be used to fetch a NonWakingForcesItem that allows applying forces to a body without waking it up.

// Apply a force without waking up the body if it is sleeping.
forces.non_waking().apply_force(force);

Forces can also apply forces and impulses at a specific point in the world. If the point is not aligned with the center of mass, it will apply a torque to the body.

// Apply an impulse at a specific point in the world.
// Unlike forces, impulses are applied immediately to the velocity.
forces.apply_linear_impulse_at_point(force, point);

As an example, you could implement radial gravity that pulls rigid bodies towards the world origin with a system like the following:

fn radial_gravity(mut query: Query<(Forces, &GlobalTransform)>) {
    for (mut forces, global_transform) in &mut query {
        // Compute the direction towards the center of the world.
        let direction = -global_transform.translation().normalize_or_zero();
        // Apply a linear acceleration of 9.81 m/s² towards the center of the world.
        forces.apply_linear_acceleration(direction.truncate() * 9.81);
    }
}

Trait Implementations

impl QueryData for Forces

SAFETY: we assert fields are readonly below

unsafe fn fetch<'__w, '__s>( _state: &'__s Self::State, _fetch: &mut <Self as WorldQuery>::Fetch<'__w>, _entity: Entity, _table_row: TableRow, ) -> Self::Item<'__w, '__s>

SAFETY: we call fetch for each member that implements Fetch.

const IS_READ_ONLY: bool = false

True if this query is read-only and may not perform mutable access.

type ReadOnly = ForcesReadOnly

The read-only variant of this QueryData, which satisfies the ReadOnlyQueryData trait.

type Item<'__w, '__s> = ForcesItem<'__w, '__s>

The item returned by this WorldQuery This will be the data retrieved by the query, and is visible to the end user when calling e.g. Query<Self>::get.

fn shrink<'__wlong: '__wshort, '__wshort, '__s>( item: Self::Item<'__wlong, '__s>, ) -> Self::Item<'__wshort, '__s>

This function manually implements subtyping for the query items.

fn provide_extra_access( state: &mut Self::State, access: &mut Access, available_access: &Access, )

Offers additional access above what we requested in update_component_access. Implementations may add additional access that is a subset of available_access and does not conflict with anything in access, and must update access to include that access.

impl ReleaseStateQueryData for Forces

where for<'__a> Read<Position>: ReleaseStateQueryData, for<'__a> Read<Rotation>: ReleaseStateQueryData, for<'__a> Write<LinearVelocity>: ReleaseStateQueryData, for<'__a> Write<AngularVelocity>: ReleaseStateQueryData, for<'__a> Read<ComputedMass>: ReleaseStateQueryData, for<'__a> Read<ComputedAngularInertia>: ReleaseStateQueryData, for<'__a> Read<ComputedCenterOfMass>: ReleaseStateQueryData, for<'__a> Option<Read<LockedAxes>>: ReleaseStateQueryData, for<'__a> Write<VelocityIntegrationData>: ReleaseStateQueryData, for<'__a> Write<AccumulatedLocalAcceleration>: ReleaseStateQueryData, for<'__a> Option<Write<SleepTimer>>: ReleaseStateQueryData, for<'__a> Has<Sleeping>: ReleaseStateQueryData,

fn release_state<'__w>(_item: Self::Item<'__w, '_>) -> Self::Item<'__w, 'static>

Releases the borrow from the query state by converting an item to have a 'static state lifetime.

impl WorldQuery for Forces

unsafe fn set_archetype<'__w, '__s>( _fetch: &mut <Self as WorldQuery>::Fetch<'__w>, _state: &'__s Self::State, _archetype: &'__w Archetype, _table: &'__w Table, )

SAFETY: we call set_archetype for each member that implements Fetch

unsafe fn set_table<'__w, '__s>( _fetch: &mut <Self as WorldQuery>::Fetch<'__w>, _state: &'__s Self::State, _table: &'__w Table, )

SAFETY: we call set_table for each member that implements Fetch

const IS_DENSE: bool = true

Returns true if (and only if) every table of every archetype matched by this fetch contains all of the matched components.

type Fetch<'__w> = ForcesFetch<'__w>

Per archetype/table state retrieved by this WorldQuery to compute Self::Item for each entity.

type State = ForcesState

State used to construct a Self::Fetch. This will be cached inside QueryState, so it is best to move as much data / computation here as possible to reduce the cost of constructing Self::Fetch.

fn shrink_fetch<'__wlong: '__wshort, '__wshort>( fetch: <Forces as WorldQuery>::Fetch<'__wlong>, ) -> <Forces as WorldQuery>::Fetch<'__wshort>

This function manually implements subtyping for the query fetches.

unsafe fn init_fetch<'__w, '__s>( _world: UnsafeWorldCell<'__w>, state: &'__s Self::State, _last_run: Tick, _this_run: Tick, ) -> <Self as WorldQuery>::Fetch<'__w>

Creates a new instance of Self::Fetch, by combining data from the World with the cached Self::State. Readonly accesses resources registered in WorldQuery::update_component_access.

fn update_component_access(state: &Self::State, _access: &mut FilteredAccess)

Adds any component accesses used by this WorldQuery to access.

fn init_state(world: &mut World) -> ForcesState

Creates and initializes a State for this WorldQuery type.

fn get_state(components: &Components) -> Option<ForcesState>

Attempts to initialize a State for this WorldQuery type using read-only access to Components.

fn matches_component_set( state: &Self::State, _set_contains_id: &impl Fn(ComponentId) -> bool, ) -> bool

Returns true if this query matches a set of components. Otherwise, returns false.