Python API reference

Generated page

This list is extracted from the registerFunction(...) calls in source/psychlua/ by website/scripts/generate-script-api.mjs. If a function is missing here, it is missing from the engine too.

Phoenix Engine embeds Hython, a pure-Haxe Python interpreter, and exposes a subset of the Lua API to .py scripts under the same names, so a script can be ported between the two languages mostly by changing its syntax.

Python scripting requires a build with PYTHON_ALLOWED (-DMODDING_LEVEL=2, the desktop default).

170 functions in 14 groups.

Index

Cameras — 9 functions
Characters — 9 functions
Hardware — 10 functions
Input — 3 functions
Misc — 17 functions
Properties — 9 functions
PyScriptLib — 15 functions
Score & health — 20 functions
Sound — 9 functions
Sprites — 28 functions
Text — 15 functions
Timers — 2 functions
Tweens — 15 functions
Window — 9 functions

Cameras

Camera control.

Function	Arguments	Notes
`cameraFade(camera, color, duration, forced, fadeOut=false)`	`camera`: string `color`: string `duration`: float `forced`: bool `fadeOut`: bool = `false`	source
`cameraFlash(camera, color, duration, forced)`	`camera`: string `color`: string `duration`: float `forced`: bool	source
`cameraSetTarget(target)`	`target`: string	source
`cameraShake(camera, intensity, duration)`	`camera`: string `intensity`: float `duration`: float	source
`getMouseX(camera)`	`camera`: string	source
`getMouseY(camera)`	`camera`: string	source
`mouseClicked(button)`	`button`: string	source
`mousePressed(button)`	`button`: string	source
`mouseReleased(button)`	`button`: string	source

Characters

Boyfriend / dad / girlfriend positioning and animation.

Function	Arguments	Notes
`addCharacterToList(name, type)`	`name`: string `type`: string	source
`dance(character='bf')`	`character`: string = `'bf'`	source
`getCharacterX(type)`	`type`: string	source
`getCharacterY(type)`	`type`: string	source
`setCharacterX(type, value)`	`type`: string `value`: float	source
`setCharacterY(type, value)`	`type`: string `value`: float	source
`setRatingFC(value)`	`value`: string	source
`setRatingName(value)`	`value`: string	source
`setRatingPercent(value)`	`value`: float	source

Hardware

GPU, GPU driver, CPU and operating system information.

Function	Arguments	Notes
`getAudioApi()`	none	Returns the audio backend, for example "OpenAL Soft \| 1.23.1". · source
`getCPUName()`	none	Returns the CPU model, for example "Intel(R) Core(TM) i7-9700K CPU @ 3.60GHz". · source
`getCPUVendor()`	none	Returns the CPU vendor, for example "Intel". · source
`getGPUDriverVersion()`	none	Returns the GPU driver version, for example "535.104.05". · source
`getGPUName()`	none	Returns the GPU model, for example "NVIDIA GeForce RTX 3060". · source
`getGPUVendor()`	none	Returns the GPU vendor, for example "NVIDIA". · source
`getGraphicsApi()`	none	Returns the graphics API version, for example "OpenGL 4.6". · source
`getOSName()`	none	Returns the operating system, for example "Windows". · source
`getOSVersion()`	none	Returns the operating system version, for example "10.0.19045". · source
`getSystemInfo()`	none	Returns a human readable report of the hardware the game runs on. · source

Input

Keyboard and gamepad polling.

Function	Arguments	Notes
`keyJustPressed(name)`	`name`: string	source
`keyPressed(name)`	`name`: string	source
`keyReleased(name)`	`name`: string	source

Misc

Strings, randomness, debug output and helpers.

Function	Arguments	Notes
`changePresence(details, state, smallImageKey, hasStartTimestamp, endTimestamp)`	`details`: string `state`: string `smallImageKey`: string (optional) `hasStartTimestamp`: bool (optional) `endTimestamp`: float (optional)	source
`close()`	none	source
`debugPrint(text1='', text2='', text3='', text4='', text5='')`	`text1`: any = `''` `text2`: any = `''` `text3`: any = `''` `text4`: any = `''` `text5`: any = `''`	source
`endSong()`	none	source
`flushGlobalSave()`	none	Flush the engine-wide save used by scripts that write FlxG.save.data. · source
`flushSaveData(name)`	`name`: string	source
`getRandomBool(chance=50)`	`chance`: float = `50`	source
`getRandomFloat(min, max=1, exclude='')`	`min`: float `max`: float = `1` `exclude`: string = `''`	source
`getRandomInt(min, max=FlxMath.MAX_VALUE_INT, exclude='')`	`min`: int `max`: int = `FlxMath.MAX_VALUE_INT` `exclude`: string = `''`	source
`getSongPosition()`	none	source
`getTextFromFile(path, ignoreModFolders=false)`	`path`: string `ignoreModFolders`: bool = `false`	source
`precacheImage(name)`	`name`: string	source
`precacheMusic(name)`	`name`: string	source
`precacheSound(name)`	`name`: string	source
`restartSong(skipTransition=false)`	`skipTransition`: bool = `false`	source
`startCountdown()`	none	source
`triggerEvent(name, arg1, arg2, strumTime)`	`name`: string `arg1`: any `arg2`: any `strumTime`: float	source

Properties

Reflective get/set of object fields.

Function	Arguments	Notes
`getObjectOrder(obj)`	`obj`: string	source
`getProperty(variable)`	`variable`: string	source
`getPropertyFromClass(classVar, variable)`	`classVar`: string `variable`: string	source
`getPropertyFromGroup(obj, index, variable)`	`obj`: string `index`: int `variable`: any	source
`removeFromGroup(obj, index, dontDestroy=false)`	`obj`: string `index`: int `dontDestroy`: bool = `false`	source
`setObjectOrder(obj, position)`	`obj`: string `position`: int	source
`setProperty(variable, value)`	`variable`: string `value`: any	source
`setPropertyFromClass(classVar, variable, value)`	`classVar`: string `variable`: string `value`: any	source
`setPropertyFromGroup(obj, index, variable, value)`	`obj`: string `index`: int `variable`: any `value`: any	source

PyScriptLib

Function	Arguments	Notes
`addHScript(file, ignoreAlreadyRunning=false)`	`file`: string `ignoreAlreadyRunning`: bool = `false`	addHScript — load a standalone HScript (.hx/.hscript) script at runtime · source
`addLuaScript(file, ignoreAlreadyRunning=false)`	`file`: string `ignoreAlreadyRunning`: bool = `false`	addLuaScript — load a Lua script at runtime · source
`addPythonScript(file, ignoreAlreadyRunning=false)`	`file`: string `ignoreAlreadyRunning`: bool = `false`	addPythonScript — load a Python script at runtime · source
`addScript(file, ignoreAlreadyRunning=false)`	`file`: string `ignoreAlreadyRunning`: bool = `false`	Generic addScript — detects extension · source
`callOnLuas(funcName, args, ignoreStops=false, ignoreSelf=true, exclusions)`	`funcName`: string (optional) `args`: list (optional) `ignoreStops`: bool = `false` `ignoreSelf`: bool = `true` `exclusions`: list (optional)	callOnLuas — compatibility alias: dispatches to Lua AND Python scripts · source
`callOnScripts(funcName, args, ignoreStops=false, ignoreSelf=true, exclusions)`	`funcName`: string (optional) `args`: list (optional) `ignoreStops`: bool = `false` `ignoreSelf`: bool = `true` `exclusions`: list (optional)	callOnScripts — preferred name (alias of callOnLuas) · source
`callScript(file, funcName, args)`	`file`: string (optional) `funcName`: string (optional) `args`: list (optional)	callScript(path, func, args) — call a function on a specific script (Lua, Python or HScript) · source
`getGlobalFromScript(file, global)`	`file`: string (optional) `global`: string (optional)	getGlobalFromScript(path, global) — read a variable from another script · source
`getRunningScripts()`	none	getRunningScripts():Array<String> — all currently loaded scripts (Lua + Python + HScript) · source
`isRunning(file)`	`file`: string	isRunning(path):Bool · source
`removeHScript(file)`	`file`: string	removeHScript — unload a standalone HScript (.hx/.hscript) script · source
`removeLuaScript(file)`	`file`: string	removeLuaScript · source
`removePythonScript(file)`	`file`: string	removePythonScript · source
`removeScript(file)`	`file`: string	removeScript — generic · source
`setGlobalFromScript(file, global, val)`	`file`: string `global`: string `val`: any	setGlobalFromScript(path, global, value) · source

Score & health

Score, misses, hits, health and rating values.

Function	Arguments	Notes
`addCombo(value=0)`	`value`: int = `0`	source
`addHealth(value=0)`	`value`: float = `0`	source
`addHits(value=0)`	`value`: int = `0`	source
`addMisses(value=0)`	`value`: int = `0`	source
`addNPS(value=0)`	`value`: int = `0`	source
`addPlaybackSpeed(value=0)`	`value`: float = `0`	source
`addScore(value=0)`	`value`: float = `0`	source
`changeMaxHealth(value=0)`	`value`: float = `0`	source
`getColorFromHex(color)`	`color`: string	source
`getHealth()`	none	source
`getHits()`	none	source
`getMaxHealth()`	none	source
`getMisses()`	none	source
`getPlaybackSpeed()`	none	source
`getScore()`	none	source
`setHealth(value=0)`	`value`: float = `0`	source
`setHits(value=0)`	`value`: int = `0`	source
`setMisses(value=0)`	`value`: int = `0`	source
`setPlaybackSpeed(value=0)`	`value`: float = `0`	source
`setScore(value=0)`	`value`: float = `0`	source

Sound

Music and sound effects.

Function	Arguments	Notes
`killSound(tag)`	`tag`: string	source
`pauseSound(tag)`	`tag`: string	source
`playMusic(sound, volume=1, loop=false)`	`sound`: string `volume`: float = `1` `loop`: bool = `false`	source
`playSound(sound, volume=1, tag=null)`	`sound`: string `volume`: float = `1` `tag`: string = `null`	source
`resumeSound(tag)`	`tag`: string	source
`soundFadeCancel(tag)`	`tag`: string	source
`soundFadeIn(tag, duration, fromValue=0, toValue=1)`	`tag`: string `duration`: float `fromValue`: float = `0` `toValue`: float = `1`	source
`soundFadeOut(tag, duration, toValue=0)`	`tag`: string `duration`: float `toValue`: float = `0`	source
`stopSound(tag)`	`tag`: string	source

Sprites

Sprites, animations and graphics.

Function	Arguments	Notes
`addAnimation(obj, name, frames, framerate=24, loop=true)`	`obj`: string `name`: string `frames`: list `framerate`: int = `24` `loop`: bool = `true`	source
`addAnimationByIndices(obj, name, prefix, indices, framerate=24)`	`obj`: string `name`: string `prefix`: string `indices`: string `framerate`: int = `24`	source
`addAnimationByIndicesLoop(obj, name, prefix, indices, framerate=24)`	`obj`: string `name`: string `prefix`: string `indices`: string `framerate`: int = `24`	source
`addAnimationByPrefix(obj, name, prefix, framerate=24, loop=true)`	`obj`: string `name`: string `prefix`: string `framerate`: int = `24` `loop`: bool = `true`	source
`addLuaSprite(tag, front=false)`	`tag`: string `front`: bool = `false`	source
`addOffset(obj, anim, x, y)`	`obj`: string `anim`: string `x`: float `y`: float	source
`getMidpointX(variable)`	`variable`: string	source
`getMidpointY(variable)`	`variable`: string	source
`getScreenPositionX(obj)`	`obj`: string	source
`getScreenPositionY(obj)`	`obj`: string	source
`luaSoundExists(tag)`	`tag`: string	source
`luaSpriteExists(tag)`	`tag`: string	source
`luaTextExists(tag)`	`tag`: string	source
`makeAnimatedLuaSprite(tag, image, x, y, spriteType="sparrow")`	`tag`: string `image`: string `x`: float `y`: float `spriteType`: string = `"sparrow"`	source
`makeGraphic(obj, width, height, color)`	`obj`: string `width`: int `height`: int `color`: string	source
`makeLuaSprite(tag, image, x, y)`	`tag`: string `image`: string `x`: float `y`: float	source
`playAnim(obj, name, forced=false, reverse=false, startFrame=0)`	`obj`: string `name`: string `forced`: bool = `false` `reverse`: bool = `false` `startFrame`: int = `0`	source
`removeLuaSprite(tag, destroy=true)`	`tag`: string `destroy`: bool = `true`	source
`scaleObject(obj, x, y, updateHitbox=true)`	`obj`: string `x`: float `y`: float `updateHitbox`: bool = `true`	source
`screenCenter(obj, pos='xy')`	`obj`: string `pos`: string = `'xy'`	source
`setBlendMode(obj, blend='')`	`obj`: string `blend`: string = `''`	source
`setGraphicSize(obj, x, y=0, updateHitbox=true)`	`obj`: string `x`: int `y`: int = `0` `updateHitbox`: bool = `true`	source
`setHealthBarColors(leftHex, rightHex)`	`leftHex`: string `rightHex`: string	source
`setObjectCamera(obj, camera='')`	`obj`: string `camera`: string = `''`	source
`setScrollFactor(obj, scrollX, scrollY)`	`obj`: string `scrollX`: float `scrollY`: float	source
`setTimeBarColors(leftHex, rightHex)`	`leftHex`: string `rightHex`: string	source
`updateHitbox(obj)`	`obj`: string	source
`updateHitboxFromGroup(group, index)`	`group`: string `index`: int	source

Text

On-screen text objects.

Function	Arguments	Notes
`addLuaText(tag)`	`tag`: string	source
`getTextFont(tag)`	`tag`: string	source
`getTextSize(tag)`	`tag`: string	source
`getTextString(tag)`	`tag`: string	source
`getTextWidth(tag)`	`tag`: string	source
`makeLuaText(tag, text, width, x, y)`	`tag`: string `text`: string `width`: int `x`: float `y`: float	Lua texts · source
`removeLuaText(tag, destroy=true)`	`tag`: string `destroy`: bool = `true`	source
`setTextAlignment(tag, alignment='left')`	`tag`: string `alignment`: string = `'left'`	source
`setTextBorder(tag, size, color, quality='quality')`	`tag`: string `size`: int `color`: string `quality`: string = `'quality'`	source
`setTextColor(tag, color)`	`tag`: string `color`: string	source
`setTextFont(tag, newFont)`	`tag`: string `newFont`: string	source
`setTextItalic(tag, italic)`	`tag`: string `italic`: bool	source
`setTextSize(tag, size)`	`tag`: string `size`: int	source
`setTextString(tag, text)`	`tag`: string `text`: string	source
`setTextWidth(tag, width)`	`tag`: string `width`: float	source

Timers

Scheduling and cancelling timers.

Function	Arguments	Notes
`cancelTimer(tag)`	`tag`: string	source
`runTimer(tag, time=1, loops=1)`	`tag`: string `time`: float = `1` `loops`: int = `1`	source

Tweens

Tweening object properties.

Function	Arguments	Notes
`cancelTween(tag)`	`tag`: string	source
`doTweenAlpha(tag, vars, value, duration, ease)`	`tag`: string `vars`: string `value`: any `duration`: float `ease`: string	source
`doTweenAngle(tag, vars, value, duration, ease)`	`tag`: string `vars`: string `value`: any `duration`: float `ease`: string	source
`doTweenColor(tag, vars, targetColor, duration, ease)`	`tag`: string `vars`: string `targetColor`: string `duration`: float `ease`: string	source
`doTweenScale(tag, vars, value, duration, ease)`	`tag`: string `vars`: string `value`: any `duration`: float `ease`: string	source
`doTweenX(tag, vars, value, duration, ease)`	`tag`: string `vars`: string `value`: any `duration`: float `ease`: string	source
`doTweenY(tag, vars, value, duration, ease)`	`tag`: string `vars`: string `value`: any `duration`: float `ease`: string	source
`doTweenZoom(tag, vars, value, duration, ease)`	`tag`: string `vars`: string `value`: any `duration`: float `ease`: string	source
`noteTweenAlpha(tag, note, value, duration, ease)`	`tag`: string `note`: int `value`: any `duration`: float `ease`: string	source
`noteTweenAngle(tag, note, value, duration, ease)`	`tag`: string `note`: int `value`: any `duration`: float `ease`: string	source
`noteTweenDirection(tag, note, value, duration, ease)`	`tag`: string `note`: int `value`: any `duration`: float `ease`: string	source
`noteTweenScaleX(tag, note, value, duration, ease)`	`tag`: string `note`: int `value`: any `duration`: float `ease`: string	source
`noteTweenScaleY(tag, note, value, duration, ease)`	`tag`: string `note`: int `value`: any `duration`: float `ease`: string	source
`noteTweenX(tag, note, value, duration, ease)`	`tag`: string `note`: int `value`: any `duration`: float `ease`: string	Tween shit, but for strums · source
`noteTweenY(tag, note, value, duration, ease)`	`tag`: string `note`: int `value`: any `duration`: float `ease`: string	source

Window

Window transparency, alpha and click-through (desktop overlay mods).

Function	Arguments	Notes
`applyWindowTransparency()`	none	Re-applies the stored settings, e.g. after the window was recreated. · source
`getWindowAlpha()`	none	The last opacity set through setWindowAlpha. · source
`getWindowTransparent()`	none	Reads back whether transparency is on (it may be suspended by fullscreen). · source
`isWindowClickThrough()`	none	Whether the window is currently ignoring the mouse. · source
`isWindowTransparencySupported()`	none	False on HTML5/Flash/mobile: every setter above is a no-op there. · source
`setWindowAlpha(alpha)`	`alpha`: float	Whole-window opacity: 0 = invisible, 1 = opaque. Windows, Linux and macOS. · source
`setWindowClickThrough(enable=true)`	`enable`: bool = `true`	Lets clicks pass through the window. Windows only. · source
`setWindowTransparencyColor(color)`	`color`: any	The color that renders see-through. Takes a number (0xFF010101) or a string ('010101', '#010101', '0xFF010101'). Windows only. · source
`setWindowTransparent(enable=true)`	`enable`: bool = `true`	Makes the window see-through: every pixel painted with the transparency color (RGB 1,1,1 by default) disappears and shows the desktop behind it. Windows only; leaves fullscreen when the game is in it. · source

Index​

Cameras​

Characters​

Hardware​

Input​

Misc​

Properties​

PyScriptLib​

Score & health​

Sound​

Sprites​

Text​

Timers​

Tweens​

Window​