Map events are the visual layer of a fluXis map. While hit objects and timing points define when to play, events define what to show — screen flashes, colour shifts, playfield rotations, shader overlays, camera moves, and much more. Events live in a separate file referenced by the map’sDocumentation 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.
EffectFile property (typically a .fse file), and they are loaded and sorted by time before gameplay begins. Every event shares the same base property (time) and many also carry group, duration, and ease fields for smooth animated transitions.
All
time values are in milliseconds from the start of the audio track — the same coordinate space as hit objects and timing points. Events are sorted by time on load, so their order in the JSON file does not matter.Effect file structure
The.fse file is a plain JSON object whose keys correspond to event-type arrays:
Common fields
Nearly every event type includes the following properties:| Field | Type | Description |
|---|---|---|
time | number | Trigger time in milliseconds (required). |
group | string | Optional event group name for use with LoopEvent. Omitted from JSON when empty. |
duration | number | Length of the animated transition in milliseconds (0 = instant). |
ease | Easing | osu-framework easing function (integer or string). 0 = None (linear). Note: laneswitch and pulse use the key easing instead of ease. |
Event types
flash — Screen Flash
flash — Screen Flash
A screen flash overlays a solid or fading colour rectangle across the entire screen (or behind the playfield). It animates from a start colour/opacity to an end colour/opacity over
duration milliseconds.JSON key: flashWhen
true, the flash renders behind the playfield (background layer). When false, it renders in front of everything.Hex colour string for the beginning of the transition (default
#FFFFFF).Opacity at the start of the transition (
0.0–1.0, default 1.0).Hex colour string for the end of the transition (default
#FFFFFF).Opacity at the end of the transition (
0.0–1.0, default 0.0).laneswitch — Lane Count Change
laneswitch — Lane Count Change
Dynamically changes the number of active lanes mid-map. The transition is animated over
speed milliseconds using the specified easing. This is the mechanism behind variable-keymode maps (e.g. alternating between 4K and 7K sections).JSON key: laneswitchThe target lane count to switch to. Must be within the keymode range supported by the map.
Duration of the lane-width animation in milliseconds.
0 means an instant switch.Easing function for the width animation. Defaults to
OutQuint (value 12).Set
ls-v2: true in the .fsc file to use the improved visibility algorithm that correctly maps finger positions during the switch. All maps created with the modern editor have this flag set automatically.colorfade — Note Color Transition
colorfade — Note Color Transition
Smoothly fades one or more of the three lane colour roles (primary, secondary, middle) to a new hex colour. The transition respects
duration and ease. Only colour roles with their fade-* flag set to true are affected.JSON key: colorfadeWhen
true, the primary lane colour is transitioned.Target colour for the primary role.
When
true, the secondary lane colour is transitioned.Target colour for the secondary role.
When
true, the middle lane colour is transitioned.Target colour for the middle role.
Zero-based index of the playfield to target.
0 = primary playfield.Sub-playfield index for split/mirrored dual-mode maps.
pulse — Border Pulse
pulse — Border Pulse
Expands and contracts a border ring around the playfield, creating a “pulse” effect. The ring grows to
width pixels over the in-phase (in-percent * duration) and shrinks back to zero for the remainder of duration.JSON key: pulseMaximum border thickness in pixels at the peak of the pulse.
Total duration of the pulse animation in milliseconds.
Fraction of
duration used for the expand phase (0.0–1.0). The remaining fraction is used for the collapse.Easing function for the pulse animation. Uses the key
easing (not ease). Defaults to Out.shake — Screen Shake
shake — Screen Shake
Rapidly displaces the entire gameplay view in a random direction for the given duration, simulating an impact or explosion. Magnitude controls the maximum displacement distance.JSON key:
shakeHow long the shake lasts in milliseconds.
Maximum displacement in pixels per shake frame. Higher values produce a more violent effect.
shader — Post-Process Shader
shader — Post-Process Shader
Applies or animates a full-screen post-processing shader effect. Each shader has up to three independent
strength parameters whose meanings vary by shader type. The transition can animate from start-params to end-params over duration milliseconds.JSON key: shaderName of the shader to apply. Valid values (from
ShaderType enum):| Name | Description |
|---|---|
Bloom | Additive glow around bright elements |
Greyscale | Desaturates the screen |
Invert | Inverts all colours |
Chromatic | Chromatic aberration (RGB fringe) |
Mosaic | Pixelation / mosaic tile effect |
Noise | Film grain / noise overlay |
Vignette | Dark vignette around screen edges |
Retro | Scanline retro CRT effect |
HueShift | Rotates hue of the entire screen |
Glitch | Glitch blocks — strength1=X, strength2=Y, strength3=block size |
SplitScreen | Tiled mirror — strength2=splits X, strength3=splits Y |
FishEye | Fisheye lens distortion |
Reflections | Recursive reflections — strength2=scale |
Glitch2 | Secondary glitch — strength1=amount, strength2=speed |
When
true, the shader is instantly set to start-params before animating to end-params.Initial shader parameter values when
use-start is true.Target shader parameter values after the transition. Contains
strength, strength2, and strength3 floats.beatpulse — Periodic Zoom Pulse
beatpulse — Periodic Zoom Pulse
Creates a repeating zoom-in/zoom-out pulse that syncs to the beat. The playfield scales up to
strength and returns to normal, repeating every interval beats for as long as the event is active.JSON key: beatpulseScale factor at the peak of each pulse (e.g.
1.05 = 5% zoom-in).Fraction of the beat interval spent zooming in. The remaining fraction is used to zoom back out. Value is
0.0–1.0.How many beats between each pulse repetition.
1 = every beat, 2 = every other beat, 0.5 = twice per beat.layerfade — Playfield Layer Fade
layerfade — Playfield Layer Fade
Fades the opacity of a specific visual layer within a playfield. Useful for hiding notes, the stage background, receptor keys, or the entire playfield.JSON key:
layerfadeTarget opacity (
0.0 = fully transparent, 1.0 = fully opaque).Which layer to fade:
| Value | Name | Description |
|---|---|---|
0 | HitObjects | The note/hold rendering layer |
1 | Stage | The playfield stage background |
2 | Receptors | The receptor key indicators |
3 | Playfield | The entire playfield |
4 | HUD | The score / health HUD overlay |
Zero-based index of the target playfield.
Sub-playfield index for dual-mode maps.
playfieldmove — Playfield Position
playfieldmove — Playfield Position
Animates the playfield’s position by offsetting it along the X, Y, and Z axes. All three axes transition simultaneously over
duration using the given easing.JSON key: playfieldmoveHorizontal offset in pixels. Positive moves the playfield right.
Vertical offset in pixels. Positive moves the playfield down.
Depth offset (reserved for future 3D support). Currently has no visual effect.
Zero-based index of the target playfield.
Sub-playfield index for dual-mode maps.
playfieldscale — Playfield Scale
playfieldscale — Playfield Scale
Animates the playfield’s scale on X and Y axes independently. Values above
1.0 enlarge the playfield; values below 1.0 shrink it.JSON key: playfieldscaleHorizontal scale factor.
1.0 = normal width.Vertical scale factor.
1.0 = normal height.Zero-based index of the target playfield.
Sub-playfield index for dual-mode maps.
playfieldrotate — Playfield Rotation
playfieldrotate — Playfield Rotation
Rotates the entire playfield around its centre point. The rotation is expressed in degrees and animated over
duration.JSON key: playfieldrotateRotation angle in degrees. Positive values rotate clockwise. The playfield snaps back to
0 only if another playfieldrotate event explicitly sets it.Zero-based index of the target playfield.
Sub-playfield index for dual-mode maps.
hitease — Hit Object Easing
hitease — Hit Object Easing
Changes the easing function applied to how hit objects approach the judgement line within their scroll group. This affects the visual feel of note movement — e.g. notes can accelerate in (
InQuad) or decelerate out (OutQuad).JSON key: hiteaseAny valid osu-framework
Easing enum value. 0 = None (linear movement, the default).scroll-multiply — Scroll Speed Multiplier (Animated)
scroll-multiply — Scroll Speed Multiplier (Animated)
Animates the scroll-speed multiplier for a named scroll group from its current value to
multiplier over duration ms. Unlike a static ScrollVelocity, this provides a smooth eased transition between speeds.JSON key: scroll-multiplyTarget scroll speed multiplier.
Named scroll groups to apply the multiplier to. Empty array targets the default group.
time-offset — Visual Time Offset
time-offset — Visual Time Offset
Shifts the visual arrival time of all hit objects, making notes appear to arrive earlier or later on screen. Useful for creating rush/delay gimmicks where notes visually drift toward or away from the receptor while being hit on time musically.JSON key:
time-offsetTarget visual time offset in milliseconds. Positive = notes appear earlier (rushed); negative = notes appear later (delayed).
When
true, the offset snaps to start-offset before animating to offset.Initial offset when
use-start is true.camera-move — Camera Position
camera-move — Camera Position
camera-scale — Camera Zoom
camera-scale — Camera Zoom
Scales the camera viewport uniformly, zooming in or out on all playfields at once.JSON key:
camera-scaleUniform scale factor.
1.0 = no zoom, 1.5 = 50% zoom in, 0.8 = slight zoom out.camera-rotate — Camera Rotation
camera-rotate — Camera Rotation
Rotates the entire camera viewport around its centre. All playfields and UI elements rotate together.JSON key:
camera-rotateRotation angle in degrees. Positive = clockwise.
loops — Loop Group
loops — Loop Group
Repeats a named group of events a given number of times, each occurrence offset by
distance milliseconds. This is a compile-time directive — when the effect file is loaded the engine expands all loop events into their constituent copies before sorting.JSON key: loopsThe
group name of the events to repeat. All events with a matching group field will be copied.Time offset in milliseconds between successive loop iterations.
How many times to repeat the group (not including the original).
notes — Note Events (Subtitles)
notes — Note Events (Subtitles)
Displays a text string on screen at a specific time. Used for subtitles, karaoke lyrics, or in-game annotations. Content is free-form text.JSON key:
notesThe text string to display on screen.
Quick-reference table
| JSON key | C# class | Primary purpose |
|---|---|---|
flash | FlashEvent | Full-screen colour overlay |
laneswitch | LaneSwitchEvent | Dynamic lane count changes |
colorfade | ColorFadeEvent | Animate lane note colours |
pulse | PulseEvent | Expanding border ring |
shake | ShakeEvent | Screen shake on impact |
shader | ShaderEvent | Post-process shader effects |
beatpulse | BeatPulseEvent | Periodic zoom pulse |
layerfade | LayerFadeEvent | Fade individual playfield layers |
playfieldmove | PlayfieldMoveEvent | Translate playfield position |
playfieldscale | PlayfieldScaleEvent | Scale playfield dimensions |
playfieldrotate | PlayfieldRotateEvent | Rotate playfield |
hitease | HitObjectEaseEvent | Change note scroll easing |
scroll-multiply | ScrollMultiplierEvent | Animated scroll speed |
time-offset | TimeOffsetEvent | Visual note arrival offset |
camera-move | CameraMoveEvent | Move camera viewport |
camera-scale | CameraScaleEvent | Zoom camera |
camera-rotate | CameraRotateEvent | Rotate camera |
loops | LoopEvent | Repeat event groups |
notes | NoteEvent | On-screen text |