Architecture

Phichain is built as a modular Rust workspace using the Bevy game engine and ECS (Entity Component System) architecture. This document explains the project structure, design decisions, and data flow.

Project Structure

Phichain uses a Cargo workspace with multiple specialized crates:

phichain/
├── phichain-chart        # Core chart data model
├── phichain-assets       # Asset management and loading
├── phichain-compiler     # Chart compilation logic
├── phichain-converter    # Format conversion CLI tool
├── phichain-editor       # Main editor application
├── phichain-game         # Game/playback engine
└── phichain-renderer     # Chart rendering utility

Crate Overview

phichain-chart

Core data structures for charts, notes, events, and BPM management.

Chart format definitions
Beat calculation system
Serialization/deserialization
Format migration

phichain-editor

Main application - Interactive chart editor with egui UI.

Bevy + egui integration
Timeline editing
Audio playback
Project management

phichain-game

Playback engine - Renders and plays charts.

Note rendering
Hit effects
Score calculation
Audio synchronization

phichain-converter

CLI tool for converting between chart formats.

Format detection
Batch conversion
Standalone binary

phichain-renderer

Rendering utility for generating chart videos/images.

Headless rendering
Video export
Image sequences

phichain-assets

Asset management for loading game resources.

Image loading
Audio loading
Resource caching

phichain-compiler

Chart compilation - Processes charts for runtime.

Event processing
Optimization
Validation

Core Dependencies

Bevy Engine (0.16.1)

Phichain is built on Bevy, a data-driven game engine using ECS architecture. Key Bevy features used:

bevy_sprite - 2D rendering for notes and judgement lines
bevy_ui - Native UI components
bevy_asset - Asset loading and hot-reloading
bevy_window - Window management
bevy_state - State machine for editor/playback modes

Additional Bevy ecosystem crates:

bevy_kira_audio - Audio playback with precise timing
bevy_egui - egui integration for editor UI
bevy_prototype_lyon - Vector graphics rendering
bevy-persistent - Save/load system data

egui (0.31.1)

The editor uses egui for its immediate-mode UI:

egui_dock - Docking panel system
egui_extras - Additional widgets and features
egui-phosphor - Icon library
egui-toast - Notification system

The editor uses bevy_egui with the immutable_ctx feature for better integration with Bevy’s ECS.

Architecture Patterns

Entity Component System (ECS)

Phichain follows Bevy’s ECS architecture: Entities: Represent chart objects (notes, judgement lines, events) Components: Data attached to entities

// Example components (simplified)
struct Note {
    time: Beat,
    note_type: NoteType,
}

struct JudgementLine {
    position: Vec2,
    rotation: f32,
}

Systems: Functions that operate on entities with specific components

// Example system (simplified)
fn update_note_position(
    mut notes: Query<(&Note, &mut Transform)>,
    time: Res<Time>,
) {
    // Update note positions based on time
}

Chart Data Model

The chart data model hierarchy:

Project - Top-level container
- Metadata (title, artist, difficulty)
- Audio file reference
- Illustration image
Chart - Contains all chart data
- Multiple judgement lines
- BPM list for timing
Judgement Lines - The moving lines that notes are attached to
- Notes (tap, hold, drag, flick)
- Events (movement, rotation, alpha)
BPM List - Timing information
- BPM changes throughout the chart
- Beat calculation utilities

Beat System

Phichain uses a beat-based timing system rather than absolute time:

// Simplified beat representation
struct Beat {
    beats: i32,      // Number of beats
    subdivisions: i32, // Current subdivision
    division: i32,   // Total subdivisions per beat
}

Benefits:

Precise timing independent of BPM
Easy tempo changes
Musical alignment

Event System

Judgement line behavior is controlled by events:

Movement events - Control X/Y position
Rotation events - Control angle
Alpha events - Control opacity
Speed events - Control note scroll speed

Each event has:

Start/end times (in beats)
Start/end values
Easing function

Format Conversion Pipeline

Parsing

External chart formats (Re:PhiEdit, official format, etc.) are parsed into intermediate representations.

Conversion

The phichain-converter crate converts formats into the standard phichain-chart data model.

Compilation

The phichain-compiler optimizes and validates the chart for runtime use.

Runtime

The phichain-game engine renders and plays the compiled chart.

Game Engine Integration

The editor integrates the game engine for real-time preview:

┌─────────────────────────────────────┐
│     phichain-editor (Bevy App)      │
├─────────────────┬───────────────────┤
│   egui UI       │   Game Preview    │
│                 │                   │
│ - Timeline      │ - Note rendering  │
│ - Inspector     │ - Line rendering  │
│ - File browser  │ - Hit effects     │
│ - Audio control │ - Audio playback  │
└─────────────────┴───────────────────┘
         │                   │
         └───────┬───────────┘
                 │
         phichain-game

Editor State Management

The editor uses Bevy’s state system for different modes:

HomeState - Project selection and settings
EditorState - Active chart editing
PlaybackState - Chart preview/playback

UI Architecture

The editor UI is organized into tabs:

src/tab/
├── arrangement/  # Main timeline view
├── events/       # Event editing
├── inspector/    # Property inspector
├── settings/     # Application settings
└── preview/      # Game preview window

Each tab is a Bevy system that renders its egui UI.

Module Responsibilities

phichain-chart

Purpose: Pure data structures with no game engine dependencies Key modules:

beat.rs - Beat/time calculations
bpm_list.rs - BPM management and tempo mapping
event.rs - Line events (movement, rotation, alpha)
note.rs - Note types and properties
line.rs - Judgement line data
project.rs - Top-level project container
format/ - Serialization for different formats
migration/ - Format version migration

phichain-editor

Purpose: Main application with UI and editing logic Key modules:

main.rs - Application entry point and Bevy setup
tab/ - UI tabs (arrangement, events, inspector)
editing/ - Editing operations and undo/redo
project.rs - Project management
audio.rs - Audio playback integration
timeline/ - Timeline rendering and interaction
hotkey/ - Keyboard shortcuts
autosave/ - Auto-save system
export.rs - Chart export functionality

phichain-game

Purpose: Core gameplay and rendering engine Key modules:

core.rs - Main game loop and timing
line.rs - Judgement line rendering
note.rs - Note spawning and rendering (handled by events)
hit_effect.rs - Visual effects for hits
audio.rs - Audio synchronization
ui.rs - In-game UI (score, combo)
loader.rs - Chart loading from files

Design Decisions

Why Bevy?

Data-driven architecture

Bevy’s ECS is perfect for managing thousands of notes and events efficiently.

Hot reloading

Bevy’s asset system enables hot-reloading of charts and assets during development.

Cross-platform

Bevy provides excellent cross-platform support (Windows, macOS, Linux, Web).

Performance

ECS architecture provides excellent performance for real-time rendering and editing.

Why egui?

Immediate mode

Immediate-mode GUI is simpler for complex editor UIs with dynamic content.

Bevy integration

bevy_egui provides seamless integration with minimal overhead.

Rich widgets

egui has excellent built-in widgets for editors (sliders, text inputs, trees).

Customizable

Easy to create custom widgets and styling for the editor.

Beat-based Timing

Using beats instead of absolute time: Pros:

Musical alignment is natural
Tempo changes don’t require recalculating note times
Easier for chart authors to work with

Cons:

Requires BPM list for playback
More complex beat-to-time conversion

Workspace Organization

Separate crates provide:

Modularity - Clear separation of concerns
Reusability - Chart library usable in other projects
Compilation speed - Only rebuild changed crates
CLI tools - Converter and renderer as standalone binaries

Data Flow Diagram

User Input → egui UI → Editor State → Chart Model → Renderer → Display
     ↓                                      ↓
 Audio Control ──────────────────→ Audio Engine → Speakers
                                           ↓
                                    Time Sync → Note Timing

Performance Considerations

The editor handles charts with 10,000+ notes efficiently using Bevy’s ECS.

Optimization strategies:

Spatial partitioning - Only render visible notes
Object pooling - Reuse entities for hit effects
Event batching - Group similar events for processing
Lazy evaluation - Compute values only when needed
Caching - Cache beat-to-time conversions

Contributing

Project Structure

Crate Overview

phichain-chart

phichain-editor

phichain-game

phichain-converter

phichain-renderer

phichain-assets

phichain-compiler

Core Dependencies

Bevy Engine (0.16.1)

egui (0.31.1)

Architecture Patterns

Entity Component System (ECS)

Chart Data Model

Beat System

Event System

Format Conversion Pipeline

Game Engine Integration

Editor State Management

UI Architecture

Module Responsibilities

phichain-chart

phichain-editor

phichain-game

Design Decisions

Why Bevy?

Why egui?

Beat-based Timing

Workspace Organization

Data Flow Diagram

Performance Considerations

Next Steps

Building

Contributing

Build docs developers (and LLMs) love

Contributing

Documentation Index

​Project Structure

​Crate Overview

phichain-chart

phichain-editor

phichain-game

phichain-converter

phichain-renderer

phichain-assets

phichain-compiler

​Core Dependencies

​Bevy Engine (0.16.1)

​egui (0.31.1)

​Architecture Patterns

​Entity Component System (ECS)

​Chart Data Model

​Beat System

​Event System

​Format Conversion Pipeline

​Game Engine Integration

​Editor State Management

​UI Architecture

​Module Responsibilities

​phichain-chart

​phichain-editor

​phichain-game

​Design Decisions

​Why Bevy?

​Why egui?

​Beat-based Timing

​Workspace Organization

​Data Flow Diagram

​Performance Considerations

​Next Steps

Building

Contributing

Build docs developers (and LLMs) love

Project Structure

Crate Overview

Core Dependencies

Bevy Engine (0.16.1)

egui (0.31.1)

Architecture Patterns

Entity Component System (ECS)

Chart Data Model

Beat System

Event System

Format Conversion Pipeline

Game Engine Integration

Editor State Management

UI Architecture

Module Responsibilities

phichain-chart

phichain-editor

phichain-game

Design Decisions

Why Bevy?

Why egui?

Beat-based Timing

Workspace Organization

Data Flow Diagram

Performance Considerations

Next Steps