Modding: Lua API

Modding Navigation
Fundamentals
Basics • Data.wak • Getting started • Lua Scripting • Useful Tools
Guides
Audio • Enemies • Environments (Fog of War) • Image Emitters • Materials • Perks • Special Behaviors • Spells • Spritesheets • Steam Workshop • Using CMake
Components/Entities
Component Documentation • Enums • List of all tags • Special Tags • Tags System • Update Order
Lua Scripting
Lua API • Utility Scripts
Other Information
Enemy Information Table • Magic Numbers • Sound Events • Spell IDs • Perk IDs • Material IDs

This page gathers together everything from lua_api_documentation.txt, with possible notes made by the community.

Note: Return values wrapped in brackets, like {entity_id}, mean an array of entities. Pay special attention to this!

Lua Tables

Noita is using Lua 5.1, and restricts the API usage unless Unsafe mods is set to "Allowed".

Restricted API

The restricted ("Safe") API is as follows:

Basic Functions - Except for load, loadstring, require, gcinfo, collectgarbage
Table Manipulation - table
String Manipulation - string
Mathematical Functions - math
BitOp - bit
jit.* Library - jit
There is a hidden undocumented function, newproxy()

Unrestricted API

The unsafe API includes everything in the Lua Reference Manual, plus BitOp, jit.*, and newproxy.

Core Functions

Top level functions defined by Noita.

do_mod_appends

do_mod_appends( filename:string )

dofile

dofile( filename:string ) -> (nil|script_return_type)|(nil,error_string)

Noita overrides the built-in dofile function with its own implementation. Returns the script's return value, if any. Returns nil,error_string if the script had errors.

dofile_once

dofile_once( filename:string ) -> (nil|script_return_type)|(nil,error_string)

Runs the script only once per lua context, returns the script's return value, if any. Returns nil,error_string if the script had errors. For performance reasons it is recommended scripts use dofile_once(), unless the standard dofile behaviour is required.

loadfile

loadfile( filename:string ) -> (nil|script_as_function)|(nil,error_string)

Noita overrides the Lua built-in loadfile function with its own implementation. This loads a Lua file and returns both a function and an error string (in case of failure).

print

print

Noita overrides the Lua built-in print function with its own implementation.

print_error

print_error

Works similar to print but also prints the text to logger.txt in the Noita folder.

Hooks

OnBiomeConfigLoaded

OnBiomeConfigLoaded()

This is the first moment during mod initialisation from which the CellFactory_* functions can be called.

OnCountSecrets

OnCountSecrets() -> int,int

The first number to return is the total and the second is the number of secrets found.

OnMagicNumbersAndWorldSeedInitialized

OnMagicNumbersAndWorldSeedInitialized()

OnModInit

OnModInit()

Called once for each mod. It is done for every mod after OnModPreInit and before OnModPostInit is called.

OnModPostInit

OnModPostInit()

Called once for each mod. It is done for every mod after OnModPreInit and OnModInit are called.

OnModPreInit

OnModPreInit()

Called once for each mod. It is done for every mod before either OnModInit and OnModPostInit is called.

OnModSettingsChanged

OnModSettingsChanged()

Will be called when the game is unpaused, if player changed any mod settings while the game was paused. Does not get called when ModSettingSet is called.

Note: This callback doesn't appear to work. Modders have resorted to using OnPausedChanged instead to detect potential settings changes.

OnPausePreUpdate

OnPausePreUpdate()

Will be called when the game is paused, either by the pause menu or some inventory menus. Please be careful with this, as not everything will behave well when called while the game is paused.

OnPausedChanged

OnPausedChanged( is_paused:bool, is_inventory_pause:bool )

OnPlayerDied

OnPlayerDied( player_entity:int )

Run when the player dies. The parameter passed in is the player_entity ID number. It is also run when starting a new game in the same session.

OnPlayerSpawned

OnPlayerSpawned( player_entity:int )

Run whenever the game spawns the player entity. The parameter passed in is the player_entity ID number. It runs each time either a new game is started, or whenever it's loaded.

OnWorldInitialized

OnWorldInitialized()

Run whenever the game creates/loads a new world. Despite the name, OnWorldPreUpdate and OnWorldPostUpdate will still be called at least once before OnWorldInitialized is called.

OnWorldPostUpdate

OnWorldPostUpdate()

This is called every time the game has finished updating the world

OnWorldPreUpdate

OnWorldPreUpdate()

This is called every time the game is about to start updating the world

Game Callback Order

The hooks are called in this order during initialisation:

OnModPreInit
OnModInit
OnModPostInit
OnMagicNumbersAndWorldSeedInitialized
OnBiomeConfigLoaded
OnWorldPreUpdate
OnWorldPostUpdate
OnWorldInitialized
OnPlayerSpawned

The game first calls the hook in data/scripts/init.lua if it exists, followed by each mod in their respective load order.

Mod Settings (settings.lua)

Each of these are hooks defined in settings.lua.

ModSettingsGui

ModSettingsGui( gui, in_main_menu:bool )

This function is called to display the settings UI for this mod. Your mod's settings won't be visible in the mod settings menu if this function isn't defined correctly.

ModSettingsUpdate

ModSettingsUpdate( init_scope:int )

This function is called to ensure the correct setting values are visible to the game via ModSettingGet(). Your mod's settings don't work if you don't have a function like this defined in settings.lua.

This function is called:

when entering the mod settings menu (init_scope will be MOD_SETTING_SCOPE_ONLY_SET_DEFAULT)
before mod initialization when starting a new game (init_scope will be MOD_SETTING_SCOPE_NEW_GAME)
when entering the game after a restart (init_scope will be MOD_SETTING_SCOPE_RESTART)
at the end of an update when mod settings have been changed via ModSettingSetNextValue() and the game is unpaused (init_scope will be MOD_SETTING_SCOPE_RUNTIME)

Note: It is unclear what values the documented constants refer to, but the possible values are between 0 and 3 (inclusive).

ModSettingsGuiCount

ModSettingsGuiCount() -> int

This function should return the number of visible setting UI elements. Your mod's settings wont be visible in the mod settings menu if this function isn't defined correctly.

If your mod changes the displayed settings dynamically, you might need to implement custom logic. The value will be used to determine whether or not to display various UI elements that link to mod settings.

At the moment it is fine to simply return 0 or 1 in a custom implementation, but we don't guarantee that will be the case in the future. This function is called every frame when in the settings menu.

General functions

EntityLoad

EntityLoad( filename:string, pos_x:number = 0, pos_y:number = 0 ) -> entity_id:int

The EntityLoad() function is used to create an entity (game object) at a specified position in the game world.

filename: The path to the XML file that defines the entity to be created.
pos_x: The x-coordinate of the position in the game world where the entity should be created. This argument is optional and defaults to 0.
pos_y: The y-coordinate of the position in the game world where the entity should be created. This argument is optional and defaults to 0.

It returns the ID of the newly-created entity.

The following example uses the GetUpdatedEntityID() function to get the ID of the entity that is currently being updated, and then uses the EntityLoad() function to create an entity at the position of that entity.

-- Get the ID of the entity that is currently being updated.
local entity_id = GetUpdatedEntityID()

-- Get the position of the entity that is currently being updated.
local pos_x, pos_y = EntityGetTransform( entity_id )

-- Create an entity defined in "data/entities/particles/image_emitters/spell_refresh_effect.xml" at the position of the entity that is currently being updated.
local new_entity_id = EntityLoad( "data/entities/particles/image_emitters/spell_refresh_effect.xml", pos_x, pos_y )

Note: The GetUpdatedEntityID() function should only be used in functions that are called from within an entity's script, as it will only return the ID of the entity that is currently being updated. In other contexts, it will return nil. Other ways to get a position may include GameGetCameraPos(), DEBUG_GetMouseWorld(), or EntityGetTransform() with other entities such as the one tagged with "player_unit" (player character).

EntityLoadEndGameItem

EntityLoadEndGameItem( filename:string, pos_x:number = 0, pos_y:number = 0 ) -> entity_id:int

EntityLoadCameraBound

EntityLoadCameraBound( filename:string, pos_x:number = 0, pos_y:number = 0 )

EntityLoadToEntity

EntityLoadToEntity( filename:string, entity:int )

Loads components from 'filename' to 'entity'. Does not load tags and other stuff.

EntitySave

EntitySave( entity_id:int, filename:string )

The EntitySave() function saves an entity to a specified xml file. It takes two arguments:

entity_id: integer representing the ID of the entity to be saved.
filename: string specifying the name and location where the entity should be saved to xml.

This function should be used with care, as it can potentially overwrite existing files. It is only available in development builds of the game.

Here is an example of how to use this function:

-- load an entity from a file
local entity_id = EntityLoad("data/entities/test_sprite.xml")

-- save the entity to a new file
EntitySave(entity_id, "temptemp/out_new_entity.xml")

This function is typically used in conjunction with EntityLoad() and EntityCreateNew() to create and save new entities. It can also be used to save entities that have been modified in some way, such as by adding or removing components.

-- create a new entity
local entity_id = EntityCreateNew("humppa")

-- add a component to the entity
EntityAddComponent2(entity_id, "SpriteComponent")

-- save the modified entity to a file
EntitySave(entity_id, "temptemp/out_modified_entity.xml")

Note that EntitySave() should only be used in development builds of the game. It is not available in the official release of the game. See also DebugGetIsDevBuild() to test whether this can be used.

EntityCreateNew

EntityCreateNew( name:string = "" ) -> entity_id:int

EntityKill

EntityKill( entity_id:int )

EntityGetIsAlive

EntityGetIsAlive( entity_id:int ) -> bool

EntityAddComponent

EntityAddComponent( entity_id:int, component_type_name:string, table_of_component_values:{string} = nil ) -> component_id:int

See Components Documentation for a list of all possible component types.

EntityRemoveComponent

EntityRemoveComponent( entity_id:int, component_id:int )

EntityGetAllComponents

EntityGetAllComponents( entity_id:int ) -> {int}

Returns a table of component ids.

EntityGetComponent

EntityGetComponent( entity_id:int, component_type_name:string, tag:string = "" ) -> {component_id}|nil

Note: Despite its name, this function actually returns an array, and not a single component. See Components Documentation for a list of all possible component types.

EntityGetFirstComponent

EntityGetFirstComponent( entity_id:int, component_type_name:string, tag:string = "" ) -> component_id|nil

Does not return components that are disabled, effectively "hiding" components that you might actually want. See Components Documentation for a list of all possible component types.

EntityGetComponentIncludingDisabled

EntityGetComponentIncludingDisabled( entity_id:int, component_type_name:string, tag:string = "" ) -> {component_id}|nil

Note: Despite its name, this function actually returns an array, and not a single component. See Components Documentation for a list of all possible component types.

EntityGetFirstComponentIncludingDisabled

EntityGetFirstComponentIncludingDisabled( entity_id:int, component_type_name:string, tag:string = "" ) -> component_id|nil

See Components Documentation for a list of all possible component types.

EntitySetTransform

EntitySetTransform( entity_id:int, x:number, y:number = 0, rotation:number = 0, scale_x:number = 1, scale_y:number = 1 )

EntityApplyTransform

EntityApplyTransform( entity_id:int, x:number, y:number = 0, rotation:number = 0, scale_x:number = 1, scale_y:number = 1 )

Sets the transform and tries to immediately refresh components that calculate values based on an entity's transform. Some components store old positions (and calculates the new one based on those). This tries to refresh those.

EntityGetTransform

EntityGetTransform( entity_id:int ) -> x:number,y:number,rotation:number,scale_x:number,scale_y:number

EntityAddChild

EntityAddChild( parent_id:int, child_id:int )

EntityGetAllChildren

EntityGetAllChildren( entity_id:int ) -> {entity_id:int}|nil

EntityGetParent

EntityGetParent( entity_id:int ) -> entity_id:int

EntityGetRootEntity

EntityGetRootEntity( entity_id:int ) -> entity_id:int

Returns the given entity if it has no parent, otherwise walks up the parent hierarchy to the topmost parent and returns it.

EntityRemoveFromParent

EntityRemoveFromParent( entity_id:int )

EntitySetComponentsWithTagEnabled

EntitySetComponentsWithTagEnabled( entity_id:int, tag:string, enabled:bool )

EntitySetComponentIsEnabled

EntitySetComponentIsEnabled( entity_id:int, component_id:int, is_enabled:bool )

EntityGetName

EntityGetName( entity_id:int ) -> name:string

EntitySetName

EntitySetName( entity_id:int, name:string )

EntityGetTags

EntityGetTags( entity_id:int ) -> string|nil

Returns a string where the tags are comma-separated, or nil if 'entity_id' doesn't point to a valid entity.

EntityGetWithTag

EntityGetWithTag( tag:string ) -> {entity_id:int}

Returns all entities with 'tag'.

EntityGetInRadius

EntityGetInRadius( pos_x:number, pos_y:number, radius:number ) -> {entity_id:int}

Returns all entities in 'radius' distance from 'x','y'. You can use math.huge as the radius to get all entities.

EntityGetInRadiusWithTag

EntityGetInRadiusWithTag( pos_x:number, pos_y:number, radius:number, entity_tag:string ) -> {entity_id:int}

Returns all entities in 'radius' distance from 'x','y' with the given tag. You can use math.huge as the radius to get all entities.

EntityGetClosest

EntityGetClosest( pos_x:number, pos_y:number ) -> entity_id:int

EntityGetClosestWithTag

EntityGetClosestWithTag( pos_x:number, pos_y:number, tag:string ) -> entity_id:int

EntityGetWithName

EntityGetWithName( name:string ) -> entity_id:int

EntityAddTag

EntityAddTag( entity_id:int, tag:string )

This function will add a single permanent tag to an entity. The tag will be serialized with the entity and remain with it until it is removed.

entity_id: integer representing the ID of the entity to add the tag to
tag: A string representing a single tag name to attach to the entity, this can be any string.

Important: You cannot add multiple tags in a single call with a comma, you must add them one by one using a function call for each one. For example, EntityAddTag(e, "enemy,ui_use_raw_name") does not add two tags, it adds a single tag with a comma in the tag name.

EntityRemoveTag

EntityRemoveTag( entity_id:int, tag:string )

EntityHasTag

EntityHasTag( entity_id:int, tag:string ) -> bool

EntityGetFilename

EntityGetFilename( entity_id:int ) -> full_path:string

Returns the name of the file (game directory included) which was originally used to create the entity.

return value example: 'data/entities/items/flute.xml'

ComponentAddTag

ComponentAddTag( component_id:int, tag:string )

ComponentRemoveTag

ComponentRemoveTag( component_id:int, tag:string )

ComponentHasTag

ComponentHasTag( component_id:int, tag:string ) -> bool

ComponentGetTags

ComponentGetTags( component_id:int ) -> string|nil

Returns a string where the tags are comma-separated, or nil if can't find 'component_id' component.

ComponentGetValue2

ComponentGetValue2( component_id:int, field_name:string ) -> multiple_types|nil

Returns one or many values matching the type or subtypes of the requested field. Reports error and returns nil if the field type is not supported or field was not found.

ComponentSetValue2

ComponentSetValue2( component_id:int, field_name:string, value_or_values:multiple_types )

Sets the value of a field. Value(s) should have a type matching the field type. Reports error if the values weren't given in correct type, the field type is not supported, or the component does not exist.

ComponentObjectGetValue2

ComponentObjectGetValue2( component_id:int, object_name:string, field_name:string ) -> multiple types|nil

Returns one or many values matching the type or subtypes of the requested field in a component subobject. Reports error and returns nil if the field type is not supported or 'object_name' is not a metaobject.

ComponentObjectSetValue2

ComponentObjectSetValue2( component_id:int, object_name:string, field_name:string, value_or_values:multiple_types )

Sets the value of a field in a component subobject. Value(s) should have a type matching the field type. Reports error if the values weren't given in correct type, the field type is not supported or 'object_name' is not a metaobject.

EntityAddComponent2

EntityAddComponent2( entity_id:int, component_type_name:string, table_of_component_values:{string-multiple_types} = nil ) -> component_id:int

Creates a component of type 'component_type_name' and adds it to 'entity_id'. 'table_of_component_values' should be a string-indexed table, where keys are field names and values are field values of correct type. The value setting works like ComponentObjectSetValue2(), with the exception that multivalue types are not supported. Additional supported values are _tags:comma_separated_string and _enabled:bool, which basically work like the same values work in entity XML files. Returns the created component, if creation succeeded, or nil.

See Components Documentation for a list of all possible component types.

ComponentGetVectorSize

ComponentGetVectorSize( component_id:int, array_member_name:string, type_stored_in_vector:string ) -> int

'type_stored_in_vector' should be "int", "float" or "string".

ComponentGetVectorValue

ComponentGetVectorValue( component_id:int, array_name:string, type_stored_in_vector:string, index:int ) -> int|number|string|nil

'type_stored_in_vector' should be "int", "float" or "string".

ComponentGetVector

ComponentGetVector( component_id:int, array_name:string, type_stored_in_vector:string ) -> {int|number|string}|nil

'type_stored_in_vector' should be "int", "float" or "string".

ComponentGetIsEnabled

ComponentGetIsEnabled( component_id:int ) -> bool

Returns true if the given component exists and is enabled, else false.

ComponentGetMembers

ComponentGetMembers( component_id:int ) -> {string-string}|nil

Returns a string-indexed table of string.

ComponentObjectGetMembers

ComponentObjectGetMembers( component_id:int, object_name:string ) -> {string-string}|nil

Returns a string-indexed table of string or nil.

ComponentGetTypeName

ComponentGetTypeName( component_id:int ) -> string

GetUpdatedEntityID

GetUpdatedEntityID() -> entity_id:int

GetUpdatedComponentID

GetUpdatedComponentID() -> component_id:int

SetTimeOut

SetTimeOut( time_to_execute:number, file_to_execute:string, function_to_call:string = nil )

Used to execute a function from a file after a certain duration.

time_to_execute: The time in seconds from now before the file and function is executed. Can be fractional, i.e. 0.5 for 500ms, or 0 for the next update.
file_to_execute: The path to the file to be loaded and executed once the duration expires.
function_to_call: Optional name of a function to call when the timer expires. Useful when trying to keep logic within the same file, for example in a component script.

Simplified example from scripts/buildings/egg_damage.lua:

function spawn_boss_dragon()
	local entity_id    = GetUpdatedEntityID()
	local pos_x, pos_y = EntityGetTransform( entity_id )

	GlobalsSetValue("boss_dragon_spawned_pos_x", pos_x)
	GlobalsSetValue("boss_dragon_spawned_pos_y", pos_y)

	play_animation( entity_id, "open")

	SetTimeOut( 0.54, "data/scripts/buildings/egg_damage.lua", "impl_spawn_boss_dragon")
end

function impl_spawn_boss_dragon()
	local pos_x = GlobalsGetValue("boss_dragon_spawned_pos_x")
	local pos_y = GlobalsGetValue("boss_dragon_spawned_pos_y")
	EntityLoad( "data/entities/animals/boss_dragon.xml", pos_x, pos_y - 16 )
end

This example first starts playing an animation followed by a delay before spawning the Dragon, that delay is achieved through SetTimeOut.

You should assume that the script being run is executed in a new Lua context without access to previously set variables, and pass variables via GlobalsSetValue and GlobalsGetValue or other shared variable mechanisms like flags or stats.

RegisterSpawnFunction

RegisterSpawnFunction( color:int, function_name:string )

SpawnActionItem

SpawnActionItem( x:number, y:number, level:int )

SpawnStash

SpawnStash( x:number, y:number, level:int, action_count:int ) -> entity_id:int

SpawnApparition

SpawnApparition( x:number, y:number, level:int ) -> spawn_state_id:int,entity_id:int

LoadEntityToStash

LoadEntityToStash( entity_file:string, stash_entity_id:int )

AddMaterialInventoryMaterial

AddMaterialInventoryMaterial( entity_id:int, material_name:string, count:int )

Used to set the count of a given material in an entity's MaterialInventoryComponent. The function always picks the first MaterialInventoryComponent on the entity, even when it is disabled.

Somewhat surprisingly, this does not add to the existing material_name count. To do that you first read the count_per_material_type property and sum together how much you want to add and the current count.

The function takes three arguments:

entity_id: id of the entity that owns the material inventory.
material_name: name of the material to be added to the inventory.
count: units of the material to set in the inventory.

Here is an example of how the function might be used in code:

function init( entity_id )
	-- Set a random seed based on the entity's position and the current game frame
	local x,y = EntityGetTransform( entity_id )
	SetRandomSeed( x + GameGetFrameNum(), y )

	-- Choose a random potion from the list of available potions
	local potion = random_from_array( potions )

	-- Put 1000 units of the chosen potion material in the entity's material inventory
	AddMaterialInventoryMaterial( entity_id, potion.material, 1000 )
end

In this example, the init function sets a random seed based on the position of the given entity and the current game frame. It then chooses a random potion from the potions array and makes it so there are 1000 units of the potion's material in the entity's material inventory using the AddMaterialInventoryMaterial function.

GetMaterialInventoryMainMaterial

GetMaterialInventoryMainMaterial( entity_id:int ) -> material_type:int

Returns the id of the material taking the largest part of the first MaterialInventoryComponent in 'entity_id', or 0 if nothing is found.

GameScreenshake

GameScreenshake( strength:number, x:number = camera_x, y:number = camera_y )

GameOnCompleted

GameOnCompleted()

GameGiveAchievement

GameGiveAchievement( id:string )

GameDoEnding2

GameDoEnding2()

GetParallelWorldPosition

GetParallelWorldPosition( world_pos_x:number, world_pos_y:number ) -> x, y

x = 0 normal world, -1 is first west world, +1 is first east world, if y < 0 it is sky, if y > 0 it is hell

BiomeMapLoad_KeepPlayer

BiomeMapLoad_KeepPlayer( filename:string, pixel_scenes:string = "data/biome/_pixel_scenes.xml" )

GameIsIntroPlaying

GameIsIntroPlaying() -> bool

GameGetIsGamepadConnected

GameGetIsGamepadConnected() -> bool

GameGetWorldStateEntity

GameGetWorldStateEntity() -> entity_id:int

GameGetPlayerStatsEntity

GameGetPlayerStatsEntity() -> entity_id:int

GameGetOrbCountAllTime

GameGetOrbCountAllTime() -> int

GameGetOrbCountThisRun

GameGetOrbCountThisRun() -> int

GameGetOrbCollectedThisRun

GameGetOrbCollectedThisRun( orb_id_zero_based:int ) -> bool

GameGetOrbCollectedAllTime

GameGetOrbCollectedAllTime( orb_id_zero_based:int ) -> bool

GameClearOrbsFoundThisRun

GameClearOrbsFoundThisRun()

GameGetOrbCountTotal

GameGetOrbCountTotal() -> int

Returns the number of orbs, picked or not.

CellFactory_GetName

CellFactory_GetName( material_id:int ) -> string

Converts a numeric material id to the material's strings id.

CellFactory_GetType

CellFactory_GetType( material_name:string ) -> int

Returns the id of a material.

CellFactory_GetUIName

CellFactory_GetUIName( material_id:int ) -> string

Returns the UI translation key for a material, or an empty string if 'material_id' is not valid. Use GameTextGetTranslatedOrNot to translate it.

CellFactory_GetAllLiquids

CellFactory_GetAllLiquids( include_statics:bool = true, include_particle_fx_materials:bool = false ) -> {string}

CellFactory_GetAllSands

CellFactory_GetAllSands( include_statics:bool = true, include_particle_fx_materials:bool = false ) -> {string}

CellFactory_GetAllGases

CellFactory_GetAllGases( include_statics:bool = true, include_particle_fx_materials:bool = false ) -> {string}

CellFactory_GetAllFires

CellFactory_GetAllFires( include_statics:bool = true, include_particle_fx_materials:bool = false ) -> {string}

CellFactory_GetAllSolids

CellFactory_GetAllSolids( include_statics:bool = true, include_particle_fx_materials:bool = false ) -> {string}

CellFactory_GetTags

CellFactory_GetTags( material_id:int ) -> {string}

GameGetCameraPos

GameGetCameraPos() -> x:number,y:number

GameSetCameraPos

GameSetCameraPos( x:number, y:number )

GameSetCameraFree

GameSetCameraFree( is_free:bool )

GameGetCameraBounds

GameGetCameraBounds() -> x:number,y:number,w:number,h:number

Returns the camera rectangle. This may not be 100% pixel perfect with regards to what you see on the screen. 'x','y' = top left corner of the rectangle.

GameRegenItemAction

GameRegenItemAction( entity_id:int )

GameRegenItemActionsInContainer

GameRegenItemActionsInContainer( entity_id:int )

GameRegenItemActionsInPlayer

GameRegenItemActionsInPlayer( entity_id:int )

GameKillInventoryItem

GameKillInventoryItem( inventory_owner_entity_id:int, item_entity_id:int )

GamePickUpInventoryItem

GamePickUpInventoryItem( who_picks_up_entity_id:int, item_entity_id:int, do_pick_up_effects:bool = true )

GameGetAllInventoryItems

GameGetAllInventoryItems( entity_id:int ) -> {item_entity_id}|nil

Returns all the inventory items that entity_id has. This function was added in the March 11, 2023 Bugfix update.

GameDropAllItems

GameDropAllItems( entity_id:int )

GameDropPlayerInventoryItems

GameDropPlayerInventoryItems( entity_id:int )

GameDestroyInventoryItems

GameDestroyInventoryItems( entity_id:int )

GameIsInventoryOpen

GameIsInventoryOpen() -> bool

GameTriggerGameOver

GameTriggerGameOver()

LoadPixelScene

LoadPixelScene( materials_filename:string, colors_filename:string, x:number, y:number, background_file:string, skip_biome_checks:bool = false, skip_edge_textures:bool = false, color_to_material_table:{string-string} = {}, background_z_index:int = 50 )

LoadBackgroundSprite

LoadBackgroundSprite( background_file:string, x:number, y:number, background_z_index:number = 40.0, check_biome_corners:bool = false )

GameCreateCosmeticParticle

GameCreateCosmeticParticle( material_name:string, x:number, y:number, how_many:int, xvel:number, yvel:number, color:uint32 = 0, lifetime_min:number = 5.0, lifetime_max:number = 10, force_create:bool = true, draw_front:bool = false, collide_with_grid:bool = true, randomize_velocity:bool = true )

This function was added in the March 11, 2023 Bugfix update.

GameCreateCosmeticParticle

GameCreateCosmeticParticle( material_name:string, x:number, y:number, how_many:int, xvel:number, yvel:number, color:uint32 = 0, lifetime_min:number = 5.0, lifetime_max:number = 10, force_create:bool = true, draw_front:bool = false, collide_with_grid:bool = true, randomize_velocity:bool = true, gravity_x:float = 0, gravity_y:float = 100.0 )

gravity_x and gravity_y were added in the June 2, 2023 Beta patch.

GameCreateParticle

GameCreateParticle( material_name:string, x:number, y:number, how_many:int, xvel:number, yvel:number, just_visual:bool, draw_as_long:bool = false, randomize_velocity:bool = true )

This randomize_velocity argument was added in the March 11, 2023 Bugfix update.

GameCreateSpriteForXFrames

GameCreateSpriteForXFrames( filename:string, x:number, y:number, centered:bool = true, sprite_offset_x:number = 0, sprite_offset_y:number = 0, frames:int = 1, emissive:bool = false )

If emissive is true, the sprite is drawn regardless of the fog of war, otherwise the fog of war is respected.

GameShootProjectile

GameShootProjectile( shooter_entity:int, x:number, y:number, target_x:number, target_y:number, projectile_entity:int, send_message:bool = true, verlet_parent_entity:int = 0 )

'shooter_entity' can be 0. Warning: If 'projectile_entity' has PhysicsBodyComponent and ItemComponent, components without the "enabled_in_world" tag will be disabled, as if the entity was thrown by player.

EntityInflictDamage

EntityInflictDamage( entity:int, amount:number, damage_type:string, description:string, ragdoll_fx:string, impulse_x:number, impulse_y:number, entity_who_is_responsible:int = 0, world_pos_x:number = entity_x, world_pos_y:number = entity_y, knockback_force:number = 0 )

For damage_type values, see DAMAGE_TYPES.

EntityIngestMaterial

EntityIngestMaterial( entity:int, material_type:number, amount:number )

Has the same effects that would occur if 'entity' eats 'amount' number of cells of 'material_type' from the game world. Use this instead of directly modifying IngestionComponent values, if possible. Might not work with non-player entities. Use CellFactory_GetType() to convert a material name to material type.

EntityRemoveIngestionStatusEffect

EntityRemoveIngestionStatusEffect( entity:int, status_type_id:string )

EntityAddRandomStains

EntityAddRandomStains( entity:int, material_type:number, amount:number )

Adds random visible stains of 'material_type' to entity. 'amount' controls the number of stain cells added. Does nothing if 'entity' doesn't have a SpriteStainsComponent. Use CellFactory_GetType() to convert a material name to material type.

EntitySetDamageFromMaterial

EntitySetDamageFromMaterial( entity:int, material_name:string, damage:number )

Modifies DamageModelComponents materials_that_damage and materials_how_much_damage variables (and their parsed out data structures)

EntityRefreshSprite

EntityRefreshSprite( entity:int, sprite_component:int )

Immediately refreshes the given SpriteComponent. Might be useful with text sprites if you want them to update more often than once a second.

EntityGetWandCapacity

EntityGetWandCapacity( entity:int ) -> int

Returns the capacity of a wand entity, or 0 if 'entity' doesnt exist.

GamePlayAnimation

GamePlayAnimation( entity_id:int, name:string, priority:int, followup_name:string = "", followup_priority:int = 0 )

Plays animation. Follow up animation ('followup_name') is applied only if 'followup_priority' is given.

GameGetVelocityCompVelocity

GameGetVelocityCompVelocity( entity_id:int ) -> x:number,y:number

GameGetGameEffect

GameGetGameEffect( entity_id:int, game_effect_name:string ) -> component_id:int

See GAME_EFFECTS for game_effect_name.

GameGetGameEffectCount

GameGetGameEffectCount( entity_id:int, game_effect_name:string ) -> int

See GAME_EFFECTS for game_effect_name.

LoadGameEffectEntityTo

LoadGameEffectEntityTo( entity_id:int, game_effect_entity_file:string ) -> effect_entity_id:int

GetGameEffectLoadTo

GetGameEffectLoadTo( entity_id:int, game_effect_name:string, always_load_new:bool ) -> effect_component_id:int,effect_entity_id:int

See GAME_EFFECTS for game_effect_name.

SetPlayerSpawnLocation

SetPlayerSpawnLocation( x:number, y:number )

UnlockItem

UnlockItem( action_id:string )

GameGetPotionColorUint

GameGetPotionColorUint( entity_id:int ) -> uint

EntityGetFirstHitboxCenter

EntityGetFirstHitboxCenter( entity_id:int ) -> (x:number,y:number)|nil

Returns the centroid of first enabled HitboxComponent found in entity, the position of the entity if no hitbox is found, or nil if the entity does not exist. All returned positions are in world coordinates.

Raytrace

Raytrace( x1:number, y1:number, x2:number, y2:number ) -> did_hit:bool,hit_x:number,hit_y:number

Does a raytrace that stops on any cell it hits.

RaytraceSurfaces

RaytraceSurfaces( x1:number, y1:number, x2:number, y2:number ) -> did_hit:bool,hit_x:number,hit_y:number

Does a raytrace that stops on any cell that is not fluid, gas (yes, technically gas is a fluid), or fire.

RaytraceSurfacesAndLiquiform

RaytraceSurfacesAndLiquiform( x1:number, y1:number, x2:number, y2:number ) -> did_hit:bool,hit_x:number,hit_y:number

Does a raytrace that stops on any cell that is not gas or fire.

RaytracePlatforms

RaytracePlatforms( x1:number, y1:number, x2:number, y2:number ) -> did_hit:bool,hit_x:number,hit_y:number

Does a raytrace that stops on any cell a character can stand on.

FindFreePositionForBody

FindFreePositionForBody( ideal_pos_x:number, idea_pos_y:number, velocity_x:number, velocity_y:number, body_radius:number ) -> x:number,y:number

GetSurfaceNormal

GetSurfaceNormal( pos_x:number, pos_y:number, ray_length:number, ray_count:int ) -> found_normal:bool,normal_x:number,normal_y:number,approximate_distance_from_surface:number

DoesWorldExistAt

DoesWorldExistAt( min_x:int, min_y:int, max_x:int, max_y:int ) -> bool

Returns true if the area inside the bounding box defined by the parameters has been streamed in and no pixel scenes are loading in the area.

StringToHerdId

StringToHerdId( herd_name:string ) -> int

HerdIdToString

HerdIdToString( herd_id:int ) -> string

GetHerdRelation

GetHerdRelation( herd_id_a:int, herd_id_b:int ) -> number

EntityGetHerdRelation

EntityGetHerdRelation( entity_a:int, entity_b:int ) -> number

EntityGetHerdRelationSafe

EntityGetHerdRelationSafe( entity_a:int, entity_b:int ) -> number

does not spam errors, but returns 0 if anything fails

PolymorphTableAddEntity

PolymorphTableAddEntity( entity_xml:string, is_rare:bool = false, add_only_one_copy:bool = true )

Adds the entity to the polymorph random table

PolymorphTableRemoveEntity

PolymorphTableRemoveEntity( entity_xml:string, from_common_table:bool = true, from_rare_table:bool = true )

Removes the entity from the polymorph random table

PolymorphTableGet

PolymorphTableGet( bool rare_table = false ) -> {string}

Returns a list of all the entities in the polymorph random table

PolymorphTableSet

PolymorphTableSet( {table_of_xml_entities}, bool rare_table = false )

Set a list of all entities as the polymorph random table

EntityGetClosestWormAttractor

EntityGetClosestWormAttractor( pos_x:number, pos_y:number ) -> entity_id:int, pos_x:number, pos_y:number

NOTE: entity_id might be NULL, but pos_x and pos_y could still be valid.

EntityGetClosestWormDetractor

EntityGetClosestWormDetractor( pos_x:number, pos_y:number ) -> entity_id:int, pos_x:number, pos_y:number, radius:number

NOTE: entity_id might be NULL, but pos_x and pos_y could still be valid

GamePrint

GamePrint( log_line:string )

GamePrintImportant

GamePrintImportant( title:string, description:string = "", ui_custom_decoration_file:string = "" )

DEBUG_GetMouseWorld

DEBUG_GetMouseWorld() -> x:number,y:number

Returns the x and y coordinates of the mouse cursor in world space. Used by various debug menus and scripts.

DEBUG_MARK

DEBUG_MARK( x:number, y:number, message:string = "", color_r:number = 1, color_g:number = 0, color_b:number = 0 )

GameGetFrameNum

GameGetFrameNum() -> int

GameGetRealWorldTimeSinceStarted

GameGetRealWorldTimeSinceStarted() -> number

InputIsKeyDown

InputIsKeyDown( key_code:int ) -> bool

Debugish function - returns if a key is down, does not depend on state. E.g. player could be in menus or inputting text. See data/scripts/debug/keycodes.lua for the constants

InputIsKeyJustDown

InputIsKeyJustDown( key_code:int ) -> bool

Debugish function - returns if a key is down this frame, does not depend on state. E.g. player could be in menus or inputting text. See data/scripts/debug/keycodes.lua for the constants

InputIsKeyJustUp

InputIsKeyJustUp( key_code:int ) -> bool

Debugish function - returns if a key is up this frame, does not depend on state. E.g. player could be in menus or inputting text. See data/scripts/debug/keycodes.lua for the constants

InputGetMousePosOnScreen

InputGetMousePosOnScreen() -> x:number, y:number

Debugish function - returns raw x, y coordinates of the mouse on screen

InputIsMouseButtonDown

InputIsMouseButtonDown( mouse_button:int ) -> bool

Debugish function - returns if mouse button is down. Does not depend on state. E.g. player could be in menus. See data/scripts/debug/keycodes.lua for the constants

InputIsMouseButtonJustDown

InputIsMouseButtonJustDown( mouse_button:int ) -> bool

Debugish function - returns if mouse button is down. Does not depend on state. E.g. player could be in menus. See data/scripts/debug/keycodes.lua for the constants.

InputIsMouseButtonJustUp

InputIsMouseButtonJustUp( mouse_button:int ) -> bool

Debugish function - returns if mouse button is down. Does not depend on state. E.g. player could be in menus. See data/scripts/debug/keycodes.lua for the constants

IsPlayer

IsPlayer( entity_id:int ) -> bool

IsInvisible

IsInvisible( entity_id:int ) -> bool

GameIsDailyRun

GameIsDailyRun() -> bool

GameIsDailyRunOrDailyPracticeRun

GameIsDailyRunOrDailyPracticeRun() -> bool

GameIsModeFullyDeterministic

GameIsModeFullyDeterministic() -> bool

GlobalsSetValue

GlobalsSetValue( key:string, value:string )

GlobalsGetValue

GlobalsGetValue( key:string, default_value:string = "" )

MagicNumbersGetValue

MagicNumbersGetValue( key:string ) -> string

SetWorldSeed

SetWorldSeed( new_seed:int )

SessionNumbersGetValue

SessionNumbersGetValue( key:string ) -> string

The possible keys are listed on Documentation:_SessionNumbers.

SessionNumbersSetValue

SessionNumbersSetValue( key:string, value:string )

The possible keys are listed on Documentation:_SessionNumbers.

SessionNumbersSave

SessionNumbersSave()

AutosaveDisable

AutosaveDisable()

StatsGetValue

StatsGetValue( key:string ) -> string|nil

Retrieves a statistics value for the current run. The possible keys are listed on Documentation:_GameStats. More examples can be found in your "AppData\LocalLow\Nolla_Games_Noita\save##\stats\sessions\*.xml" files as attributes of the `<stats>` tag.

Note: "killed_by" will be in the format "[origin] | [cause]", for example: "Minä | slice" or " | explosion".

Example:

	local raw_death_msg = StatsGetValue("killed_by")
	local origin, cause = string.match(raw_death_msg, "(.*) | (.*)")

StatsGlobalGetValue

StatsGlobalGetValue( key:string ) -> string

The possible keys are listed on Documentation:_GameStats.

StatsBiomeGetValue

StatsBiomeGetValue( key:string ) -> string

Works the same as StatsGetValue, the difference is that StatsBiomeGetValue() tracks the stats diff since calling StatsResetBiome().

StatsBiomeReset

StatsBiomeReset()

StatsLogPlayerKill

StatsLogPlayerKill( killed_entity_id:int = 0 )

CreateItemActionEntity

CreateItemActionEntity( action_id:string, x:number = 0, y:number = 0 ) -> entity_id:int

GetRandomActionWithType

GetRandomActionWithType( x:number, y:number, max_level:int, type:int, i:int = 0 ) -> string

GetRandomAction

GetRandomAction( x:number, y:number, max_level:number, i:int = 0) -> string

GameGetDateAndTimeUTC

GameGetDateAndTimeUTC() -> year:int,month:int,day:int,hour:int,minute:int,second:int

GameGetDateAndTimeLocal

GameGetDateAndTimeLocal() ->year:int,month:int,day:int,hour:int,minute:int,second:int,jussi:bool

The jussi boolean tells you whether it's currently the midsummer holiday. This return value is not documented in the lua_api_documentation.txt file that comes with Noita, probably to obscure the holiday easter egg.

GameEmitRainParticles

GameEmitRainParticles( num_particles:int, width_outside_camera:number, material_name:string, velocity_min:number, velocity_max:number, gravity:number, droplets_bounce:bool, draw_as_long:bool )

This function is used to create weather precipitation in the game world. It must be called every update to continue the effect. The particle material used will remain in the game world once it has contacted a surface.

num_particles: The number of particles to emit. Snow is between 1 and 4, light rain is between 4 and 7, and heavy rain is between 10 and 15.
width_outside_camera: The width of the particle emitter outside the camera's view.
material_name: The name of the material to use for the particles. Must be a valid material name.
velocity_min: The minimum velocity of the particles.
velocity_max: The maximum velocity of the particles.
gravity: The gravity to apply to the particles. Snow is set to 10 while rain is set to 200.
droplets_bounce: Whether or not the droplets should bounce off surfaces. If set to true, the droplets will bounce off surfaces like raindrops. If set to false, the droplets will land on surfaces like snowflakes.
draw_as_long: Whether or not the particles should be drawn as elongated streaks to simulate rain. If set to true, the particles will be drawn as elongated streaks. If set to false, the particles will be drawn as small dots.

The velocity_min and velocity_max parameters control the range of velocity values for the particles. A higher range will result in faster particles. Snow has a range of 30-60 while rain has a range of 200-220.

GameCutThroughWorldVertical

GameCutThroughWorldVertical( x:int, y_min:int, y_max:int, radius:number, edge_darkening_width:number )

Each beam adds a little overhead to things like chunk creation, so please call this sparingly.

BiomeMapGetVerticalPositionInsideBiome

BiomeMapGetVerticalPositionInsideBiome( x:number, y:number ) -> number

BiomeMapGetName

BiomeMapGetName( x:number = camera_x, y:number = camera_y ) -> name

Return the name of the biome. As a general rule, the biome's name will be in the format $biome_[biome name]. For example, it will return $biome_snowcastle for the Hiisi Base (snowcastle.xml).

Return _EMPTY_ for the surface.

SetRandomSeed

SetRandomSeed( x:number, y:number )

Sets the current seed of the random number generator, so that for the same input you get the same sequence every time.

Random

Random( a:int = optional, b:int = optional ) -> number|int.

This is kinda messy. If given 0 arguments, returns number between 0.0 and 1.0. If given 1 arguments, returns int between 0 and 'a'. If given 2 arguments returns int between 'a' and 'b'.

Randomf

Randomf( min:number = optional, max:number = optional ) -> number

This is kinda messy. If given 0 arguments, returns number between 0.0 and 1.0. If given 1 arguments, returns number between 0.0 and 'a'. If given 2 arguments returns number between 'a' and 'b'.

RandomDistribution

RandomDistribution( min:int, max:int, mean:int, sharpness:number = 1, baseline:number = 0.005 ) -> int

RandomDistributionf

RandomDistributionf( min:number, max:number, mean:number, sharpness:number = 1, baseline:number = 0.005 ) -> number

ProceduralRandom

ProceduralRandom( x:number, y:number, a:int|number = optional, b:int|number = optional ) -> int|number

This is kinda messy. If given 2 arguments, returns number between 0.0 and 1.0. If given 3 arguments, returns int between 0 and 'a'. If given 4 arguments returns number between 'a' and 'b'.

ProceduralRandomf

ProceduralRandomf( x:number, y:number, a:number = optional, b:number = optional ) -> number

This is kinda messy. If given 2 arguments, returns number between 0.0 and 1.0. If given 3 arguments, returns a number between 0 and 'a'. If given 4 arguments returns a number between 'a' and 'b'.

ProceduralRandomi

ProceduralRandomi( x:number, y:number, a:int = optional, b:int = optional ) -> number

This is kinda messy. If given 2 arguments, returns 0 or 1. If given 3 arguments, returns an int between 0 and 'a'. If given 4 arguments returns an int between 'a' and 'b'.

PhysicsAddBodyImage

PhysicsAddBodyImage( entity_id:int, image_file:string, material:string = "", offset_x:number = 0, offset_y:number = 0, centered:bool = false, is_circle:bool = false, material_image_file:string = "", use_image_as_colors:bool = true ) -> int_body_id

Does not work with PhysicsBody2Component. Returns the id of the created physics body.

PhysicsAddBodyCreateBox

PhysicsAddBodyCreateBox( entity_id:int, material:string, offset_x:number, offset_y:number, width:int, height:int, centered:bool = false ) -> int|nil

Does not work with PhysicsBody2Component. Returns the id of the created physics body.

PhysicsAddJoint

PhysicsAddJoint( entity_id:int, body_id0:int, body_id1:int, offset_x:number, offset_y:number, joint_type:string ) -> int|nil

Does not work with PhysicsBody2Component. Returns the id of the created joint.

For joint_type values, see JOINT_TYPE.

PhysicsApplyForce

PhysicsApplyForce( entity_id:int, force_x:number, force_y:number )

PhysicsApplyTorque

PhysicsApplyTorque( entity_id:int, torque:number )

PhysicsApplyTorqueToComponent

PhysicsApplyTorqueToComponent( entity_id:int, component_id:int, torque:number )

PhysicsApplyForceOnArea

PhysicsApplyForceOnArea( calculate_force_for_body_fn:function, ignore_this_entity:int, area_min_x:number, area_min_y:number,area_max_x:number, area_max_y:number )

Applies a force calculated by 'calculate_force_for_body_fn' to all bodies in an area. 'calculate_force_for_body_fn' should be a lua function with the following signature:

function( body_entity:int, body_mass:number, body_x:number, body_y:number, body_vel_x:number, body_vel_y:number, body_vel_angular:number ) -> force_world_pos_x:number,force_world_pos_y:number,force_x:number,force_y:number,force_angular:number

PhysicsRemoveJoints

PhysicsRemoveJoints( world_pos_min_x:number, world_pos_min_y:number, world_pos_max_x:number, world_pos_max_y:number )

PhysicsSetStatic

PhysicsSetStatic( entity_id:int, is_static:bool )

PhysicsGetComponentVelocity

PhysicsGetComponentVelocity( entity_id:int, component_id:int ) -> vel_x:number,vel_y:number

PhysicsGetComponentAngularVelocity

PhysicsGetComponentAngularVelocity( entity_id:int, component_id:int ) -> vel:number

PhysicsBody2InitFromComponents

PhysicsBody2InitFromComponents( entity_id:int )

PhysicsVecToGameVec

PhysicsVecToGameVec( x:number, y:number = 0 ) -> x:number,y:number

GameVecToPhysicsVec

GameVecToPhysicsVec( x:number, y:number = 0 ) -> x:number,y:number

LooseChunk

LooseChunk( world_pos_x:number, world_pos_y:number, image_filename:string, max_durability:int = 2147483647 )

AddFlagPersistent

AddFlagPersistent( key:string ) -> bool_is_new

RemoveFlagPersistent

RemoveFlagPersistent( key:string )

HasFlagPersistent

HasFlagPersistent( key:string ) -> bool

GameAddFlagRun

GameAddFlagRun( flag:string )

Adds a run flag if it's not yet set, else it does nothing.

This function does nothing if it's called before the world is initialised (see OnWorldInitialized).

GameRemoveFlagRun

GameRemoveFlagRun( flag:string )

Removes the run flag if it's set, else it does nothing.

This function does nothing if it's called before the world is initialised (see OnWorldInitialized).

GameHasFlagRun

GameHasFlagRun( flag:string ) -> bool

Returns true if the run flag is set.

This function returns false if it's called before the world is initialised (see OnWorldInitialized).

You can get all set flags at once by reading WorldStateComponent:flags.

GameTriggerMusicEvent

GameTriggerMusicEvent( event_path:string, can_be_faded:bool, x:number, y:number )

GameTriggerMusicCue

GameTriggerMusicCue( name:string )

GameTriggerMusicFadeOutAndDequeueAll

GameTriggerMusicFadeOutAndDequeueAll( relative_fade_speed:number = 1 )

GamePlaySound

GamePlaySound( bank_filename:string, event_path:string, x:number, y:number )

GameEntityPlaySound

GameEntityPlaySound( entity_id:int, event_name:string )

Plays a sound through all AudioComponents with matching sound in 'entity_id'.

GameEntityPlaySoundLoop

GameEntityPlaySoundLoop( entity:int, component_tag:string, intensity:number )

Plays a sound loop through an AudioLoopComponent tagged with 'component_tag' in 'entity'. 'intensity' affects the intensity passed to the audio event. Must be called every frame when the sound should play.

GameSetPostFxParameter

GameSetPostFxParameter( name:string, x:number, y:number, z:number, w:number )

Can be used to pass custom parameters to the post_final shader, or override values set by the game code. The shader uniform called 'name' will be set to the latest given values on this and following frames.

GameUnsetPostFxParameter

GameUnsetPostFxParameter( name:string )

Will remove a post_final shader parameter value binding set via game GameSetPostFxParameter().

GameTextGetTranslatedOrNot

GameTextGetTranslatedOrNot( text_or_key:string ) -> string

Retrieves a translation by key if the string starts with a dollar sign, or echoes the text that was passed in. If using a translation key it must start with a dollar sign.

A blank string is returned if

The translation key doesn't exist.
If the translation expects params.
The string passed in is blank or nil.

The original text is returned if the string does not start with a dollar sign.

GameTextGet

GameTextGet( key:string, param0:string = "", param1:string = "", param2:string = "" ) -> string

Retrieves a translation by key with optional arguments to be used in the translation. The translation key must start with a dollar sign.

A blank string is returned if

The translation key doesn't exist.
If the translation expects params but none were given.
The translation key does not begin with '$'.

The two-letter language code is returned if 'key' is a single character. The game crashes if 'key' is nil or a blank string.

For example to retrieve a cause of death message: GameTextGet("$menugameover_causeofdeath_killer_cause", "Wiki", "editing") returns "Wiki's editing" for English or "editing de Wiki" for French.

GuiCreate

GuiCreate() -> gui:obj

GuiDestroy

GuiDestroy( gui:obj )

GuiStartFrame

GuiStartFrame( gui:obj )

GuiOptionsAdd

GuiOptionsAdd( gui:obj, option:int )

Sets the options that apply to widgets during this frame. For 'option' use the values in the GUI_OPTION table in "data/scripts/lib/utilities.lua". Values from consecutive calls will be combined. For example calling this with the values GUI_OPTION.Align_Left and GUI_OPTION.GamepadDefaultWidget will set both options for the next widget. The options will be cleared on next call to GuiStartFrame().

GuiOptionsRemove

GuiOptionsRemove( gui:obj, option:int )

Sets the options that apply to widgets during this frame. For 'option' use the values in the GUI_OPTION table in "data/scripts/lib/utilities.lua". Values from consecutive calls will be combined. For example calling this with the values GUI_OPTION.Align_Left and GUI_OPTION.GamepadDefaultWidget will set both options for the next widget. The options will be cleared on next call to GuiStartFrame().

GuiOptionsClear

GuiOptionsClear( gui:obj )

Clears the options that apply to widgets during this frame.

GuiOptionsAddForNextWidget

GuiOptionsAddForNextWidget( gui:obj, option:int )

Sets the options that apply to the next widget during this frame. For 'option' use the values in the GUI_OPTION table in "data/scripts/lib/utilities.lua". Values from consecutive calls will be combined. For example calling this with the values GUI_OPTION.Align_Left and GUI_OPTION.GamepadDefaultWidget will set both options for the next widget

GuiColorSetForNextWidget

GuiColorSetForNextWidget( gui:obj, red:number, green:number, blue:number, alpha:number )

Sets the color of the next widget during this frame. Color components should be in the 0-1 range.

GuiZSet

GuiZSet( gui:obj, z:float )

Sets the rendering depth ('z') of the widgets following this call. Larger z = deeper. The z will be set to 0 on the next call to GuiStartFrame().

GuiZSetForNextWidget

GuiZSetForNextWidget( gui:obj, z:float )

Sets the rendering depth ('z') of the next widget following this call. Larger z = deeper.

GuiIdPush

GuiIdPush( gui:obj, id:int )

Can be used to solve ID conflicts. All ids given to Gui* functions will be hashed with the ids stacked (and hashed together) using GuiIdPush() and GuiIdPop(). The id stack has a max size of 1024, and calls to the function will do nothing if the size is exceeded.

GuiIdPushString

GuiIdPushString( gui:obj, str:string )

Pushes the hash of 'str' as a gui id. See GuiIdPush().

GuiIdPop

GuiIdPop( gui:obj )

See GuiIdPush().

GuiAnimateBegin

GuiAnimateBegin( gui:obj )

Starts a scope where animations initiated using GuiAnimateAlphaFadeIn() etc. will be applied to all widgets.

GuiAnimateEnd

GuiAnimateEnd( gui:obj )

Ends a scope where animations initiated using GuiAnimateAlphaFadeIn() etc. will be applied to all widgets.

GuiAnimateAlphaFadeIn

GuiAnimateAlphaFadeIn( gui:obj, id:int, speed:number, step:number, reset:bool )

Does an alpha tween animation for all widgets inside a scope set using GuiAnimateBegin() and GuiAnimateEnd().

GuiAnimateScaleIn

GuiAnimateScaleIn( gui:obj, id:int, acceleration:number, reset:bool )

Does a scale tween animation for all widgets inside a scope set using GuiAnimateBegin() and GuiAnimateEnd().

GuiText

GuiText( gui:obj, x:number, y:number, text:string )

GuiImage

GuiImage( gui:obj, id:int, x:number, y:number, sprite_filename:string, alpha:number = 1, scale:number = 1, scale_y:number = 0, rotation:number = 0, rect_animation_playback_type:int = GUI_RECT_ANIMATION_PLAYBACK.PlayToEndAndHide, rect_animation_name:string = "" )

'scale' will be used for 'scale_y' if 'scale_y' equals 0.

GuiImageNinePiece

GuiImageNinePiece( gui:obj, id:int, x:number, y:number, width:number, height:number, alpha:number = 1, sprite_filename:string = "data/ui_gfx/decorations/9piece0_gray.png", sprite_highlight_filename:string = "data/ui_gfx/decorations/9piece0_gray.png" )

GuiButton

GuiButton( gui:obj, id:int, x:number, y:number, text:string ) -> clicked:bool,right_clicked:bool

The old parameter order where 'id' is the last parameter is still supported. The function dynamically picks the correct order based on the type of the 4th parameter.

GuiImageButton

GuiImageButton( gui:obj, id:int, x:number, y:number, text:string, sprite_filename:string ) -> clicked:bool,right_clicked:bool

GuiSlider

GuiSlider( gui:obj, id:int, x:number, y:number, text:string, value:number, value_min:number, value_max:number, value_default:number, value_display_multiplier:number, value_formatting:string, width:number ) -> new_value:number

This is not intended to be outside mod settings menu, and might bug elsewhere.

GuiTextInput

GuiTextInput( gui:obj, id:int, x:number, y:number, text:string, width:number, max_length:int, allowed_characters:string = "" ) -> new_text

'allowed_characters' should consist only of ASCII characters. This is not intended to be outside mod settings menu, and might bug elsewhere.

GuiBeginAutoBox

GuiBeginAutoBox( gui:obj )

Together with GuiEndAutoBoxNinePiece() this can be used to draw an auto-scaled background box for a bunch of widgets rendered between the calls.

GuiEndAutoBoxNinePiece

GuiEndAutoBoxNinePiece( gui:obj, margin:number = 5, size_min_x:number = 0, size_min_y:number = 0, mirrorize_over_x_axis:bool = false, x_axis:number = 0, sprite_filename:string = "data/ui_gfx/decorations/9piece0_gray.png", sprite_highlight_filename:string = "data/ui_gfx/decorations/9piece0_gray.png" )

GuiTooltip

GuiTooltip( gui:obj, text:string, description:string )

GuiBeginScrollContainer

GuiBeginScrollContainer( gui:obj, id:int, x:number, y:number, width:number, height:number, scrollbar_gamepad_focusable:bool = true, margin_x:number = 2, margin_y:number = 2 )

This can be used to create a container with a vertical scroll bar. Widgets between GuiBeginScrollContainer() and GuiEndScrollContainer() will be positioned relative to the container.

GuiEndScrollContainer

GuiEndScrollContainer( gui:obj )

See GuiBeginScrollContainer().

GuiLayoutBeginHorizontal

GuiLayoutBeginHorizontal( gui:obj, x:number, y:number, position_in_ui_scale:bool = false, margin_x:number = 2, margin_y:number = 2 )

If 'position_in_ui_scale' is 1, x and y will be in the same scale as other gui positions, otherwise x and y are given as a percentage (0-100) of the gui screen size.

GuiLayoutBeginVertical

GuiLayoutBeginVertical( gui:obj, x:number, y:number, position_in_ui_scale:bool = false, margin_x:number = 0, margin_y:number = 0 )

If 'position_in_ui_scale' is 1, x and y will be in the same scale as other gui positions, otherwise x and y are given as a percentage (0-100) of the gui screen size.

GuiLayoutAddHorizontalSpacing

GuiLayoutAddHorizontalSpacing( gui:obj, amount:number = optional )

Will use the horizontal margin from current layout if amount is not set.

GuiLayoutAddVerticalSpacing

GuiLayoutAddVerticalSpacing( gui:obj, amount:number = optional )

Will use the vertical margin from current layout if amount is not set.

GuiLayoutEnd

GuiLayoutEnd( gui:obj )

GuiLayoutBeginLayer

GuiLayoutBeginLayer( gui:obj )

Puts following things to a new layout layer. Can be used to create non-layouted widgets inside a layout.

GuiLayoutEndLayer

GuiLayoutEndLayer( gui:obj )

GuiGetScreenDimensions

GuiGetScreenDimensions( gui:obj ) -> width:number,height:number

Returns dimensions of viewport in the gui coordinate system (which is equal to the coordinates of the screen bottom right corner in gui coordinates). The values returned may change depending on the game resolution because the UI is scaled for pixel-perfect text rendering.

GuiGetTextDimensions

GuiGetTextDimensions( gui:obj, text:string, scale:number = 1, line_spacing:number = 2 ) -> width:number,height:number

Returns size of the given text in the gui coordinate system.

GuiGetImageDimensions

GuiGetImageDimensions( gui:obj, image_filename:string, scale:number = 1 ) -> width:number,height:number

Returns size of the given image in the gui coordinate system.

GuiGetPreviousWidgetInfo

GuiGetPreviousWidgetInfo( gui:obj ) -> clicked:bool, right_clicked:bool, hovered:bool, x:number, y:number, width:number, height:number, draw_x:number, draw_y:number, draw_width:number, draw_height:number

Returns the final position, size etc calculated for a widget. Some values aren't supported by all widgets.

GameIsBetaBuild

GameIsBetaBuild() -> bool

DebugGetIsDevBuild

DebugGetIsDevBuild() -> bool

DebugEnableTrailerMode

DebugEnableTrailerMode()

GameGetIsTrailerModeEnabled

GameGetIsTrailerModeEnabled() -> bool

Debug_SaveTestPlayer

Debug_SaveTestPlayer()

This doesn't do anything at the moment.

DebugBiomeMapGetFilename

DebugBiomeMapGetFilename( x:number = camera_x, y:number = camera_y ) -> string

EntityConvertToMaterial

EntityConvertToMaterial( entity_id:int, material:string )

ConvertEverythingToGold

ConvertEverythingToGold( material_dynamic:string = "", material_static:string = "" )

ConvertMaterialEverywhere

ConvertMaterialEverywhere( material_from_type:int, material_to_type:int )

Converts 'material_from' to 'material_to' everwhere in the game world, replaces 'material_from_type' to 'material_to_type' in the material (CellData) global table, and marks 'material_from' as a "Transformed" material. Every call will add a new entry to WorldStateComponent which serializes these changes, so please call sparingly. The material conversion will be spread over multiple frames. 'material_from' will still retain the original name id and wang color. Use CellFactory_GetType() to convert a material name to material type.

ConvertMaterialOnAreaInstantly

ConvertMaterialOnAreaInstantly( area_x:int, area_y:int, area_w:int, area_h:int, material_from_type:int, material_to_type:int, trim_box2d:bool, update_edge_graphics_dummy:bool )

Converts cells of 'material_from_type' to 'material_to_type' in the given area. If 'box2d_trim' is true, will attempt to trim the created cells where they might otherwise cause physics glitching. 'update_edge_graphics_dummy' is not yet supported.

LoadRagdoll

LoadRagdoll( filename:string, pos_x:float, pos_y:float, material:string ="meat", scale_x:float=1, impulse_x:float=0, impulse_y:float=0 )

Loads a given .txt file as a ragdoll into the game, made of the material given in material.

GetDailyPracticeRunSeed

GetDailyPracticeRunSeed() -> int

ModIsEnabled

ModIsEnabled( mod_id:string ) -> bool

Returns true if a mod with the id 'mod_id' is currently active. For example mod_id = "nightmare".

ModGetActiveModIDs

ModGetActiveModIDs() -> {string}

Returns a table filled with the IDs of currently active mods. The IDs are ordered by the mod load order.

ModGetAPIVersion

ModGetAPIVersion() -> int

ModSettingGet

ModSettingGet( id:string ) -> bool|number|string|nil

Returns the value of a mod setting. 'id' should normally be in the format 'mod_name.setting_id'. Cache the returned value in your lua context if possible.

ModSettingSet

ModSettingSet( id:string, value:bool|number|string )

Sets the value of a mod setting. 'id' should normally be in the format 'mod_name.setting_id'.

ModSettingGetNextValue

ModSettingGetNextValue( id:string ) -> bool|number|string|nil

Returns the latest value set by the user, which might not be equal to the value that is used in the game (depending on the 'scope' value selected for the setting).

ModSettingSetNextValue

ModSettingSetNextValue( id:string, value:bool|number|string, is_default:bool )

Sets the latest value set by the user, which might not be equal to the value that is displayed to the game (depending on the 'scope' value selected for the setting).

ModSettingRemove

ModSettingRemove( id:string ) -> was_removed:bool

ModSettingGetCount

ModSettingGetCount() -> int

Returns the number of mod settings defined. Use ModSettingGetAtIndex to enumerate the settings.

ModSettingGetAtIndex

'index' should be 0-based index. Returns nil if 'index' is invalid.

StreamingGetIsConnected

StreamingGetIsConnected() -> bool

StreamingGetConnectedChannelName

StreamingGetConnectedChannelName() -> string

StreamingGetVotingCycleDurationFrames

StreamingGetVotingCycleDurationFrames() -> int

StreamingGetRandomViewerName

StreamingGetRandomViewerName() -> string

Returns the name of a random stream viewer who recently sent a chat message. Returns "" if the 'Creatures can be named after viewers' setting is off.

StreamingGetSettingsGhostsNamedAfterViewers

StreamingGetSettingsGhostsNamedAfterViewers() -> bool

StreamingSetCustomPhaseDurations

StreamingSetCustomPhaseDurations( time_between_votes_seconds:number, time_voting_seconds:number )

Sets the duration of the next wait and voting phases. Use -1 for default duration.

StreamingForceNewVoting

StreamingForceNewVoting()

Cancels whatever is currently going on, and starts a new voting. _streaming_on_vote_start() and _streaming_get_event_for_vote() will be called as usually.

StreamingSetVotingEnabled

StreamingSetVotingEnabled( enabled:bool )

Turns the voting UI on or off.

SetValueNumber

SetValueNumber( key:string, value:number )

GetValueNumber

GetValueNumber( key:string, default_value:number ) -> number

SetValueInteger

SetValueInteger( key:string, value:int )

GetValueInteger

GetValueInteger( key:string, default_value:int ) -> int

SetValueBool

SetValueBool( key:string, value:number )

GetValueBool

GetValueBool( key:string, default_value:number ) -> bool