Modding: Making a custom spritesheet

From Noita Wiki
Jump to navigation Jump to search
Modding Navigation
BasicsData.wakGetting startedLua ScriptingUseful Tools
AudioEnemiesEnvironments (Fog of War) • Image EmittersMaterialsPerksSpellsSteam WorkshopSpritesheetsUsing CMake
Component DocumentationEnumsList of all tagsSpecial Tags
Lua Scripting
Lua APIUtility Scripts
Other Information
Enemy Information TableMagic NumbersSound EventsSpell IDsPerk IDsMaterial IDs

Customizing or creating a new spritesheet is relatively simple. But it's still recommended to have gone through the Modding: Basics and have a mod directory set up before delving deeper here.

Most animal (ie. character) visuals consist of the following parts:

  • Basic animations spritesheet
  • Hotspot spritesheet
  • Stains spritesheet
  • Metadata XML defining all aspects of the spritesheet: animation positions, names, frame sizes, speeds, etc.
  • Ragdoll folder

Creating a custom player character

We'll use the player character as an example from here on, as it's probably the most edited character.

Animations spritesheet


An annotated version of the player spritesheet, for getting started quicker
the player spritesheet, annotated

To the right you can find an annotated version of the player spritesheet, for easier time getting started.

  • Each row is one animation
  • Each animation has its own size, frame count, speed, y-position, name, etc.
    • Does not matter if these match with other animations
    • Only has to match with the values specified in the Metadata XML
  • Same animation can have multiple names in the metadata, thus essentially acting as multiple animations

The player spritesheet is currently the biggest one in Noita, having closer to 50 animations in it. Not all of these are required; some are played very rarely and a couple are just leftovers.

Hotspot spritesheet


  • Simple positions for defining any extra attachments to the character
    • Eg. physics-simulated cape, left arm for holding the wand, etc.
    • Can also work as general positions for shooting, triggering crouch, etc.
  • Hotspots spritesheet contains only the hotspot pixels, and nothing else.
    • Hotspots can also be defined in simple xy-coordinates in the entity file, without an extra spritesheet. This is more common for wands.
  • Each hotspot has its own color, the hexcodes must match exactly the defined values.
  • Has to match the player spritesheet dimensions exactly. (Just overlay it on another layer and ust save it separately)
  • Hotspot entities are attached in the actual player entity data/entities/player_base.xml, but the colors are defined in the sheet Metadata XML

Stains spritesheet


  • Has to be in the same folder as main animations spritesheet
  • Has to match the player spritesheet dimensions exactly.
  • init.lua has to have the following magic line pointing to the default enemies_gfx directory, which has to contain the sprites you want to generate UVs for.
    • ModDevGenerateSpriteUVsForDirectory( "data/enemies_gfx" )
  • Then running the game via noita_dev.exe will generate the UV maps under your own mod's data/generated/.
  • This is only a concern if you are making a new "shaped" character. If you're simply giving the player robes a new color, the default stains will most likely still work.

Metadata XML


  • Animations can have events tied to them, eg. "kick" or "throw"; these are crucial to their inner workings.
    • These are actually triggered even just by playing the animation manually in Lua: GamePlayAnimation(player_entity, "kick", 10)

Ragdoll folder


This folder has two very simple parts: Each body part in its own image file, and a single text file listing all the body parts filepaths.

  • The ragdoll files have to be the exact same size as the very first frame of the very first animation in your spritesheet (ie. "reference frame")
  • You can have as many or as few ragdoll parts as you want
  • Joints are generated automatically from overlapping pixels.
    • In other words: If you don't want your ragdoll just falling apart from drowning, you need to have at least a single "same" pixel present in both body parts that you want to joint together.

Bonus: Cape color

A couple of enemies have a cape, in addition to the player. Changing this usually has to be done via Lua.

The player's cape has a special name, so you can just fetch it using that:

local cape = EntityGetWithName("cape")
local cape_verlet = EntityGetFirstComponentIncludingDisabled(cape, "VerletPhysicsComponent")
ComponentSetValue2(cape_verlet, "cloth_color", 0xFF0011BB)
ComponentSetValue2(cape_verlet, "cloth_color_edge", 0xFF0011BB)

Note that colors are usually defined as "ABGR" in Noita, which is reverse from how most graphics software typically display the hex values in RGBA. So for the above example, in order:

  • Alpha: FF
  • Blue: 00
  • Green: 11
  • Red: BB

Tying everything together

When editing existing character sheets, you basically have got two options for adding the files into the game.

Either replace all the files in-place in the data/ folder

  • Not usually a good solution, but for simple player character mods this should be OK, as you shouldn't have multiple of these active anyway.

OR set the values manually via Lua in init.lua

  • Possibly better compatibility with other mods
  • See the example mod mods/starting_loadouts for an example on how to do this.

If you're creating an entirely new character, just add your files under files/ in whatever folder structure you deem the best.