Modding: Lua Scripting

Basic info and examples for writing Lua scripts for Noita mods. Note that scripting is only a part of modding, be sure to read about the Entity Component System as well.

Places to hook your scripts

 * The best place to get started.
 * Doesn’t need any overwriting, this is specially unique to your mod.
 * See Modding Basics


 * Called on every wand shot, highly intertwined with the engine code.
 * Note compatibility, as explained below


 * Called once when entering the biome
 * Note compatibility, as explained below


 * Probably the best and most-used place to hook your random code
 * Most everything else that you can find under  is actually defined in some entity via this component.
 * See the official  for a list of how to hook into different actions with this component.

Hooking in a compatible way
When dealing with common scripts used heavily by the game itself and other mods, it might be a good idea to append to it, instead of simply overwriting it via the  path.

When every modder is doing this, their code will get appended in the player's mod loading order, and nothing is forcefully overwritten.

Restricted Libraries
Some of the default Lua libraries are restricted and will not run in the mod files. A incomplete list of restricted libraries and functions:


 * IO
 * OS
 * require

Some of the functionality of these libraries has been reimplemented in the Lua API. Without the IO library, it is far more difficult to save persistent data between runs. The only two ways to store persistent data are by using flags or the    file.

Get the current entity
"Current" means the entity in which your script is running via a  (or other such trigger). Not all scripts are run this way, for example init.lua.

In the above snippet the entity could be player, wand, projectile, anything; depending on where the script is run from. This is the easiest way to fetch the currently running entity, so it deserves a mention.

Bonus: in  this will give you the player entity.

Get player entity
The basic utility script returns a list of player entities, so we have to jump through a small hoop to get just one.

For brevity, the fetching of player entity is left out in subsequent examples. Many hooks expose the player entity already, but this can be used as a backup if they don't.

Run init code only once
ie. only upon starting a new game, not when you load a savegame

Shoot a projectile through Lua
Note that there is also the direct API function, but it requires a few lines of setup, which the included utility function already does for you.