Scripted Stages

This chapter will walk you through the process of adding a script to a Stage, 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/stages if you want to keep things organized)

// Remember to import each class you want to reference in your script!
import funkin.play.stage.Stage;

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

    // Add override functions here!
}

You can then add override functions to perform custom behavior.

Custom Behavior when adding a Character

Considering characters get applied later in the initialization process, you would need to override the function addCharacter if you want to perform custom behavior involving characters. With this, you can set a shader to the added character immediately after they're added. An example of this is found in the script for the stage Mall (Erect)¹

// ...

// Line 35
override function addCharacter(character:BaseCharacter, charType:CharacterType):Void
{
    // Apply the shader automatically to each character as it gets added.
    super.addCharacter(character, charType);
    trace('Applied stage shader to ' + character.characterName);
    character.shader = colorShader;
}

// ...

Custom Behavior when building a Stage

By overriding the function buildStage, you can set up custom behavior to activate when stage props get initialized. By doing this, you can immediately apply a shader effect to props or instantly add scripted props to the stage. This is done in the stage script for Tankman Battlefield²

// ...

// Line 21
override function buildStage()
{
    super.buildStage();

    clouds = new FlxTiledSprite(Paths.image('tankClouds'), 3200, 235, true, false);
    clouds.setPosition(-1100, 20);
    clouds.scrollFactor.set(0.25, 0.25);
    clouds.zIndex = 12;

    clouds.velocity.x = 8;

    PlayState.instance.currentStage.add(clouds);
    PlayState.instance.currentStage.refresh(); // Apply z-index.

    tankAngle = FlxG.random.int(-90, 45);
    tankSpeed = FlxG.random.float(5, 7);
}

// ...

---

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

2. https://github.com/FunkinCrew/funkin.assets/blob/main/preload/scripts/stages/tankmanBattlefield.hxc ↩