Custom Classes Docs + other features docs

Author: Jamextreme140

wiki/modding/scripting/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/custom-classes/enums.md

@@ -0,0 +1,56 @@
+---
+author: Ne_Eo, Frakits & Jamextreme140
+desc: This page explains how to create custom classes for your mod!
+lastUpdated: 2025-09-12T09:36:28.820Z
+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`.
+
+## More HScript Features
+
+- [Enums](./enums.md)
+- [Property Fields](./property-fields.md)
+- [Static Extension](./static-extension.md)

wiki/modding/scripting/custom-classes/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)
+
+Next to variables, properties are the second option for dealing with data on a class. However, unlike variables, they offer more control of which kind of field access should be allowed and how it should be generated.
+
+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/custom-classes/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 can be a powerful tool which allows augmenting types without actually changing them.
+
+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/custom-classes/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
@@ -85,6 +85,6 @@ 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="./custom-classes/index.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

@@ -36,7 +36,11 @@
             ["hxvlc", "Using hxvlc for videos"],
             ["custom-options", "Custom Options"],
             ["custom-controls", "Custom Controls"],
-            ["custom-classes", "Custom Classes"],
+            ["custom-classes/index", "Custom Classes", [
+                ["enums", "Enums"],
+                ["property-fields", "Property Fields"],
+                ["static-extension", "Static Extension"]
+            ]],
             ["3d-rendering", "3D rendering - UNFINISHED"],
             ["script-calls", "All of the script calls - UNFINISHED"],
             ["script-snippets", "Useful script snippets for modders - UNFINISHED"],