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.

​
Download from GitHub Releases

The easiest way to get started with Phichain is to download pre-built binaries from GitHub Releases.
1

Visit the Releases Page

Navigate to the Phichain Releases page on GitHub.
2

Download for Your Platform

Choose the appropriate build for your system:
  • Windows (x64): phichain-v*-x86_64-pc-windows-msvc.zip
  • Windows (ARM64): phichain-v*-aarch64-pc-windows-msvc.zip
  • Linux (x64): phichain-v*-x86_64-unknown-linux-gnu.zip
  • macOS (Intel): phichain-v*-x86_64-apple-darwin.zip
  • macOS (Apple Silicon): phichain-v*-aarch64-apple-darwin.zip
3

Extract the Archive

Extract the downloaded .zip file to a location of your choice. The archive contains:
  • phichain / phichain.exe - Main editor executable
  • phichain-converter / phichain-converter.exe - Format conversion tool
  • phichain-renderer / phichain-renderer.exe - Rendering utilities
  • assets/ - Required resource files
  • lang/ - Localization files
  • start.bat - Windows launcher script (Windows only)
4

Launch Phichain

Run the editor:
  • Windows: Double-click start.bat or run phichain.exe
  • Linux/macOS: Run ./phichain from a terminal

​
System Requirements

​
Minimum Requirements

  • OS: Windows 10+, Ubuntu 20.04+, macOS 10.15+
  • CPU: x86_64 or ARM64 processor
  • RAM: 4 GB
  • Graphics: GPU with Vulkan/Metal/DirectX 12 support
  • Storage: 200 MB available space
  • OS: Windows 11, Ubuntu 22.04+, macOS 12+
  • RAM: 8 GB or more
  • Graphics: Dedicated GPU for smooth rendering of complex charts
  • Display: 1920x1080 or higher resolution

​
Graphics Backend

Phichain uses the Bevy game engine with WGPU for rendering:
  • Windows: DirectX 12 (default), Vulkan
  • Linux: Vulkan
  • macOS: Metal
On Windows, the start.bat script sets WGPU_BACKEND=dx12 for optimal compatibility.

​
Building from Source

For developers or users who want the latest features, you can build Phichain from source.

​
Prerequisites

1

Install Rust

Install the Rust toolchain from rustup.rs:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Verify installation:
rustc --version
cargo --version
2

Install System Dependencies

Linux (Ubuntu/Debian):
sudo apt-get update
sudo apt-get install -y g++ pkg-config libx11-dev libasound2-dev libudev-dev libxkbcommon-x11-0
sudo apt-get install -y libwayland-dev libxkbcommon-dev
macOS: No additional dependencies required - Xcode Command Line Tools should be sufficient.Windows: No additional dependencies required - MSVC toolchain is used.
3

Clone the Repository

git clone https://github.com/ivan-1f/phichain.git
cd phichain

​
Build Commands

# Build all crates in development mode (faster compile, slower runtime)
cargo build

​
Build Output

Compiled binaries are located in:
  • Debug builds: target/debug/
  • Release builds: target/release/
Release builds are significantly faster at runtime and recommended for actual chart editing. Development builds are primarily useful for debugging.

​
Platform-Specific Instructions

​
Windows

  1. Extract the downloaded archive
  2. Run start.bat to launch with optimal settings: 
    @echo off
set RUST_BACKTRACE=1
set WGPU_BACKEND=dx12
phichain.exe
pause
The batch script sets:
  • RUST_BACKTRACE=1 - Enable error backtraces for debugging
  • WGPU_BACKEND=dx12 - Use DirectX 12 backend

​
Linux

  1. Extract the archive: unzip phichain-v*.zip
  2. Make the binary executable: chmod +x phichain
  3. Run: ./phichain
On Linux, ensure your GPU drivers support Vulkan. For integrated Intel GPUs, you may need to install mesa-vulkan-drivers.

​
macOS

  1. Extract the archive
  2. Make the binary executable: chmod +x phichain
  3. Run: ./phichain
On macOS, you may need to allow the application in System Preferences > Security & Privacy if you see a gatekeeper warning.

​
Troubleshooting

​
”Failed to create window” or Graphics Errors

Cause: GPU drivers or graphics backend issues Solutions:
  • Update your GPU drivers to the latest version
  • On Windows, try setting WGPU_BACKEND=vulkan instead of dx12
  • Verify your GPU supports the required graphics API (Vulkan/Metal/DX12)

​
“Failed to load assets”

Cause: Missing or incorrectly placed asset files Solution: Ensure the assets/ and lang/ directories are in the same location as the executable: 
phichain/
├── phichain(.exe)
├── assets/
│   ├── audio/
│   └── image/
└── lang/
    ├── en_us/
    └── zh_cn/

​
Audio Playback Issues

Cause: Missing audio system dependencies or unsupported format Solutions:
  • Linux: Install ALSA libraries: sudo apt-get install libasound2-dev
  • Ensure your audio file is in a supported format (WAV, MP3, OGG, FLAC)
  • Check system audio output is not muted or used by another application

​
Build Errors: “linker error” or “missing library”

Cause: Missing system development dependencies Solution: Install all required dependencies for your platform (see Building from Source section)

​
Performance Issues

Solutions:
  • Use release builds instead of debug builds
  • Close other GPU-intensive applications
  • Reduce the number of visible notes by zooming into smaller timeline sections
  • Check if integrated graphics is being used instead of dedicated GPU

​
Linux-Specific: X11/Wayland Issues

Cause: Display server compatibility Solutions:
  • If using Wayland, try forcing X11: GDK_BACKEND=x11 ./phichain
  • Install both X11 and Wayland support libraries

​
Version Notes

Phichain uses semantic versioning. The current version can be found in phichain-editor/Cargo.toml: 
[package]
name = "phichain"
version = "1.0.0-beta.5"
  • Dev builds include build numbers: 1.0.0-beta.5+build.123
  • Release builds use clean version tags: 1.0.0-beta.5

​
Next Steps

Quickstart Guide

Learn how to create your first chart with Phichain

Build docs developers (and LLMs) love

Get started for freeTalk to us