Repository navigation
Scripting
Scripts in Rhythmo can be active in only one song, or be applied globally to every song. You can use scripts to make custom backgrounds, add special functions, make cool mechanics, etc.
Your script should either be located in assets/scripts/[name].hxs, or in assets/songs/[song-name]/[name].hxs.
However, if your script is a scripted state or substate, it should be located in assets/classes/[name].hxs.
But also, it doesn't have to be an .hxs file.
The following extensions are also supported:
.hx.hxc.hscript
The following are not supported:
- Keywords:
-
package,import(another function emulates this),class,typedef,metadata,final
-
- Wildcard imports (
import flixel.*) - Access modifiers (e.g.,
private,public)
-
Function_Stop- Cancels functions (e.g.,startCountdown,endSong). -
Function_Continue- Continues the game like normal. -
platform- Returns the current platform (e.g., Windows, Linux). -
version- Returns the current game version.
-
import(daClass:String, ?asDa:String)- See Imports for more. -
trace(value:Dynamic)- The equivalent oftracein normal Haxe. -
stopScript()- Stops the current script. -
addScript(path:String)- Adds a new script during gameplay (PlayState). -
importScript(source:String)- Gives access to another script's local functions and variables.
To import a class, use:
import('package.Class');To import an enumerator, use:
import('package.Enum');To import with an alias, use:
import('package.Class', 'Name');
var aliasClass:Name;You can basically use this to import any class/enum you'd like.
Otherwise, here is a list of the current classes you can use that are already imported:
ArrayBoolDateDateToolsDynamicERegFloatIntLambdaMathReflectStdStringStringBufStringToolsSysTypeXml
AchievementsApplicationAssetsBarConductorDiscordClientExtendableStateExtendableSubStateFileFileSystemFlxAxesFlxBackdropFlxBasicFlxCameraFlxCameraFollowStyleFlxColorFlxEaseFlxGFlxGroupFlxMathFlxObjectFlxRuntimeShaderFlxSoundFlxSpriteFlxSpriteGroupFlxTextFlxTextAlignFlxTextBorderStyleFlxTimerFlxTweenFlxTypedGroupGameSpriteHighScoreInputJsonLibLocalizationLuaScriptMainModHandlerNotePathPathsPlayStateRatingSaveDataScriptedStateScriptedSubStateSongTJSONUtilities
Some useful templates to get started. For the default template, use this.
import('flixel.FlxSprite');
import('states.PlayState');
function create() {
var spr:FlxSprite = new FlxSprite(0, 0).makeGraphic(50, 50, FlxColor.BLACK);
add(spr);
}import('flixel.FlxSprite');
import('states.PlayState');
import('backend.Paths');
function create() {
var spr:FlxSprite = new FlxSprite(0, 0).loadGraphic(Paths.image('gameplay/banan'), true, 102, 103);
spr.animation.add('rotate', [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14], 14);
spr.animation.play('rotate');
spr.screenCenter();
add(spr);
}import('flixel.text.FlxText');
import('states.PlayState');
function create() {
var text:FlxText = new FlxText(0, 0, 0, "Hello World", 64);
text.screenCenter();
add(text);
}import('sys.FileSystem');
import('sys.io.File');
import('haxe.Json');
var json:Dynamic;
function create() {
if (FileSystem.exists('assets/data.json'))
json = Json.parse(File.getContent('assets/data.json'));
trace(json);
}import('states.ScriptedState');
import('substates.ScriptedSubState');
import('backend.ExtendableState');
import('flixel.text.FlxText');
import('flixel.FlxSprite');
import('backend.Input');
import('flixel.FlxG');
function create() {
var bg:FlxSprite = new FlxSprite(0, 0).makeGraphic(1280, 720, FlxColor.WHITE);
add(bg);
var text:FlxText = new FlxText(0, 0, FlxG.width, "I am a custom state!", 48);
text.color = FlxColor.BLACK;
add(text);
}
function update(elapsed:Float) {
if (Input.justPressed('accept'))
ExtendableState.switchState(new ScriptedState('name', [/* arguments, if any */])); // load custom state
if (Input.justPressed('exit'))
state.openSubState(new ScriptedSubState('name', [/* arguments, if any */])); // load custom substate
}Additionally, if you want to load your custom state from the main menu, navigate to assets/data/menuList.txt and add in your state's name, as well as a main menu asset for it in assets/images/menu/mainmenu/[name].png.
And just in case your script doesn't load or something goes wrong, press F4 to be sent to the main menu.
Script 1:
// assets/helpers/spriteHandler.hxs
import('flixel.FlxSprite');
import('backend.Paths');
import('flixel.FlxG');
function createSprite(x:Float, y:Float, graphic:String) {
var spr:FlxSprite = new FlxSprite(x, y);
spr.loadGraphic(Paths.image(graphic));
state.add(spr);
trace("sprite " + sprite + " created");
}Script 2:
var otherScript = importScript('helpers.spriteHandler');
function create() {
otherScript.createSprite(0, 0, 'sprite');
}import('flixel.addons.display.FlxRuntimeShader');
import('openfl.filters.ShaderFilter');
import('openfl.utils.Assets');
import('flixel.FlxG');
import('backend.Paths');
var shader:FlxRuntimeShader;
var shader2:FlxRunTimeShader;
function create() {
shader = new FlxRuntimeShader(Assets.getText(Paths.frag('rain')), null);
shader.setFloat('uTime', 0);
shader.setFloatArray('uScreenResolution', [FlxG.width, FlxG.height]);
shader.setFloat('uScale', FlxG.height / 200);
shader.setFloat("uIntensity", 0.5);
shader2 = new ShaderFilter(shader);
FlxG.camera.filters = [shader2];
}
function update(elapsed:Float) {
shader.setFloat("uTime", shader.getFloat("uTime") + elapsed);
shader.setFloatArray("uCameraBounds", [
FlxG.camera.scroll.x + FlxG.camera.viewMarginX,
FlxG.camera.scroll.y + FlxG.camera.viewMarginY,
FlxG.camera.scroll.x + FlxG.camera.width,
FlxG.camera.scroll.y + FlxG.camera.height
]);
}Similar to HScript, your script should either be located in assets/scripts/[name].lua, or in assets/songs/[song-name]/[name].lua.
-
Function_Stop- Cancels functions (e.g., startCountdown, endSong). -
Function_Continue- Continues the game like normal. -
platform- Returns the current platform (e.g., Windows, Linux). -
version- Returns the current game version. -
lua.version- Returns the current lua version. -
lua.versionJIT- Returns the current luajit version.
-
trace(value:Dynamic)- The equivalent oftracein normal Haxe.- Additionally, you can also use
printinstead.
- Additionally, you can also use
-
stopScript()- Stops the current script. -
stdInt(x:Float)- Converts a floating point number into an integer.
Basic template:
function create()
-- Called when the script is created.
end
function startCountdown()
-- Called when the countdown starts in PlayState.
end
function update(elapsed)
-- Called every frame.
end
function beatHit(curBeat)
-- Called every beat hit in PlayState.
end
function stepHit(curStep)
-- Called every step hit in PlayState.
end
function pause()
-- Called when the game is paused.
end
function resume()
-- Called when the game is resumed.
end
function noteHit(note, rating)
-- Called when a note is hit.
end
function noteMiss(direction)
-- Called when a note is missed.
end
function endSong()
-- Called when the song ends.
end
function destroy()
-- Called when the script is destroyed.
endIf you need any general help or something goes wrong with your script, report an issue here.