What are the default units in Avian?

[B0ryskart0n]

I'd like to clarify what units does avian2d use to simulate dynamic bodies.

I'm mostly confused about gravity here. The docs mention default gravitational acceleration to be 9.81$\frac{m}{s^2}$, but I think it might actually be in $\frac{px}{s^2}$.

If so, then what is the purpose of defining the PIXELS_PER_METER constant?
Is there a physical concept within avian that actually uses meters and not pixels? (I am pretty sure that both Position and Velocity work in px)?
Or should I just treat the underlying physics here like swapping each [m] with [px], like in the definiton of Newton [N] for example: $N \coloneq \frac{kg \cdot px}{s^2}$

An additional question arises, what is the default mass unit?

[Jondolf]

Avian (and physics engines in general) don't really have specific physical units. The main thing is just that they should be dimensionally consistent with real-world physics, for example velocity is "distance units per time units", and mass is defined as "volume units times density units". Depending on the scale of the world, you could treat "distance units" as meters, or centimeters, or pixels; you just need to consider how this affects other units like mass, since volume of course depends on your chosen distance unit.

In practice, I strongly recommend most games to use SI units and MKS (meters, kilograms, seconds) unless you're working at small or large enough scales where using meters would lead to very small or very large values. For example, a tiny car game might prefer that 1 unit = 1 cm, while a planet simulation might want astrological units. But for most games where object sizes are naturally expressed in meters, it is generally the most intuitive option from a physics perspective.

The problem in 2D is that the default 2D camera assumes that 1 unit = 1 pixel, so if you're using meters, 1 meter = 1 pixel. This obviously isn't what you want for most games. You have roughly three options:

1. Scale the camera's projection such that you can use meters for your game world, and the visual result is just scaled up to match your expected pixels-per-meter scaling factor. This is generally the best option from a simulation standpoint (also see Box2D's recommendation), unless it's important to use actual pixels.
2. Keep the camera and your rendered objects as-is, but scale all physics inputs and outputs to match your expected pixels-per-meter scaling factor. This can get quite inconvenient and error-prone pretty fast.
3. Use pixels for both visuals and physics. This can lead to very large values for masses and forces, as their units are also derived from distance being in pixels.

I would typically recommend (1) if you don't need pixels for gameplay reasons, and (3) otherwise.

If you do pick (3), it's recommended to set the PhysicsLengthUnit. It does not scale any actual values in the simulation, but it configures some internal thresholds and tolerances to better match the scale of your world. By default, the physics is tuned to work best with dynamic objects whose dimensions are roughly in the range of 0.1-10 units (typically meters), but with pixels your object sizes can easily be tens or hundreds of pixels.

[B0ryskart0n]

Many thanks for taking the time for this extended explanation.

I'm creating a real-ish game and I'd like to think in SI units so I can calculate forces, masses, etc. on a piece of paper and apply those scenarios as-is in the game.
However, the game is pixel art, so I'm keeping everything pixel perfect, and so I don't know exactly how to balance your suggestions. Scaling the camera projection might conflict with this art style.

Would you suggest then to operate on pixels and each time when dealing with length units translate back and forth?
Example below:

use avian2d::prelude::*;
use bevy::prelude::*;

const PIXELS_PER_METER: f32 = 16.0;
const METERS_PER_PIXEL: f32 = 1.0 / PIXELS_PER_METER;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins.set(ImagePlugin::default_nearest()))
        .add_plugins(PhysicsPlugins::default().with_length_unit(PIXELS_PER_METER))
        .insert_resource(Gravity(-10.0 * Vec2::Y * PIXELS_PER_METER)) // Adjusting the gravity units
        .add_systems(Startup, startup)
        .add_systems(FixedUpdate, log_state)
        .run();
}

fn log_state(q_bodies: Query<(&ComputedMass, &LinearVelocity, &Transform)>) {
    q_bodies.iter().for_each(|(mass, velocity, transform)| {
        println!(
            "{}, {}, {}",
            mass.value(),
            velocity.y * METERS_PER_PIXEL,
            transform.translation.y * METERS_PER_PIXEL
        );
    })
}

fn startup(mut commands: Commands) {
    commands.spawn((
        RigidBody::Dynamic,
        Transform::from_translation(10.0 * Vec3::X * PIXELS_PER_METER), // 10m to the right
        Collider::rectangle(1.0 * PIXELS_PER_METER, 1.0 * PIXELS_PER_METER), // 1m^2
        ColliderDensity(METERS_PER_PIXEL.powf(2.0)),                    // density = 1 kg/m^2
    ));
}

Is .with_length_unit() necessary there?

Or would you suggest a different approach?

[B0ryskart0n]

After some further research I now understand fully what you suggested in (1). Using https://docs.rs/bevy_camera/0.18.0/bevy_camera/struct.OrthographicProjection.html#structfield.scale does exactly (I think) what I need.
Setting scale: METERS_PER_PIXEL does the trick and now all the unitless physical quantities can be interpreted in SI.
One just needs to remember that sprite sizes, etc. will be in meters and not in pixels, so one can use https://docs.rs/bevy/latest/bevy/sprite/struct.Sprite.html#structfield.custom_size.