Current modding API version: 4

lua_readtable()
EntityLoad( filename, [optional]pos_x, [optional]pos_y ) -> entity_id
EntityLoadCameraBound( filename, [optional]pos_x, [optional]pos_y )
EntityLoadToEntity( filename, entity ) [Loads components from 'filename' to
'entity'. Does not load tags and other stuff.]
EntitySave( entity_id, filename ) (note: works only in dev builds)
EntityCreateNew( [optional]name ) -> entity_id
EntityKill( entity_id )
EntityGetIsAlive( entity_id ) -> bool
EntityAddComponent( entity_id, component_type_name,
[optional]table_of_component_values ) -> component_id
EntityRemoveComponent( entity_id, component_id )
EntityGetAllComponents( entity_id ) -> {component_id}
EntityGetComponent( entity_id, component_type_name, [optional]tag ) ->
{component_id}|nil
EntityGetFirstComponent( entity_id, component_type_name, [optional]tag ) ->
component_id|nil
EntityGetComponentIncludingDisabled( entity_id, component_type_name,
[optional]tag ) -> {component_id}|nil
EntityGetFirstComponentIncludingDisabled( entity_id, component_type_name,
[optional]tag ) -> component_id|nil
EntitySetTransform( entity_id, x, [optional]y, [optional]rotation,
[optional]scale_x, [optional]scale_y )
EntityApplyTransform( entity_id, x, [optional]y, [optional]rotation,
[optional]scale_x, [optional]scale_y ) [Some components store old positions (and
calculates the new one based on those). This tries to refresh those.]
EntityGetTransform( entity_id ) -> x,y,rotation,scale_x,scale_y
EntityAddChild( parent_id, child_id )
EntityGetAllChildren( entity_id ) -> {entity_id}|nil
EntityGetParent( entity_id ) -> entity_id
EntityGetRootEntity( entity_id ) -> entity_id [returns the given entity if it has
no parent, otherwise walks up the parent hierarchy to the highest parent and
returns it]
EntityRemoveFromParent( entity_id )
EntitySetComponentsWithTagEnabled( entity_id, tag, enabled )
EntitySetComponentIsEnabled( entity_id, component_id, is_enabled )
EntityGetName( entity_id ) -> string
EntitySetName( entity_id, name )
EntityGetTags( entity_id ) -> string|nil [string is comma separated]
EntityGetWithTag( entity_tag ) -> {entity_id}
EntityGetInRadius( pos_x, pos_y, radius ) -> {entity_id}
EntityGetInRadiusWithTag( pos_x, pos_y, radius, entity_tag ) -> {entity_id}
EntityGetClosest( pos_x, pos_y ) -> entity_id
EntityGetClosestWithTag( pos_x, pos_y, string tag ) -> entity_id
EntityGetWithName( name ) -> entity_id
EntityAddTag( entity_id, tag )
EntityRemoveTag( entity_id, tag )
EntityHasTag( entity_id, tag ) -> bool
ComponentGetValue( component_id, variable_name ) -> string|nil [Deprecated, use
ComponentGetValue2() instead.]
ComponentGetValueBool( component_id, variable_name ) -> bool [Deprecated, use
ComponentGetValue2() instead.]
ComponentGetValueInt( component_id, variable_name ) -> int [Deprecated, use
ComponentGetValue2() instead.]
ComponentGetValueFloat( component_id, variable_name ) -> number [Deprecated, use
ComponentGetValue2() instead.]
ComponentGetValueVector2( component_id, variable_name ) -> x,y [Deprecated, use
ComponentGetValue2() instead.]
ComponentSetValue( component_id, variable_name, value ) [Deprecated, use
ComponentSetValue2() instead.]
ComponentSetValueVector2( component_id, variable_name, x, y ) [Deprecated, use
ComponentSetValue2() instead.]
ComponentSetValueValueRange( component_id, variable_name, min, max ) [Deprecated,
use ComponentSetValue2() instead.]
ComponentSetValueValueRangeInt( component_id, variable_name, min, max )
[Deprecated, use ComponentSetValue2() instead.]
ComponentSetMetaCustom( component_id, variable_name, value ) [Deprecated, use
ComponentSetValue2() instead.]
ComponentGetMetaCustom( component_id, variable_name ) -> string|nil [Deprecated,
use ComponentGetValue2() instead.]
ComponentObjectGetValue( component_id, object_name, variable_name ) -> string|nil
[Deprecated, use ComponentObjectGetValue2() instead.]
ComponentObjectGetValueBool( component_id, object_name, variable_name ) -> string|
nil [Deprecated, use ComponentObjectGetValue2() instead.]
ComponentObjectGetValueInt( component_id, object_name, variable_name ) -> string|
nil [Deprecated, use ComponentObjectGetValue2() instead.]
ComponentObjectGetValueFloat( component_id, object_name, variable_name ) -> string|
nil [Deprecated, use ComponentObjectGetValue2() instead.]
ComponentObjectSetValue( component_id, object_name, variable_name, value )
[Deprecated, use ComponentObjectSetValue2() instead.]
ComponentGetValue2( component_id, field_name ) -> 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( component_id, field_name, value(s) ) [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( component_id, object_name, field_name ) -> 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( component_id, object_name, field_name, value(s) ) [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( entity_id, component_type_name,
[optional]table_of_component_values ) -> component_id [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. Returns the created
component, if creation succeeded, or nil.
ComponentGetVectorSize( component_id, array_member_name, type_of_vector ) -> int
ComponentGetVectorValue( component_id, array_name, type, i ) -> multiple return
types|nil
ComponentGetVector( component_id, array_name, type ) -> {multiple types}|nil
ComponentGetIsEnabled( component_id ) -> bool [Returns true if the given component
exists and is enabled, else false.]
ComponentGetMembers( component_id ) -> {string-string} [returns a string-indexed
table of string]
ComponentObjectGetMembers( component_id, object_name ) -> {string-string}|nil
[returns a string-indexed table of string]
ComponentGetTypeName( component_id ) -> string
GetUpdatedEntityID() -> entity_id
GetUpdatedComponentID() -> component_id
SetTimeOut( time_to_execute:number, file_to_execute:string, function_to_call:string
= nil )
RegisterSpawnFunction( uint32 color, string function_name )
SpawnActionItem( x, y, level )
SpawnStash( x, y, level, action_count ) -> entity_id
SpawnApparition( x, y, level ) -> int,entity_id
LoadEntityToStash( entity_file, stash_id )
AddMaterialInventoryMaterial( entity_id, material_name, count )
GameScreenshake( strength, [optional]pos_x, [optional]pos_y )
GameOnCompleted()
GameDoEnding2()
BiomeMapLoad_KeepPlayer( filename, pixel_scenes = 'data/biome/_pixel_scenes.xml' )
BiomeMapLoad( filename )
BiomeSetValue( filename, field_name, value ) [Can be used to edit biome configs
during mod initialization. See the nightmare mod for an usage example.]
BiomeGetValue( filename, field_name ) -> multiple types|nil [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.]
GameIsIntroPlaying() -> bool
GameGetIsGamepadConnected() -> bool
GameGetWorldStateEntity() -> entity_id
GameGetPlayerStatsEntity() -> entity_id
GameGetOrbCountAllTime() -> int
GameGetOrbCountThisRun() -> int
GameGetOrbCollectedThisRun( int orb_id_zero_based ) -> bool
GameGetOrbCollectedAllTime( int orb_id_zero_based ) -> bool
GameClearOrbsFoundThisRun()
CellFactory_GetName( int material_id ) -> string
CellFactory_GetType( string material_name ) -> int
CellFactory_GetAllLiquids( include_statics = true ) -> {string}
CellFactory_GetAllSands( include_statics = true ) -> {string}
CellFactory_GetAllGases( include_statics = true ) -> {string}
CellFactory_GetAllFires( include_statics = true ) -> {string}
CellFactory_GetAllSolids( include_statics = true ) -> {string}
GameGetCameraPos() -> x,y
GameSetCameraPos( x, y )
GameSetCameraFree( is_free )
GameRegenItemAction( entity_id )
GameRegenItemActionsInContainer( entity_id )
GameRegenItemActionsInPlayer( entity_id )
GameKillInventoryItem( inventory_owner_entity_id, item_entity_id )
GameKillInventoryItem( who_picks_up_entity_id, item_entity_id )
GameDropAllItems( entity_id )
GameDropPlayerInventoryItems( entity_id )
GameDestroyInventoryItems( entity_id )
GameTriggerGameOver()
LoadPixelScene( string materials_filename, string colors_filename, x, y, string
background_file, skip_biome_checks = false, skip_edge_textures = false,
color_to_material_table = {}, int background_z_index = 50 )
LoadBackgroundSprite( string background_file, x, y, float background_z_index =
40.0, bool check_biome_corners = false )
GameCreateParticle( string material_name, x, y, how_many, xvel, yvel, just_visual,
[optional]draw_as_long )
GameCreateSpriteForXFrames( string filename, world_x, world_y, bool centered =
true, sprite_offset_x = 0, sprite_offset_y = 0, frames = 1 )
GameShootProjectile( who_shot, x, y, target_x, target_y, projectile_entity,
send_message = true )
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 )
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.]
GamePlayAnimation( entity_id, name, priority, [followup_name],
[followup_priority] )
GameGetVelocityCompVelocity( entity_id ) -> x,y
GameGetGameEffect( entity_id, string GAME_EFFECT ) -> component_id
GameGetGameEffectCount( entity_id, string GAME_EFFECT ) -> uint
SetPlayerSpawnLocation( x, y )
UnlockItem( action_id )
GameGetPotionColorUint( entity_id ) -> uint
EntityGetFirstHitboxCenter( entity_id ) -> 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( x1, y1, x2, y2 ) -> did_hit,hit_x,hit_y [Does a raytrace that stops on
any cell it hits.]
RaytraceSurfaces( x1, y1, x2, y2 ) -> did_hit,hit_x,hit_y [Does a raytrace that
stops on any cell that is not fluid, gas (yes, technically gas is a fluid), or
fire.]
RaytraceSurfacesAndLiquiform( x1, y1, x2, y2 ) -> did_hit,hit_x,hit_y [Does a
raytrace that stops on any cell that is not gas or fire.]
RaytracePlatforms( x1, y1, x2, y2 ) -> did_hit,hit_x,hit_y [Does a raytrace that
stops on any cell a character can stand on.]
FindFreePositionForBody( ideal_pos_x, idea_pos_y, velocity_x, velocity_y,
body_radius ) -> x,y
GetSurfaceNormal( pos_x, pos_y, ray_length, ray_count ) ->
found_normal,normal_x,normal_y,approximate_distance_from_surface
DoesWorldExistAt( min_x, min_y, max_x, max_y ) -> 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( herd_name:string ) -> int
HerdIdToString( herd_id:int ) -> string
GetHerdRelation( herd_id_a:int, herd_id_b:int ) -> number
EntityGetHerdRelation( entity_a:int, entity_b:int ) -> number
GenomeSetHerdId( entity_id:int, new_herd_id:string ) [Deprecated, use
GenomeStringToHerdID() and ComponentSetValue2() instead.]
GamePrint( string log_line )
GamePrintImportant( string title, description )
DEBUG_GetMouseWorld() -> x,y
DEBUG_MARK( x, y, string message="", color_r=1, color_g=0, color_b=0 )
GameGetFrameNum() -> int
GameGetRealWorldTimeSinceStarted() -> number
IsPlayer( entity ) -> bool
GameIsDailyRun( entity ) -> bool
GlobalsSetValue( key, value )
GlobalsGetValue( key, default_value = "" )
MagicNumbersGetValue( key ) -> string
SessionNumbersGetValue( key ) -> string
SessionNumbersSetValue( key, value )
SessionNumbersSave()
AutosaveDisable()
StatsGetValue( key ) -> string
StatsBiomeGetValue( key ) -> string
StatsBiomeReset()
StatsLogPlayerKill()
CreateItemActionEntity( action_id, [optional]x, [optional]y ) -> entity_id
GetRandomActionWithType( x, y, max_level, type, i = 0) -> string
GetRandomAction( x, y, max_level, i = 0) -> string
GameGetDateAndTimeUTC() ->
year_int,month_int,day_int,hour_int,minute_int,second_int
GameGetDateAndTimeLocal() ->
year_int,month_int,day_int,hour_int,minute_int,second_int
GameEmitRainParticles( num_particles, width_outside_camera, material_name,
velocity_min, velocity_max, gravity, droplets_bounce, draw_as_long )
BiomeMapSetSize( w, h ) [This is available if BIOME_MAP in magic_numbers.xml points
to a lua file, in the context of that file.]
BiomeMapGetSize() -> w,h [This is available if BIOME_MAP in magic_numbers.xml
points to a lua file, in the context of that file.]
BiomeMapSetPixel( x, y, color_int ) [This is available if BIOME_MAP in
magic_numbers.xml points to a lua file, in the context of that file.]
BiomeMapGetPixel( x, y ) -> color_int [This is available if BIOME_MAP in
magic_numbers.xml points to a lua file, in the context of that file.]
BiomeMapLoadImage( x, y, path ) [This is available if BIOME_MAP in
magic_numbers.xml points to a lua file, in the context of that file.]
BiomeMapLoadImageCropped( x, y, path, image_x, image_y, image_w, image_h ) [This is
available if BIOME_MAP in magic_numbers.xml points to a lua file, in the context of
that file.]
BiomeMapGetVerticalPositionInsideBiome( x, y ) -> number
BiomeMapGetName( [optional]x, [optional]y ) -> name
SetRandomSeed(x,y)
Random( [optional]a, [optional]b ) -> 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( min, max ) -> 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( min, max, mean, (sharpness=1.f), (baseline=0.005) ) -> int
RandomDistributionf( min, max, mean, (sharpness=1.f), (baseline=0.005) ) -> number
ProceduralRandom( x, y, [optional]a, [optional]b ) -> 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( x, y, [optional]a, [optional]b ) -> 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( x, y, [optional]a, [optional]b ) -> 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( entity_id, image_file, material = "", offset_x = 0, offset_y =
0, bool centered = false, bool is_circle = false, material_image_file = "", bool
use_image_as_colors = true ) -> int_body_id [Does not work with
PhysicsBody2Component.]
PhysicsAddBodyCreateBox( entity_id, material, offset_x, offset_y, width, height,
bool centered = false ) -> int_body_id|nil [Does not work with
PhysicsBody2Component.]
PhysicsAddJoint( entity_id, body_id0, body_id1, offset_x, offset_y, string
joint_type ) -> int_joint_id [Does not work with PhysicsBody2Component.]
PhysicsApplyForce( entity_id, float force_x, float force_y )
PhysicsApplyTorque( entity_id, float torque )
PhysicsApplyTorqueToComponent( entity_id, component_id, float torque )
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,for
ce_angular:number
PhysicsRemoveJoints( world_pos_min_x, world_pos_min_y, world_pos_max_x,
world_pos_max_y )
PhysicsSetStatic( entity_id, bool is_static )
PhysicsGetComponentVelocity( entity_id, component_id ) -> vel_x,vel_y
PhysicsGetComponentAngularVelocity( entity_id, component_id ) -> vel
PhysicsBody2InitFromComponents( entity_id )
PhysicsVecToGameVec( x, [optional]y ) -> x,y
GameVecToPhysicsVec( x, [optional]y ) -> x,y
LooseChunk( world_pos_x, world_pos_y, image_filename, [optional] max_durability )
LoadGameEffectEntityTo( entity_id, string game_effect_entity_file ) ->
effect_entity_id
GetGameEffectLoadTo( entity_id, string game_effect_entity_file, always_load_new )
-> effect_component_id
AddFlagPersistent( key ) -> bool_is_new
RemoveFlagPersistent( key )
HasFlagPersistent( key ) -> bool
GameAddFlagRun( flag )
GameRemoveFlagRun( flag )
GameHasFlagRun( flag ) -> bool
GameTriggerMusicEvent( event_path, can_be_faded, x, y )
GameTriggerMusicCue( name )
GameTriggerMusicFadeOutAndDequeueAll( [optional]relative_fade_speed )
GamePlaySound( bank_filename, event_path, x, y )
GameEntityPlaySound( entity, event_name )
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( name:string ) [Will remove a post_final shader parameter
value binding set via game GameSetPostFxParameter().]
GameTextGetTranslatedOrNot( text_or_key ) -> string
GameTextGet( key, [optional] param0, [optional] param1, [optional] param2 ) ->
string
GuiCreate() -> gui
GuiDestroy( gui )
GuiStartFrame( gui )
GuiText( gui, x, y, text )
GuiTextCentered( gui, x, y, text )
GuiButton( gui, x, y, text, id ) -> bool_clicked
GuiLayoutBeginHorizontal( gui, x_rel, y_rel )
GuiLayoutBeginVertical( gui, x_rel, y_rel )
GuiLayoutAddHorizontalSpacing( gui )
GuiLayoutAddVerticalSpacing( gui )
GuiLayoutEnd( gui )
DebugGetIsDevBuild() -> bool
DebugEnableTrailerMode()
GameGetIsTrailerModeEnabled() -> bool
Debug_SaveTestPlayer() [This doesn't do anything at the moment.]
EntityConvertToMaterial( entity_id, string material )
ConvertEverythingToGold()
ModIsEnabled( mod_id ) -> bool [Returns true if a mod with the id 'mod_id' is
currently active. For example mod_id = "nightmare". ]
ModGetActiveModIDs() -> {string} [Returns a table filled with the IDs of currently
active mods.]
ModGetAPIVersion() -> uint
ModLuaFileAppend( to_filename, from_filename ) [Basically calls
dofile(from_filename) at the end of 'to_filename'. Available only during mod
initialization.]
ModTextFileGetContent( filename ) -> string [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( filename, new_content ) [Sets the content the game sees for
the file 'filename'. Allows access only to mod and data files. Available only
during mod initialization.]
ModTextFileWhoSetContent( filename ) -> string [Returns the id of the last mod that
called ModTextFileSetContent with 'filename', or "". Available only during mod
initialization.]
ModMagicNumbersFileAdd( filename ) [Available only during mod initialization.]
ModMaterialsFileAdd( filename ) [Available only during mod initialization.]
ModRegisterAudioEventMappings( filename ) [Available only during mod
initialization.]
ModDevGenerateSpriteUVsForDirectory( directory_path ) [Available only during mod
initialization via noita_dev.exe]
RegisterProjectile( entity_filename )
RegisterGunAction()
RegisterGunShotEffects()
BeginProjectile( entity_filename )
EndProjectile()
BeginTriggerTimer( timeout_frames )
BeginTriggerHitWorld()
BeginTriggerDeath()
EndTrigger()
SetProjectileConfigs()
StartReload( reload_time )
ActionUsesRemainingChanged( inventoryitem_id, uses_remaining )
ActionUsed( inventoryitem_id )
LogAction( action_name )
OnActionPlayed( action_id )
OnNotEnoughManaForAction()
BaabInstruction( name )
SetValueNumber( key, value )
GetValueNumber( key, default_value )
SetValueInteger( key, value )
GetValueInteger( key, default_value )
SetValueBool( key, value )
GetValueBool( key, default_value )
dofile( filename ) -> nil|script_return_type|nil,error_string [Returns the script's
return value, if any. Returns nil,error_string if the script had errors.]
dofile_once( filename ) -> 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.]