Lua api documentation (WIP) - Vortex2Oblivion/LeatherEngine GitHub Wiki

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

  • 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

  • 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
⚠️ **GitHub.com Fallback** ⚠️