Module plugin 

Helpers to network avian components.

Some subtle footguns with avian replication:

• AvianReplicationMode::Position is the preferred mode. Position and Rotation are the canonical simulation state. By default, synchronization is one-way from those components to Transform, so gameplay should move physics bodies through Position and Rotation.
• for Predicted entities, your Position is replicated as Confirmed<Position>. This triggers an immediate rollback on the client which inserts the correct Position.
• for Interpolated entities, it is possible that only one of Position or Rotation gets added (and not both at the same time). This can happen if Rotation doesn’t get updated frequently for your entity, since we insert the real component only after receiving two remote updates. This can cause issues because the sync_pos_to_transform system from avian only does the sync from Position/Rotation -> Transform when BOTH are present on the same time. So you might be stuck with a Transform::default() for a short-while, until both Position/Rotation are present on the entity. For that reason it’s best to add rendering components on Interpolated entities only when BOTH Position and Rotation are present.
• Inserting RigidBody on an entity automatically inserts Position/Rotation/Transform on it. For that reason you do NOT want to add RigidBody on interpolated entities because it’s going to display the entity at Transform::default() until the first interpolation updates are received. (And also because you don’t want any avian systems to run for Interpolated entities)
• Do not forget to disable some of the avian plugins!

PhysicsPlugins::default()
    .build()
    // disable the position<>transform sync plugins as it is handled by lightyear_avian
    .disable::<PhysicsTransformPlugin>()
    // FrameInterpolation handles interpolating Position and Rotation
    .disable::<PhysicsInterpolationPlugin>()

Position mode scheduling

When frame interpolation and correction are enabled, the important ordering is:

PreUpdate:
  receive replication -> rollback and replay -> repair frame history

RunFixedMainLoop (before the fixed loop):
  restore canonical Position/Rotation
  -> optionally canonicalize Transform for transform-driven FixedUpdate gameplay

FixedPostUpdate (for every fixed tick):
  optionally import an authored Transform
  -> Avian physics
  -> optionally copy Position/Rotation back to Transform
  -> prediction history + frame history

PostUpdate:
  frame-interpolate Position/Rotation
  -> apply visual correction to Position/Rotation
  -> copy changed Position/Rotation to Transform
  -> propagate Transform

The restore step prevents the visual values written in the previous PostUpdate from entering the next simulation tick. Transform-to-position synchronization is disabled by default, so a stale Transform cannot overwrite rollback-corrected physics state. Set AvianReplicationMode::Position { sync_to_transform: true } only when gameplay intentionally authors Transform during fixed ticks.

Visual correction uses frame-interpolation rules and history. Registering correction with add_correction installs the frame-interpolation plugin automatically, and rollback adds FrameInterpolate when it stores the previous visual value. If neither visual feature is wanted, omit correction; rollback then snaps directly to canonical physics state.

Position mode automatically registers velocity-aware Hermite interpolation for the (Position, Rotation, LinearVelocity, AngularVelocity) bundle. Delayed interpolation, frame interpolation, and visual correction select it whenever all four components are present. The per-component rules remain useful for archetypes that do not contain the complete bundle. Velocities use linear fallback rules there, and all four components receive visual correction (linear error decay for velocities, which do not implement Ease).

By default, Position mode also registers Position, Rotation, LinearVelocity, and AngularVelocity for filtered rigid-body replication and prediction. Position and Rotation get linear interpolation, correction, and a small default rollback tolerance. Set LightyearAvianPlugin::register_physics_components to false when the application owns these registrations, for example to use app.component::<C>().replicate().predict().with_rollback_condition(...) or deterministic input-only replication. !

Structs

LightyearAvianPlugin

Plugin that integrates Avian with Lightyear for networked physics replication.

Enums

AvianReplicationMode

Indicate which components you are replicating over the network