Hit objects are the interactive elements of a fluXis map — the notes a player must press, hold, or avoid. Every hit object is a JSON entry in theDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/InventiveRhythm/fluXis/llms.txt
Use this file to discover all available pages before exploring further.
HitObjects array of the .fsc file. At minimum an object needs a time, a lane, and a type. The engine reads the full list, sorts it by time, and then hands each object to the appropriate ruleset handler based on its type field. Whether you are building a simple four-key pattern or a complex multi-group scroll section, all note data flows through this single, compact schema.
All time values across fluXis are in milliseconds from the start of the audio track. A note at
time: 1000 appears exactly one second into the song.JSON properties
The point in the song, in milliseconds, at which the note must be hit. The engine sorts all hit objects by this value before gameplay begins, so order inside the JSON file does not matter.
The column number for the note, counting from
1 (leftmost) to the keymode count (rightmost). For a 4K map valid values are 1–4. The maximum lane value present in the entire HitObjects array determines the keymode of the map.Duration of a long note (hold note) in milliseconds. When this value is greater than
0 and type is Normal, the note becomes a long note. The player must press the key at time and release it at time + holdtime. A value of 0 means the object is a regular tap note.Name of the hit-sound sample to play when this note is hit (e.g.
"normal", "clap", "whistle"). The engine resolves this name against the active skin’s sound bank. When omitted or null, the default hit-sound for the skin is used.Optional scroll-group identifier. Notes that share the same group string are governed by a single
ScrollGroup, allowing independent scroll velocity stacks for different lanes or visual layers. When omitted the note belongs to the default scroll group.When
true the note is invisible to the player but still registers as a judgeable object. Used for hidden-note gimmicks or tutorial sequences where input must be detected silently.Determines the gameplay behaviour of the note.
| Value | Name | Description |
|---|---|---|
0 | Normal | Standard tap note. Becomes a long note when holdtime > 0. |
1 | Tick | Tick note — a smaller, lightweight note that counts toward combo but does not break it on miss. Uses visual-lane for display position. |
2 | Landmine | Mine — a note the player must not hit. Pressing it during its window causes a health penalty. |
Overrides the rendered horizontal position of a Tick note without changing its input lane. Allows a tick note to visually float between columns for choreography purposes. Only meaningful when
type is 1 (Tick).Note types in detail
Normal Note
A standard tap. Press the key at the correct time.
holdtime is 0.Long Note (Hold)
Press and hold.
type is Normal and holdtime > 0. Both the press and release are judged separately, so a long note contributes two combo increments to MaxCombo.Tick Note
A lightweight hit that builds combo without a harsh miss penalty. Use
visual-lane to position it anywhere on the playfield.Landmine
An avoidance note. The player must release or never press this lane during the note’s window or they will take a health penalty.
JSON examples
Normal tap note (4K, lane 2, 180 BPM beat 1)
Long note (hold for 500 ms)
A long note is aNormal type with holdtime set. The player must press at time and release at time + holdtime.
EndTime is 1000 + 500 = 1500 ms.
Tick note with visual offset
Landmine
Long note in a named scroll group
Computed properties (runtime only)
These values are calculated by the engine and are never written to the JSON file. They are listed here so you understand how the game derives them.time + holdtime for long notes; equals time for tap notes. Marks the moment the hold window closes.true when holdtime > 0 and type == Normal. Drives the long-note renderer.true when type == Landmine. Shorthand used internally by the hit-detection pipeline.Each normal tap note counts as 1 combo point. Each long note counts as 2 (one for the press, one for the release). Tick notes also increment combo. Landmines do not contribute to combo.