Scripted Levels

This chapter will walk you through the process of adding a script to a Story Menu Level, and giving examples of the kind of custom behavior which can be implemented with this functionality.

Start by creating a scripted class file with the .hxc extension (in the mods/mymod/scripts/levels if you want to keep things organized).

// Remember to import each class you want to reference in your script!
import funkin.ui.story.Level;

// Choose a name for your scripted class that will be unique, and make sure to specifically extend the Level class.
// This class's functions will override the default behavior for the level.
class BonusWeekLevel extends Level {
    public function new() {
        // The constructor gets called once, when the game loads.
        // The constructor takes one parameter, which is the level ID for the level you are applying the script to.
        super('bonusWeek');
    }

    // Add override functions here!
}

You can then add override functions to perform custom behavior.

Hiding specific Songs from the Menu

By overriding the function getSongDisplayNames, you can hide certain songs from showing up on the story menu until a certain criteria is met. An example for this can be found in the script file for the Weekend 1 level.¹

// ...

// Line 16
override function getSongDisplayNames(difficultyId:String):Array<String>
{
    if (Save.instance.hasBeatenLevel('weekend1'))
    {
        // Blazin' is a secret song ;)
        return ["Darnell", "Lit Up", "2hot", "Blazin'"];
    }
    else
    {
        return ["Darnell", "Lit Up", "2hot"];
    }
}

// ...

Locking the Level

If you want to lock the level behind a specific check, you must override the function isUnlocked. When the player tries to enter a locked week, the menu canceling sound will play and any further behavior would be skipped. By returning false in that function, the level will be locked until the player meets the criteria inside the check. The game currently does not contain a good example for this.

Making the Level invisible

As opposed to locking the level, making the level invisible will omit it from the Story Menu entirely. This does not omit the level's songs from being included from the Freeplay menu. To achieve this, you must override the function isVisible, which by default returns true. The game currently does not contain a good example for this.

Omitting Songs from the Level

Even if you override getSongDisplayNames, the songs omitted will still be able to be played normally, both through the Story Menu and the Freeplay Menu. However, if you were to override the getSongs function instead, you can exclude songs from both the Freeplay Menu and the Story Menu songs playlist, meaning that the player wouldn't be able to play a song that you wish to exclude. You could also override this function to include a new song for the level if the player has met a condition. By default, this function returns a copy of the array of song ids listed in the level's .json file. The game currently does not have a good example for this.

---

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