add startOutro, deprecate switchTo

[Geokureli]

related to #2565

adds startOutro which is called from FlxG.switchState with a callback that - when called - triggers the actual switching. switchTo is now deprecated because it doesn't work with the proposed changes for Flixel 6.0.0

It's worth noting that this new system doesn't allow states to prevent switches, by evaluating the next state instance, but based on the name "switchTo" and how switchTo is currently used I don't think that was ever a desired feature, but rather a side-effect to how it was implemented, if devs want to use this kind of state flow control they can make some proprietary system for handling that.

The Old Way

when FlxG.switchState is called, switchTo is called, a fade to black is started, after which stateSwitch is called again and it will actually switch states.

package states;

import flixel.text.FlxBitmapText;
import flixel.FlxState;
import flixel.FlxG;

class StateOutroTestState extends FlxState
{
    var switchingStates:Bool = false;
    
    override function create()
    {
        super.create();
        
        final text = new FlxBitmapText("StateOutroTestState");
        text.scale.scale(4);
        text.updateHitbox();
        // show in random position so it's clear that a state switch happened
        text.x = FlxG.random.float(0, FlxG.width - text.width);
        text.y = FlxG.random.float(0, FlxG.height - text.height);
        add(text);
    }
    
    override function update(elapsed)
    {
        super.update(elapsed);
        
        if (FlxG.keys.justReleased.SPACE && switchingStates == false)
        {
            // prevents switch state calls while already playing the outro
            switchingStates = true;
            FlxG.switchState(new StateOutroTestState());
        }
    }
    
    // --- --- --- --- --- --- ---  The Important Part   --- --- --- --- --- --- --- //
    var outroComplete = false;
    override function switchTo(nextState:FlxState):Bool
    {
        if (outroComplete)
            return true;
        
        camera.fade(function ()
        {
            outroComplete = true;
            FlxG.switchState(nextState);
        });
        return false;
    }
    // --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- //
}

Note: This way still works perfectly fine but overriding switchTo in a class that derives from FlxState will show the warning: "switchTo is deprecated, use startOutro".

The New Way

In this way, startOutro simply passes the complete callback into the fade

package states;

import flixel.text.FlxBitmapText;
import flixel.FlxState;
import flixel.FlxG;

class StateOutroTestState extends FlxState
{
    var switchingStates:Bool = false;
    
    override function create()
    {
        super.create();
        
        final text = new FlxBitmapText("StateOutroTestState");
        text.scale.scale(4);
        text.updateHitbox();
        // show in random position so it's clear that a state switch happened
        text.x = FlxG.random.float(0, FlxG.width - text.width);
        text.y = FlxG.random.float(0, FlxG.height - text.height);
        add(text);
    }
    
    override function update(elapsed)
    {
        super.update(elapsed);
        
        if (FlxG.keys.justReleased.SPACE && switchingStates == false)
        {
            // prevents switch state calls while already playing the outro
            switchingStates = true;
            FlxG.switchState(new StateOutroTestState());
        }
    }
    
    // --- --- --- --- --- --- ---  The Important Part   --- --- --- --- --- --- --- //
    override function startOutro(onOutroComplete:()->Void)
    {
        camera.fade(onOutroComplete);
    }
    // --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- //
}

Pretty sexy, if I do say so, myself.