Friday Night Funkin' Cookbook
Friday Night Funkin' CookbookAdvancedScript Event Callbacks

Script Event Callbacks

Reading time: 7 minutes

This chapter will walk you through the process of using script event callbacks for a more advanced custom behavior, which will get called whenever a certain event within the game happens.

Several base classes use functions that get an event dispatched to them whenever something in the game happens, such as when getting created or destroyed. With your scripted class, you can override these callbacks to perform custom behavior when these would receive a dispatched event. Not every base class has every callback to their disposal.

Overriding Script Event Callbacks

Even if most base classes have the script event callbacks as empty functions, others have behavior that is entirely dependant on them. As such, you can skip the behavior or call it under a condition depending on if and where you put your super function call. One such example is in the script file for Boyfriend (Christmas)2

// ...

public override function onNoteHit(event:HitNoteScriptEvent)
{
  // ...

  // Override the hit note animation.
  switch (event.note.kind)
  {
    case "censor":
      holdTimer = 0;
      this.playSingAnimation(event.note.noteData.getDirection(), false, 'censor');
      return;
    case "hey":
      holdTimer = 0;
      this.playAnimation('hey', true, true);
      return;
    default:
      super.onNoteHit(event);
  }
}

// ...

Script Event Cancelling

While most cannot be cancelled, cancelling some events provides more leeway to the custom behavior. An example to this would be having pre-song cutscenes, as seen in the script file for the song Darnell1

// ...

// Line 78
public override function onCountdownStart(event:CountdownScriptEvent):Void
{
  super.onCountdownStart(event);

  // ...

  if (hasPlayedCutscene && !hasPlayedInGameCutscene)
  {
    trace('Pausing countdown to play in game cutscene');

    hasPlayedInGameCutscene = true;

    event.cancel(); // CANCEL THE COUNTDOWN!

    PlayState.instance.camHUD.visible = false;
    introCutscene();
  }

   // ...

}

// ...

You can also stop propagating the event (making it no longer go to other functions)


// ...

public override function onNoteMiss(event:NoteScriptEvent):Void
{
  event.cancel();
  event.shouldPropagate = false; // causes it to stop propagating to other events! (meaning other functions will no longer get this event sent *AFTER* this function has been called)
}

// ...

List of Script Event Callbacks

There is a predefined list of every script event callback the game has set up to be overridable, with their respective event type whose fields you can read from or write to. More of these will be added to the future.

  • onScriptEvent(event:ScriptEvent) - Called when any sort of script event would get dispatched. This is called before the event's respective callback.

    • Available to Songs, Stage Props, Boppers, Characters, Stages, Backing Cards, Freeplay DJs, Note Kinds, Dialogue Boxes, Speakers, Conversations and Modules.

  • onCreate(event:ScriptEvent) - Called when the base class gets created in the game.

    • Available to Songs, Stage Props, Boppers, Characters, Stages, Backing Cards, Freeplay DJs, Note Kinds, Dialogue Boxes, Speakers, Conversations and Modules.

  • onDestroy(event:ScriptEvent) - Called when the base class gets destroyed in the game.

    • Available to Songs, Stage Props, Boppers, Characters, Stages, Backing Cards, Freeplay DJs, Note Kinds, Dialogue Boxes, Speakers, Conversations and Modules.

  • onUpdate(event:UpdateScriptEvent) - Called when the base class gets updated in the game.

    • Available to Songs, Stage Props, Boppers, Characters, Stages, Backing Cards, Freeplay DJs, Note Kinds, Dialogue Boxes, Speakers, Conversations and Modules.

  • onStateChangeBegin(event:StateChangeScriptEvent) - Called when the State changing process begins.

    • Available to Backing Cards, Freeplay DJs and Modules.

  • onStateChangeEnd(event:StateChangeScriptEvent) - Called when the State changing process ends.

    • Available to Backing Cards, Freeplay DJs and Modules.

  • onStateCreate(event:ScriptEvent) - Called when the State that was switched to gets created.

    • Available to Modules.

  • onSubStateOpenBegin(event:SubStateScriptEvent) - Called when the SubState opening process begins.

    • Available to Backing Cards, Freeplay DJs and Modules.

  • onSubStateOpenEnd(event:SubStateScriptEvent) - Called when the SubState opening process ends.

    • Available to Backing Cards, Freeplay DJs and Modules.

  • onSubStateCloseBegin(event:SubStateScriptEvent) - Called when the SubState closing process begins.

    • Available to Backing Cards, Freeplay DJs and Modules.

  • onSubStateCloseEnd(event:SubStateScriptEvent) - Called when the SubState closing process ends.

    • Available to Backing Cards, Freeplay DJs and Modules.

  • onFocusLost(event:FocusScriptEvent) - Called when the focus from the game window is lost.

    • Available to Backing Cards, Freeplay DJs and Modules.

  • onFocusGained(event:FocusScriptEvent) - Called when the focus from the game window is gained.

    • Available to Backing Cards, Freeplay DJs and Modules.

  • onAdd(event:ScriptEvent) - Called when the base class is added to the game stage.

    • Available to Stage Props, Boppers and Characters.

  • onNoteIncoming(event:NoteScriptEvent) - Called when a note is within the field of view.

    • Available to Songs, Boppers, Characters, Stages, Notekinds and Modules.

  • onNoteHit(event:HitNoteScriptEvent) - Called when a note is hit by either character.

    • Available to Songs, Boppers, Characters, Stages, Notekinds and Modules.

  • onNoteMiss(event:NoteScriptEvent) - Called when a note is missed by either character.

    • Available to Songs, Boppers, Characters, Stages, Notekinds and Modules.

  • onNoteHoldDrop(event:HoldNoteScriptEvent) - Called when a hold note is dropped by either character.

    • Available to Songs, Boppers, Characters, Stages, Notekinds and Modules.

  • onStepHit(event:SongTimeScriptEvent) - Called when the Conductor reaches a new step of the music.

    • Available to Songs, Boppers, Characters, Stages, Backing Cards, Freeplay DJs and Modules.

  • onBeatHit(event:SongTimeScriptEvent) - Called when the Conductor reaches a new beat of the music.

    • Available to Songs, Boppers, Characters, Stages, Backing Cards, Freeplay DJs and Modules.

  • onPause(event:PauseScriptEvent) - Called when the main gameplay is paused.

    • Available to Songs, Boppers, Characters, Stages and Modules.

  • onResume(event:ScriptEvent) - Called when the main gameplay is resumed.

    • Available to Songs, Boppers, Characters, Stages and Modules.

  • onSongLoaded(event:SongLoadScriptEvent) - Called when song chart has been parsed but before the notes have been placed, both when starting the song for the first time and retrying the song.

    • Available to Songs, Boppers, Characters, Stages and Modules.

  • onSongStart(event:ScriptEvent) - Called when the song starts.

    • Available to Songs, Boppers, Characters, Stages and Modules.

  • onSongEnd(event:ScriptEvent) - Called when the song ends.

    • Available to Songs, Boppers, Characters, Stages and Modules.

  • onGameOver(event:ScriptEvent) - Called when the player runs out of health but before the game over substate is opened.

    • Available to Songs, Boppers, Characters, Stages and Modules.

  • onSongRetry(event:SongRetryEvent) - Called when the song retrying process begins, either through the pause menu or through the game over screen.

    • Available to Songs, Boppers, Characters, Stages and Modules.

  • onNoteGhostMiss(event:GhostMissNoteScriptEvent) - Called when the player pressed a key with no notes on the strumline.

    • Available to Songs, Boppers, Characters, Stages and Modules.

  • onSongEvent(event:SongEventScriptEvent) - Called when a song event (such as Focus Camera) is triggered.

    • Available to Songs, Boppers, Characters, Stages and Modules.

  • onCountdownStart(event:CountdownScriptEvent) - Called when the countdown is about to start.

    • Available to Songs, Boppers, Characters, Stages and Modules.

  • onCountdownStep(event:CountdownScriptEvent) - Called when a countdown changes its current step.

    • Available to Songs, Boppers, Characters, Stages and Modules.

  • onCountdownEnd(event:CountdownScriptEvent) - Called when the countdown ends.

    • Available to Songs, Boppers, Characters, Stages and Modules.

  • onDialogueCompleteLine(event:DialogueScriptEvent) - Called when the player advanced the dialogue while it's being typed.

    • Available to Dialogue Boxes, Speakers and Conversations.

  • onDialogueLine(event:DialogueScriptEvent) - Called when the player advances the dialogue while it's idling.

    • Available to Dialogue Boxes, Speakers and Conversations.

  • onDialogueSkip(event:DialogueScriptEvent) - Called when the dialogue gets skipped.

    • Available to Dialogue Boxes, Speakers and Conversations.

  • onDialogueEnd(event:DialogueScriptEvent) - Called when the dialogue ends.

    • Available to Dialogue Boxes, Speakers and Conversations.

  • onCapsuleSelected(event:CapsuleScriptEvent) - Called when the Freeplay capsule is selected.

    • Available to Backing Cards, Freeplay DJs and Modules.

  • onDifficultySwitch(event:CapsuleScriptEvent) - Called when the difficulty is switched in the Freeplay menu.

    • Available to Backing Cards, Freeplay DJs and Modules.

  • onSongSelected(event:CapsuleScriptEvent) - Called when the song is selected in the Freeplay menu.

    • Available to Backing Cards, Freeplay DJs and Modules.

  • onFreeplayIntroDone(event:FreeplayScriptEvent) - Called when the Freeplay intro sequence is finished - sort of like onCountdownStart but for the Freeplay menu.

    • Available to Backing Cards, Freeplay DJs and Modules.

  • onFreeplayOutro(event:FreeplayScriptEvent) - Called when the Freeplay closing process begins.

    • Available to Backing Cards, Freeplay DJs and Modules.

  • onFreeplayClose(event:FreeplayScriptEvent) - Called when the Freeplay closing process ends.

    • Available to Backing Cards, Freeplay DJs and Modules.

  • onCharacterSelect(event:CharacterSelectScriptEvent) - Called when a character has been hovered over in the Character Select menu.

    • Available to Modules.

  • onCharacterConfirm(event:CharacterSelectScriptEvent) - Called when the character selection has been confirmed in the Character Select menu.

    • Available to Modules.

  • onCharacterDeselect(event:CharacterSelectScriptEvent) - Called when the character selection has been cancelled in the Character Select menu.

    • Available to Modules.

List of Event Types

There is a predefined list of script events, whose fields are readable and, in some cases, changeable, that get dispatched to script event callbacks. More of these will be added in the future. See above which callback accepts which event.

  • ScriptEvent, with fields:

    • (read-only) cancelable - If the event can be canceled.
    • (read-only) type - The type of the event.
    • (read-only) shouldPropagate - If the event can be dispatched to its respective callback. If false, it will only get dispatched to onScriptEvent.
    • (read-only) eventCanceled - If the event has been cancelled.
    • cancelEvent() - Cancels the event, if possible.
    • cancel() - Cancels the event, if possible.
    • stopPropagation() - Stops the propagation of this event.

  • UpdateScriptEvent, with fields:

    • Inherited from ScriptEvent.
    • (read-only) elapsed - How much time has passed since the last update.

  • StateChangeScriptEvent, with fields:

    • Inherited from ScriptEvent.
    • (read-only) targetState - The State that was switched to.

  • SubStateScriptEvent, with fields:

    • Inherited from ScriptEvent.
    • (read-only) targetState - The SubState that was opened/closed.

  • FocusScriptEvent, with fields:

    • Inherited from ScriptEvent.

  • NoteScriptEvent, with fields:

    • Inherited from ScriptEvent.
    • (read-only) note - The NoteSprite associated with this event.
    • (read-only) comboCount - The currently ongoing combo.
    • playSound - Whether to play a miss sound when missing a note.
    • healthChange - The amount of health to add to the player. Can be a negative value too.

  • HitNoteScriptEvent, with fields:

    • Inherited from NoteScriptEvent.
    • judgement - The judgement received from hitting the note.
    • score - The score received from hitting the note.
    • isComboBreak - If the hit caused a combo break.
    • hitDiff - The time difference (in milliseconds) when the player hit the note.
    • doesNotesplash - If the note does a splash, defaults to true when the judgement is "sick".

  • HoldNoteScriptEvent, with fields:

    • Inherited from NoteScriptEvent.
    • holdNote - The SustainTrail object associated with this event.
    • score - The score received from hitting the note.
    • isComboBreak - If the hit caused a combo break.
    • hitDiff - The time difference (in milliseconds) when the player hit the note.
    • doesNotesplash - If the note does a splash, defaults to true when the judgement is "sick".

  • SongTimeScriptEvent, with fields:

    • Inherited from ScriptEvent.
    • (read-only) beat - The current beat of the song.
    • (read-only) step - The current step of the song.

  • PauseScriptEvent, with fields:

    • Inherited from ScriptEvent.
    • gitaroo - If the Gitaroo Man easter egg should be used.

  • SongLoadScriptEvent, with fields:

    • Inherited from ScriptEvent.
    • (read-only) id - The song id associated with the event.
    • (read-only) difficulty - The song difficulty associated with the event.
    • notes - An Array of SongNoteData objects representing the notes for the chart.
    • events - An Array of SongEventData objects representing the events for the chart.

  • SongRetryEvent, with fields:

    • Inherited from ScriptEvent.
    • (read-only) difficulty - The new difficulty of the song.

  • GhostMissNoteScriptEvent, with fields:

    • Inherited from ScriptEvent.
    • (read-only) dir - The direction (1-4) that was mistakenly pressed.
    • (read-only) hasPossibleNotes - If there were notes within judgement range when the key was pressed.
    • healthChange - The amount of health to add to the player. Can be a negative value too.
    • scoreChange - The amount of score to add to the player. Can be a negative value too.
    • playSound - Whether to play a miss sound.
    • playAnim - Whether to play a miss animation.

  • SongEventScriptEvent, with fields:

    • Inherited from ScriptEvent.
    • (read-only) eventData - The SongEventData object associated with the event.

  • CountdownScriptEvent, with fields:

    • Inherited from ScriptEvent.
    • (read-only) step - The current countdown step. Can be BEFORE, THREE, TWO, ONE, GO or AFTER.

  • DialogueScriptEvent, with fields:

    • Inherited from ScriptEvent.
    • (read-only) conversation - The Conversation object associated with the event.

  • CapsuleScriptEvent, with fields:

    • Inherited from ScriptEvent.
    • (read-only) capsule - The freeplay song capsule associated with the event.
    • (read-only) difficultyId - The ID of the currently selected difficulty in the Freeplay menu.
    • (read-only) variationId - The ID of the currently selected variation in the Freeplay menu.

  • FreeplayScriptEvent, with fields:

    • Inherited from ScriptEvent.

  • CharacterSelectScriptEvent, with fields:

    • Inherited from ScriptEvent.
    • (read-only) characterId - The ID of the player associated with the event.

  1. https://github.com/FunkinCrew/funkin.assets/blob/main/preload/scripts/songs/darnell.hxc ↩

  2. https://github.com/FunkinCrew/funkin.assets/blob/main/preload/scripts/characters/bf-christmas.hxc ↩

Contributors:
Kolo
MightyTheArmiddilo
Kade
Cameron Taylor
anysad
Last modified:
Created:
Category:  Advanced
Tags:
 , 
Edit page | Add new page