How ppy/osu-framework works
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.