Song Script

Empty Script

Example song scripts can be found at the following links: 1 2 3 4

function create() {}
function cutscene() {
    // code here
    game.startCountdown();
}
function createPost() {}
function countdownTick(tick:Int) {} // 0 = 3, 1 = 2, 2 = 1, 3 = Go!
function songStart() {}
function update(elapsed:Int) {}
function updatePost() {}
function gameOver() {}
function gameOverUpdate(elapsed:Float) {}
function gameOverEnd() {}
function pause() {}
function camMove(char:String) {} 
function noteSpawn(note) {}
function opponentNoteHit(note) {}
function goodNoteHit(note) {}
function noteMiss(?note) {}
function comboPop(rating:String, combo:Int, ?msTiming:Float) {}
function songEnd() {
    // code here lol
    game.endSong();
}
function stepHit(step:Int) {}
function beatHit(beat:Int) {}
function sectionHit(section:Int) {}
function eventLoad(eventName:String, value1:String, value2:String) {}
function event(eventName:String, value1:String, value2:String) {}

How to Use

You can make a global script at scripts/<yourcoolscriptname>.hxs.

You can make a song exclusive script in songs/<songname>/scripts/<yourcoolscriptname>.hxs.

These scripts execute when the playstate is active.

Variables

• game: The active playstate instance.
• Paths: The global paths instance.
• add(object:FlxBasic): Shorthand for PlayState.instance.add.
• addToHUD(object:FlxBasic): Utility that adds a sprite to the HUD camera.
• addToTop(object:FlxBasic): Utility that adds a sprite to the top camera.
• remove(object:FlxBasic): Shorthand for PlayState.instance.remove.
• STOP: A value that can be returned in most callback functions to stop the function from completing. This could be used to create your own functionality and visuals per-callback. (does not work on every callback, list pending)

Useful game variables

There are a few variables in the PlayState that can be useful in your song script depending on what you're looking to achieve.

• game.moveHealthIcons: Bool, if false, the health icons won't follow the health bar.
• game.bopHealthIcons: Bool, if false, the health icons won't bop.
• game.moveCamera: Bool, if false, the camera won't move with each mustHitSection.
• game.forceCutscene: Bool, if true, the game will show song cutscenes, even if not in story mode.
• game.disableInput: Bool, if true, the player's inputs will be disabled.
• game.camZooming: Bool, if true, the camera will bump.
• game.doStrumIntro: Bool, if false, the strums will not tween in, good for a custom intro or just repositioning strums.
• game.bopSpeed: Int, bumps the camera every X beats. (default: 4)
• game.camBumpZoom: Float, how hard the game camera bumps. (default: 0.015)
• game.hudBumpZoom: Float, how hard the hud bumps. (default: 0.03)

Useful game functions

• game.moveCam(target:Dynamic): Shortcut for moving the game camera, target can either be "bf", "gf", "dad" or an array with 2 floats.
• game.preloadEvent(eventName:String, value1:String, value2:String): Preloads an uncharted event.
• game.invokeEvent(eventName:String, value1:String, value2:String): Invokes an uncharted event.
• game.openDialogueBox(boxType:String, dialogue:Array<String>, callback:Void -> Void): Opens a custom dialogue box.

Callbacks (All Optional)

• create(): Called after all song scripts are loaded.
• cutscene(): Called if available in any script and the game is in story mode. If you use this function in your script, you'll have to call game.startCountdown().
• createPost(): Called when PlayState#create is complete.
• countdownTick(tick:Int): Called on each countdown tick.
• songStart(): Called after the countdown is complete.
• update(elapsed:Float): Called every frame.
• updatePost(): Called after PlayState#update is complete.
• gameOver(): Called when the player runs out of health or calls a reset. If you'd like to open a custom game over substate, do it here.
• gameOverStart(): Called when the default game over substate opens. It can be accessed and altered via GameOverSubstate.instance.
• gameOverUpdate(elapsed:Float): Called every frame on the default game over substate.
• gameOverEnd(): Called when the end function is called in the default game over substate.
• pause(): Called when the player pauses the game.
• camMove(char:String): Called when a mustHitSection camera change is made. Char is either "dad" or "bf".
• noteSpawn(note:Note): Called when a new note is created. Use note.isSustainNote to see if the note is a hold, and note.mustPress to see if it's the player's note or not.
• opponentNoteHit(note:Note): Called when the opponent hits a note.
• goodNoteHit(note:Note): Same as above but for the player.
• noteMiss(?note:Note): Called if the player misses a note. Note could be null if player doesn't use ghost tapping.
• comboPop(rating:String, combo:Int, ?msTiming:Float): Called when a combo sprite is supposed to popup. If the rating is a miss, msTiming will be null.
• songEnd(): Called when the song is about to end. If you use this function, be sure to call game.endSong().
• sectionHit(section:Int): Called when a section is hit.
• stepHit(step:Int): Called when a step is hit.
• beatHit(beat:Int): Called when a beat is hit.
• eventLoad(eventName:String, value1:String, value2:String): Called when an event gets preloaded.
• event(eventName:String, value1:String, value2:String): Called when an event is invoked.

Note: These do not all necessarily execute in the order shown.