Skip to content
Overlunky/Playlunky Lua API

Generic functions

__load

same as loadsource

function __load(): integer

Returns integer

__loadfile

same as loadfilesource

function __loadfile(): integer

Returns integer

__loadlib

same as package.loadlibsource

function __loadlib(path: string, func: string): any
path: string
func: string

Returns any (may be nil)

__require

same as requiresource

function __require(path: string): any
path: string

Returns any (may be nil)

add_custom_type

source

function add_custom_type(types: ENT_TYPE[]): ENT_TYPE
types: ENT_TYPE[]

Returns ENT_TYPE

function add_custom_type(): ENT_TYPE

Returns ENT_TYPE

Adds new custom type (group of ENT_TYPE) that can be later used in functions like get_entities_by or set_(pre/post)_entity_spawn Use empty array or no parameter to get new unique ENT_TYPE that can be used for custom EntityDB

add_money

source

function add_money(amount: integer, display_time?: integer): integer
amount: integer
display_time?: integeroptional

Returns integer

Adds money to the state.money_shop_total and displays the effect on the HUD for money change Can be negative, default display_time = 60 (about 2s). Returns the current money after the transaction

add_money_slot

source

function add_money_slot(amount: integer, player_slot: integer, display_time?: integer): integer
amount: integer
player_slot: integer
display_time?: integeroptional

Returns integer

Adds money to the state.items.player_inventory[player_slot].money and displays the effect on the HUD for money change Can be negative, default display_time = 60 (about 2s). Returns the current money after the transaction

clear_cache

source

function clear_cache()
function clear_cache(path: string)
path: string

Clear cache for a file path or the whole directory

clear_state

source

function clear_state(slot: integer)
slot: integer

Clear save state from slot 1..4.

create_fmod_guid_map

source

function create_fmod_guid_map(path: string): FMODguidMap?
path: string

Returns FMODguidMap? (may be nil)

Creates an FMODguidMap by parsing a GUIDs.txt exported from FMOD Studio from disk relative to this script. This is useful if you want to use a human readable FMOD event path to create a CustomEventDescription instead of using an FMOD GUID string.

create_image

source

function create_image(path: string): IMAGE, integer, integer
path: string

Returns IMAGE, integer, integer

Create image from file. Returns a tuple containing id, width and height. Depending on the image size, this can take a moment, preferably don't create them dynamically, rather create all you need in global scope so it will load them as soon as the game starts

create_image_crop

source

function create_image_crop(path: string, x: integer, y: integer, w: integer, h: integer): IMAGE, integer, integer
path: string
x: integer
y: integer
w: integer
h: integer

Returns IMAGE, integer, integer

Create image from file, cropped to the geometry provided. Returns a tuple containing id, width and height. Depending on the image size, this can take a moment, preferably don't create them dynamically, rather create all you need in global scope so it will load them as soon as the game starts

create_layer

source

function create_layer(layer: integer)
layer: integer

Initializes an empty layer that doesn't currently exist.

create_level

source

function create_level()

Initializes an empty front and back layer that don't currently exist. Does nothing(?) if layers already exist.

destroy_grid

source

function destroy_grid(uid: integer)
uid: integer
function destroy_grid(x: number, y: number, layer: LAYER)
x: number
y: number
layer: LAYER

Destroy the grid entity (by uid or position), and its item entities, removing them from the grid without dropping particles or gold. Will also destroy monsters or items that are standing on a linked activefloor or chain, though excludes MASK.PLAYER to prevent crashes

destroy_layer

source

function destroy_layer(layer: integer)
layer: integer

Destroys a layer and all entities in it.

destroy_level

source

function destroy_level()

Destroys all layers and all entities in the level. Usually a bad idea, unless you also call create_level and spawn the player back in.

dofile

source

function dofile(): integer

Returns integer

force_journal

source

function force_journal(chapter: integer, entry: integer)
chapter: integer
entry: integer

Force the journal to open on a chapter and entry# when pressing the journal button. Only use even entry numbers. Set chapter to JOURNALUI_PAGE_SHOWN.JOURNAL to reset. (This forces the journal toggle to always read from game_manager.save_related.journal_popup_ui.entry_to_show etc.)

get_adventure_seed

source

function get_adventure_seed(run_start?: boolean): integer, integer
run_start?: booleanoptional

Returns integer, integer

Get the current adventure seed pair, or optionally what it was at the start of this run, because it changes every level.

get_bank

source

function get_bank(path: string): CustomBank?
path: string

Returns CustomBank? (may be nil)

Gets an existing loaded bank if a file at the same path was already loaded

get_bucket

documented onlysource

function get_bucket(): Bucket

Returns Bucket

Returns the Bucket of data stored in shared memory between Overlunky and Playlunky

get_character_heart_color

source

function get_character_heart_color(type_id: ENT_TYPE): Color
type_id: ENT_TYPE

Returns Color

Same as Player.get_heart_color

get_color

source

function get_color(color_name: string, alpha?: integer): uColor
color_name: string
alpha?: integeroptional

Returns uColor

Convert a string to a color, you can use the HTML color names, or even HTML color codes, just prefix them with '#' symbol You can also convert hex string into a color, prefix it with '0x', but use it only if you need to since lua allows for hex values directly too. Default alpha value will be 0xFF, unless it's specified Format: [name], #RRGGBB, #RRGGBBAA, 0xBBGGRR, 0xAABBGGRR

get_current_money

source

function get_current_money(): integer

Returns integer

Just convenient way of getting the current amount of money short for state->money_shop_total + loop[inventory.money + inventory.collected_money_total]

get_event_by_id

source

function get_event_by_id(guid_string: string): CustomEventDescription?
guid_string: string

Returns CustomEventDescription? (may be nil)

Gets a CustomEventDescription if the event description is loaded using an FMOD GUID string. The string representation must be formatted as 32 digits seperated by hyphens and enclosed in braces: {00000000-0000-0000-0000-000000000000}.

get_frame

source

function get_frame(): integer

Returns integer

Get the current frame count since the game was started*. You can use this to make some timers yourself, the engine runs at 60fps. This counter is paused if the pause is set with flags PAUSE.FADE or PAUSE.ANKH.

get_frametime

source

function get_frametime(): number

Returns number

Get engine target frametime (1/framerate, default 1/60).

get_frametime_unfocused

source

function get_frametime_unfocused(): number

Returns number

Get engine target frametime when game is unfocused (1/framerate, default 1/33).

get_global_frame

documented onlysource

function get_global_frame(): integer

Returns integer

Get the current global frame count since the game was started. You can use this to make some timers yourself, the engine runs at 60fps. This counter keeps incrementing with game loop. Never stops.

get_hud

source

function get_hud(): HudData?

Returns HudData? (may be nil)

Get the HudData the game draws the vanilla HUD from.

get_id

source

function get_id(): string

Returns string

Get your sanitized script id to be used in import.

get_level_config

source

function get_level_config(config: LEVEL_CONFIG): integer
config: LEVEL_CONFIG

Returns integer

Gets the value for the specified config

get_liquid_layer

source

function get_liquid_layer(): integer

Returns integer

Get the current layer that the liquid is spawn in. Related function set_liquid_layer

get_liquids_at

source

function get_liquids_at(x: number, y: number, layer: LAYER): integer, integer
x: number
y: number
layer: LAYER

Returns integer, integer

Optimized function to check for the amount of liquids at a certain position, by accessing a 2d array of liquids by third of a tile. Try the liquids.lua example to know better how it works. Returns a pair of water and lava, in that order. Water blobs increase the number by 2 on the grid, while lava blobs increase it by 3. The maximum is usually 6. Coarse water increase the number by 3, coarse and stagnant lava by 6. Combinations of both normal and coarse can make the number higher than 6.

get_local_prng

source

function get_local_prng(): PRNG?

Returns PRNG? (may be nil)

Get the thread-local version of prng

get_local_state

source

function get_local_state(): StateMemory?

Returns StateMemory? (may be nil)

Get the thread-local version of state

get_ms

source

function get_ms(): integer

Returns integer

Get the current timestamp in milliseconds since the Unix Epoch.

get_performance_counter

source

function get_performance_counter(): integer

Returns integer

Retrieves the current value of the performance counter, which is a high resolution (<1us) time stamp that can be used for time-interval measurements.

get_performance_frequency

source

function get_performance_frequency(): integer

Returns integer

Retrieves the frequency of the performance counter. The frequency of the performance counter is fixed at system boot and is consistent across all processors. Therefore, the frequency need only be queried upon application initialization, and the result can be cached.

get_save_state

source

function get_save_state(slot: integer): StateMemory?
slot: integer

Returns StateMemory? (may be nil)

Get StateMemory from a save_state slot.

get_setting

source

function get_setting(setting: GAME_SETTING): integer?
setting: GAME_SETTING

Returns integer? (may be nil)

Gets the specified setting, values might need to be interpreted differently per setting

get_speedhack

source

function get_speedhack(): number

Returns number

Get the current speedhack multiplier

get_start_level_paused

source

function get_start_level_paused(): boolean

Returns boolean

Returns true if the level pause hack is enabled

god

source

function god(g: boolean)
g: boolean

Enable/disable godmode for players.

god_companions

source

function god_companions(g: boolean)
g: boolean

Enable/disable godmode for companions.

grow_chainandblocks

source

function grow_chainandblocks(x: integer, y: integer): boolean
x: integer
y: integer

Returns boolean

function grow_chainandblocks(): boolean

Returns boolean

Grow chains from ENT_TYPE_FLOOR_CHAIN_CEILING and chain with blocks on it from ENT_TYPE_FLOOR_CHAINANDBLOCKS_CEILING, it starts looking for the ceilings from the top left corner of a level. To limit it use the parameters, so x = 10 will only grow chains from ceilings with x < 10, with y = 10 it's ceilings that have y > (level bound top - 10)

grow_poles

source

function grow_poles(l: LAYER, max_length: integer)
l: LAYER
max_length: integer
function grow_poles(l: LAYER, max_length: integer, area: AABB, destroy_broken: boolean)
l: LAYER
max_length: integer
area: AABB
destroy_broken: boolean

Grow pole from GROWABLE_CLIMBING_POLE entities in a level, area default is whole level, destroy_broken default is false

grow_vines

source

function grow_vines(l: LAYER, max_length: integer)
l: LAYER
max_length: integer
function grow_vines(l: LAYER, max_length: integer, area: AABB, destroy_broken: boolean)
l: LAYER
max_length: integer
area: AABB
destroy_broken: boolean

Grow vines from GROWABLE_VINE and VINE_TREE_TOP entities in a level, area default is whole level, destroy_broken default is false

import

documented onlysource

function import(id: string, version: string?, optional: boolean?): table
id: string
version: string?
optional: boolean?

Returns table

Load another script by id "author/name" and import its exports table. Enables the imported script if it isn't already, except when it is unsafe and yours is not, since enabling a script runs it and only the user gets to make that call for an unsafe one. Returns:

  • table if the script has exports
  • nil if the script was found but has no exports
  • false if the script was not found, or is unsafe and not enabled, but optional is set to true
  • an error if the script was not found, or is unsafe and not enabled, and the optional argument was not set

inputs_to_buttons

source

function inputs_to_buttons(inputs: INPUTS): number, number, BUTTON
inputs: INPUTS

Returns number, number, BUTTON

Converts INPUTS to (x, y, BUTTON)

intersection

source

function intersection(A: Vec2, B: Vec2, C: Vec2, D: Vec2): Vec2
A: Vec2
B: Vec2
C: Vec2
D: Vec2

Returns Vec2

Find intersection point of two lines [A, B] and [C, D], returns INFINITY if the lines don't intersect each other [parallel]

is_character_female

source

function is_character_female(type_id: ENT_TYPE): boolean
type_id: ENT_TYPE

Returns boolean

Same as Player.is_female

list_char_mods

source

function list_char_mods(): any

Returns any (may be nil)

List all char_*.png files recursively from Mods/Packs. Returns table of file paths.

list_data_dir

source

function list_data_dir(dir?: string): any
dir?: stringoptional

Returns any (may be nil)

List files in directory relative to the mods data directory (Mods/Data/...). Returns table of file/directory names or nil if not found.

list_dir

source

function list_dir(dir?: string): any
dir?: stringoptional

Returns any (may be nil)

List files in directory relative to the script root. Returns table of file/directory names or nil if not found.

load

source

function load(): integer

Returns integer

A chunk loaded by the stock load/loadfile/dofile gets the real _G as its _ENV, so these have to give the chunk the calling script's environment instead.

load_bank

source

function load_bank(path: string, flags: integer): CustomBank?
path: string
flags: integer

Returns CustomBank? (may be nil)

Loads a bank from disk relative to this script, ownership might be shared with other code that loads the same file. Returns nil if the file can't be found. Loading a bank file will load the banks metadata, but not non-streaming sample data. Once a bank has finished loading, all metadata can be accessed meaning that event descriptions can be found with get_event_by_id() or using create_fmod_guid_map() and calling FMODguidMap:get_event(). The banks loading state can be queried using CustomBank:get_loading_state() which will return an FMOD_LOADING_STATE.

load_death_screen

source

function load_death_screen()

Immediately ends the run with the death screen, also calls the save_progress

load_screen

source

function load_screen()

Immediately load a screen based on state.screen_next and stuff

load_state

source

function load_state(slot: integer)
slot: integer

Load level state from slot 1..4, if a save_state was made in this level.

loadfile

source

function loadfile(): integer

Returns integer

lowbias32

source

function lowbias32(x: integer): integer
x: integer

Returns integer

Some random hash function

lowbias32_r

source

function lowbias32_r(x: integer): integer
x: integer

Returns integer

Reverse of some random hash function

play_adventure

source

function play_adventure()

Initializes some adventure run related values and loads the character select screen, as if starting a new adventure run from the Play menu. Character select can be skipped by changing state.screen_next right after calling this function, maybe with warp(). If player isn't already selected, make sure to set state.items.player_select and state.items.player_count appropriately too.

play_seeded

source

function play_seeded(seed?: integer)
seed?: integeroptional

Initializes some seeded run related values and loads the character select screen, as if starting a new seeded run after entering the seed.

register_console_command

source

function register_console_command(name: string, cmd: function)
name: string
cmd: function
Callback signature not known from the code.

Adds a command that can be used in the console.

require

source

function require(path: string): any
path: string

Returns any (may be nil)

Custom implementation to trick Lua into allowing to require 'lib.module' more than once given it was called from a different source

rgba

source

function rgba(r: integer, g: integer, b: integer, a: integer): uColor
r: integer
g: integer
b: integer
a: integer

Returns uColor

Converts a color to int to be used in drawing functions. Use values from 0..255.

save_progress

source

function save_progress(): boolean

Returns boolean

Saves the game to savegame.sav, unless game saves are blocked in the settings. Also runs the ON.SAVE callback. Fails and returns false, if you're trying to save too often (2s).

save_script

source

function save_script(): boolean

Returns boolean

Runs the ON.SAVE callback. Fails and returns false, if you're trying to save too often (2s).

save_state

source

function save_state(slot: integer)
slot: integer

Save current level state to slot 1..4. These save states are invalid and cleared after you exit the current level, but can be used to rollback to an earlier state in the same level. You probably definitely shouldn't use save state functions during an update, and sync them to the same event outside an update (i.e. GUIFRAME, POST_UPDATE). These slots are already allocated by the game, actually used for online rollback, and use no additional memory. Also see SaveState if you need more.

script_enabled

documented onlysource

function script_enabled(id: string, version?: string): boolean
id: string
version?: stringoptional

Returns boolean

Check if another script is enabled by id "author/name". You should probably check this after all the other scripts have had a chance to load.

seed_prng

source

function seed_prng(seed: integer)
seed: integer

Seed the game prng.

set_adventure_seed

source

function set_adventure_seed(first: integer, second: integer)
first: integer
second: integer

Set the current adventure seed pair. Use just before resetting a run to recreate an adventure run.

set_character_heart_color

source

function set_character_heart_color(type_id: ENT_TYPE, color: Color)
type_id: ENT_TYPE
color: Color

Same as Player.set_heart_color

set_frametime

source

function set_frametime(frametime?: number)
frametime?: numberoptional

Set engine target frametime (1/framerate, default 1/60). Always capped by your GPU max FPS / VSync. To run the engine faster than rendered FPS, try update_state. Set to 0 to go as fast as possible. Call without arguments to reset. Also see set_speedhack

set_frametime_unfocused

source

function set_frametime_unfocused(frametime?: number)
frametime?: numberoptional

Set engine target frametime when game is unfocused (1/framerate, default 1/33). Always capped by the engine frametime. Set to 0 to go as fast as possible. Call without arguments to reset.

set_hotkey

documented onlysource

function set_hotkey(cb: function, key: KEY, flags?: HOTKEY_TYPE): CallbackId
cb: function
key: KEY
flags?: HOTKEY_TYPEoptional

Returns CallbackId

Returns unique id >= 0 for the callback to be used in clear_callback or -1 if the key could not be registered. Add callback function to be called on a hotkey, using Windows hotkey api. These hotkeys will override all game and UI input and can work even when the game is unfocused. They are by design very intrusive and won't let anything else use the same key combo. Can't detect if input is active in another instance, use ImGuiIO if you need Playlunky hotkeys to react to Overlunky input state. Key is a KEY combo (e.g. KEY.OL_MOD_CTRL | KEY.X), possibly returned by GuiDrawContext:key_picker. Doesn't work with mouse buttons.
The callback signature is nil on_hotkey(KEY key)

set_infinite_loop_detection_enabled

source

function set_infinite_loop_detection_enabled(enable: boolean)
enable: boolean

Disable the Infinite Loop Detection of 420 million instructions per frame, if you know what you're doing and need to perform some serious calculations that hang the game updates for several seconds.

set_journal_enabled

source

function set_journal_enabled(b: boolean)
b: boolean

Enables or disables the journal

set_level_config

source

function set_level_config(config: LEVEL_CONFIG, value: integer)
config: LEVEL_CONFIG
value: integer

Set the value for the specified config

set_seed

source

function set_seed(seed: integer)
seed: integer

Set seed and reset run.

set_setting

source

-- set some visual settings needed by your mod
-- doing this here will reapply these after visiting the options, which would reset them to real values


set_callback(function()
    if state.screen_next == SCREEN.LEVEL then
        -- use the secret tiny hud size
        set_setting(GAME_SETTING.HUD_SIZE, 3)
        -- force opaque textboxes
        set_setting(GAME_SETTING.TEXTBOX_OPACITY, 0)
    end
end, ON.PRE_LOAD_SCREEN)
function set_setting(setting: GAME_SETTING, value: integer): boolean
setting: GAME_SETTING
value: integer

Returns boolean

Sets the specified setting temporarily. These values are not saved and might reset to the users real settings if they visit the options menu. (Check example.) All settings are available in unsafe mode and only a smaller subset SAFE_SETTING by default for Hud and other visuals. Returns false, if setting failed.

set_speedhack

source

function set_speedhack(multiplier?: number)
multiplier?: numberoptional

Set multiplier (default 1.0) for a QueryPerformanceCounter hook based speedhack, similar to the one in Cheat Engine. Call without arguments to reset. Also see set_frametime

show_journal

source

function show_journal(chapter: JOURNALUI_PAGE_SHOWN, page: integer)
chapter: JOURNALUI_PAGE_SHOWN
page: integer

Open the journal on a chapter and page. The main Journal spread is pages 0..1, so most chapters start at 2. Use even page numbers only.

toggle_journal

source

function toggle_journal()

Open or close the journal as if pressing the journal button. Will respect visible journal popups and force_journal.

two_lines_angle

source

function two_lines_angle(A: Vec2, common: Vec2, B: Vec2): number
A: Vec2
common: Vec2
B: Vec2

Returns number

function two_lines_angle(line1_A: Vec2, line1_B: Vec2, line2_A: Vec2, line2_B: Vec2): number
line1_A: Vec2
line1_B: Vec2
line2_A: Vec2
line2_B: Vec2

Returns number

Measures angle between two lines with one common point

update_liquid_collision_at

source

function update_liquid_collision_at(x: number, y: number, add: boolean, layer?: LAYER)
x: number
y: number
add: boolean
layer?: LAYERoptional

Updates the floor collisions used by the liquids, set add to false to remove tile of collision, set to true to add one optional layer parameter to be used when liquid was moved to back layer using set_liquid_layer

update_state

source

function update_state()

Run state update manually, i.e. simulate one logic frame. Use in e.g. POST_UPDATE, but be mindful of infinite loops, this will cause another POST_UPDATE. Can even be called thousands of times to simulate minutes of gameplay in a few seconds.

warp

source

function warp(world: integer, level: integer, theme: integer)
world: integer
level: integer
theme: integer

Warp to a level immediately.