How evast9919/lazer-sandbox works
1. What this repo is
- This is a custom osu!lazer ruleset/plugin called *Sandbox*. It is not a standalone app; it plugs into the osu! client as a game mode and also contains a matching test project for visual and component tests.
2. Top-level split: runtime vs tests
- The repository is divided into:
- osu.Game.Rulesets.Sandbox: the production ruleset and game content.
- osu.Game.Rulesets.Sandbox.Tests: a test harness with many TestScene* scenes.
- For an architecture diagram, treat the test project as a separate validation/runtime sandbox that exercises the same UI and gameplay components under test scenes.
3. Ruleset integration boundary
- Core integration points are:
- SandboxRuleset.cs as the ruleset entry point.
- SandboxInputManager.cs for input handling.
- Beatmaps/SandboxBeatmap.cs and SandboxBeatmapConverter.cs for converting osu! beatmaps into this ruleset’s hit objects.
- Difficulty/SandboxDifficultyCalculator.cs for rule-specific difficulty/star computation.
- Judgements/SandboxJudgement.cs and Objects/SandboxHitObject.cs / Objects/Drawables/DrawableSandboxHitObject.cs for gameplay object lifecycle.
- This is the main boundary between osu!lazer’s generic framework and Sandbox-specific behavior.
4. Gameplay model
- The ruleset appears to define a generic “sandbox hit object” abstraction and then render/score it via a drawable layer.
- The flow is: converted beatmap → sandbox hit objects → drawable hit objects → judgement/scoring.
- That pattern is important because it separates data representation from on-screen behavior.
5. Screen-level product structure
- The repo bundles several distinct experiences under the ruleset:
- MainRulesetScreen.cs for the main sandbox landing page.
- FlappyDonScreen.cs for a Flappy Bird-style mini-game.
- NumbersScreen.cs for number-based gameplay/visualization.
- VisualizerScreen.cs for music visualizer experiences.
- RulesetsScreen.cs for managing downloadable/available rulesets.
- A useful diagram would show these as feature screens hosted inside the ruleset shell.
6. Shared UI framework
- Common UI and overlay pieces live under UI/ and are reused across screens:
- SandboxOverlay, SandboxCheckbox, SandboxSettings, SandboxSettingsSection, ColourPickerDropdown, SettingsDropdownContainer.
- InteractiveContainer, StoryboardContainer, TrackController, SandboxPlayfield, DrawableSandboxRuleset.
- These form a shared UI layer that sits above the underlying gameplay/rendering components.
7. Reusable visual/graphics primitives
- Graphics/ contains reusable containers such as ContentFitContainer and InnerShadowContainer.
- The Resources/Shaders folder shows custom rendering effects:
- inner shadow,
- rounded bars,
- shared ruleset utility shader code.
- These are cross-cutting rendering primitives used by multiple screens and widgets rather than isolated game logic.
8. FlappyDon subsystem
- The FlappyDon feature is implemented as a self-contained mini-game:
- Components/Bird, Obstacles, PipeObstacle, PipeSprite, GroundSprite, BackgroundSprite, Backdrop, FlappyDonGame, FlappyDonScalingContainer.
- This subsystem has its own composition root (FlappyDonScreen) and asset set, so it should be diagrammed as an internally contained game mode within Sandbox.
9. Numbers subsystem
- The Numbers feature is similarly isolated:
- DrawableNumber renders individual numbers.
- NumbersPlayfield manages arrangement/playfield behavior.
- NumbersScreen hosts the experience.
- This is a lighter-weight feature module, likely focused on animated rendering and interaction rather than full rhythm gameplay.
10. Visualizer subsystem
- The visualizer is the most layered feature area:
- VisualizerScreen hosts it.
- Components/LayoutController switches between layouts.
- Layouts/TypeA and Layouts/TypeB define alternate presentation modes.
- Visualizers/Circular and Visualizers/Linear define different audio-reactive renderers.
- MusicHelpers/ provides beatmap/rate/intensity/amplitude plumbing.
- Particles, ParticlesDrawable, and settings sections control additional effects.
- Data flow here is: music/beatmap state → music helper providers → layout/controller → drawable visualizer components.
11. Rulesets browsing / online integration
- Screens/Rulesets includes update/download UI:
- DrawableLatestRulesetUpdate, RulesetDownloadType, RulesetPanel.
- The Online/ folder contains GetLatestReleaseRequest and GitHubRelease, indicating the ruleset can query GitHub releases to detect or present updates.
- This is the repo’s only clear external-service boundary besides osu!lazer itself.
12. Configuration and extension layer
- Configuration/SandboxRulesetConfigManager.cs centralizes ruleset-specific settings storage.
- Extensions/ contains shared utilities for math, noise generation, osu! integration helpers, and projectile helpers.
- These are support libraries that reduce coupling across the feature screens and gameplay components.
13. Assets and content
- Content is bundled with the ruleset:
- sound samples in Resources/Samples,
- textures for FlappyDon, icons, and visualizer assets,
- custom shaders.
- The asset pipeline is therefore an important runtime dependency, not just static decoration.
14. Testing architecture
- The test project mirrors the runtime structure with TestScene* classes for:
- game integration,
- graphics containers,
- UI components,
- visualizer behaviors,
- FlappyDon and ruleset object tests.
- This suggests a component-driven architecture where most features are testable in isolation as drawable scenes, which is common in osu! framework projects.
15. How to draw the system
- A good architecture diagram would show:
- osu!lazer host at the top,
- SandboxRuleset as the integration layer,
- branches for gameplay objects, shared UI, feature screens, visualizer/music helpers, and online release lookup,
- and a separate test harness mirroring those feature areas.
- The key architectural idea is that Sandbox is a multi-feature ruleset plugin with a shared UI/graphics foundation and several self-contained mini-applications under one ruleset.
Main entry points: RulesetTestScene.cs Test harness · SandboxRuleset.cs Sandbox ruleset · MainRulesetScreen.cs Main screen · DrawableSandboxRuleset.cs Shared UI
Components 27
Runtime Ruleset
Production ruleset, gameplay model, shared UI, and feature screens.
- Sandbox ruleset · Ruleset entry point wired into the osu! client.
osu.Game.Rulesets.Sandbox/SandboxRuleset.cs - Input manager · Ruleset-specific input handling and binding.
osu.Game.Rulesets.Sandbox/SandboxInputManager.cs - Beatmap converter · Converts osu! beatmaps into Sandbox hit objects.
osu.Game.Rulesets.Sandbox/Beatmaps/SandboxBeatmapConverter.cs - Sandbox beatmap · Ruleset-specific beatmap representation.
osu.Game.Rulesets.Sandbox/Beatmaps/SandboxBeatmap.cs - Difficulty calc · Computes Sandbox-specific difficulty and star values.
osu.Game.Rulesets.Sandbox/Difficulty/SandboxDifficultyCalculator.cs - Hit object · Core Sandbox gameplay object abstraction.
osu.Game.Rulesets.Sandbox/Objects/SandboxHitObject.cs - Drawable object · Visual and interactive rendering for Sandbox hit objects.
osu.Game.Rulesets.Sandbox/Objects/Drawables/DrawableSandboxHitObject.cs - Judgement · Ruleset judgement and score resolution.
osu.Game.Rulesets.Sandbox/Judgements/SandboxJudgement.cs - Shared UI · Reusable overlays, playfield containers, settings, and interaction helpers.
osu.Game.Rulesets.Sandbox/UI/DrawableSandboxRuleset.cs - Screen shell · Common screen base classes for the ruleset experience.
osu.Game.Rulesets.Sandbox/Screens/SandboxScreen.cs - Main screen · Main Sandbox landing page and entry hub.
osu.Game.Rulesets.Sandbox/Screens/Main/MainRulesetScreen.cs - FlappyDon · Self-contained Flappy Bird-style feature screen.
osu.Game.Rulesets.Sandbox/Screens/FlappyDon/FlappyDonScreen.cs - Numbers · Number-based gameplay and visualization screen.
osu.Game.Rulesets.Sandbox/Screens/Numbers/NumbersScreen.cs - Visualizer · Audio-reactive visualizer experience with layouts and effects.
osu.Game.Rulesets.Sandbox/Screens/Visualizer/VisualizerScreen.cs - Rulesets · Ruleset browsing and release/update presentation.
osu.Game.Rulesets.Sandbox/Screens/Rulesets/RulesetsScreen.cs - Online updates · GitHub release request and release metadata handling.
osu.Game.Rulesets.Sandbox/Online/GetLatestReleaseRequest.cs - Config manager · Central storage for ruleset-specific settings.
osu.Game.Rulesets.Sandbox/Configuration/SandboxRulesetConfigManager.cs - Graphics primitives · Reusable visual containers such as content fitting and inner shadows.
osu.Game.Rulesets.Sandbox/Graphics/ContentFitContainer.cs - Visualizer core · Layout controller, music helpers, particle effects, and visualizer renderers.
osu.Game.Rulesets.Sandbox/Screens/Visualizer/Components/LayoutController.cs - Flappy core · Bird, obstacles, sprites, and scaling container for FlappyDon.
osu.Game.Rulesets.Sandbox/Screens/FlappyDon/Components/FlappyDonGame.cs - Numbers core · Drawable number and playfield logic.
osu.Game.Rulesets.Sandbox/Screens/Numbers/Components/NumbersPlayfield.cs
Test Harness
Validation project with drawable and component test scenes.
- Test harness · Separate validation runtime with drawable scene-based tests.
osu.Game.Rulesets.Sandbox.Tests/RulesetTestScene.cs - UI tests · Test scenes for overlays and interaction containers.
osu.Game.Rulesets.Sandbox.Tests/UI/TestSceneSandboxOverlay.cs - Graphics tests · Test scenes for graphics containers and rendering effects.
osu.Game.Rulesets.Sandbox.Tests/Graphics/TestSceneInnerShadowContainer.cs - Flappy tests · Test scenes for FlappyDon gameplay and background components.
osu.Game.Rulesets.Sandbox.Tests/FlappyDon/TestSceneFlappyDonGame.cs - Numbers tests · Test scenes for numbers drawable and playfield behavior.
osu.Game.Rulesets.Sandbox.Tests/NumbersGame/TestSceneNumbersPlayfield.cs - Visualizer tests · Test scenes for visualizer particles, layout, and settings behavior.
osu.Game.Rulesets.Sandbox.Tests/Visualizer/TestSceneParticles.cs
Connections 28
- Sandbox ruleset → Input manager: creates · The ruleset installs its input layer.
- Sandbox ruleset → Beatmap converter: uses · Ruleset integration includes beatmap conversion.
- Sandbox ruleset → Difficulty calc: uses · Ruleset integration includes difficulty calculation.
- Sandbox ruleset → Shared UI: hosts · The ruleset renders the shared UI and playfield layer.
- Sandbox ruleset → Screen shell: opens · Main navigation lives under the sandbox screen shell.
- Beatmap converter → Sandbox beatmap: produces · Conversion yields Sandbox beatmap data.
- Sandbox beatmap → Hit object: contains · Beatmaps are composed of Sandbox hit objects.
- Hit object → Drawable object: renders as · Gameplay objects are materialized as drawable hit objects.
- Drawable object → Judgement: scores via · Drawable objects resolve judgements and scoring.
- Shared UI → Graphics primitives: composes · Shared UI builds on reusable rendering containers.
- Shared UI → Config manager: reads · UI surfaces consume centralized ruleset configuration.
- Main screen → Shared UI: uses · Landing page is built from shared UI pieces.
- Main screen → FlappyDon: navigates to · Main screen exposes the FlappyDon experience.
- Main screen → Numbers: navigates to · Main screen exposes the numbers experience.
- Main screen → Visualizer: navigates to · Main screen exposes the visualizer experience.
- Main screen → Rulesets: navigates to · Main screen exposes ruleset browsing and updates.
- Rulesets → Online updates: queries · Ruleset browsing can check GitHub releases.
- FlappyDon → Flappy core: hosts · FlappyDon screen composes its mini-game subsystem.
- Numbers → Numbers core: hosts · Numbers screen composes its playfield subsystem.
- Visualizer → Visualizer core: hosts · Visualizer screen composes layout, music, and effect logic.
- Visualizer core → Config manager: uses · Visualizer settings are driven by ruleset config.
- Visualizer core → Graphics primitives: uses · Visualizer renderers rely on shared graphics helpers.
- Test harness → Sandbox ruleset: exercises · The test project validates the production ruleset behavior.
- Test harness → UI tests: includes · UI scene tests cover overlay and interaction components.
- Test harness → Graphics tests: includes · Graphics scene tests cover rendering primitives.
- Test harness → Flappy tests: includes · FlappyDon scenes validate the mini-game subsystem.
- Test harness → Numbers tests: includes · Numbers scenes validate drawable and playfield behavior.
- Test harness → Visualizer tests: includes · Visualizer scenes validate layouts and effects.