Custom Classes Docs + other HScript features docs (#155)

Author: Jamextreme140

wiki/modding/scripting/custom-classes.md

@@ -0,0 +1,50 @@
+---
+author: Ne_Eo, Frakits & Jamextreme140
+desc: This page explains how to create custom classes for your mod!
+lastUpdated: 2025-09-19T04:13:02.526Z
+title: Custom Classes
+---
+# Custom Classes
+
+Custom classes can be made either inside the script you need it in or you can make a script file corresponding with the name of the class in ``./source``, and using <syntax lang="haxe">import</syntax> to import it.
+
+Here is a basic Song Script code that uses it:
+```haxe
+package; // Allow `package` declaration. Ignored by the interpreter.
+
+class SpecialSprite extends FlxSprite {
+  public static function getSprite(v:String) {
+    return new SpecialSprite(v);
+  }
+
+  public var customValue(default, set):String = null;
+  private function set_customValue(v:String):String {
+      if(v == "powerful") 
+          trace("I'm powerful!");
+      loadGraphic(Paths.image(v));
+      return customValue = v;
+  }  
+        
+  public function new(customValue:String) {
+      super(200, 400, null);
+      this.customValue = customValue;
+      //other code stuff
+  }
+
+  public override function update(elapsed) {
+      super.update(elapsed);
+  }
+}
+
+function create() {
+  var spr = SpecialSprite.getSprite("powerful");
+  add(spr);
+}
+```
+
+## Particularities
+As of writing this, this system is limited and also presents some defects. For example:
+- You cannot extend FlxGroups or other typed classes *(the ones that end with a ``<T>``)*. This will be implemented in the future.
+- Compiled Classes that do not override a function in their code cannot have that function overridden by custom classes. For example, you can't override the `draw` method in a custom class that extends <syntax lang="haxe">FlxParticle</syntax>, because <syntax lang="haxe">FlxParticle</syntax> does not override `draw`. This will be fixed in the future.
+- private variables and functions has not effect. They can be accessed as public variables.
+- You can only extend a class that is in the packages, `flixel`, `funkin` and `modchart`.

wiki/modding/scripting/features/custom-classes.md

@@ -0,0 +1,50 @@
+---
+author: Jamextreme140
+desc: This page explains how to use scripted enums for your mod!
+lastUpdated: 2025-09-12T08:53:13.034Z
+title: Enums
+---
+# Enums
+
+Enums are a good choice if only a finite set of values should be allowed. It can be made inside the script you need it in.
+
+Here is a basic Enum Script example:
+
+```haxe
+enum TypeValue {
+  NUMBER(n:Int);
+  DECIMAL(d:Float, ?p:Int);
+  CHARACTER(s:String);
+  BOOLEAN(b:Bool);
+}
+
+var type:TypeValue;
+
+function create() {
+  type = TypeValue.DECIMAL(10.1234, 2);
+  
+  // You need to type the full enum field for each case
+  // i.e. you can't type the enum field directly (limitation for now)
+  switch(type) {
+    case TypeValue.NUMBER(number): 
+      trace("number: " + number);
+    case TypeValue.DECIMAL(decimal, precision): 
+      if(precision != null)
+        trace("decimal: " + decimal + " | rounded decimal: " + roundDecimal(decimal, precision));
+      else
+        trace("decimal: " + decimal);
+    case TypeValue.CHARACTER(char): 
+      trace("character: " + char);
+    default: 
+      trace("unknown type");
+  }
+}
+  
+
+function roundDecimal(Value:Float, Precision:Int) {
+  var mult:Float = Math.pow(10, Precision);
+  return Math.fround(Value * mult) / mult;
+}
+```
+
+Supports Enum matching with arguments for switch statements (for real and scripted enums).

wiki/modding/scripting/features/enums.md

@@ -0,0 +1,12 @@
+---
+author: Jamextreme140
+desc: This page explains how to use the following scripting features in your mod!
+lastUpdated: 2025-09-19T04:11:01.175Z
+title: Scripting Features
+---
+# Scripting Features
+
+- [Custom Classes](./custom-classes.md)
+- [Enums](./enums.md)
+- [Property Fields](./property-fields.md)
+- [Static Extension](./static-extension.md)

wiki/modding/scripting/features/index.md

@@ -0,0 +1,37 @@
+---
+author: Jamextreme140
+desc: This page explains how to use property fields for your mod!
+lastUpdated: 2025-09-12T09:49:51.453Z
+title: Property Fields
+---
+# Property Fields (get/set variables)
+
+Property Fields provide a way to control access to script or class fields, offering more flexibility than simple variables. They are defined by specifying read and write access identifiers within parentheses after the field name.
+
+Here is a basic Property Field usage example:
+
+`./songs/script1.hx`
+
+```haxe
+public var myvar(default, set):Int;
+
+function set_myvar(val:Int):Int {
+  if(val > 10) return myvar = val;
+  return val;
+}
+```
+
+`./songs/[SONG NAME]/scripts/script2.hx`
+
+```haxe
+function create() {
+    myvar = 20; // This will trigger the set call stored on the field.
+}
+```
+
+More information about property fields [here](https://haxe.org/manual/class-field-property.html).
+
+## Particularities
+As of writing this, this system presents some limitations. For example:
+- `(get, null)` or `(null, set)` has no effect for writing nor reading, it acts like (get, default).
+- Calling the get/set function directly will trigger that function twice due to accessing the property field on call (if is a real variable, like `(get, null)` or `(default, set)`). For example, calling directly `set_myvar` will call the same function again when tries to write on `myvar`. Avoid doing this unless you have a full property field (a non-real variable, i.e. `(get, set)` or `(get, never)`). This will be fixed in the future.

wiki/modding/scripting/features/property-fields.md

@@ -0,0 +1,35 @@
+---
+author: Jamextreme140
+desc: This page explains how to use static extension for your mod!
+lastUpdated: 2025-09-12T09:50:05.405Z
+title: Static Extension
+---
+# Static Extension
+
+Static extensions provide a mechanism to "extend" existing types with new functionality without modifying their original source code. This can be used either with real and custom classes.
+
+Here is a basic Static Extension example:
+
+```haxe
+using StringTools;
+
+class IntExtender {
+  static public function triple(i:Int) {
+    return i * 3;
+  }
+}
+
+// need to create/import the custom class
+// before setting the extension (limitation for now)
+using IntExtender;
+
+var str = "  Hello World!  ";
+
+function create() {
+  trace(str.trim()); // "Hello World!"
+  trace(12.triple()); // 36
+}
+
+```
+
+More information about static extension [here](https://haxe.org/manual/lf-static-extension.html).

wiki/modding/scripting/features/static-extension.md

@@ -1,7 +1,7 @@
 ---
 author: Frakits
 desc: This page explains how to script the engine
-lastUpdated: 2025-01-08T23:47:04.206Z
+lastUpdated: 2025-09-12T09:36:28.820Z
 title: Scripting
 ---
 # Scripting
@@ -76,6 +76,7 @@ We have a special variable named `__script__` that points to the script that is
 - <a href="./script-calls.md">All of the script calls</a>
 
 And if you wanna go advanced, follow the rest of the articles here:
+- <a href="./features/index.md">Scripting Features</a>
 - <a href="./playstate-scripts/pause-gameover-scripts.md">Pause/Game Over Scripts</a>
 - <a href="./playstate-scripts/cutscenes-dialogue-scripts.md">Cutscenes/Dialogue Scripts</a>
 - <a href="./playstate-scripts/character-stage-scripts.md">Character/Stage Scripts</a><br><br>
@@ -85,6 +86,5 @@ And if you wanna go advanced, follow the rest of the articles here:
 - <a href="./3d-rendering.md">3D rendering</a>
 - <a href="./hxvlc.md">Using hxvlc for videos</a><br><br>
 - <a href="./scripted-assets-libraries.md">Scripted Assets Libraries</a>
-- <a href="./custom-classes.md">Custom Classes</a>
 - <a href="./ndll-scripting.md">NDLL Scripting</a>
 - <a href="./custom-transitions.md">Custom Transitions</a>

wiki/modding/scripting/index.md

@@ -23,6 +23,12 @@
         ["cutscenes-dialogues", "Cutscenes/Dialogues"],
         ["note-splashes", "Note Splashes"],
         ["scripting/index", "Scripting", [
+            ["features/index", "Features", [
+                ["custom-classes", "Custom Classes"],
+                ["enums", "Enums"],
+                ["property-fields", "Property Fields"],
+                ["static-extension", "Static Extension"]
+            ]],
             ["playstate-scripts/index", "PlayState Scripts", [
                 ["gameplay-scripts", "Gameplay Scripts"],
                 ["events-notetypes-scripts", "Events/Notetype Scripts"],
@@ -36,7 +42,6 @@
             ["hxvlc", "Using hxvlc for videos"],
             ["custom-options", "Custom Options"],
             ["custom-controls", "Custom Controls"],
-            ["custom-classes", "Custom Classes"],
             ["3d-rendering", "3D rendering - UNFINISHED"],
             ["script-calls", "All of the script calls - UNFINISHED"],
             ["script-snippets", "Useful script snippets for modders - UNFINISHED"],