Chart Format Overview

Understanding Phichain’s multi-format chart support and conversion capabilities

Phichain supports multiple chart formats, enabling seamless conversion between different Phigros charting ecosystems. Each format has its own strengths and use cases.

Supported Formats

Phichain

Native format with advanced features and full toolchain support

Official

Official Phigros format for game compatibility

RPE

Re:PhiEdit format with enhanced easing support

Primitive

Internal intermediate representation

Format Comparison

Feature	Phichain	Official	RPE	Primitive
File Extension	.json	.json	.json	.json
Easing Support	Full	Linear only	Full	Full
BPM Changes	Multiple	Single per line	Multiple	Multiple
Child Lines	Yes	No	Partial	No
Curve Notes	Yes	No	No	No
Game Compatible	No	Yes	Via conversion	No
Editor Support	Phichain Editor	Official	Re:PhiEdit	N/A

Conversion Flow

All format conversions in Phichain go through the Primitive format as an intermediate representation:

This architecture ensures:

• Consistent conversion logic
• Easy addition of new formats
• Preservation of common features
• Predictable data transformations

When to Use Each Format

Phichain Format

Use when:

• Creating charts in Phichain Editor
• You need advanced features like child lines or curve notes
• Working with complex BPM changes
• Collaborating with other Phichain users

Advantages:

• Full feature set
• Best editor integration
• Human-readable structure
• Version migration support

Official Format

Use when:

• Exporting for gameplay in official Phigros
• Sharing charts with players
• Testing in the actual game
• You need maximum compatibility

Advantages:

• Direct game compatibility
• Widely supported
• Well-documented structure
• Battle-tested format

Limitations:

• Linear easing only (non-linear gets approximated)
• Single BPM per line
• No advanced features

RPE Format

Use when:

• Importing charts from Re:PhiEdit
• You need easing function support
• Working with event layers
• Collaborating with RPE users

Advantages:

• Rich easing support
• Event layer system
• Popular in community
• Re:PhiEdit compatible

Note: Some RPE features like event layers are flattened during import.

Primitive Format

Use when:

• Debugging conversion issues
• Writing custom tools
• Understanding internal structure
• Implementing new format support

Advantages:

• Simple, normalized structure
• Easy to parse and generate
• Core feature set only
• Format-agnostic

Conversion Examples

CLI

# Convert Official to Phichain
phichain convert official.json phichain.json

# Convert Phichain to RPE
phichain convert chart.json output.rpe.json --format rpe

# Convert RPE to Official
phichain convert input.rpe.json official.json --format official

Rust API

use phichain_chart::format::official::OfficialChart;
use phichain_chart::serialization::PhichainChart;
use phichain_chart::primitive::Format;

// Load Official format
let official: OfficialChart = serde_json::from_str(&json_str)?;

// Convert to Primitive, then to Phichain
let primitive = official.into_primitive()?;
let phichain = PhichainChart::from_primitive(primitive)?;

// Serialize
let output = serde_json::to_string_pretty(&phichain)?;

Compatibility Notes

Feature Loss During Conversion

Converting from feature-rich formats to simpler ones may lose data:

• Phichain → Official: Loses child lines, curve notes, non-linear easing
• RPE → Official: Event layers are flattened, easing approximated
• Any → Primitive: Loses format-specific metadata

Always keep original files when converting!

Easing Approximation

When converting non-linear easing to Official format, curves are approximated by breaking them into multiple linear segments (1/32 beat intervals). This maintains visual accuracy while staying compatible.

Version Migration

Phichain format supports automatic migration between versions:

use phichain_chart::migration::migrate;
use phichain_chart::serialization::PhichainChart;

let mut chart: PhichainChart = serde_json::from_str(&old_json)?;
let migrated = migrate(chart)?; // Upgrades to latest format

See the Phichain Format Spec for details on format version changes and migration.

Next Steps

Phichain Format Spec

Deep dive into the native format structure

Conversion Tool

Learn format conversion workflows