FlxSubState is a special state that can be opened from within a FlxState or another FlxSubState.

When opened, a FlxSubState will be displayed on top of all other states/substates, and only the top-most FlxSubState will be responsive. By default, states below the top-most FlxSubState will stop being updated, although you can change this behavior, if desired.

Use openSubState to open a FlxSubState, and close to close it, giving control back to the parent FlxState or FlxSubState.

You can even define openCallback and/or closeCallback functions to be called when the FlxSubState is opened or closed, respectively.

FlxSubState is a versatile utility that can be used for in-game menus, pause screens, or other pop-up type screens.

// open and display a new sub-state from withing a FlxState or FlxSubState
openSubState(new MySubState());

Demonstration

package;

import flixel.FlxG;
import flixel.FlxSprite;
import flixel.FlxState;
import flixel.FlxSubState;
import flixel.text.FlxText;
import flixel.ui.FlxButton;
import flixel.util.FlxColor;
import flixel.util.FlxDestroyUtil;
import flixel.util.FlxSpriteUtil;

class PlayState extends FlxState
{
	private var sprite:FlxSprite;
	
	override function create()
	{
		super.create();
		
		sprite = new FlxSprite("assets/sprite.png");
		sprite.screenCenter();
		sprite.velocity.set(200, 200);
		add(sprite);
		
		var text = new FlxText();
		text.text = "I am the PlayState.";
		text.color = FlxColor.CYAN;
		text.size = 16;
		text.setBorderStyle(FlxTextBorderStyle.SHADOW, FlxColor.BLUE, 4);
		text.screenCenter();
		add(text);
		
		var button = new FlxButton(0, 0, "Open SubState", openSub);
		button.screenCenter();
		button.y = text.y + text.height + 16;
		add(button);
	}
	
	private function openSub():Void
	{
		openSubState(new OtherState());
	}
	
	override function update(elapsed:Float):Void
	{
		super.update(elapsed);
		
		if (sprite.x < 0 || sprite.x > FlxG.width)
		{
			sprite.velocity.x *= -1;
		}
		if (sprite.y < 0 || sprite.y > FlxG.height)
		{
			sprite.velocity.y *= -1;
		}
	}
}

class OtherState extends FlxSubState
{
	public function new()
	{
		super(0x33000000);
	}
	
	override function create()
	{
		super.create();
		
		var text = new FlxText();
		text.text = "I am the OtherState.";
		text.color = FlxColor.PINK;
		text.size = 16;
		text.setBorderStyle(FlxTextBorderStyle.SHADOW, FlxColor.RED, 4);
		text.screenCenter();
		
		var button = new FlxButton(0, 0, "Close SubState", closeSub);
		button.screenCenter();
		button.y = text.y + text.height + 16;
		
		var bg:FlxSprite = new FlxSprite();
		bg.makeGraphic(Std.int(text.width + 16), Std.int(text.height + button.height + 36), FlxColor.WHITE);
		FlxSpriteUtil.drawRect(bg, 1, 1, bg.width - 2, bg.height - 2, FlxColor.BLACK);
		bg.screenCenter();
		
		add(bg);
		add(text);
		add(button);
	}
	
	private function closeSub():Void
	{
		close();
	}
}