Song Events

Overview

The song event system allows chart creators to trigger gameplay changes at specific points in a song. Events can control camera focus, zoom, character swaps, stage changes, and more.

Class Hierarchy

SongEvent (base class)
  ├── FocusCameraSongEvent
  ├── ZoomCameraSongEvent
  ├── SetCharacterSongEvent
  ├── SetStageSongEvent
  ├── PlayAnimationSongEvent
  ├── ScrollSpeedEvent
  └── ScriptedSongEvent (custom events)

SongEvent

Base class for all song events.

Properties

String

Unique identifier for this event type

processOldEvents

Bool

default:"false"

If true, events are handled even when skipping forward in the song

Methods

`new(id:String, ?params:SongEventParams)`

Creates a new event handler.

public function new() {
  super('MyEvent', {
    processOldEvents: true
  });
}

String

required

Event type identifier

params

SongEventParams

Optional parameters (processOldEvents)

`handleEvent(data:SongEventData):Void`

Handles the event when it’s triggered. Must be overridden.

public override function handleEvent(data:SongEventData):Void
{
  var value = data.getFloat('value') ?? 1.0;
  // Perform event action
}

`getEventSchema():SongEventSchema`

Returns the chart editor schema for this event.

public override function getEventSchema():SongEventSchema
{
  return new SongEventSchema([{
    name: 'value',
    title: 'Value',
    defaultValue: 1.0,
    type: SongEventFieldType.FLOAT
  }]);
}

`getTitle():String`

Returns the human-readable title.

public override function getTitle():String {
  return 'My Custom Event';
}

`getIconPath():String`

Returns the path to the event’s icon.

public override function getIconPath():String {
  return 'ui/chart-editor/events/my-event';
}

Built-in Events

FocusCameraSongEvent

Changes camera focus to a character or position.

Event Data

{
  "e": "FocusCamera",
  "v": {
    "char": 0,
    "x": 0,
    "y": -10,
    "duration": 4.0,
    "ease": "quad",
    "easeDir": "InOut"
  }
}

char

Int

default:"0"

Target: -1 (Position), 0 (Player/BF), 1 (Opponent/Dad), 2 (Girlfriend)

Float

default:"0"

X offset or absolute X position

Float

default:"0"

Y offset or absolute Y position

duration

Float

default:"4.0"

Tween duration in steps

ease

String

default:"CLASSIC"

Easing function: linear, INSTANT, CLASSIC, sine, quad, cube, etc.

easeDir

String

default:"In"

Easing direction: In, Out, InOut

Examples

// Focus on Boyfriend
{
  "e": "FocusCamera",
  "v": { "char": 0 }
}

// Focus 10px above Girlfriend with smooth easing
{
  "e": "FocusCamera",
  "v": {
    "char": 2,
    "y": -10,
    "duration": 8.0,
    "ease": "sine",
    "easeDir": "InOut"
  }
}

// Focus on specific position
{
  "e": "FocusCamera",
  "v": {
    "char": -1,
    "x": 640,
    "y": 360,
    "ease": "INSTANT"
  }
}

ZoomCameraSongEvent

Changes camera zoom level.

Event Data

{
  "e": "ZoomCamera",
  "v": {
    "zoom": 1.3,
    "duration": 4.0,
    "mode": "direct",
    "ease": "linear",
    "easeDir": "In"
  }
}

zoom

Float

default:"1.0"

Target zoom level

duration

Float

default:"4.0"

Tween duration in steps

mode

String

default:"direct"

“stage” (relative to stage zoom) or “direct” (absolute)

ease

String

default:"linear"

Easing function

easeDir

String

default:"In"

Easing direction

Examples

// Instant zoom to 1.5x
{
  "e": "ZoomCamera",
  "v": {
    "zoom": 1.5,
    "ease": "INSTANT"
  }
}

// Smooth zoom out
{
  "e": "ZoomCamera",
  "v": {
    "zoom": 0.8,
    "duration": 16.0,
    "ease": "quad",
    "easeDir": "Out"
  }
}

Other Built-in Events

SetCharacterSongEvent

Swaps a character mid-song
Useful for character transformations

SetStageSongEvent

Changes the entire stage
Can trigger scene transitions

PlayAnimationSongEvent

Forces a character to play a specific animation
Useful for cutscenes

ScrollSpeedEvent

Changes scroll speed mid-song
Can speed up or slow down gameplay

SetCameraBopSongEvent

Controls camera bop intensity
Affects camera “bounce” on beats

SetHealthIconSongEvent

Changes a character’s health icon
Useful for character transformations

Creating Custom Events

Basic Custom Event

package;

import funkin.play.event.SongEvent;
import funkin.data.song.SongData.SongEventData;
import funkin.data.event.SongEventSchema;
import funkin.data.event.SongEventSchema.SongEventFieldType;

class FlashScreenEvent extends SongEvent
{
  public function new()
  {
    super('FlashScreen');
  }
  
  public override function handleEvent(data:SongEventData):Void
  {
    if (PlayState.instance == null) return;
    
    var color = data.getString('color') ?? 'FFFFFF';
    var duration = data.getFloat('duration') ?? 0.5;
    
    // Flash the screen
    FlxG.camera.flash(FlxColor.fromString('#$color'), duration);
  }
  
  public override function getTitle():String
  {
    return 'Flash Screen';
  }
  
  public override function getEventSchema():SongEventSchema
  {
    return new SongEventSchema([{
      name: 'color',
      title: 'Flash Color',
      defaultValue: 'FFFFFF',
      type: SongEventFieldType.STRING
    }, {
      name: 'duration',
      title: 'Duration',
      defaultValue: 0.5,
      step: 0.1,
      type: SongEventFieldType.FLOAT,
      units: 'seconds'
    }]);
  }
}

Advanced Custom Event

class ShakeStageEvent extends SongEvent
{
  public function new()
  {
    super('ShakeStage');
  }
  
  public override function handleEvent(data:SongEventData):Void
  {
    if (PlayState.instance == null) return;
    
    var intensity = data.getFloat('intensity') ?? 0.05;
    var duration = data.getFloat('duration') ?? 1.0;
    var axes = data.getString('axes') ?? 'XY';
    
    var xShake = axes.indexOf('X') != -1;
    var yShake = axes.indexOf('Y') != -1;
    
    FlxG.camera.shake(intensity, duration, null, true, 
      xShake ? HORIZONTAL : (yShake ? VERTICAL : BOTH));
  }
  
  public override function getTitle():String
  {
    return 'Shake Stage';
  }
  
  public override function getEventSchema():SongEventSchema
  {
    return new SongEventSchema([{
      name: 'intensity',
      title: 'Intensity',
      defaultValue: 0.05,
      min: 0,
      max: 1,
      step: 0.01,
      type: SongEventFieldType.FLOAT
    }, {
      name: 'duration',
      title: 'Duration',
      defaultValue: 1.0,
      min: 0,
      step: 0.1,
      type: SongEventFieldType.FLOAT,
      units: 'seconds'
    }, {
      name: 'axes',
      title: 'Shake Axes',
      defaultValue: 'XY',
      type: SongEventFieldType.ENUM,
      keys: ['Both' => 'XY', 'X Only' => 'X', 'Y Only' => 'Y']
    }]);
  }
}

Event Data Access

Reading Event Values

public override function handleEvent(data:SongEventData):Void
{
  // Get typed values
  var floatVal = data.getFloat('myFloat') ?? 1.0;
  var intVal = data.getInt('myInt') ?? 0;
  var stringVal = data.getString('myString') ?? 'default';
  var boolVal = data.getBool('myBool') ?? false;
  
  // Get raw value
  var rawValue = data.value;
}

Event Schema Types

Field Types

SongEventFieldType.INTEGER    // Whole numbers
SongEventFieldType.FLOAT      // Decimal numbers
SongEventFieldType.STRING     // Text
SongEventFieldType.BOOL       // True/false
SongEventFieldType.ENUM       // Dropdown selection

Schema Example

new SongEventSchema([{
  name: 'target',           // Internal name
  title: 'Target Character', // Display name
  defaultValue: 0,          // Default value
  type: SongEventFieldType.ENUM,
  keys: [                   // Enum options
    'Player' => 0,
    'Opponent' => 1,
    'Girlfriend' => 2
  ]
}, {
  name: 'speed',
  title: 'Speed Multiplier',
  defaultValue: 1.0,
  min: 0.1,                 // Minimum value
  max: 5.0,                 // Maximum value
  step: 0.1,                // Increment step
  type: SongEventFieldType.FLOAT,
  units: 'x'                // Display units
}]);

Easing Functions

Available easing functions from FlxEase:

linear
sine, quad, cube, quart, quint
expo, circ, back, bounce, elastic
smoothStep, smootherStep

Easing directions:

In - Slow start, fast end
Out - Fast start, slow end
InOut - Slow start and end

Usage in Charts

Chart JSON Format

{
  "events": [
    {
      "t": 1000,
      "e": "FocusCamera",
      "v": {
        "char": 1,
        "duration": 4.0,
        "ease": "quad",
        "easeDir": "Out"
      }
    },
    {
      "t": 2000,
      "e": "ZoomCamera",
      "v": {
        "zoom": 1.3,
        "mode": "direct",
        "ease": "INSTANT"
      }
    }
  ]
}

Float

required

Event timestamp in milliseconds

String

required

Event type ID

Dynamic

required

Event-specific values/parameters

Best Practices

Use processOldEvents: true for events that should always execute, like camera position changes. Use false (default) for momentary effects like flashes.

Always check if PlayState.instance exists before accessing it in event handlers. Events can be processed in the chart editor.

Event schemas are used by the chart editor to provide a user-friendly interface. Well-defined schemas make events easier to use.

Core

Audio

Play

Data

Modding

Overview

Class Hierarchy

SongEvent

Properties

Methods

`new(id:String, ?params:SongEventParams)`

`handleEvent(data:SongEventData):Void`

`getEventSchema():SongEventSchema`

`getTitle():String`

`getIconPath():String`

Built-in Events

FocusCameraSongEvent

Event Data

Examples

ZoomCameraSongEvent

Event Data

Examples

Other Built-in Events

Creating Custom Events

Basic Custom Event

Advanced Custom Event

Event Data Access

Reading Event Values

Event Schema Types

Field Types

Schema Example

Easing Functions

Usage in Charts

Chart JSON Format

Best Practices

Build docs developers (and LLMs) love

Core

Audio

Play

Data

Modding

​Overview

​Class Hierarchy

​SongEvent

​Properties

​Methods

​new(id:String, ?params:SongEventParams)

​handleEvent(data:SongEventData):Void

​getEventSchema():SongEventSchema

​getTitle():String

​getIconPath():String

​Built-in Events

​FocusCameraSongEvent

​Event Data

​Examples

​ZoomCameraSongEvent

​Event Data

​Examples

​Other Built-in Events

​Creating Custom Events

​Basic Custom Event

​Advanced Custom Event

​Event Data Access

​Reading Event Values

​Event Schema Types

​Field Types

​Schema Example

​Easing Functions

​Usage in Charts

​Chart JSON Format

​Best Practices

Build docs developers (and LLMs) love

Overview

Class Hierarchy

SongEvent

Properties

Methods

`new(id:String, ?params:SongEventParams)`

`handleEvent(data:SongEventData):Void`

`getEventSchema():SongEventSchema`

`getTitle():String`

`getIconPath():String`

Built-in Events

FocusCameraSongEvent

Event Data

Examples

ZoomCameraSongEvent

Event Data

Examples

Other Built-in Events

Creating Custom Events

Basic Custom Event

Advanced Custom Event

Event Data Access

Reading Event Values

Event Schema Types

Field Types

Schema Example

Easing Functions

Usage in Charts

Chart JSON Format

Best Practices