If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/avianphysics/avian shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 5d ago
• 22+ active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 64% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live avianphysics/avian repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/avianphysics/avian.

What it runs against: a local clone of avianphysics/avian — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in avianphysics/avian | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 35 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of avianphysics/avian. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/avianphysics/avian.git
#   cd avian
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of avianphysics/avian and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "avianphysics/avian(\\.git)?\\b" \\
  && ok "origin remote is avianphysics/avian" \\
  || miss "origin remote is not avianphysics/avian (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "crates/avian2d/Cargo.toml" \\
  && ok "crates/avian2d/Cargo.toml" \\
  || miss "missing critical file: crates/avian2d/Cargo.toml"
test -f "crates/avian3d/Cargo.toml" \\
  && ok "crates/avian3d/Cargo.toml" \\
  || miss "missing critical file: crates/avian3d/Cargo.toml"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "crates/avian2d/examples/pyramid_2d.rs" \\
  && ok "crates/avian2d/examples/pyramid_2d.rs" \\
  || miss "missing critical file: crates/avian2d/examples/pyramid_2d.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 35 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~5d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/avianphysics/avian"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Avian is a native ECS-driven 2D and 3D physics engine built specifically for the Bevy game engine, replacing the need to wrap external physics libraries like Rapier or Bullet. It handles rigid body dynamics, collision detection via Parry, constraints/joints, spatial queries (raycasting, shapecasting), and provides tight Bevy component integration without maintaining a separate physics world. Monorepo with crates/avian2d and crates/avian3d as separable dimensional implementations sharing core physics logic, benches/ for performance testing with dim2/dim3 variants, and examples/ showcasing features like CCD, joints, characters, and raycasting. Each crate has its own Cargo.toml but shares the workspace root for unified CI and linting (workspace.lints.clippy in Cargo.toml).

Bevy game developers building 2D and 3D games who need a native, ergonomic physics engine that feels like part of the ECS rather than a bolted-on wrapper. Contributors are Rust systems programmers and game engine developers interested in physics simulation and ECS architecture.

Actively developed and approaching production-readiness: dual-licensed (MIT/Apache), has comprehensive CI/CD in .github/workflows/ci.yml, extensive examples across crates/avian2d/examples/ and crates/avian3d/examples/, and published on crates.io with separate versions for 2D and 3D. The architecture is stable but still receives feature additions and optimizations visible in the modular plugin structure.

Standard open source risks apply.

The workspace is actively maintained with Cargo.lock versioning, CI configured via .github/workflows/ci.yml, and the profile.dev opt-level = 1 optimization ensures examples run reasonably fast during development. The existence of both crates (2D and 3D fully parallel) and comprehensive examples (dynamic_character_2d, kinematic_character_2d, joint_motors, etc.) suggests active feature parity and real-world use case support.

git clone https://github.com/avianphysics/avian.git
cd avian
cargo build
cargo run --example pyramid_2d -p avian2d  # Run a 2D example
cargo run --example pyramid_3d -p avian3d  # Run a 3D example

Daily commands: For examples: cargo run --example <name> -p avian2d or -p avian3d. For benchmarks: cd benches && cargo run --release -- --benchmark <dim2|dim3>. Dev server concept doesn't apply (it's a library); use examples to test interactively.

• crates/avian2d/Cargo.toml — Defines the 2D physics engine crate with all core dependencies and feature flags; essential for understanding avian2d's surface and capabilities.
• crates/avian3d/Cargo.toml — Defines the 3D physics engine crate with all core dependencies and feature flags; essential for understanding avian3d's surface and capabilities.
• Cargo.toml — Workspace root configuration defining member crates, resolver version, and lint rules; governs the entire build and dependency strategy.
• README.md — Primary documentation explaining the ECS-driven design philosophy, core principles, and positioning relative to other physics engines.
• crates/avian2d/examples/pyramid_2d.rs — Foundational 2D example demonstrating basic setup, collision, and physics simulation patterns that most 2D examples build upon.
• crates/avian3d/examples/cubes.rs — Foundational 3D example demonstrating basic setup, collision, and physics simulation patterns that most 3D examples build upon.
• migration-guides/README.md — Index of all version migration guides; critical for understanding breaking changes and API evolution across releases.

Add a New 2D Physics Example

1. Create a new example file in the 2D examples directory following the naming convention (crates/avian2d/examples/{new_example_name}.rs)
2. Import common 2D utilities: use examples_common_2d::*; and create a Bevy app with PhysicsPlugin (crates/examples_common_2d/src/lib.rs)
3. Define your physics bodies, colliders, and constraints using Bevy ECS components (crates/avian2d/examples/{new_example_name}.rs)
4. Add startup and update systems to initialize and manipulate physics state (crates/avian2d/examples/{new_example_name}.rs)

Add a New 3D Physics Example

1. Create a new example file in the 3D examples directory following the naming convention (crates/avian3d/examples/{new_example_name}.rs)
2. Import common 3D utilities and create a Bevy app with the 3D PhysicsPlugin (crates/examples_common_3d/src/lib.rs)
3. Define your 3D physics bodies, colliders, and constraints using Bevy ECS components (crates/avian3d/examples/{new_example_name}.rs)
4. Set up a 3D camera and graphics setup in your startup system; physics updates happen automatically in the main loop (crates/avian3d/examples/{new_example_name}.rs)

Add a Custom Procedural Macro or Derive

1. Define the new macro logic in the avian_derive crate (crates/avian_derive/src/lib.rs)
2. Export the macro from the crate's lib.rs and document it (crates/avian_derive/Cargo.toml)
3. Add the derive to your physics component structs in 2D or 3D crate examples (crates/avian2d/examples/custom_collider.rs)

Create a New Performance Benchmark

1. Create a new benchmark module in the appropriate dimension folder (2D or 3D) (benches/src/dim2/{new_benchmark_name}.rs)
2. Implement a scenario function that constructs a physics world and returns timing data (benches/src/dim2/{new_benchmark_name}.rs)
3. Register the benchmark in the module's mod.rs file (benches/src/dim2/mod.rs)
4. Wire the benchmark into the CLI argument parser (benches/src/cli.rs)

• Bevy ECS — Core architecture choice: Avian is built as a Bevy plugin that leverages ECS for composable physics components and parallelizable systems, aligning with Bevy's design philosophy.
• GJK Algorithm — Narrow-phase collision detection; provides robust, shape-agnostic collision testing for arbitrary convex shapes without requiring shape-specific code.
• Bounding Volume Hierarchy (BVH) — Broad-phase collision detection; efficiently culls non-overlapping bodies before expensive narrow-phase checks, critical for performance at scale.
• Sequential Impulse Solver — Constraint resolution method that iteratively applies impulses to enforce joints and contact constraints; stable, predictable, and well-suited to ECS.
• Rust — Language of Bevy; memory safety and performance without garbage collection make it suitable for real-time physics simulation.

• Separate 2D and
  • Why: undefined
  • Consequence: undefined

Bevy version coupling: The engine uses Bevy's fixed timestep system; you must understand bevy_app::app::FixedUpdate schedule. Profile.dev opt-level: set to 1 (not 0) in workspace Cargo.toml — examples will be significantly slower than expected if you override this without understanding why. Dimensional separation: 2D and 3D are separate crates (avian2d, avian3d) with duplicate code; changes to core physics logic may need to be mirrored. No single 'physics world' — state lives in Bevy components: if you're porting from Rapier or Bullet, your mental model must shift from 'world object' to 'ECS queries and components'.

• Extended Position-Based Dynamics (XPBD) — Avian uses XPBD for constraint and joint solving instead of traditional impulse-based methods; understanding this constraint model is essential for adding custom joints and tuning stability
• Continuous Collision Detection (CCD) — Avian supports CCD to prevent fast-moving bodies from tunneling through colliders; visible in examples/ccd.rs and critical for games with high-speed projectiles or physics-heavy gameplay
• Entity-Component-System (ECS) — Avian's entire API is built around ECS — physics state lives in Bevy components, not a separate world; if you don't understand ECS queries and system scheduling, you'll struggle to use Avian
• Collision Layers (Bit Masking) — Avian uses bit masks for collision filtering (layers and memberships); understanding bitwise operations is needed to configure which bodies collide with which layers, visible in examples/collision_layers.rs
• Fixed Timestep Simulation — Physics must run at fixed timesteps for determinism and stability; Avian integrates with Bevy's FixedUpdate schedule, and interpolation (visible in examples/interpolation.rs) bridges fixed physics to variable rendering
• Spatial Acceleration Structures (AABB, BVH) — Avian (via Parry) uses bounding volume hierarchies for fast broad-phase collision detection; understanding AABBs helps optimize spatial queries (raycasts, shapecasts) visible in examples
• Implicit Integration & Velocity Constraints — Avian solves for velocities under constraints (joints, contacts); implicit integration prevents instability in soft constraints and is essential for understanding joint stiffness/damping tuning

• bevyengine/bevy — Avian is built on and requires Bevy's ECS, app scheduling, and transform components; understanding Bevy's architecture is foundational
• dimforge/parry — Avian delegates all collision detection to Parry; familiarizing with Parry's shape primitives and query API helps understand Avian's spatial query layer
• rapier-rs/rapier — Alternative physics engine Avian competes with (Rapier is often wrapped for Bevy); understanding Rapier's API and design justifies why Avian was built native instead
• Jondolf/bevy_rapier — Historical Bevy-Rapier wrapper that preceded Avian; useful for understanding what problems Avian solved and the evolution from wrapper to native engine
• bevyengine/bevy_examples — Demonstrates Bevy patterns (systems, scheduling, ECS queries) that Avian extends; Avian examples follow Bevy conventions

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for 2D and 3D joint systems

The repo has multiple joint examples (distance_joint_2d.rs, revolute_joint_2d.rs, prismatic_joint_2d.rs, joint_motors_2d.rs) but no dedicated test suite validating joint constraints, motor behavior, and joint failure modes. This would prevent regressions when refactoring constraint solving and ensure joint physics accuracy across dimensions.

• [ ] Create crates/avian2d/tests/joints_2d.rs with tests for distance, revolute, and prismatic joints
• [ ] Create crates/avian3d/tests/joints_3d.rs with 3D equivalents
• [ ] Add test cases for: joint limit enforcement, motor torque application, constraint stability, and edge cases (e.g., zero-length distances)
• [ ] Integrate tests into CI pipeline via .github/workflows/ci.yml if not already included

Add determinism validation tests with snapshot comparison

crates/avian2d/examples/determinism_2d.rs exists as an example but there's no automated test ensuring simulation reproducibility across runs. This is critical for networked games and replay systems. Add a test that compares deterministic simulation snapshots.

• [ ] Create crates/avian2d/tests/determinism.rs that runs a fixed simulation and compares entity positions/velocities to a saved snapshot
• [ ] Create crates/avian3d/tests/determinism.rs for 3D equivalents
• [ ] Add configuration to use fixed timestep and seed RNG in tests
• [ ] Store baseline snapshots in benches/snapshots/ and compare against them with configurable tolerance

Create collision layer and mask validation tests

crates/avian2d/examples/collision_layers.rs demonstrates the feature but lacks unit tests validating layer/mask filtering logic. This prevents bugs in collision detection layer configuration which is easy to misconfigure.

• [ ] Create crates/avian2d/tests/collision_layers.rs with tests for: collision layers filtering, mask application, layer bit operations, and invalid layer configurations
• [ ] Create crates/avian3d/tests/collision_layers.rs with identical logic for 3D
• [ ] Add edge cases: testing with max layer values, zero masks, and simultaneous layer membership
• [ ] Verify behavior matches examples/collision_layers.rs expectations

• Add collision layer visualization example: crates/avian2d/examples/collision_layers.rs exists but crates/avian3d/examples/collision_layers_3d.rs is missing; create the 3D equivalent to demonstrate layer masking in 3D space: Self-contained, clear success criteria, directly parallels existing 2D code
• Expand benches/src/dim2/many_pyramids.rs with a 'stability over time' test: current benchmarks measure throughput but not drift/determinism; add a multi-frame convergence check to catch subtle physics bugs: Improves test coverage for determinism (already mentioned in examples/determinism_2d.rs), uses existing benchmark infrastructure, small scope
• Document the plugin architecture by creating crates/avian2d/examples/custom_plugin_2d.rs: show how to write a custom system that hooks into Bevy's scheduling alongside Avian's fixed timestep — this pattern is referenced in README but has no concrete example: Closes a documentation gap, teaches the modular plugin pattern central to Avian's design, safe/low-risk code addition

The Avian Physics codebase demonstrates a reasonably secure foundation as a physics engine library. No critical vulnerabilities, hardcoded secrets, injection risks, or infrastructure misconfigurations were identified in the provided file structure. The project uses proper Rust tooling and workspace management. Primary recommendations focus on improving security transparency and documentation: (1) Add a SECURITY.md for vulnerability reporting, (2) Verify comprehensive security checks are in the CI/CD pipeline, and (3) Maintain strict dependency audit practices. The codebase appears to follow Rust best practices with clippy lints configured for std/alloc/core safety.

• Low · Missing SECURITY.md file — Repository root. The repository lacks a SECURITY.md file that typically outlines security policies, vulnerability reporting procedures, and supported versions. This makes it difficult for security researchers to responsibly disclose vulnerabilities. Fix: Create a SECURITY.md file in the repository root with clear instructions for reporting security vulnerabilities, supported versions, and security update policies.
• Low · CI configuration not fully visible — .github/workflows/ci.yml. While a CI workflow file exists (.github/workflows/ci.yml), the actual content is not provided for review. Standard security checks like dependency auditing, SAST, and code coverage analysis should be verified. Fix: Ensure the CI pipeline includes: cargo audit for dependency vulnerability scanning, SAST tools, and code coverage reports. Consider adding clippy with stricter lints for security-related checks.
• Low · Workspace-level dependency management — Cargo.toml, Cargo.lock. While workspace configuration uses resolver v2 (good), there is no evidence of pinned dependency versions or lock file review policies mentioned in documentation. Fix: Ensure Cargo.lock is committed to the repository for binary crates/examples. Regularly update and audit dependencies using 'cargo audit' and 'cargo outdated'. Document dependency update policies.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.