avian_fdm 0.1.0

6-DoF Flight Dynamics Model for Bevy + Avian 0.6
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

[![License: LGPL-3.0+](https://img.shields.io/badge/license-LGPL--3+-blue.svg)](LICENSE)
[![ci](https://github.com/viccuad/avian_fdm/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/viccuad/avian_fdm/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/avian_fdm)](https://crates.io/crates/avian_fdm)
[![docs.rs](https://img.shields.io/docsrs/avian_fdm)](https://docs.rs/avian_fdm)

# avian_fdm

**Avian FDM** is 6-DoF Flight Dynamics Model plugin for
[Bevy](https://bevyengine.org/) + [Avian](https://crates.io/crates/avian3d).

---

## Example

Small recording of the provided J-3 Cub visual example.
First a controlled turn to starboard, then a harsh climb into a high AoA stall,
departing, diving, and recovering.

https://github.com/user-attachments/assets/529451a4-5d66-4297-af42-f22bafc50001

## Design

`avian_fdm` turns an Avian rigid-body hierarchy into a physically plausible
aircraft. You build your aircraft by assembling `AeroZone` entities around
an `AircraftCoreBundle` root.

Each physics step, the `avian_fdm` plugin evaluates aerodynamic and propulsive
forces for every `AeroZone` and accumulates them into Avian's
`ConstantForce`/`ConstantTorque` on the root body. Avian's integrator then
advances the state forward, `avian_fdm` never writes to position, velocity, or
orientation directly.

Mass, centre of gravity, and the full inertia tensor are computed automatically
by Avian from `ColliderDensity` on each child collider. In addition, several
emergent behaviors appear when computing the AeroZones together.

## Features

- ISA atmosphere (0-20 km) with density, pressure, temperature, viscosity
- Per-zone lift, drag, and side-force from tabulated coefficients (1D or 2D)
  - Reynolds-number-dependent coefficient lookup
  - Post-stall aerodynamics via Viterna-Corrigan extrapolation
- Pitch, roll, and yaw damping (per-zone or whole-aircraft LOD fallback)
- Induced drag (Oswald span efficiency)
- Zone-based damage/failure model with graceful degradation
- Automatic mass, CG, and inertia tensor from collider geometry
- Debug gizmo overlays for forces, moments, zones, and colliders
- Supports both avian3d f32 and f64 backends

### Emergent behavior

The zone-based architecture produces physically correct behaviors without
explicit global coefficients. Forces and moment arms are computed at each
zone's position, and Avian recomputes mass/CG/inertia from colliders. 
The following appear naturally: Stall, wing drop, snap roll, Spin autorotation,
Dutch roll, phugoid, short-period, spiral mode, Adverse yaw, Control authority,
Damage effects, and others.

See the lib.rs documentation for the complete list of emergent behaviors.

## Quick start

Add dependencies to `Cargo.toml`:

```toml
[dependencies]
avian_fdm              = "0.1"
avian_fdm_j3cub_jsbsim = "0.1"
avian3d                = "0.6"
bevy                   = "0.18"
```

Spawn the reference J-3 Cub aircraft:

```rust,ignore
use avian_fdm::prelude::*;
use avian_fdm_j3cub_jsbsim::presets::j3cub;
use avian3d::prelude::{LinearVelocity, PhysicsPlugins};
use bevy::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(PhysicsPlugins::default())
        .add_plugins(AircraftFdmPlugin::default())
        .add_systems(Startup, spawn)
        .run();
}

fn spawn(mut commands: Commands) {
    let root = j3cub::spawn(
        &mut commands,
        Transform::from_xyz(0.0, 300.0, 0.0),
    );
    commands.entity(root).insert(LinearVelocity(Vec3::new(27.0, 0.0, 0.0)));
}
```


## Feature flags

| Feature | Default | Description |
|---|---|---|
| `f32` | yes | Avian3d f32 physics backend (standard Bevy precision) |
| `f64` | -- | Avian3d f64 physics backend (mutually exclusive with f32) |
| `debug-plugin` | yes | Bevy Gizmo overlays for forces, moments, and zones |

Exactly one of `f32` or `f64` must be enabled. They are mutually exclusive.
For f64, use `default-features = false, features = ["f64"]`.

The JSBSim-derived J-3 Cub reference aircraft is in the separate
`avian_fdm_j3cub_jsbsim` crate (GPL-3.0-only, due to JSBSim data provenance).

## Version compatibility

| avian_fdm | Bevy | avian3d |
|---|---|---|
| 0.1 | 0.18 | 0.6 |

## License

`avian_fdm` is licensed under [LGPL-3.0-or-later](LICENSE).

`avian_fdm_j3cub_jsbsim` is licensed under GPL-3.0-only (JSBSim-derived data).