Modding: Making a custom material

Getting started
To make a custom material and even reactions between materials, like acid eating through ground, create an XML file with the same structure as the original materials file, for instance: Then, in your mod's  you need to tell the game to add your custom material(s) like so: This will add two new materials and a reaction that turns the first material into the second when it comes in contact with air. Because we did not specify any properties it will use the defaults instead, which in this case means they are liquids with the same color as specified in. That's the minimum amount of work that's required to add a new material. It's boring but it gives you a starting point from which you can start experimenting.

Basics
Now that we know how to get our custom materials into the game, let's first learn about a few important things. First of all, the  of each material needs to be unique, if you define a new material with an already existing name it will overwrite the previously defined material with the same name. The name is not shown ingame so go ahead and prefix it with something, for instance  instead of just , make sure the prefix has a low chance of ever being used by anyone else.

Next up, there are two ways to define a material, either as a completely new material in which case you would use, or by basing it off an existing material by using  , when you use the latter, you need to specify a material to inherit from using the property  , if you don't, the game will crash. The same goes for specifying a  on , only   can and must have a. This allows you to basically make a copy of an existing material with just slightly different properties.

The next important thing is the, which also needs to be unique and is how the game knows what materials to place in the world when loading wang tiles or pixel scenes. So when there is a big blob of the color  (the format being hexadecimal ARGB, alpha, red, green, blue), it will know to place lava there, because lava has. When you define a new material with the same wang color as an existing one, that new material will get placed instead wherever that wang color is used. So make sure to use something unique. But... how? The only way is to pick one randomly and then simply use your text editor to search for that value to check if it already exists or not. The chances of picking an already existing one randomly are relatively small though, because with 255 different values for red, green and blue, there are a total of 16.581.375 different combinations! And that's even without taking alpha into account.

Making a new material based on an already existing one is a fun and easy way to experiment. You have two options, copying an existing material entirely, or simply extending it by inheriting from it. As an example, let's make a liquid version of sand: Here we inherited from the material  by using   and specifying , gave it a custom  ,   and then the important part, we override the parents property   by specifying our own:.

At this point you should be able to make any material you like by looking at similar existing materials and creating a modified version of them.

Adding graphics and texture
When no graphics are specified, the  with full opacity will be used as a graphic instead. That's not good so let's define our own by adding it as a child element of our material: This will make the material translucent green, if we want to use a texture instead we would do this: Now our material would use a different texture. It's also possible to fine tune the graphics by adding textures for the edges for all kinds of orientations, but that is beyond the scope of this article.

Material types
The type of a material is determined by multiple properties, the first and most defining one being, which can be one of 4 different values:. They are confusing because you might think that ground is solid, right? WRONG! It's static liquid sand!... What? So what exactly is solid then? Solids are mostly physics objects like boxes, ice, glass, etc and will be simulated using the Box2D physics system. If you make your entire world out of a solid material, it's going to lag like hell because it will constantly collide with itself. So instead you would use static sand, that is sand that floats in the air and can be stood upon, that's basically what every "ground" in noita is.

Sand itself however is not it's own type, but simply a subtype of liquid. A combination of  and. Most types of materials are a combination of different properties, just check out a similar material as to what you want to make in the default materials in order to find out how to make it.

As for properties, usually all properties starting with  only apply when. All properties starting with  to   and so on. If you specify a inapplicable one it will simply have no effect. Explanations for most properties can be found at the bottom of this article.

Stain and ingestion effects
Materials can apply different effects like wet, slimed, oiled etc when entities get stained with that material, or apply ingestion effects when eaten. Only liquids can apply stains, although sand can too, just not very reliably since the material needs to be on top of the to-be-stained entity. To define those effects, add them as a child element, just like : To make your material stain, you also need to set.

Reactions
Reactions define how materials interact with each other, for example lava melting metals, acid eating through ground, steam condensating into water, or draught of midas turning everything to gold. This is how you define a reaction: The probability determines how fast the reaction happens, input cell 1 and 2 are the materials required for the reaction to happen and output cell 1 and 2 what they turn into respectively. This one would slowly turn  into   when it comes in contact with air. It's also possible to define a reaction that happens when a reaction does not meet the requirement, for that you can use.

Have you noticed that you can add tags to materials? This makes the reaction system very flexible. Instead of specifying reactions for every material, you can also specify a tag inside a reaction, which means it will react with any material using that tag. For instance: This is a reaction that applies a reaction to every material with a  tag, that on contact with a material that has a   tag turns it into a material with the same name but   appended. For instance, has the   tag, so the reaction would turn it into. Don't forget that for this to work, a material with  needs to exist.

There is a whole lot more to reactions that is best to be explored by studying the  as it would go well beyond the scope of this article.

Making materials deal damage
How much damage a materials deals is not a property of the material, but rather a property of the  of the to-be-damaged entity. That means if you want a material to deal contact damage to the player, you would have to get the player entity, get it's  and change the   and   properties to include your new material. The properties are both a comma seperated string. Example:

This would cause acid to deal 0.005 damage, lava 0.003 and magic_gas_hp_regeneration would heal 0.005 because it's a negative number. The numbers are damage per particle, per tick, divided by 25. So if you want something to deal 0.1 damage per particle, you have to set the damage to 0.004. However, because modifying a comma seperated string is clunky and changes to  and   don't take immediate effect, you can use these helper functions:

Then use them like this in your  right after your player spawns:

Making enemies take damage from a certain material is much harder since it requires modification of every enemies  individually and therefore not explained in this article at this time.

List of all known material properties
Lastly here is a list that was compiled through experimentation and analyzing the  file.