Custom pause/game over article

Author: Kade-github

assets/content/cookbook/Expert/05.CustomPauseAndGameOver.md

@@ -0,0 +1,137 @@
+[tags]: / "expert,module,hscript"
+
+# Custom Pause and Game Over states
+
+Creating custom pause and game over states was made much easier in the 0.8.0 update, allowing you to use two new vital properties in [PlayState](https://thekade.net/funkin-api/funkin/play/PlayState.html#shouldSubstatePause):
+
+-   `shouldSubstatePause`
+-   `isGameOverState`
+
+These two properties allow you to set if the default functionality of the next *sub-state* PlayState opens.
+
+
+## Custom Pause Menu
+
+### Module Setup
+
+A setup for a module is typically required, although a song/stage script could also work (as they also have access to the [onPause](https://thekade.net/funkin-api/funkin/modding/events/PauseScriptEvent.html) event)
+
+The difference between a Module and a Song script here would be what level of integration you want the pause menu to be. Do you want it to be overriding every pause? Or only on one song?
+
+With a module you can do both, but it's up to you if you want to do it another way.
+
+```haxe
+package kade.hex.modules;
+
+import funkin.modding.module.Module;
+import funkin.play.PlayState;
+// Your custom pause state would be here
+import kade.hex.substates.HexPauseMenu;
+
+// ...
+
+class Hex_Hud extends Module
+{
+    public var shouldUseHexHud:Bool = false;
+
+    // ...
+
+    public override function onSongLoaded(event:SongLoadScriptEvent)
+    {
+        // A check to see if we're in the right note style for this hud
+        if (PlayState.instance.noteStyle.id == "hex")
+            shouldUseHexHud = true;
+
+        // ...
+    }
+
+    public override function onPause(event:PauseScriptEvent)
+    {
+        if (!shouldUseHexHud)
+            return;
+        // Ignore base game's pause menu
+        event.cancelEvent();
+
+        // Flags to 'pause' the game
+        PlayState.instance.persistentUpdate = false;
+        PlayState.instance.persistentDraw = true;
+
+        // Create and show our pause menu
+        final pauseSubState = new HexPauseMenu();
+        PlayState.instance.shouldSubstatePause = true;
+        PlayState.instance.openSubState(pauseSubState);
+    }
+
+    // ...
+}
+
+```
+
+## Custom Game Over
+
+A custom game over is similar, as it is also a sub-state that pauses the game. Though it is a bit different by also needing you to set the `isGameOverState` to `true` (along with other things)
+
+### Module Setup
+
+```haxe
+import kade.hex.substates.HexGameOverMenu;
+
+// ...
+
+class Hex_Hud extends Module
+{
+    // ...
+
+    public override function onGameOver(event:ScriptEvent)
+    {
+        if (!shouldUseHexHud)
+            return;
+
+        // Ignore base game's game over menu
+        event.cancelEvent();
+
+        // General game over flags the game sets when calling its own game over
+
+        PlayState.instance.persistentUpdate = false;
+        PlayState.instance.persistentDraw = true;
+        
+        PlayState.instance.isPlayerDying = true;
+
+        PlayState.instance.playerStrumline.clean();
+        PlayState.instance.opponentStrumline.clean();
+
+        PlayState.instance.vwooshTimer.cancel();
+
+        PlayState.instance.songScore = 0;
+
+        final gameOverSub = new HexGameOverMenu();
+
+        PlayState.instance.isGameOverState = true;
+        PlayState.instance.shouldSubstatePause = true;
+        PlayState.instance.openSubState(gameOverSub);
+    }
+
+    // ...
+}
+```
+
+### Pause/GameOver Sub-State Setup
+
+Then you can create your own custom Sub-State that'll be opened.
+
+```haxe
+package kade.hex.substates;
+
+import funkin.ui.MusicBeatSubState;
+
+// ...
+
+// This can also be HexGameOverMenu
+class HexPauseMenu extends MusicBeatSubState
+{
+    // ... code is surely here
+    // also: to close this sub-state, simply calling `close();` will work!
+}
+```
+
+> Author: [Kade](https://github.com/Kade-github)