Scripting

The engine's biggest feature yet, scripting.
Currently, you can script in HScript (haxe scripting language), or in NDLL format (compiled C++ code), but mainly in HScript, which should make the experience similar to coding in source code.
Scripting can change not only gameplay, but also menus and other engine functions.

We will focus on writing in HScript, so whenever you have to create a script, the filename has to end with an .hx.
(you can also use .hscript, .hxc and .hxs)

Scripting relies heavily on having a console opened at all times.

The console helps you track down errors and bugs with your script. To access it, you can either:

Press F2 to open a window, or
Start the game in a cmd or powershell window (or in terminal for linux/mac users)

Our HScript accepts special syntax from Haxe 4.3.x

Things like ?., ?? and ??= are accepted in our HScript language.
Using those is beneficial as they prove to be very useful to keeping your code clean.
Example usage:

if (FlxG.sound.music != null) trace(FlxG.sound.music.time);

trace(FlxG.sound?.music);

var time:Float;
if (FlxG.sound.music != null) time = FlxG.sound.music.time;
else time = 0;

time = FlxG.sound?.music ?? 0;

if (FlxG.save.data.isOpen == null) FlxG.save.data.isOpen = true;

FlxG.save.data.isOpen ??= true;

Script Events

Scripting relies heavily on Events, which triggers callbacks and returns a struct of parameters, basically unclogging the parameter list of functions.
Which means, handling a note hit looks something like this:

function onNoteHit(event) {
    trace(event.note); // the note that has been hit
    trace(event.score); // how much score gained from this
    event.cancel(); // cancels out any other handling (useful if you want to write custom note pressing)
}

There's a lot of other events, such as onStartCountdown, onGamePause, onCameraMove and more.
You can find them all in All of the script calls.

Despite all of that, functions like update, beatHit, stepHit still receive one parameter (elapsed:Float, curBeat:Int, curStep:Int)

Importing Classes

Some classes are pre-imported (FlxSprite, FlxMath, FlxAxis etc.), but for classes that aren't pre-imported, it's still possible to import like this:

import flixel.addons.display.FlxBackdrop;

(using does not work, yet)

To start on basic scripting, you can follow these articles here:

And if you wanna go advanced, follow the rest of the articles here:

Written by: Frakits

Last updated: 2024-09-05

Edit this page on GitHub