# awtterpip/bevy_oxr architecture

> Architecture diagram of the GitHub repository awtterpip/bevy_oxr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/awtterpip/bevy_oxr
- Repository: https://github.com/awtterpip/bevy_oxr

## Overview

##### Project Type and Purpose
- This is a Rust Cargo workspace providing a modular, plugin-driven extension (“Bevy Mod XR”) to the Bevy game engine.
- It delivers a core XR abstraction crate plus two backend crates (OpenXR and WebXR) and a utilities crate.
- Its goal is to let Bevy apps easily add VR/AR support via OpenXR on desktop and WebXR in the browser.

##### File Structure Overview
- Root: workspace Cargo.toml, CI (.github/workflows), Nix files (flake.nix, default.nix), xbuild for cross-compiling.
- crates/
- bevy_xr — core, engine-agnostic XR types & traits (actions, sessions, spaces, camera, hands).
- bevy_openxr — OpenXR backend plugin, with sub-modules for init, sessions, action binding, rendering (Vulkan & D3D12), features (handtracking, overlay, passthrough), examples.
- bevy_webxr — WebXR backend plugin for browser/WebAssembly.
- bevy_xr_utils — optional utilities (hand gizmos, tracking & transform helpers, predefined action sets).

##### Key Insights from README
- Primary support for OpenXR (desktop) with future WebXR support.
- Examples demonstrate plugin usage (`3d_scene`, `actions`, `overlay`, etc.).
- External runtime dependency: system’s OpenXR loader (Linux package) and browser WebXR APIs.

a. Main Components to Show
- User’s Bevy Application
- Bevy Engine Core (ECS, rendering, asset pipelines)
- bevy_xr (core abstraction layer)
- Backend plugins
- bevy_openxr → OpenXR runtime → GPU driver (Vulkan/D3D12) → hardware
- bevy_webxr → Browser WebXR API → WebGL/WebGPU → hardware
- bevy_xr_utils (optional toolkit layer)
- Examples/project binaries
- Build & CI layer (Cargo workspace, .cargo config, Nix, CI workflows)

b. Relationships & Data Flows
- Your Bevy app depends on bevy_xr_utils (opt-in) and on exactly one backend plugin (bevy_openxr or bevy_webxr).
- bevy_xr provides the Plugin trait and shared resources (XRSession, XRActions, XRSpaces).
- Backend plugins implement those abstractions, register systems into the Bevy App.
- At runtime, plugin systems call into the OpenXR loader or browser WebXR to:
- Initialize sessions
- Synchronize input actions
- Acquire swapchains, render via Vulkan/D3D12 or WebGL/WebGPU
- Poll events and update ECS resources
- bevy_xr_utils hooks into those shared resources to provide gizmos and utility transforms.

c. Architectural Patterns & Principles
- Modular crate separation: core abstraction vs. backends vs. utilities.
- Plugin architecture leveraging Bevy’s ECS and schedule system.
- Feature-gated modules for optional XR features (hand tracking, overlays, passthrough).
- Graphics adapter pattern: separate renderer implementations behind a common graphics trait.

d. Key Technologies & Libraries
- Rust & Cargo workspaces
- Bevy game engine (ECS, rendering pipeline)
- OpenXR loader/runtime
- Vulkan & Direct3D12 graphics APIs
- WebXR API in browsers, WebAssembly target
- Nix/flakes and xbuild for reproducible builds & cross-compilation
- GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Bevy Application"
        App["User's Bevy App"]:::app
    end

    %% Engine Core
    subgraph "Bevy Engine Core"
        ECS["ECS & Rendering Core"]:::engine
    end

    App -->|"register plugins"| ECS

    %% Core Abstraction Layer
    subgraph "Core Abstraction (bevy_xr)"
        XRCore["bevy_xr"]:::core
        subgraph "Modules"
            Actions["actions.rs"]:::coreModule
            Session["session.rs"]:::coreModule
            Spaces["spaces.rs"]:::coreModule
            Types["types.rs"]:::coreModule
            Camera["camera.rs"]:::coreModule
            Hands["hands.rs"]:::coreModule
        end
    end
    App -->|"add_plugin"| XRCore

    %% Utilities Layer
    subgraph "Utilities (bevy_xr_utils)"
        UtilsCore["bevy_xr_xr_utils"]:::util
        HG["hand_gizmos.rs"]:::utilModule
        TU["tracking_utils.rs"]:::utilModule
        TR["transform_utils.rs"]:::utilModule
        PA["xr_utils_actions.rs"]:::utilModule
    end
    App -->|"opt-in utils"| UtilsCore

    %% Backend Plugins
    subgraph "Backend Plugins"
        subgraph "OpenXR Plugin (bevy_openxr)"
            OXCore["bevy_openxr"]:::backend
            subgraph "Init & Session"
                Init["init.rs"]:::backendModule
                SessionO["session.rs"]:::backendModule
            end
            subgraph "Action Binding"
                ActionBind["action_binding.rs"]:::backendModule
                SetAtt["action_set_attaching.rs"]:::backendModule
                SetSync["action_set_syncing.rs"]:::backendModule
            end
            subgraph "Features"
                HandFeat["handtracking.rs"]:::backendModule
                OverlayFeat["overlay.rs"]:::backendModule
                PassFeat["passthrough.rs"]:::backendModule
            end
            subgraph "Graphics"
                Graphics["graphics.rs"]:::backendModule
                Vulkan["vulkan.rs"]:::backendModule
                D3D12["d3d12.rs"]:::backendModule
            end
            subgraph "Runtime"
                Poll["poll_events.rs"]:::backendModule
                RenderO["render.rs"]:::backendModule
            end
            subgraph "Core Types & Helpers"
                OXTypes["types.rs"]:::backendModule
                Helpers["helper_traits.rs"]:::backendModule
                Resources["resources.rs"]:::backendModule
                SpacesO["spaces.rs"]:::backendModule
            end
            subgraph "Examples"
                Examples["examples/"]:::examples
            end
        end
        subgraph "WebXR Plugin (bevy_webxr)"
            WebXR["bevy_webxr"]:::backend
            Mod["mod.rs"]:::backendModule
        end
    end

    App -->|"choose backend"| OXCore
    App -->|"choose backend"| WebXR

    %% External Dependencies
    subgraph "External Dependencies"
        OpenXRLoader["OpenXR Loader"]:::external
        BrowserAPI["Browser WebXR API"]:::external
        GPU["GPU Driver\n(Vulkan/D3D12/WebGL/WebGPU)"]:::external
        Hardware["Hardware"]:::external
    end

    Poll -->|"poll events"| OpenXRLoader
    ActionBind -->|"sync actions"| OpenXRLoader
    RenderO -->|"frame render"| GPU
    GPU --> Hardware
    Mod -->|"calls WebXR API"| BrowserAPI
    BrowserAPI -->|"render via WebGL/WebGPU"| GPU

    XRCore -->|"defines Plugin trait\n& shared resources"| OXCore
    XRCore -->|"defines Plugin trait\n& shared resources"| WebXR

    UtilsCore -->|"hooks into\nshared resources"| XRCore

    %% Build & CI Layer
    subgraph "Build & CI"
        Cargo["Cargo.toml"]:::build
        Config[".cargo/config.toml"]:::build
        CI[".github/workflows/ci.yaml"]:::build
        Flake["flake.nix"]:::build
        NixDefault["default.nix"]:::build
        Xbuild["xbuild/default.nix"]:::build
    end

    Cargo --> XRCore
    Cargo --> OXCore
    Cargo --> WebXR
    Cargo --> UtilsCore

    %% Click Events
    click XRCore "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_xr/src/lib.rs"
    click Actions "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_xr/src/actions.rs"
    click Session "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_xr/src/session.rs"
    click Spaces "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_xr/src/spaces.rs"
    click Types "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_xr/src/types.rs"
    click Camera "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_xr/src/camera.rs"
    click Hands "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_xr/src/hands.rs"
    click OXCore "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_openxr/src/lib.rs"
    click Init "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_openxr/src/openxr/init.rs"
    click SessionO "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_openxr/src/openxr/session.rs"
    click ActionBind "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_openxr/src/openxr/action_binding.rs"
    click SetAtt "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_openxr/src/openxr/action_set_attaching.rs"
    click SetSync "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_openxr/src/openxr/action_set_syncing.rs"
    click HandFeat "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_openxr/src/openxr/features/handtracking.rs"
    click OverlayFeat "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_openxr/src/openxr/features/overlay.rs"
    click PassFeat "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_openxr/src/openxr/features/passthrough.rs"
    click Graphics "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_openxr/src/openxr/graphics.rs"
    click Vulkan "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_openxr/src/openxr/graphics/vulkan.rs"
    click D3D12 "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_openxr/src/openxr/graphics/d3d12.rs"
    click Poll "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_openxr/src/openxr/poll_events.rs"
    click RenderO "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_openxr/src/openxr/render.rs"
    click OXTypes "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_openxr/src/openxr/types.rs"
    click Helpers "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_openxr/src/openxr/helper_traits.rs"
    click Resources "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_openxr/src/openxr/resources.rs"
    click SpacesO "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_openxr/src/openxr/spaces.rs"
    click Examples "https://github.com/awtterpip/bevy_oxr/tree/main/crates/bevy_openxr/examples"
    click WebXR "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_webxr/src/lib.rs"
    click Mod "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_webxr/src/webxr/mod.rs"
    click UtilsCore "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_xr_utils/src/lib.rs"
    click HG "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_xr_utils/src/hand_gizmos.rs"
    click TU "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_xr_utils/src/tracking_utils.rs"
    click TR "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_xr_utils/src/transform_utils.rs"
    click PA "https://github.com/awtterpip/bevy_oxr/blob/main/crates/bevy_xr_utils/src/xr_utils_actions.rs"

    %% Styles
    classDef app fill:#FFD580,stroke:#CC8400,color:#000;
    classDef engine fill:#E0E0E0,stroke:#A0A0A0,color:#000;
    classDef core fill:#B3E5FC,stroke:#039BE5,color:#000;
    classDef backend fill:#C8E6C9,stroke:#388E3C,color:#000;
    classDef util fill:#F8BBD0,stroke:#C2185B,color:#000;
    classDef external fill:#F5F5F5,stroke:#9E9E9E,color:#000;
    classDef build fill:#FFCCBC,stroke:#D84315,color:#000;
    classDef coreModule fill:#E1F5FE,stroke:#0288D1,color:#000;
    classDef backendModule fill:#DCEDC8,stroke:#7CB342,color:#000;
    classDef utilModule fill:#FCE4EC,stroke:#AD1457,color:#000;
    classDef examples fill:#FFF9C4,stroke:#FBC02D,color:#000;
```
