# ppy/osu-framework architecture

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

- Interactive diagram: https://gitdiagram.com/ppy/osu-framework
- Repository: https://github.com/ppy/osu-framework

## Overview

##### Project type and purpose
- Type: A cross-platform game framework written in .NET (C#), providing core game loop, graphics, audio, input, IO, testing, and project templates.
- Purpose: Supply reusable engine components (rendering, audio, input, DI, resource management) for building games (e.g., osu!), with support for Desktop, Android, and iOS.

##### Major architectural layers/components
a. Core Framework (osu.Framework namespace)
– Subsystems:
- Allocation & Dependency Injection (DependencyContainer, ResolvedAttribute)
- Bindables (data-binding primitives)
- Configuration (IConfigManager, tracking)
- FrameworkEnvironment, Game.cs (game loop orchestration)
- Threading & Timing (Scheduler, GameThread, DrawThread, FramedClock)
- Testing (VisualTests, headless host)
- Utilities (Extensions, Utils, Validation, RNG)
b. Graphics
– Core abstractions: Drawable, DrawNode, Renderer interfaces
– OpenGL backend (Graphics/OpenGL)
– Veldrid backend (Graphics/Veldrid)
– Texture & Shader management, Shaders, Effects, Animations
– Video decoding (FFmpeg wrappers under Graphics/Video + NativeLibs)
c. Audio
– High-level: AudioManager, AudioComponent, Track, Sample
– BASS integration via NativeLibs (runtimes/*/*.native .dll/.so/.dylib)
– Mixing, Callbacks, Virtual sample/track fallback
d. Input
– InputManager, StateChanges, Events, Handlers (Keyboard, Mouse, Touch, Joystick, MIDI)
e. IO & Resource Stores
– ResourceStore, DllResourceStore, OnlineStore
– Serialization (Json converters), Storage-backed stores
– Network requests (WebRequest abstractions)
f. Platform Abstraction
– osu.Framework.Platform: DesktopGameHost, Linux/MacOS/Windows hosts, SDL2/SDL3 layers, Apple/iOS/Android adaptations
g. NativeLibs & Build Scripts
– scripts/ffmpeg for building platform-specific codecs
– packaged native dependencies for audio/video
h. Templates & Samples
– osu.Framework.Templates (empty & Flappy templates)
– SampleGame.* projects for Android, Desktop, iOS
i. Tests & Benchmarks
– osu.Framework.Tests (unit and visual tests)
– osu.Framework.Benchmarks

##### Relationships & data flow
- The **Game** (entry point in SampleGame.* or Test host) → instantiates **DependencyContainer** → loads subsystems (Graphics, Audio, Input, IO).
- **Graphics subsystem** delegates to chosen backend (OpenGL or Veldrid), which calls platform windowing & native GL/Veldrid APIs.
- **Audio subsystem** calls into native BASS libraries packaged under NativeLibs.
- **Input subsystem** polls OS/device via Platform abstraction (SDL2/SDL3 or native) and emits events to Drawables.
- **IO/ResourceStores** fetch assets (fonts, textures, audio, video) from disk, embedded resources, or online.
- **Testing/VisualTests** uses HeadlessGameHost or mock containers to isolate components (DI, rendering, input) for test drivers.
- **SampleGame** projects reference the framework (via NuGet or local csproj) and wire up Game subclasses plus platform-specific host glue.

##### Architectural patterns & design principles
- **Layered modularity**: Clean separation of core API, platform, backends, and consumers.
- **Dependency Injection**: via osu.Framework.Allocation for loose coupling and testability.
- **Factory & Strategy**: pluggable backends (OpenGL vs Veldrid) and input handlers.
- **Resource Caching**: automatic texture/font/video caching with expiry.
- **Event-driven**: input and rendering pipelines produce discrete events processed in order.
- **Cross-platform**: conditional compilation, platform projects, and runtime native library selection.

##### Capturing essential details
- Don’t just list files—group by subsystem responsibility.
- How **native libs** (FFmpeg, BASS) flow into your audio/video subsystems.
- **test harness** interaction (VisualTests), demonstrating isolated testing capability.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Consumers
    subgraph "Consumers" 
        direction TB
        Templates["Project Templates"]:::consumer
        SampleGames["SampleGame"]:::consumer
        SampleDesktop["SampleGame.Desktop"]:::consumer
        SampleAndroid["SampleGame.Android"]:::consumer
        SampleiOS["SampleGame.iOS"]:::consumer
    end

    subgraph "Tests & Benchmarks"
        direction TB
        Tests["Unit & Visual Tests"]:::consumer
        Benchmarks["Benchmarks"]:::consumer
    end

    %% Core Framework
    subgraph "Core Framework" 
        direction TB
        AllocationDI["Allocation & Dependency Injection"]:::core
        Bindables["Bindables"]:::core
        Configuration["Configuration"]:::core
        FrameworkEnvGame["FrameworkEnvironment & Game Loop"]:::core
        ThreadingTiming["Threading & Timing"]:::core
        Utilities["Utilities"]:::core
    end

    %% Subsystems
    subgraph "Graphics Subsystem"
        direction TB
        GraphicsCore["Graphics Core Abstractions"]:::core
        OpenGLBackend["OpenGL Backend"]:::backend
        VeldridBackend["Veldrid Backend"]:::backend
        VideoDecoding["Video Decoding (FFmpeg)"]:::backend
    end

    subgraph "Audio Subsystem"
        direction TB
        AudioAPI["Audio API"]:::core
        BASSNative["Native BASS Libraries"]:::native
    end

    subgraph "Input Subsystem"
        direction TB
        InputSubsystem["Input Manager & Handlers"]:::core
    end

    subgraph "IO & Resource Stores"
        direction TB
        IOStores["IO & Resource Stores"]:::core
    end

    subgraph "Platform Abstraction"
        direction TB
        PlatformAbstraction["Platform Hosts & SDL2/3"]:::platform
    end

    subgraph "NativeLibs & Build Scripts"
        direction TB
        NativeLibs["NativeLibs & Build Scripts"]:::native
    end

    %% Relationships
    SampleGames -->|uses| FrameworkEnvGame
    SampleDesktop -->|uses| FrameworkEnvGame
    SampleAndroid -->|uses| FrameworkEnvGame
    SampleiOS -->|uses| FrameworkEnvGame
    Templates -->|scaffold| FrameworkEnvGame

    Tests -.->|test harness| FrameworkEnvGame
    Tests -.->|test subsystems| GraphicsCore
    Tests -.->|test subsystems| AudioAPI
    Tests -.->|test subsystems| InputSubsystem
    Benchmarks -->|measure| FrameworkEnvGame

    FrameworkEnvGame -->|orchestrates| AllocationDI
    FrameworkEnvGame -->|uses| Bindables
    FrameworkEnvGame -->|uses| Configuration
    FrameworkEnvGame -->|manages| ThreadingTiming
    FrameworkEnvGame -->|provides| Utilities

    FrameworkEnvGame -->|initializes| GraphicsCore
    FrameworkEnvGame -->|initializes| AudioAPI
    FrameworkEnvGame -->|initializes| InputSubsystem
    FrameworkEnvGame -->|initializes| IOStores

    GraphicsCore -->|delegates| OpenGLBackend
    GraphicsCore -->|delegates| VeldridBackend
    GraphicsCore -->|handles video| VideoDecoding
    OpenGLBackend -->|calls| PlatformAbstraction
    VeldridBackend -->|calls| PlatformAbstraction

    AudioAPI -->|calls| BASSNative
    BASSNative -->|packaged in| NativeLibs

    InputSubsystem -->|polls via| PlatformAbstraction

    IOStores -->|fetch assets from| NativeLibs
    IOStores -->|network via| PlatformAbstraction

    PlatformAbstraction -->|uses| NativeLibs

    %% Click Events
    click AllocationDI "https://github.com/ppy/osu-framework/tree/master/osu.Framework/Allocation/"
    click Bindables "https://github.com/ppy/osu-framework/tree/master/osu.Framework/Bindables/"
    click Configuration "https://github.com/ppy/osu-framework/tree/master/osu.Framework/Configuration/"
    click FrameworkEnvGame "https://github.com/ppy/osu-framework/blob/master/osu.Framework/FrameworkEnvironment.cs"
    click FrameworkEnvGame "https://github.com/ppy/osu-framework/blob/master/osu.Framework/Game.cs"
    click ThreadingTiming "https://github.com/ppy/osu-framework/tree/master/osu.Framework/Threading/"
    click ThreadingTiming "https://github.com/ppy/osu-framework/tree/master/osu.Framework/Timing/"
    click Utilities "https://github.com/ppy/osu-framework/tree/master/osu.Framework/Utils/"
    click GraphicsCore "https://github.com/ppy/osu-framework/tree/master/osu.Framework/Graphics/"
    click OpenGLBackend "https://github.com/ppy/osu-framework/tree/master/osu.Framework/Graphics/OpenGL/"
    click VeldridBackend "https://github.com/ppy/osu-framework/tree/master/osu.Framework/Graphics/Veldrid/"
    click VideoDecoding "https://github.com/ppy/osu-framework/tree/master/osu.Framework/Graphics/Video/"
    click AudioAPI "https://github.com/ppy/osu-framework/tree/master/osu.Framework/Audio/"
    click BASSNative "https://github.com/ppy/osu-framework/tree/master/osu.Framework.NativeLibs/runtimes/"
    click BASSNative "https://github.com/ppy/osu-framework/tree/master/osu.Framework.NativeLibs/scripts/ffmpeg/"
    click InputSubsystem "https://github.com/ppy/osu-framework/tree/master/osu.Framework/Input/"
    click IOStores "https://github.com/ppy/osu-framework/tree/master/osu.Framework/IO/"
    click PlatformAbstraction "https://github.com/ppy/osu-framework/tree/master/osu.Framework/Platform/"
    click NativeLibs "https://github.com/ppy/osu-framework/tree/master/osu.Framework.NativeLibs/"
    click Templates "https://github.com/ppy/osu-framework/tree/master/osu.Framework.Templates/"
    click SampleGames "https://github.com/ppy/osu-framework/tree/master/SampleGame/"
    click SampleDesktop "https://github.com/ppy/osu-framework/tree/master/SampleGame.Desktop/"
    click SampleAndroid "https://github.com/ppy/osu-framework/tree/master/SampleGame.Android/"
    click SampleiOS "https://github.com/ppy/osu-framework/tree/master/SampleGame.iOS/"
    click Tests "https://github.com/ppy/osu-framework/tree/master/osu.Framework.Tests/"
    click Benchmarks "https://github.com/ppy/osu-framework/tree/master/osu.Framework.Benchmarks/"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085
    classDef platform fill:#d4edda,stroke:#155724,color:#155724
    classDef backend fill:#fff3cd,stroke:#856404,color:#856404
    classDef native fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef consumer fill:#ffeeba,stroke:#856404,color:#856404
```
