add info abt new labels, alt insts and locking songs outta freeplay

Author: KoloInDaCrib

assets/content/cookbook/Advanced/3.ScriptedSongs.md

@@ -24,4 +24,76 @@ class BallisticSong extends Song {
 
 You can then add override functions to perform custom behavior.
 
+## Custom 'NEW'-Label criteria
+
+Usually, in the Freeplay menu, a song would not have the glowing 'NEW' label. However if you override the function `isSongNew`, you can have the label appear if a specific criteria is met. An example of this is found in the script for Cocoa[^cocoa] which returns true if the variation is Pico and the player hasn't beaten Cocoa Pico Mix.
+```haxe
+// ...
+
+// Line 29
+public override function isSongNew(currentDifficulty:String, currentVariation:String):Bool
+{
+    if (currentVariation == 'pico') return !Save.instance.hasBeatenSong(this.id, null, 'pico');
+
+    return false;
+}
+
+// ...
+```
+
+## Custom Alternate Instrumental behavior
+
+Instead of reading from the song's metadata file for possible alternate instrumentals, you can use scripts to lock some of them out of being used until a criteria is met. An example of this is found in the script for Stress[^stress] which locks the pico instrumental behind completing the pico remix, as well as not provide the default instrumental if the song is selected on the pico variation.
+```haxe
+// ...
+
+// Line 42
+public override function listAltInstrumentalIds(difficultyId:String, variationId:String):Array<String>
+{
+    if (difficultyId == 'easy' || difficultyId == 'normal' || difficultyId == 'hard')
+    {
+        var hasBeatenPicoMix = Save.instance.hasBeatenSong(this.id, null, 'pico');
+
+        switch (variationId)
+        {
+            case 'pico':
+                // return hasBeatenPicoMix ? [''] : [];
+                // No Pico mix on BF instrumental, sorry!
+                return [];
+            default:
+                return hasBeatenPicoMix ? ['pico'] : [];
+        }
+    }
+
+    return [];
+}
+
+// ...
+```
+
+## Hiding the Song from the Freeplay Menu
+
+The most important thing to override here is the function `listDifficulties`. If you return an empty array, the song will be omitted from the Freeplay menu. An example to this is in the song 2hot[^2hot]
+```haxe
+// ...
+        
+// Line 51
+public function listDifficulties(variationId:String, variationIds:Array<String>, showLocked:Bool):Array<String>
+{
+    if (showLocked || Save.instance.hasBeatenLevel('weekend1'))
+    {
+        return super.listDifficulties(variationId, variationIds);
+    }
+
+    // Hide all difficulties if the player has not beaten the week.
+    return [];
+}
+
+// ...
+```
+
+[^cocoa]: <https://github.com/FunkinCrew/funkin.assets/blob/main/preload/scripts/songs/cocoa.hxc>
+[^2hot]: <https://github.com/FunkinCrew/funkin.assets/blob/main/preload/scripts/songs/2hot.hxc>
+[^stress]: <https://github.com/FunkinCrew/funkin.assets/blob/main/preload/scripts/songs/stress.hxc>
+
 > Author: [EliteMasterEric](https://github.com/EliteMasterEric)