scripted stage and useful funcs

i think the whitty stage was named alleyway idk i only have the KE version

Author: KoloInDaCrib

assets/content/cookbook/Advanced/11.ScriptedStages.md

@@ -0,0 +1,77 @@
+[tags]: / "advanced,hscript,stage"
+
+# 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)
+
+```haxe
+// 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 immidiately after they're added. An example of this is found in the script for the stage Mall (Erect)[^mall]
+```haxe
+// ...
+
+// 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 immidiately apply a shader effect to props or instantly add scripted props to the stage. This is done in the stage script for Tankman Battlefield[^tank]
+```haxe 
+// ...
+
+// 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);
+}
+
+// ...
+```
+
+[^mall]: <https://github.com/FunkinCrew/funkin.assets/blob/main/preload/scripts/stages/mallXmasErect.hxc>
+[^tank]: <https://github.com/FunkinCrew/funkin.assets/blob/main/preload/scripts/stages/tankmanBattlefield.hxc>
+
+> Author: [KoloInDaCrib](https://github.com/KoloInDaCrib)