[ADDITION] Article for scripted levels

assets/content/cookbook/Advanced/10.ScriptedLevels.md

@@ -0,0 +1,65 @@
+[tags]: / "advanced,hscript,level"
+
+# Scripted Levels
+
+This chapter will walk you through the process of adding a script to a Story Menu Level, 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/levels` if you want to keep things organized).
+
+```haxe
+// Remember to import each class you want to reference in your script!
+import funkin.ui.story.Level;
+
+// Choose a name for your scripted class that will be unique, and make sure to specifically extend the Level class.
+// This class's functions will override the default behavior for the level.
+class BonusWeekLevel extends Level {
+    public function new() {
+        // The constructor gets called once, when the game loads.
+        // The constructor takes one parameter, which is the level ID for the level you are applying the script to.
+		super('bonusWeek');
+	}
+
+    // Add override functions here!
+}
+```
+
+You can then add override functions to perform custom behavior.
+
+## Hiding specific Songs from the Menu
+
+By overriding the function `getSongDisplayNames`, you can hide certain songs from showing up on the story menu until a certain criteria is met. An example for this can be found in the script file for the Weekend 1 level.[^weekend1]
+```haxe
+// ...
+
+// Line 16
+override function getSongDisplayNames(difficultyId:String):Array<String>
+{
+    if (Save.instance.hasBeatenLevel('weekend1'))
+    {
+        // Blazin' is a secret song ;)
+        return ["Darnell", "Lit Up", "2hot", "Blazin'"];
+    }
+    else
+    {
+        return ["Darnell", "Lit Up", "2hot"];
+    }
+}
+
+// ...
+```
+
+## Locking the Level
+
+If you want to lock the level behind a specific check, you must override the function `isUnlocked`. When the player tries to enter a locked week, the menu canceling sound will play and any further behavior would be skipped. By returning false in that function, the level will be locked until the player meets the criteria inside the check. The game currently does not contain a good example for this.
+
+## Making the Level invisible
+
+As opposed to locking the level, making the level invisible will omit it from the Story Menu entirely. This does not omit the level's songs from being included from the Freeplay menu. To achieve this, you must override the function `isVisible`, which by default returns true. The game currently does not contain a good example for this.
+
+## Omitting Songs from the Level
+
+Even if you override `getSongDisplayNames`, the songs omitted will still be able to be played normally, both through the Story Menu and the Freeplay Menu. However, if you were to override the `getSongs` function instead, you can exclude songs from both the Freeplay Menu and the Story Menu songs playlist, meaning that the player wouldn't be able to play a song that you wish to exclude. You could also override this function to include a new song for the level if the player has met a condition. By default, this function returns a copy of the array of song ids listed in the level's .json file. The game currently does not have a good example for this.
+
+[^weekend1]: <https://github.com/FunkinCrew/funkin.assets/blob/main/preload/scripts/levels/weekend1.hxc>
+
+> Author: [KoloInDaCrib](https://github.com/KoloInDaCrib)