Modding: Basics

This page aims to briefly go through all the basic concepts of Noita modding: ECS, the directory structure, Lua hooks, etc.

Mod installation locations
The two common mod locations are:


 * - Use this for manually downloaded mods or mod development.
 * - Mods that you've downloaded through Steam Workshop can be found here.

Mod directory structure
This is an example mod, that shows the typical file structure you should follow. myAwesomeMod/ ├── data/ │   └── enemies_gfx/ │      └── player.png ├── files/ │   └── my_custom_script.lua ├── init.lua └── mod.xml

Lets break it down a bit:
 * This is the root folder, the base path of your mod. Choose this carefully, as you will have to reference it all over the code later on. Note that this is not the visible "name" of the mod.
 * This folder follows exactly the same structure as the Noita's data files that we extracted earlier. Use this ONLY when you want to override base assets.
 * A folder that gathers together all enemy & friendly spritesheets
 * The player animation spritesheet (minä, the purple witch). Inside the data/ folder this is directly replacing the base game spritesheet when this mod is activated.
 * This folder is for any and all custom assets/scripts/data you want to include in your mod, should be used when you don't want to directly replace existing assets (ie. almost always)
 * A custom script file, which could be doing literally anything or be called from anywhere. Try to name yours a bit better than this example.
 * The starting point of your mod, includes hooks for post-/pre- world init, player spawn, etc. This is where you should probably start with a "Hello world"
 * The mod metadata definition file, includes the name, description and bunch of other settings.
 * This folder is for any and all custom assets/scripts/data you want to include in your mod, should be used when you don't want to directly replace existing assets (ie. almost always)
 * A custom script file, which could be doing literally anything or be called from anywhere. Try to name yours a bit better than this example.
 * The starting point of your mod, includes hooks for post-/pre- world init, player spawn, etc. This is where you should probably start with a "Hello world"
 * The mod metadata definition file, includes the name, description and bunch of other settings.
 * The starting point of your mod, includes hooks for post-/pre- world init, player spawn, etc. This is where you should probably start with a "Hello world"
 * The mod metadata definition file, includes the name, description and bunch of other settings.
 * The mod metadata definition file, includes the name, description and bunch of other settings.
 * The mod metadata definition file, includes the name, description and bunch of other settings.

Referencing files in different paths
As noted above, the  and   folders behave very differently from eachother. Due to this, you reference files in them slightly differently aswell. The  can essentially be considered as its own virtual filesystem inside Noita which can be referenced directly, but everything else needs to have your full mod path in it. For example including files in Lua, with the above structure: The same exact thing applies in XML aswell when defining paths (eg. spritesheets, projectiles, effects, anything)

The Entity Component System basics
Entities are based on a couple of simple rules:


 * Can contain any number of components, even same ones
 * Can have child entities, defining their own components
 * Can inherit from other entities, copying over their functionality
 * Can have only one name
 * Can have multiple tags

Example
Lets break down an example entity, from the base game file:  This is one of the simplest entities you can find, composed of only three components inside it. If spawned in-game, you should see a simple animated banner flag dropping to the ground, without any special functionality.


 * is generally required for anything dealing with physics. It can define a number of things (eg. gravity for individual entities), but here we simply initiate it with default values. You can find all of the values in.
 * gives the entity very simple physical properties. It'll always fall down, stop at any walls and it generally cannot collide with proper physics objects, nor can it be kicked. For proper physics, you'd want a PhysicsBodyComponent alongside with PhysicsShapeComponent, you can find many different examples of this in the data files.
 * simply attaches an image file to the entity, with any given offsets and such. Here an XML file is defined as the source for the image, which is required when you want to add animated sprites to an entity. If your sprite is a still image, you can reference it directly here aswell.

Lets take a look at the image file  next: These separate metadata files are essentially outside of the Entity Component System, and simply define the sprite metadata in the same XML format as everything else. Thus no documentation can be found for the XML elements in the component_documentation.txt, because these are not components nor entities. But lets break this down aswell:


 * Here we finally reference the actual image file we want to draw


 * The main  element has only one   child element, it could have multiple of these, one for each animation (normal for any characters)
 * The animation name is "stand", and it's referenced as the default one aswell. The names can be anything, but it has to match with whatever's using them.
 * The  attributes are quite self-explanatory, but basically the most essential part when defining animations. These have to match with the spritesheet in your image file.

You can go take a look at the file, and this all should become fairly obvious.

Creating and deleting entities
There are a multitude of ways in which you can spawn/kill entities. The simplest way is directly with Lua:


 * Spawn with
 * Delete with

Just as an example, other possible spawn/kill places include:


 * can be used to spawn any entity upon projectile collision
 * can be used to limit frequently used entities' spawn rates / distances (eg. enemies, lanterns, ...)
 * literally gives an entity a certain time to live
 * enables hitpoints and taking damage for the entity. Entity is killed upon reaching 0 health.
 * ...and many more!

Tags
Entities and components both can have any number of tags attached to them. Tags are a very simple way to categorize one type of "thing", and can be easily created on the fly without any extra definitions. For example, fetching a list of all enemies around the player is this easy:.

Most tags don't have anything else to them, but there is a group of special tags which have in-engine hard-coded functionality attached to them.

Notes:


 * Entity tags are defined in the  attribute, while Component tags are defined in the   attribute.
 * The engine currently supports only a very limited amount of custom tags, which is global across all mods. This is important to keep in mind for inter-mod compatibilty.
 * Via community testing, the upper limits seem to be currently be about =224 and  =210
 * The special tags are integral to whole Entity-Component system of Noita, so make sure to read through that page

Entity inheritance

 * Implemented via the  component
 * Base entity filepath in the  attribute
 * Override base entity components by defining new ones inside the Base element tags
 * When overriding, the Base entity must have the components defined that you are trying to override. Otherwise an error will occur.
 * Your own additions go normally outside the Base element


 * You can inherit from as many Base entities as you like
 * All entity tags will be bunched together

init.lua
The first piece of code that is run for any mod. Includes pre-determined function names you can use for hooking into certain events and provides a place to gather together all your mod's file overrides.

The following bits are taken almost straight from. All of the code is optional, you can include only the parts that you need.

Overriding and extending systems
These lines are usually added to the end/beginning of. This code runs when all mods' filesystems are registered.

Good to go through

 * A lot of variables to control the behaviour of many aspects of the game and gameplay. From virtual resolution (for controlling the amount of world you see) to the amount of blood animals spill, good to go through.


 * A lot of utility functions ready-made by Nolla. Includes helpers for a lot of basic 2D platformer math, the ECS and more. Good read through to get an idea how things work and not re-implement basic things many times.

Probably not too useful starting out

 * A table of how all the game's animals (including the player) feel toward eachother.
 * Can be edited freely; eg. make everyone friendly towards the player.


 * Includes all the basic translations for the game. Good for cross-linking certain spell names, because most of the text seen in-game is not actually present in the code, but here.
 * Can also be edited freely, if you want to eg. rename/rewrite any spells or parts of the game.


 * "Global" biome function registration. Any names defined here are available to all wang tiles and pixel scenes.
 * Note: All biome will still need an implementation for these functions separately.
 * Can be edited freely to add your own.


 * The "main" OpenGL shader file, can be edited and appended freely to create your own shader effects. Not recommended without a prior experience of programming / shaders.

Lists of interest

 * Materials:
 * Perks:
 * Potions:
 * Spells:
 * Status effects:
 * See above section on init.lua for how to extend these

Debugging
Noita does not currently have any sort of dedicated IDE / testing environment for development. A lot of the development time will indeed be spent just restarting the game to try out new changes. Below is a list of the most common ways for debugging Noita mods:


 * 1) The development build :
 * 2) *Starts with a development console. This is the best way to directly find out any errors in your Lua / XML as they happen.
 * 3) *The executable should be located in, but can only be started from the root folder (ie. next to the ). If you've followed instructions so far, it should already be there.
 * 4) *Press  to show a list of keybinds. Press   to enable most debugging features.
 * 5) *Required for seeing  output in the console, but   still works anywhere (rendered in-game on the lower left corner).
 * 6) *Note: This is known to decrease performance for many people. So it's totally fine to switch between the two builds frequently.
 * 7) Logging to file:
 * 8) *Enable via specific magic numbers.
 * 9) *Or download a nice mod which does this for you: Modworkshop
 * 10) *Logs to
 * 11) CheatGUI Mod:
 * 12) *Great for testing gameplay features, without fiddling with any debug features.
 * 13) *Spawn items/perks/wands, teleport, increase health, etc. All straight from in-game HUD
 * 14) *Download: [Steam Workshop | Github]
 * 15) Noita also supports the Decoda Lua debugger:
 * 16) *Needs separate setup. Instructions found in

Note: The game is supposed to detect when any mod files change and consequently hard-restart the game upon starting a new game, but this is known to not work too reliably currently. Thus for now it's advised to always restart your game entirely via manually exiting / killing the game first.