madavidcoder/circle-seige

1. Overall shape

Circle Siege is a two-part game: a Godot frontend for rendering, input, UI, and gameplay, and a Rust backend for audio analysis. The architectural boundary is between the real-time game client and the audio/event-generation layer.

2. Frontend runtime

The frontend/ directory is the main shipped game. It contains a Godot project (project.godot), scenes (main.tscn, ChordTelegraph.tscn, Projectile.tscn, RadialTelegraph.tscn), and many GDScript components that implement the menu, game loop, HUD, and effects.

3. Frontend composition

The game client is organized as scene-based modules:

- main.gd / main.tscn for top-level app flow

- menu.gd for start/settings/input selection

- director.gd for orchestrating gameplay events

- player.gd for cursor-following player behavior

- projectile.gd, chord_telegraph.gd, radial_telegraph.gd for hazards and warning visuals

- lives_display.gd, near_miss_fx.gd, shockwave.gd, beat_particles.gd, spectrum.gd for feedback and HUD

4. Gameplay data flow

The primary in-game flow is: audio source selection → beat/energy analysis → spawning of telegraphs/projectiles → player dodges with mouse input → HUD/visual feedback updates. The director appears to be the central gameplay coordinator that turns audio timing into attack patterns.

5. Audio source modes

The README and assets show three input modes:

- Demo tracks bundled as demo_*.jsonl and demo.wav

- Local file input chosen by the player

- System audio loopback for live music from apps like Spotify

This is a major architectural boundary because the backend must handle multiple audio sources, while the frontend presents them as game modes.

6. Rust backend role

The backend/ crate is a separate Rust executable with main.rs, processor.rs, and record.rs. Based on the README tech stack, it handles audio analysis, FFT/tempo/beat detection, and record generation. It is not the game itself; it is the analysis engine that produces timing/intensity data for the frontend to consume.

7. Backend responsibilities

The backend likely has three concerns:

- command-line startup and configuration (clap in the README)

- asynchronous processing / streaming (tokio)

- beat and tempo analysis (aubio, plus any FFT/feature extraction logic in processor.rs)

record.rs likely defines the event/trace format used for playback or exporting analysis results.

8. Trace-based playback

The presence of demo_chill.jsonl, demo_normal.jsonl, and demo_hard.jsonl suggests the game can play back precomputed event traces rather than analyzing audio every time. That makes the frontend capable of deterministic demo playback, while the backend likely generates or records these traces for live or offline use.

9. Visual and accessibility layer

The frontend includes custom shaders and theme resources (flow_gradient.gdshader, *.tres, gradient_bg.gd, audiowide.tres, syne*.tres) plus settings for movement reduction and high-contrast modes. This is a distinct UI/visual subsystem layered on top of gameplay, not part of the audio analysis pipeline.

10. Input and control model

Player control is intentionally minimal: the mouse position drives the player avatar, and keyboard input is mostly reserved for menu navigation. That means the core runtime loop is: cursor input + audio-derived hazards + collision/life management.

11. External dependency boundary

The project depends on Godot Engine for the client runtime and Rust for analysis tooling. The README also calls out a Windows-only limitation due to audio loopback compatibility, which affects deployment architecture because system-audio capture is part of the core feature set.

12. How to draw the architecture

A useful diagram would show:

- a Godot game client containing menu, gameplay director, entities, HUD, and effects

- a Rust audio analysis service/tool producing beat/event records

- audio inputs feeding the Rust side

- JSONL/demo traces or live analysis output feeding the game director

- mouse/keyboard input feeding the player/menu

- rendered visuals and collision feedback as the client’s output

The central integration point is the event stream that converts music into obstacle patterns.