Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ivan-1f/phichain/llms.txt

Use this file to discover all available pages before exploring further.

This guide will walk you through creating your first chart in Phichain, from launching the editor to saving your work.

​
Prerequisites

Before starting, ensure you have:
  • Phichain installed on your system (see Installation)
  • An audio file for your chart (WAV, MP3, OGG, or FLAC format)
  • Optional: An illustration image (PNG or JPG format)

​
Step 1: Launch the Editor

1

Start Phichain

Launch Phichain using your platform’s method:
# Run start.bat or double-click it
start.bat
The home screen will appear, showing recent projects and options to create or open projects.
2

Choose Your Language

If needed, select your preferred language from the language selector:
  • English (en_us)
  • 中文 (zh_cn)
The editor supports full internationalization through the rust-i18n system.

​
Step 2: Create a New Project

1

Click 'Create Project'

On the home screen, click the Create Project button to open the project creation dialog.
2

Fill in Project Metadata

Enter information about your chart:
pub struct ProjectMeta {
    pub composer: String,    // Music composer/artist name
    pub charter: String,     // Your name as charter
    pub illustrator: String, // Illustration artist name
    pub name: String,        // Song/chart name
    pub level: String,       // Difficulty level (e.g., "EZ 5", "HD 12", "IN 15")
}
Example:
  • Name: My First Chart
  • Composer: Artist Name
  • Charter: Your Name
  • Illustrator: Artist Name
  • Level: HD 10
3

Select Audio File

Click Select Music and choose your audio file. Supported formats:
  • .wav - Uncompressed audio (recommended for best quality)
  • .mp3 - Compressed audio
  • .ogg - Ogg Vorbis compressed audio
  • .flac - Lossless compressed audio
The file must be named music.* with one of the above extensions when saved to the project directory.
4

Select Illustration (Optional)

Click Select Illustration and choose a background image:
  • .png - PNG image (supports transparency)
  • .jpg / .jpeg - JPEG image
The file will be saved as illustration.* in the project directory.
5

Choose Project Location

Select a folder where your project will be created. The project structure will be:
my-project/
├── chart.json         # Chart data (notes, lines, events)
├── meta.json          # Project metadata
├── music.wav          # Audio file
└── illustration.png   # Background image (optional)

​
Step 3: Understanding the Interface

Once your project loads, you’ll see the main editor interface:

​
Layout Overview

  • Top Bar: Menu, action buttons, and quick settings
  • Timeline Panel (bottom): Horizontal timeline showing notes and events over time
  • Inspector Panel (right): Properties and settings for selected objects
  • Game Preview (center): Visual preview of your chart during playback
  • Line List Panel (left): List of judgment lines in your chart
  • Action Panel: Undo/redo, copy/paste, and other editing actions

​
Key UI Components

The timeline shows your chart’s content horizontally:
  • X-axis: Time (measured in beats)
  • Each row: A judgment line and its notes
  • Note types: Visualized with different colors and shapes
Controls:
  • Scroll: Pan horizontally through time
  • Ctrl + Scroll: Zoom in/out on timeline
  • Click: Select notes or events
  • Drag: Move notes

​
Playback Controls

  • Spacebar: Play/pause
  • Timeline scrubbing: Click or drag the playhead
  • Metronome: Enable in settings for beat timing assistance
  • Playback speed: Adjust for easier editing

​
Step 4: Adding Your First Notes

1

Ensure BPM is Set

Before adding notes, verify the BPM (beats per minute) matches your song:
  1. Open the BPM List tab
  2. Set the initial BPM (default is usually 120)
  3. Add BPM changes if your song has tempo variations
Accurate BPM is crucial for proper beat alignment. Use a BPM detection tool or the song’s metadata if you’re unsure.
2

Select a Judgment Line

Click on a line in the Line List panel. The default project includes one line to start with.
3

Add Notes to the Timeline

Click in the timeline where you want to add a note:
pub enum NoteKind {
    Tap,                          // Single tap note
    Drag,                         // Drag note (slides)
    Hold { hold_beat: Beat },     // Hold note with duration
    Flick,                        // Flick note
}
Adding notes:
  • Default click adds a Tap note
  • Change note type in the Inspector after placing
  • For Hold notes, specify the hold duration in beats
4

Adjust Note Properties

Select a note and modify in the Inspector:
  • Beat: Precise timing position
  • Position: Horizontal position on the judgment line (-infinity to +infinity)
  • Kind: Change between Tap, Drag, Hold, and Flick
  • Hold Duration: For Hold notes only
5

Add More Lines (Optional)

For more complex charts:
  1. Click + in the Line List to add a new judgment line
  2. Each line can have its own notes and movement patterns
  3. Lines can move, rotate, and change opacity independently

​
Step 5: Adding Line Movements

Make your chart dynamic by animating judgment lines:
1

Select a Line

Click a line in the Line List to select it.
2

Add Line Events

In the timeline or Inspector, add events:
pub enum LineEvent {
    Position,   // Move the line's position
    Rotation,   // Rotate the line
    Opacity,    // Change line transparency
    Speed,      // Change note scroll speed
}
Each event has:
  • Start/End Beat: When the animation begins and ends
  • Start/End Value: Animation values
  • Easing: Animation curve (linear, ease-in, ease-out, etc.)
3

Preview Movement

Press Spacebar to play and watch your line animations in the game preview.

​
Step 6: Testing Your Chart

1

Open Game Tab

Switch to the Game tab to see a full playback simulation.
2

Play Through Your Chart

  • Press Spacebar to start playback
  • Watch note timing and line movements
  • Check for any visual or timing issues
3

Adjust Playback Settings

Fine-tune the preview:
  • Enable Hit Sounds for audio feedback
  • Adjust Note Speed for visibility testing
  • Use Metronome to verify beat alignment

​
Step 7: Saving Your Project

1

Save with Hotkey

Press Ctrl+S (Windows/Linux) or Cmd+S (macOS) to save your project.
// Phichain saves two files:
// 1. chart.json - All chart data
// 2. meta.json - Project metadata

let chart = serialize_chart(chart_params, line_params);
std::fs::write(project.path.chart_path(), serde_json::to_string(&chart)?)?;
std::fs::write(project.path.meta_path(), serde_json::to_string(&project.meta)?)?;
2

Verify Save Success

Check for a success notification in the bottom-right corner. The project folder now contains:
  • chart.json - Your chart data
  • meta.json - Updated metadata
3

Auto-Save (Optional)

Phichain includes an auto-save feature to prevent data loss. Check settings to enable/configure auto-save intervals.

​
Step 8: Exporting Your Chart

When ready to share or use your chart:
1

Export from Editor

Use the Export functionality in the editor to prepare your chart for distribution.
2

Convert Formats (Optional)

Use phichain-converter to convert between formats:
# Convert from official format to RPE format
phichain-converter --input chart.json --output chart.rpe
Supported formats:
  • Official Phigros (.json)
  • RPE (Re:PhiEdit format)

​
Quick Tips

Essential hotkeys for efficient editing:
  • Ctrl+S: Save project
  • Ctrl+W: Close project
  • Ctrl+Z: Undo
  • Ctrl+Y: Redo
  • Spacebar: Play/pause
  • Ctrl+Plus/Minus: Zoom timeline
  • Delete: Delete selected notes
For precise note placement:
  • Enable Grid Snap to align notes to beats
  • Use the Metronome to hear beat timing
  • Zoom in on the timeline for fine adjustments
  • Check the beat counter in the timeline header
Efficiently edit multiple notes:
  • Click: Select single note
  • Ctrl+Click: Add to selection
  • Drag box: Select multiple notes
  • Ctrl+C/V: Copy and paste selections
If the editor feels slow:
  • Use release builds instead of debug builds
  • Close unused tabs in the editor
  • Reduce visible timeline range by zooming in
  • Disable unnecessary visual effects in settings

​
Common Pitfalls

Incorrect BPM: The most common mistake! Always verify your BPM settings match the song. Incorrect BPM will cause all notes to be misaligned.
Missing Files: Ensure music.* and optional illustration.* files remain in the project directory. Moving or renaming them will break the project.
Auto-generated Files: Don’t manually edit chart.json or meta.json unless you understand the format. Always use the editor for modifications.

​
Next Steps

Now that you’ve created your first chart, explore more advanced features:

Editor Guide

Learn advanced editing techniques and workflows

Chart Format

Understand the chart.json structure and data format

Line Events

Master complex line animations and movements

Export & Share

Prepare your charts for distribution and playback

​
Getting Help

If you encounter issues or have questions:

Build docs developers (and LLMs) love

Get started for freeTalk to us