The fluXis .fsc Map File Format: Complete Reference

Every fluXis map is stored as a UTF-8 encoded JSON file with the .fsc extension. The file sits inside a mapset folder alongside its audio, background image, cover art, and any optional video or effect files. When fluXis loads a map it deserialises this file into a MapInfo object, which acts as the single source of truth for everything the gameplay engine needs — from song metadata down to individual hit objects. Understanding the top-level structure is the first step to hand-crafting or programmatically generating maps.

The .fsc extension stands for fluXis Chart. All file paths stored inside the JSON (audio, background, etc.) are relative to the mapset folder, not absolute paths on disk.

Minimal example

The JSON snippet below is the smallest valid .fsc file. Every required array must be present, and at least one timing point and one hit object are mandatory.

{
  "AudioFile": "audio.mp3",
  "BackgroundFile": "bg.jpg",
  "CoverFile": "cover.jpg",
  "VideoFile": "",
  "EffectFile": "",
  "StoryboardFile": "",
  "metadata": {
    "title": "Example Song",
    "artist": "Example Artist",
    "mapper": "YourName",
    "difficulty": "Normal",
    "source": "",
    "tags": "",
    "previewtime": 15000
  },
  "colors": {
    "accent": "#523fbb"
  },
  "HitObjects": [
    { "time": 1000, "lane": 1, "hitsound": "normal", "type": 0 }
  ],
  "TimingPoints": [
    { "time": 0, "bpm": 180, "signature": 4 }
  ],
  "ScrollVelocities": [],
  "HitSoundFades": [],
  "AccuracyDifficulty": 8,
  "HealthDifficulty": 8,
  "dual": 0,
  "extra-playfields": 0
}

Top-level properties

File references

AudioFile

string

required

Filename of the audio track relative to the mapset folder (e.g. "audio.mp3"). fluXis supports MP3, OGG, and FLAC. An empty string means no audio is loaded.

BackgroundFile

string

required

Filename of the background image shown during gameplay (e.g. "bg.jpg"). Common formats are JPG and PNG. An empty string disables the background.

CoverFile

string

Filename of the cover art displayed in song selection and result screens. Recommended square dimensions (e.g. 500×500 px). Defaults to an empty string when omitted.

VideoFile

string

Filename of an optional background video (e.g. "video.mp4"). The video plays behind the playfield during gameplay. Leave empty to disable.

EffectFile

string

Filename of the map events JSON file (e.g. "effects.fse"). This is a separate file that holds all visual event lists (flashes, shaders, playfield transforms, etc.). See the Events page for the full schema.

StoryboardFile

string

Filename of the storyboard JSON file. Storyboards are independent of the effect file and drive more complex scripted visual overlays.

Metadata object

metadata

object

required

An object containing all human-readable information about the map. Serialised with the JSON key metadata.

Show metadata fields

title

string

required

The full song title (e.g. "Mystic Garden"). Displayed in song selection.

title-rm

string

Romanized version of the title for non-Latin scripts (e.g. Latin reading of a Japanese title).

artist

string

required

Name of the musical artist or composer.

artist-rm

string

Romanized version of the artist name.

mapper

string

required

Username of the person who created this difficulty.

difficulty

string

required

Difficulty label shown in song selection (e.g. "Hard", "Insane"). Free-form text.

source

string

Where the audio originates — game soundtrack, album name, etc.

bg-source

string

Attribution or source URL for the background image.

cover-source

string

Attribution or source URL for the cover art.

Colors object

colors

object

Optional per-map colour overrides for lane note colours. All values are hex strings ("#RRGGBB" or "#RRGGBBAA"). Serialised with the JSON key colors.

Show colors fields

accent

string

Primary accent colour used for UI highlights and the judgement line glow. Falls back to the player’s skin highlight when empty.

primary

string

Colour applied to the “primary” lane group (outer lanes). Transparent when empty, meaning the skin default is used.

secondary

string

Colour applied to the “secondary” lane group (inner lanes).

middle

string

Colour applied to the centre lane in odd-keymode layouts.

Game data arrays

HitObjects

HitObject[]

required

Ordered list of all notes, long notes, tick notes, and landmines. The engine sorts this array by time on load. Must contain at least one entry for the map to pass validation. See Hit Objects for the full schema.

TimingPoints

TimingPoint[]

required

List of BPM and time-signature change markers. At least one timing point starting at or before the first hit object is required. See Timing for the full schema.

ScrollVelocities

ScrollVelocity[]

List of scroll-velocity multipliers that speed up or slow down note travel independently of BPM. Can be empty. See Timing for details.

HitSoundFades

HitSoundFade[]

List of hit-sound volume automation entries. Each entry fades a named sound channel to a target volume over a given duration. Can be empty. See Timing for the full schema.

Difficulty settings

AccuracyDifficulty

float

default:"8"

Controls the hit-window sizes. Higher values shrink the windows, demanding tighter timing. Valid range is 0–10.

HealthDifficulty

float

default:"8"

Controls how quickly health drains on misses and recovers on hits. Higher values are more punishing. Valid range is 0–10.

Advanced options

dual

integer (DualMode)

default:"0"

Enables dual-playfield mode. Serialised as the JSON key dual.

Value	Name	Description
`0`	`Disabled`	Standard single playfield
`1`	`Mirrored`	Two playfields side-by-side, both playing the same notes mirrored
`2`	`Separate`	Two independent playfields, each with their own lane layout and hit objects

extra-playfields

integer

default:"0"

Number of additional decorative playfields to render (0–9). These are visual layers without interactive hit objects, used for storyboard-style effects. Serialised as the JSON key extra-playfields.

ls-v2

boolean

default:"false"

When true, the improved v2 lane-switch visibility algorithm is used for LaneSwitchEvent. Maps created in the modern editor always set this flag.

force-169

boolean

default:"false"

Forces a 16:9 aspect ratio viewport during gameplay regardless of the player’s screen resolution.

visualization-enabled

boolean

default:"false"

Enables the audio-reactive background visualisation layer during gameplay.

editor-time

integer

Stores the last cursor position in the editor (milliseconds) so the mapper can resume where they left off. Not used during gameplay.

File layout inside a mapset

A typical mapset folder looks like this:

<mapset-id>/
├── song.mp3          ← AudioFile
├── background.jpg    ← BackgroundFile
├── cover.jpg         ← CoverFile
├── video.mp4         ← VideoFile  (optional)
├── easy.fsc          ← one .fsc per difficulty
├── hard.fsc
└── hard.fse          ← EffectFile for hard.fsc  (optional)

Each difficulty is a separate .fsc file inside the same mapset folder. They all share the same audio and background files, but each can reference its own EffectFile and StoryboardFile.

Map Format

Editor

The fluXis .fsc Map File Format: Complete Reference

Minimal example

Top-level properties

File references

Metadata object

Colors object

Game data arrays

Difficulty settings

Advanced options

File layout inside a mapset

Build docs developers (and LLMs) love

Map Format

Editor

Documentation Index

​Minimal example

​Top-level properties

​File references

​Metadata object

​Colors object

​Game data arrays

​Difficulty settings

​Advanced options

​File layout inside a mapset

Build docs developers (and LLMs) love

Minimal example

Top-level properties

File references

Metadata object

Colors object

Game data arrays

Difficulty settings

Advanced options

File layout inside a mapset