Lua api documentation (WIP)

Lua API Documentation

Basic Types

Name	Description
Int	Any whole number.
Float	Any number.
Bool	true or false.
String	Text
Void	No return value.
Dynamic	Any type.

Examples

function start(song)
    set('scoreTxt.alpha', 0.5)
end

Sets score text to half transparent

function start(song)
    tween('boyfriend', { x = get('boyfriend.x') + 300 }, 1, 'cubeInOut', 3, function()
        tween('boyfriend', { x = get('boyfriend.x') - 300 }, 1, 'cubeInOut')
    end)
end

Smoothly moves boyfriend 300 pixels to the right after waiting 3 seconds, and then back to left 300 pixels.

function start(song)
    newText('yourMom', 'i am a little goofy', 0, 0, 16)
    set('yourMom.borderColor', color(0, 0, 0))
    set('yourMom.borderStyle', "OUTLINE")
    setObjectCamera('yourMom', 'hud')
    add('yourMom')

    tween("yourMom", { x = 640, y = 360 }, 2, "linear", 0, function()
        tween("yourMom", { x = 0, y = FlxG.height - 18 }, 2, "linear")
    end)

    loadScript("test-script")

    print(exists('yourMom'))
end

Creates and moves a text label across the screen with tweens (also loads another script named 'test-script' and prints whether or not the yourMom sprite exists)

-- when the stage lua is created
function create(stage)
	print(stage .. ' is our stage!')

	-- make our sprites B)
	makeStageSprite('stageback', 'stageback', -600, -200, 1)
	setActorScroll(0.9, 0.9, 'stageback')

	makeStageSprite('stagefront', 'stagefront', -650, 600, 1.1)
	setActorScroll(0.9, 0.9, 'stagefront')

	makeStageSprite('stagecurtains', 'stagecurtains', -500, -300, 0.9)
	setActorScroll(1.3, 1.3, 'stagecurtains')

	-- set extra properties like camera zoom (can be done in json still but frick you)
	set('stage.camZoom', 0.9)
end

-- same as start function in a regular modchart
function start(stage)
	
end

-- called each frame with elapsed being the seconds between the last frame
function update(elapsed)

end

-- every time a beat hit is called on the song this happens
function beatHit(curBeat)

end

-- any other functions from regular modcharts can also be put here :DDD

Template Stage Lua

Global Variables

Song Information

Variable	Description	Type
songLower	The current song as lower case.	String
difficulty	The current difficulty.	String
difficulty (Legacy pre 0.4.1)	The current difficulty from 0 to 2	Int
bpm / songBpm	Current BPM (Beats per minute)	Float
keyCount	Opponent's key count currently (equal to playerKeyCount unless specifically specified).	Int
playerKeyCount	Player's key count currently.	Int
scrollspeed	The current scroll speed.	Float
fpsCap	FPS Cap setting value.	Int
opponentPlay	Playing as the opponent?	Bool
bot	Botplay setting value.	Bool
noDeath	No Death setting value.	Bool
downscrollBool	Downscroll setting value.	Bool
downscroll (Deprecated ⚠️)	Downscroll setting value (0 or 1).	Int
middlescroll	Middlescroll setting value.	Bool
flashingLights / flashing	Flashing Lights setting value.	Bool
distractions (Not Implemented ❌)	Distractions setting value (always true).	Bool
animatedBackgrounds	Animated Backgrounds setting value.	Bool
cameraZooms	Camera Zooms setting value.	Bool
shaders	Shaders are enabled for user?	Bool
charsAndBGs	Characters and BGs are rendered for user?	Bool
curBeat	The current 'beat' (4th note) of the song.	Int
curStep	The current 'step' (16th note) of the song.	Int
crochet	Time between each 'beat' (4 note) of the song in milliseconds.	Float
stepCrochet	Time between each 'step' (16th note) of the song in milliseconds.	Float
safeZoneOffset	Safe frames in milliseconds.	Float
hudZoom	Zoom of the HUD (defaults to 1).	Float
cameraZoom	Zoom of the camera (defaults to 1.05).	Float
cameraAngle	Angle of the camera (defaults to 0).	Float
camHudAngle	Angle of the HUD (defaults to 0).	Float
followXOffset	Offset of camera follow on the X axis.	Float
followYOffset	Offset of camera follow on the Y axis.	Float
showOnlyStrums	If true, all hud elements besides strums and notes will be shown (defaults to false).	Bool
strumLine1Visible	If false, the left strum line will be hidden (defaults to true).	Bool
strumLine2Visible	If false, the right strum line will be hidden (defaults to true).	Bool
screenWidth	The width of the main desktop monitor.	Int
screenHeight	The height of the main desktop monitor.	Int
windowWidth	The width of the game window.	Int
windowHeight	The height of the game window.	Int
hudWidth	The width of the HUD.	Int
hudHeight	The height of the HUD.	Int
mustHit	Camera is pointing at dad when false, boyfriend when true.	Bool
strumLineX	The X position of the strum line.	Int
strumLineY	The Y position of the strum line.	Int
characterPlayingAs	The character playing as.	Int
inReplay	In a replay?	Bool
player1	Character name of player one.	String
player2	Character name of player two.	String
curStage	Name of the current stage.	String
mobile	Running on a mobile device?	Bool
curMod	The current selected mod.	String
developer	Is developer mode enabled?	Bool
version	Engine version	String

Misc

• FlxColor

  • Has each static property from the haxeflixel class itself as a property you can access (no functions).

• FlxG

  • Has 3 properties, width, height, and elapsed, these are all equal to the respective values in flixel.FlxG

• FlxMath

  • Has 6 properties, EPSILON, MAX_VALUE_FLOAT, MAX_VALUE_INT, MIN_VALUE_FLOAT, MIN_VALUE_INT and SQUARE_ROOT_OF_TWO, these are all equal to the respective values in flixel.math.FlxMath

• Math

  • Has 4 properties, NEGATIVE_INFINITY, NaN, PI, and POSITIVE_INFINITY, these are all equal to the respective values in Math

• Conductor

  • Has all static properties from game.Conductor.

• SONG

  • Equivalent to states.PlayState.SONG.

• leatherEngine

  • Has 4 properties, "version", "cwd", "systemName" and "path".

• lua

  • Has 2 properties, "version", and "versionJIT", these are string versions of the current Lua version and LuaJIT version respectively.

Global Functions

Function	Parameters	Description	Execute on	Stage Arguments
onCreate() / createLua() / new()		Called when lua is setup	BOTH
create()	song:String	Called before other code in PlayState	MODCHART
create()	stage:String	Called before other code in PlayState	STAGE
createStage()		Called when stage is created	BOTH
createPost()		Called when after other code in PlayState	BOTH
update()	elapsed:Float	Called every frame	BOTH
updatePost()	elapsed:Float	Called every frame after other code	BOTH
beatHit()	beat:Int	Called every beat	BOTH
stepHit()	step:Int	Called every step	BOTH
generateStaticArrows()		Called when static arrows are generated	BOTH
start()	song:String	Called before countdown starts	BOTH	stage:String
startCountdown()	count:Int	Called when countdown ticks	BOTH
startSong() / songStart()		Called when song starts	BOTH
endSong()		Called when song ends	BOTH
turnChange()	character:String	Called when turn changed	BOTH
playerOneTurn()		Called when turn changed	BOTH
playerTwoTurn()		Called when turn changed	BOTH
onDeath()	songPos:Float	Called when player dies	BOTH
playerOneSing()	data:Int, songPosition:Float, type:String, strumTime:Float, character:Int	Called when player hits a note	BOTH
playerOneSingHeld()	data:Int, songPosition:Float, type:String, strumTime:Float, character:Int	Called when player hits a sustain note	BOTH
playerOneSingExtra()	data:Int, songPosition:Float, type:String, strumTime:Float, character:Int	Called when opponent extra character hits a note	BOTH
playerOneMiss()	data:Int, songPosition:Float, type:String, strumTime:Float, character:Int	Called when player misses a note	BOTH
playerTwoSing()	data:Int, songPosition:Float, type:String, strumTime:Float, character:Int	Called when opponent hits a note	BOTH
playerTwoSingHeld()	data:Int, songPosition:Float, type:String, strumTime:Float, character:Int	Called when opponent hits a sustain note	BOTH
playerTwoSingExtra()	data:Int, songPosition:Float, type:String, strumTime:Float, character:Int	Called when opponent extra character hits a note	BOTH
popUpScore()	rating:String, combo:Int	Called when ratings and combo pop up	BOTH
keyPressed()	key:Int	Called when a key is pressed	BOTH
keyReleased()	key:Int	Called when a key is released	BOTH
onEvent()	name:String, position:Float, argument1:String, argument2:String	Called when an event is called	BOTH
onEventLoaded()	name:String, position:Float, argument1:String, argument2:String	Called when an event is loaded	BOTH

Callback Functions

Function	Description	Parameters	Return
print	Prints to the console.	data:Dynamic	Void
triggerEvent	Triggers and event.	event_name:String, argument_1:Dynamic, argument_2:Dynamic	Void
addCharacterToMap	Adds a character to m map. Useful for inserting other group characters midsong	m:String, character:String	Void
pressed	Checks for a key held	key:String = "SPACE"	Void
justReleased	Checks for a key released	key:String = "SPACE"	Void
justPressed	Checks for a key pressed	key:String = "SPACE"	Void
setGraphicSize	Sets the width and height for an object	id:String, width:Int = 0, height:Int = 0	Void
updateHitbox	Updates the hitbox for an object, be sure to call after scaling an object	id:String	Void
setBlendMode	Sets the blend mode for an object	id:String, blend:String = ''	Void
getSingDirectionID	Sets the sing direction from an integer	id:Int	Void
makeGraphic	Makes a graphic from a color hex	id:String, width:Int, height:Int, color:String	Void
makeGraphicRGB	Makes a graphic from a color rgb	id:String, width:Int, height:Int, color:String	Void
color	Returns a hex color from rgba	r:Int, g:Int, b:Int, a:Int = 255	Int
colorString	Returns a hex color from string	color:String	Int
colorRGB	Returns a hex color from rgb	r:Int, g:Int, b:Int	Int
colorRGBA (Deprecated ⚠️ use color() instead!)	Returns a hex color from rgba	r:Int, g:Int, b:Int, a:Int = 255	Int
rgbToHsv	Returns hsv from rgb	r:Int, g:Int, b:Int	Array
dominantColor	Returns the dominant color of a sprite	id:String	Int
dominantColorFrame	Returns the dominant color of a sprite's current frame	id:String	Int
center	Centers an actor	id:String, ?direction:String = "xy"	Void
screenCenter (Deprecated ⚠️ use center() instead!)	Centers an actor	id:String, ?direction:String = "xy"	Void
actorScreenCenter (Deprecated ⚠️ use center() instead!)	Centers an actor	id:String	Void
add	Adds an object to PlayState	id:String	Void
remove	Removes an object from PlayState	id:String, splice:Bool = true	Void
kill	Kills an object in PlayState	id:String	Void
destroy	Destroys an object in PlayState	id:String	Void
destroySprite (Deprecated ⚠️ use destroy() instead!)	Destroys an object in PlayState	id:String	Void
insert	Inserts an object in PlayState in a specific order	id:String, position:Int	Void
addStage	Adds an object to the stage	id:String	Void
removeStage	Removes an object from the stage	id:String, splice:Bool = true	Void
insertStage	Inserts an object in the current stage in a specific order	id:String, position:Int	Void
makeSprite	Makes a new sprite	id:String, filename:String, x:Float, y:Float, size:Float = 1, ?sizeY:Float = null	Void
makeAnimatedSprite	Makes a new animated sprite	id:String, filename:String, x:Float, y:Float, size:Float = 1, ?sizeY:Float = null	Void
makeDancingSprite	Makes a new dancing sprite	id:String, filename:String, x:Float, y:Float, size:Float = 1, ?oneDanceAnimation:Bool, ?antialiasing:Bool, ?sizeY:Float = null	Void
makeSpriteCopy	Makes a copy of an already existing sprite	id:String, targetID:String	Void
newSprite	Makes a new sprite without adding it	id:String, filename:String, x:Float, y:Float, size:Float = 1, ?sizeY:Float = null	Void
newAnimatedSprite	Makes a new animated sprite without adding it	id:String, filename:String, x:Float, y:Float, size:Float = 1, ?sizeY:Float = null	Void
newDancingSprite	Makes a new dancing sprite without adding it	id:String, filename:String, x:Float, y:Float, size:Float = 1, ?oneDanceAnimation:Bool, ?antialiasing:Bool, ?sizeY:Float = null	Void
newSpriteCopy	Makes a copy of an already existing sprite without adding it	id:String, targetID:String	Void
makeStageSprite	Makes a sprite from the stage's folder	id:String, width:Int, height:Int, color:String	Void
makeStageAnimatedSprite	Makes an animated sprite from the stage's folder	id:String, width:Int, height:Int, color:String	Void
makeStageDancingSprite	Makes a dancing sprite from the stage's folder	id:String, filename:String, x:Float, y:Float, size:Float = 1, ?oneDanceAnimation:Bool, ?antialiasing:Bool, ?sizeY:Float = null	Void
exists	Checks for a sprite existing	id:String	Bool
makeText	Makes a new text	id:String, text:String, x:Float, y:Float, size:Int = 32, font:String = "vcr.ttf", fieldWidth:Float = 0	Void
newText	Makes a new text without adding it	id:String, text:String, x:Float, y:Float, size:Int = 32, font:String = "vcr.ttf", fieldWidth:Float = 0	Void
setActorText	Sets the text of a text object	id:String, text:String	Void
setActorFont	Sets the font of a text object	id:String, font:String	Void
setActorOutlineColor	Sets the color of a text object	id:String, color:String	Void
setActorAlignment	Sets the alignment of a text object	id:String, color:String	Void
addActorTrail	Adds a trail to an actor	id:String, length:Int = 10, delay:Int = 3, alpha:Float = 0.4, diff:Float = 0.05	Void
removeActorTrail	Removes a trail from an actor	id:String	Void
getIsColliding	Checks if 2 sprites are colliding	sprite1Name:String, sprite2Name:String	Bool
setActorLayer	Sets the layer of an actor	id:String, layer:Int	Void
getActorLayer	Gets the layer of an actor	id:String	Int
getHealth	Gets the heath of the player (0 - 2)		Float
getMinHealth	Gets the minimum health		Float
getMaxHealth	Gets the maximum health		Float
changeHealthRange	Changes the maximum and minimum health	minHealth:Float, maxHealth:Float	Void
setCamera	Adds a object id to a camera (game or hud)	id:String, camera:String = ""	Void
setObjectCamera (Deprecated ⚠️ use setCamera() instead!)	Adds a object id to a camera (game or hud)	id:String, camera:String = ""	Void
setObjectCameras	Sets an object to a list of cameras split by ','	id:String, camStr:String	Void
setNoteCameras	Sets all notes and strums to a list of cameras split by ','	camStr:String	Void
flashCamera	Flashes a camera.	camera:String = "", color:String = "#FFFFFF", time:Float = 1, force:Bool = false	Void
makeCamera	Makes a new camera	camStr:String	Void
getCameraScrollX	Gets the X scroll factor of a camera	camStr:String	Float
getCameraScrollY	Gets the Y scroll factor of a camera	camStr:String	Float
setCamPosition	Sets camera follow position for the game camera	x:Int, y:Int	Void
getCameraX	Gets the camera follow position for the game camera on the X axis		Float
getCameraY	Gets the camera follow position for the game camera on the Y axis		Float
getCamZoom	Gets the game camera zoom		Float
setCamZoom	Sets the game camera zoom	zoomAmount:Float	Void
setHudAngle	Sets the angle of the HUD	angle:Float	Void
setHudPosition	Sets the position of the HUD	x:Int, y:Int	Void
getHudX	Gets the X position of the HUD		Float
getHudY	Gets the Y position of the HUD		Float
getHudZoom	Gets the hud camera zoom		Float
setHudZoom	Sets the hud camera zoom	zoomAmount:Float	Void
setStrumlineX	Sets the strum lime X position	x:Float, ?dontMove:Bool = false	Void
setStrumlineY	Sets the strum lime Y position	y:Float, ?dontMove:Bool = false	Void
makeNoteCopy	Makes a copy of a note sprite	id:String, noteIdx:Int	Void
getUnspawnNotes	Returns the length of the notes waiting to be spawned into the game		Int
getUnspawnedNoteNoteType (Deprecated ⚠️ use getUnspawnedNoteArrowType() instead!)	Returns the note type of an unspawned note	id:Int	String
getUnspawnedNoteArrowType	Returns the note type of an unspawned note	id:Int	String
getUnspawnedNoteStrumtime	Returns the strum time of an unspawned note	id:Int	Float
getUnspawnedNoteMustPress	Returns if an unspawned note is on the player's or opponent's side	id:Int	Bool
getUnspawnedNoteSustainNote	Returns if an unspawned note is a sustain note	id:Int	Bool
getUnspawnedNoteNoteData (Deprecated ⚠️ use getUnspawnedNoteData() instead!)	Returns an unspawned note's lane	id:Int	Int
getUnspawnedNoteData	Returns an unspawned note's lane	id:Int	Int
getUnspawnedNoteScaleX	Returns an unspawned note's scale on the X axis	id:Int	Float
getUnspawnedNoteScaleY	Returns an unspawned note's scale on the Y axis	id:Int	Float
getUnspawnedNoteSingAnimPrefix	Returns an unspawned note's sing animation prefix (defaults to 'sing')	id:Int	String
setUnspawnedNoteXOffset	Returns an unspawned note's offset on the X axis	id:Int	Float
setUnspawnedNoteYOffset	Returns an unspawned note's offset on the Y axis	id:Int	Float
setUnspawnedNoteAngle	Returns an unspawned note's angle	id:Int	Float
setUnspawnedNoteSingAnimPrefix	Sets an unspawned note's sing animation prefix	id:Int, prefix:String	String
getRenderedNotes	Returns the length of the notes rendered in game		Int
isSustain	Is a note a sustain note?	id:Int	Bool
isParentSustain	Is a note a parent sustain note?	id:Int	Bool
anyNotes	Is the notes length not 0?		Bool
getRenderedNoteX	Returns the X position of a rendered note	id:Int	Int
getRenderedNoteY	Returns the Y position of a rendered note	id:Int	Int
getRenderedNoteType (Deprecated ⚠️ use getRenderedNoteData() instead!)	Returns an rendered note's lane	id:Int	Int
getRenderedNoteData	Returns an rendered note's lane	id:Int	Int
getRenderedNoteArrowType	Returns an rendered note's arrow type	id:Int	String
getRenderedNoteParentX	Returns an rendered note's parent note X	id:Int	Float
getRenderedNoteParentY	Returns an rendered note's parent note Y	id:Int	Float
getRenderedNoteHit	Returns if a rendered note is on the player or opponent's side	id:Int	Bool
getRenderedNoteCalcX	i have no idea	id:Int	Float
getRenderedNoteStrumtime	Returns the strum time of a rendered note	id:Int	Float
getRenderedNoteScaleX	Returns the X scale of a rendered note	id:Int	Float
getRenderedNoteScaleY	Returns the Y scale of a rendered note	id:Int	Float
isRenderedNoteSustainEnd	Checks if the rendered note is a sustain end	id:Int	Bool
getRenderedNoteSustainScaleY	Gets the scale of a sustain on the Y axis	id:Int	Float
getRenderedNoteOffsetX	Gets the offset of a rendered note on the X axis	id:Int	Float
getRenderedNoteOffsetY	Gets the offset of a rendered note on the Y axis	id:Int	Float
getRenderedNoteWidth	Gets the width of a rendered note	id:Int	Float
getRenderedNoteHeight	Gets the height of a rendered note	id:Int	Float
getRenderedNotePrevNoteStrumtime	Gets the strum time of a rendered note's parent	id:Int	Float
setRenderedNotePos	Sets the X and Y positions of a rendered note	x:Float, y:Float, id:Int	Void
setRenderedNoteAlpha	Sets the alpha of a rendered note	alpha:Float, id:Int	Void
setRenderedNoteScale	Sets the scale of a rendered note	scale:Float, id:Int	Void
setRenderedNoteScaleX	Sets the scale of a rendered note on the X axis	scaleX:Float, id:Int	Void
setRenderedNoteScaleY	Sets the scale of a rendered note on the Y axis	scaleY:Float, id:Int	Void
setRenderedNoteScaleXY	Sets the scale of a rendered note on the X and Y axis	scaleX:Float, scaleY:Float, id:Int	Void
setRenderedNoteAngle	Sets the angle of a rendered note	angle:Float, id:Int	Void
setRenderedNoteSkewX	Sets the skew of a rendered note on the X axis	skew:Float, id:Int	Void
setRenderedNoteSkewY	Sets the skew of a rendered note on the Y axis	skew:Float, id:Int	Void
setActorX (Deprecated ⚠️ use set() instead!)	Sets the X position of an actor	x:Float, id:String	Void
setActorAccelerationX (Deprecated ⚠️ use set() instead!)	Sets the X acceleration of an actor	x:Float, id:String	Void
setActorDragX (Deprecated ⚠️ use set() instead!)	Sets the X drag of an actor	x:Float, id:String	Void
setActorVelocityX (Deprecated ⚠️ use set() instead!)	Sets the X velocity of an actor	x:Float, id:String	Void
setActorOriginX (Deprecated ⚠️ use set() instead!)	Sets the X origin of an actor	x:Float, id:String	Void
setActorFlipX (Deprecated ⚠️ use set() instead!)	Sets if an actor is flipped on the X axis	flip:Bool, id:String	Void
getActorX (Deprecated ⚠️ use set() instead!)	Gets the X position of an actor	id:String	Float
getOriginalCharX (Deprecated ⚠️ use set() instead!)	Gets the original X position of an actor before any changes to the position have been made.	id:String	Float
setActorY (Deprecated ⚠️ use set() instead!)	Sets the Y position of an actor	y:Float, id:String	Void
setActorAccelerationY (Deprecated ⚠️ use set() instead!)	Sets the Y acceleration of an actor	y:Float, id:String	Void
setActorDragY (Deprecated ⚠️ use set() instead!)	Sets the Y drag of an actor	y:Float, id:String	Void
setActorVelocityY (Deprecated ⚠️ use set() instead!)	Sets the Y velocity of an actor	y:Float, id:String	Void
setActorOriginY (Deprecated ⚠️ use set() instead!)	Sets the Y origin of an actor	y:Float, id:String	Void
setActorFlipY (Deprecated ⚠️ use set() instead!)	Sets if an actor is flipped on the Y axis	flip:Bool, id:String	Void
getActorY (Deprecated ⚠️ use set() instead!)	Gets the Y position of an actor	id:String	Float
getOriginalCharY (Deprecated ⚠️ use set() instead!)	Gets the original Y position of an actor before any changes to the position have been made.	id:String	Float
setActorPos (Deprecated ⚠️ use set() instead!)	Sets the position of an actor	y:Float, y:Float, id:String	Void
setActorScroll (Deprecated ⚠️ use set() instead!)	Sets the scroll factor of an actor	y:Float, y:Float, id:String	Void
setActorAntialiasing (Deprecated ⚠️ use set() instead!)	Enables or disable antialiasing of an actor	antialiasing:Bool, id:String	Void
addActorAnimation	Adds an animation to an actor	id:String, prefix:String, anim:String, fps:Int = 30, looped:Bool = true	Void
addActorAnimationIndices	Adds an animation to an actor with a list of indices	id:String, prefix:String, indiceString:String, anim:String, fps:Int = 30, looped:Bool = true	Void