provide information about scripted song events

Author: KoloInDaCrib

assets/content/cookbook/Advanced/12.ScriptedEvents.md

@@ -0,0 +1,115 @@
+[tags]:  / "advanced,hscript,events"
+
+# Scripted Song Events
+
+This chapter will walk you through the process of creating a custom song event, which could be used in songs through the chart editor.
+
+Start by creating a scripted class file with the `.hxc` extension (in the `mods/mymod/scripts/events` if you want to keep things organized)
+
+```haxe
+// Remember to import each class you want to reference in your script!
+import funkin.play.event.SongEvent;
+
+// Choose a name for your scripted class that will be unique, and make sure to specifically extend the SongEvent class.
+class FocusCameraSongEvent extends SongEvent {
+    public function new() {
+        // The constructor gets called once, when the game loads.
+        // The constructor takes one parameter, which is the event ID for your custom event.
+        super('FocusCamera');
+    }
+
+    // Add override functions here!
+}
+```
+
+You can then add override functions to perform custom behavior.
+
+## Performing behavior when getting called
+
+To provide custom behavior to the event that gets called when the song reaches the event's position, you must override the function `handleEvent`. Overriding this function is mandatory, as if your custom event doesn't include it, the game will crash when attempting to activate the event. The function comes with a parameter from which you can retreive some information about the event, such as the property values provided. An example of this can be found in the event Play Animation[^playanim]
+
+```haxe
+// ...
+
+// Line 18
+public override function handleEvent(data:SongEventData)
+{
+    // Does nothing if there is no PlayState camera or stage.
+    if (PlayState.instance == null || PlayState.instance.currentStage == null) return;
+
+    var targetName = data.getString('target');
+    var anim = data.getString('anim');
+    var force = data.getBool('force');
+    if (force == null) force = false;
+
+    // ...
+}
+
+// ...
+
+```
+
+## Providing song event properties
+
+The game supports providing events some additional properties for more leeway in functionality. For this, you need to override the function `getEventSchema` that returns an array of anonymous objects, each representing a property your event can have. The structure of these anonymous objects is as follows:
+
+- `name`: The internal name of the property, which you can use to get the value of the property when executing the event.
+
+- `title`: The visible name of the property, as displayed in the chart editor events toolbox.
+
+- `type`: The type of the event. Can be either `string` (text properties), `integer`, `float`, `bool` or `enum` (dropdown properties).
+
+- `defaultValue`: An optional default value for the property.
+
+- `keys`: Is an optional map with keys representing the visible name and values representing the internal name of the property values.
+
+    - Accessible to the `enum `properties.
+
+- `min`: Represents the optional minimum value that the property could have.
+
+    - Available to the `integer` and `float` properties. 
+
+- `max`: Represents the optional maximum value that the property could have.
+
+    - Available to the `integer` and `float` properties.
+
+- `step`: Represents the amount the value steps by for each change in the toolbox. This field is optional and defaults to `0.1`.
+
+    - Available to the `integer` and `float` properties.
+
+- `units`: Represents the unit of measure for the numeric value. (i.e. pixels, steps etc.)
+
+    - Available to the `integer` and `float` properties.
+
+## Custom song event chart editor icon
+
+Chart editor supports both static and animated song event icons in the spritesheet format. To provide a custom icon for your event in the chart editor, you need to put two things in the `mods/mymod/images/ui/chart-editor/events` folder: 
+
+- An image of your song event icon named after what you put in the event's constructor.
+
+- An XML file for your song event icon, even if it's a single frame.
+
+    - The frame names must start with the text you put inside the event's constructor.
+
+Once you made sure both assets are where they should be and have the correct names, your song event should have a custom icon in the chart editor.
+
+## Custom song event title
+
+To give your song event an unique title that will be displayed in the chart editor's event toolbox dropdown, you must override the function `getTitle` with the return of your desired event title. An example of this is found in the event Zoom Camera[^camzoom]
+
+```haxe
+// ...
+
+// Line 91
+public override function getTitle():String
+{
+    return 'Zoom Camera';
+}
+
+// ...
+```
+
+[^playanim]: <https://github.com/FunkinCrew/Funkin/blob/main/source/funkin/play/event/PlayAnimationSongEvent.hx>
+[^camzoom]: <https://github.com/FunkinCrew/Funkin/blob/main/source/funkin/play/event/ZoomCameraSongEvent.hx>
+
+> Author: [KoloInDaCrib](https://github.com/KoloInDaCrib)