Modding: Lua API

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

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

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

EntitySave

 * Note: works only in dev builds

EntityGetComponent

 * Note: Despite its name, this function actually returns an array, and not a single component.

EntityGetFirstComponent

 * Does not return components that are disabled, effectively "hiding" components that you might actually want.

EntityGetComponentIncludingDisabled

 * Note: Despite its name, this function actually returns an array, and not a single component.

EntityApplyTransform
Some components store old positions (and calculates the new one based on those). This tries to refresh those.

EntityGetRootEntity
returns the given entity if it has no parent, otherwise walks up the parent hierarchy to the highest parent and returns it

EntityGetTags
string is comma separated

ComponentGetValue2
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
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
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
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
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.

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

ComponentGetMembers
returns a string-indexed table of string

ComponentObjectGetMembers
returns a string-indexed table of string

EntityIngestMaterial
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.

EntityAddRandomStains
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
Modifies DamageModelComponents materials_that_damage and materials_how_much_damage variables (and their parsed out data structures)

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

EntityGetFirstHitboxCenter
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
Does a raytrace that stops on any cell it hits.

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

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

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

DoesWorldExistAt
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.

GenomeSetHerdId
Deprecated, use GenomeStringToHerdID and ComponentSetValue2 instead.

Random
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
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'.

ProceduralRandom
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
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
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
Does not work with PhysicsBody2Component.

PhysicsAddBodyCreateBox
Does not work with PhysicsBody2Component.

PhysicsAddJoint
Does not work with PhysicsBody2Component.

PhysicsApplyForceOnArea
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

GameEntityPlaySoundLoop
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
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
Will remove a post_final shader parameter value binding set via game GameSetPostFxParameter.

Debug_SaveTestPlayer
This doesn't do anything at the moment.

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

ModGetActiveModIDs
Returns a table filled with the IDs of currently active mods.

dofile
Returns the script's return value, if any. Returns nil,error_string if the script had errors.

dofile_once
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.

= Available only inside a custom BIOME_MAP =

BiomeMapSetSize
This is available if BIOME_MAP in magic_numbers.xml points to a lua file, in the context of that file.

BiomeMapGetSize
This is available if BIOME_MAP in magic_numbers.xml points to a lua file, in the context of that file.

BiomeMapSetPixel
This is available if BIOME_MAP in magic_numbers.xml points to a lua file, in the context of that file.

BiomeMapGetPixel
This is available if BIOME_MAP in magic_numbers.xml points to a lua file, in the context of that file.

BiomeMapConvertPixelFromUintToInt
To make sense of the BiomeMapGetPixel return values. E.g. if( BiomeMapGetPixel( x, y ) == BiomeMapConvertPixelFromUintToInt( 0xFF36D517 ) ) then print('hills') end

BiomeMapLoadImage
This is available if BIOME_MAP in magic_numbers.xml points to a lua file, in the context of that file.

BiomeMapLoadImageCropped
This is available if BIOME_MAP in magic_numbers.xml points to a lua file, in the context of that file.

= Available only during mod initialization =

ModLuaFileAppend
Basically calls dofile(from_filename) at the end of 'to_filename'. Available only during mod initialization.

ModTextFileGetContent
Returns the current (modded or not) content of the data file 'filename'. Allows access only to data files and files from enabled mods. Available only during mod initialization.

ModTextFileSetContent
Sets the content the game sees for the file 'filename'. Allows access only to mod and data files. Available only during mod initialization.

ModTextFileWhoSetContent
Returns the id of the last mod that called ModTextFileSetContent with 'filename', or "". Available only during mod initialization.

ModMagicNumbersFileAdd
Available only during mod initialization.

ModMaterialsFileAdd
Available only during mod initialization.

ModRegisterAudioEventMappings
Available only during mod initialization.

ModDevGenerateSpriteUVsForDirectory
Available only during mod initialization via noita_dev.exe

BiomeSetValue
Can be used to edit biome configs during initialization. See the nightmare mod for an usage example.

BiomeGetValue
Can be used to read biome configs. 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.

BiomeObjectSetValue
Can be used to edit biome configs during initialization. See biome_modifiers.lua for an usage example.

BiomeVegetationSetValue
Can be used to edit biome config MaterialComponents during initialization. Sets the given value in all found VegetationComponent with matching tree_material. See biome_modifiers.lua for an usage example.

BiomeMaterialSetValue
Can be used to edit biome config MaterialComponents during initialization. Sets the given value in the first found MaterialComponent with matching material_name. See biome_modifiers.lua for an usage example.

BiomeMaterialGetValue
Can be used to read biome config MaterialComponents during initialization. Returns the given value in the first found MaterialComponent with matching material_name. See biome_modifiers.lua for an usage example.

= Available only in data/scripts/gun/gun.lua =

BaabInstruction
= Deprecated =

ComponentGetValue
Deprecated, use ComponentGetValue2 instead.

ComponentGetValueBool
Deprecated, use ComponentGetValue2 instead.

ComponentGetValueInt
Deprecated, use ComponentGetValue2 instead.

ComponentGetValueFloat
Deprecated, use ComponentGetValue2 instead.

ComponentGetValueVector2
Deprecated, use ComponentGetValue2 instead.

ComponentSetValue
Deprecated, use ComponentSetValue2 instead.

ComponentSetValueVector2
Deprecated, use ComponentSetValue2 instead.

ComponentSetValueValueRange
Deprecated, use ComponentSetValue2 instead.

ComponentSetValueValueRangeInt
Deprecated, use ComponentSetValue2 instead.

ComponentSetMetaCustom
Deprecated, use ComponentSetValue2 instead.

ComponentGetMetaCustom
Deprecated, use ComponentGetValue2 instead.

ComponentObjectGetValue
Deprecated, use ComponentObjectGetValue2 instead.

ComponentObjectGetValueBool
Deprecated, use ComponentObjectGetValue2 instead.

ComponentObjectGetValueInt
Deprecated, use ComponentObjectGetValue2 instead.

ComponentObjectGetValueFloat
Deprecated, use ComponentObjectGetValue2 instead.

ComponentObjectSetValue
Deprecated, use ComponentObjectSetValue2 instead.