From 027890d601105eaf2f9798f8b558b4c41952f3e2 Mon Sep 17 00:00:00 2001 From: Jaime Humberto Macias Bustamante Date: Fri, 12 Sep 2025 03:13:23 -0700 Subject: [PATCH 1/2] Custom Classes Docs + other features docs --- wiki/modding/scripting/custom-classes.md | 43 -------------- .../modding/scripting/custom-classes/enums.md | 50 +++++++++++++++++ .../modding/scripting/custom-classes/index.md | 56 +++++++++++++++++++ .../custom-classes/property-fields.md | 37 ++++++++++++ .../custom-classes/static-extension.md | 35 ++++++++++++ wiki/modding/scripting/index.md | 4 +- wiki/wiki.json | 6 +- 7 files changed, 185 insertions(+), 46 deletions(-) delete mode 100644 wiki/modding/scripting/custom-classes.md create mode 100644 wiki/modding/scripting/custom-classes/enums.md create mode 100644 wiki/modding/scripting/custom-classes/index.md create mode 100644 wiki/modding/scripting/custom-classes/property-fields.md create mode 100644 wiki/modding/scripting/custom-classes/static-extension.md diff --git a/wiki/modding/scripting/custom-classes.md b/wiki/modding/scripting/custom-classes.md deleted file mode 100644 index f45d3472..00000000 --- a/wiki/modding/scripting/custom-classes.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -author: Ne_Eo & Frakits -desc: This page explains how to create custom classes for your mod! -lastUpdated: 2024-09-11T09:37:50.000Z -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 import to import it. - -Here is a basic Song Script code that uses it: -```haxe -class SpecialSprite extends FlxSprite { - public var customValue:String = null; - public function new(?x:Float = 0, ?y:Float = 0, ?graphic:FlxGraphicAsset, customValue:String) { // it also has to start with the same arguments as the super class, (limitation for now) - super(x, y, graphic); // this does nothing currently, its purely visual for now, but it will be used in the future - this.customValue = customValue; - //other code stuff - } - - public override function update(elapsed) { - super.update(elapsed); - } -} - -function create() { - var spr = new SpecialSprite(200, 400, null, "powerful"); - add(spr); -} -``` - -## Particularities -As of writing this, this system is very limited and also presents some defects. For example: -- You cannot extend FlxGroups or other typed classes *(the ones that end with a ````)*. -- Classes that override a class needs to have the same arguments on the constructor as the class it overrides. Same when creating the instance of the class. -- 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 FlxParticle, because FlxParticle does not override `draw`. -- all variables need to be public in order to be accessed inside the class. -- static variables are not supported. (yet) -- static functions are not supported. (yet) -- private variables are not supported. They act as public variables. -- private functions are not supported. They act as public functions. -- You cannot extend a custom class. (yet) -- You can only extend a class that is in the packages, `flixel`, `funkin` \ No newline at end of file diff --git a/wiki/modding/scripting/custom-classes/enums.md b/wiki/modding/scripting/custom-classes/enums.md new file mode 100644 index 00000000..47eebc98 --- /dev/null +++ b/wiki/modding/scripting/custom-classes/enums.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). diff --git a/wiki/modding/scripting/custom-classes/index.md b/wiki/modding/scripting/custom-classes/index.md new file mode 100644 index 00000000..419f653f --- /dev/null +++ b/wiki/modding/scripting/custom-classes/index.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 import 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 ````)*. 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 FlxParticle, because FlxParticle 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) diff --git a/wiki/modding/scripting/custom-classes/property-fields.md b/wiki/modding/scripting/custom-classes/property-fields.md new file mode 100644 index 00000000..2802d5f2 --- /dev/null +++ b/wiki/modding/scripting/custom-classes/property-fields.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. diff --git a/wiki/modding/scripting/custom-classes/static-extension.md b/wiki/modding/scripting/custom-classes/static-extension.md new file mode 100644 index 00000000..ca7f14d3 --- /dev/null +++ b/wiki/modding/scripting/custom-classes/static-extension.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). diff --git a/wiki/modding/scripting/index.md b/wiki/modding/scripting/index.md index 6ccc129b..0346cf2c 100644 --- a/wiki/modding/scripting/index.md +++ b/wiki/modding/scripting/index.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: - 3D rendering - Using hxvlc for videos

- Scripted Assets Libraries -- Custom Classes +- Custom Classes - NDLL Scripting - Custom Transitions \ No newline at end of file diff --git a/wiki/wiki.json b/wiki/wiki.json index b2f33425..a2514499 100644 --- a/wiki/wiki.json +++ b/wiki/wiki.json @@ -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"], From b846a848acb5c6f794b66052842dc29a0284d964 Mon Sep 17 00:00:00 2001 From: Jaime Humberto Macias Bustamante Date: Thu, 18 Sep 2025 21:33:37 -0700 Subject: [PATCH 2/2] better sorted scripting features --- .../index.md => features/custom-classes.md} | 8 +------- .../scripting/{custom-classes => features}/enums.md | 0 wiki/modding/scripting/features/index.md | 12 ++++++++++++ .../{custom-classes => features}/property-fields.md | 2 +- .../{custom-classes => features}/static-extension.md | 2 +- wiki/modding/scripting/index.md | 2 +- wiki/wiki.json | 11 ++++++----- 7 files changed, 22 insertions(+), 15 deletions(-) rename wiki/modding/scripting/{custom-classes/index.md => features/custom-classes.md} (91%) rename wiki/modding/scripting/{custom-classes => features}/enums.md (100%) create mode 100644 wiki/modding/scripting/features/index.md rename wiki/modding/scripting/{custom-classes => features}/property-fields.md (84%) rename wiki/modding/scripting/{custom-classes => features}/static-extension.md (78%) diff --git a/wiki/modding/scripting/custom-classes/index.md b/wiki/modding/scripting/features/custom-classes.md similarity index 91% rename from wiki/modding/scripting/custom-classes/index.md rename to wiki/modding/scripting/features/custom-classes.md index 419f653f..4aa1a014 100644 --- a/wiki/modding/scripting/custom-classes/index.md +++ b/wiki/modding/scripting/features/custom-classes.md @@ -1,7 +1,7 @@ --- author: Ne_Eo, Frakits & Jamextreme140 desc: This page explains how to create custom classes for your mod! -lastUpdated: 2025-09-12T09:36:28.820Z +lastUpdated: 2025-09-19T04:13:02.526Z title: Custom Classes --- # Custom Classes @@ -48,9 +48,3 @@ As of writing this, this system is limited and also presents some defects. For e - 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 FlxParticle, because FlxParticle 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) diff --git a/wiki/modding/scripting/custom-classes/enums.md b/wiki/modding/scripting/features/enums.md similarity index 100% rename from wiki/modding/scripting/custom-classes/enums.md rename to wiki/modding/scripting/features/enums.md diff --git a/wiki/modding/scripting/features/index.md b/wiki/modding/scripting/features/index.md new file mode 100644 index 00000000..2db3601a --- /dev/null +++ b/wiki/modding/scripting/features/index.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) diff --git a/wiki/modding/scripting/custom-classes/property-fields.md b/wiki/modding/scripting/features/property-fields.md similarity index 84% rename from wiki/modding/scripting/custom-classes/property-fields.md rename to wiki/modding/scripting/features/property-fields.md index 2802d5f2..237a486f 100644 --- a/wiki/modding/scripting/custom-classes/property-fields.md +++ b/wiki/modding/scripting/features/property-fields.md @@ -6,7 +6,7 @@ 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. +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: diff --git a/wiki/modding/scripting/custom-classes/static-extension.md b/wiki/modding/scripting/features/static-extension.md similarity index 78% rename from wiki/modding/scripting/custom-classes/static-extension.md rename to wiki/modding/scripting/features/static-extension.md index ca7f14d3..eb83fd94 100644 --- a/wiki/modding/scripting/custom-classes/static-extension.md +++ b/wiki/modding/scripting/features/static-extension.md @@ -6,7 +6,7 @@ title: Static Extension --- # Static Extension -Static extensions can be a powerful tool which allows augmenting types without actually changing them. +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: diff --git a/wiki/modding/scripting/index.md b/wiki/modding/scripting/index.md index 0346cf2c..26bea1c7 100644 --- a/wiki/modding/scripting/index.md +++ b/wiki/modding/scripting/index.md @@ -76,6 +76,7 @@ We have a special variable named `__script__` that points to the script that is - All of the script calls And if you wanna go advanced, follow the rest of the articles here: +- Scripting Features - Pause/Game Over Scripts - Cutscenes/Dialogue Scripts - Character/Stage Scripts

@@ -85,6 +86,5 @@ And if you wanna go advanced, follow the rest of the articles here: - 3D rendering - Using hxvlc for videos

- Scripted Assets Libraries -- Custom Classes - NDLL Scripting - Custom Transitions \ No newline at end of file diff --git a/wiki/wiki.json b/wiki/wiki.json index a2514499..40793f30 100644 --- a/wiki/wiki.json +++ b/wiki/wiki.json @@ -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,11 +42,6 @@ ["hxvlc", "Using hxvlc for videos"], ["custom-options", "Custom Options"], ["custom-controls", "Custom Controls"], - ["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"],