Page contents

Offline copy of Perks, materials and world content.

Noita: perks, materials and world content

Documentation status: In progress. Source checked: 2026-10-06. In-game validation: not recorded. This chapter extends entities and spells into other gameplay lists and world data. Use the installed game files as the versioned reference because Noita's online developer modding basics page remains a short outline.

Append a perk to the perk list

The custom perk guide names data/scripts/perks/perk_list.lua as the vanilla list and uses ModLuaFileAppend from init.lua to add a mod-owned Lua file. Define a unique perk ID, localized UI name and description, icon paths, pool inclusion and a pickup effect. The guide distinguishes a hardcoded game_effect from a custom func callback; a name and icon alone do not create new behavior. Test the perk via a controlled spawn after player creation, then test normal Holy Mountain selection, stacking/duplicates and a reloaded run. Record whether the perk is intentionally omitted from the default pool.

Define a material with a unique identity

The custom material guide describes an XML <Materials> file added during initialization with ModMaterialsFileAdd. A material can use CellData or inherit from another material with CellDataChild; it needs a unique name, UI string and wang_color. Search installed material data and other enabled mods for that color because a collision can make pixel scenes resolve to the wrong material. Add graphics or texture paths under your mod folder, then test the material in a controlled world area. If adding a reaction, verify inputs/outputs and test interaction with vanilla liquids, fire and terrain; a reaction that points at a nonexistent output material is not a complete feature.

Materials and status effects are related but separate. The guide explains that damage caused by a material can depend on an entity's DamageModelComponent, not just the material definition. Likewise, a status effect needs its own entry and application path. Trace the installed data/scripts/status_effects/status_list.lua, the entity receiving it and any player-facing string/icon before claiming the status is available in play. The modding basics index identifies those list files as extension points.

Place content in a biome or world

A mod-owned entity or material is not automatically generated in a biome. The custom environment guide describes biome files, world layout, pixel scenes and shared files that multiple mods may edit. Map the path from world map to biome script to spawn list before changing anything. Use a small, distinctive test placement and compare a fresh world seed with the mod enabled and disabled. If two mods change the same world file, record which one wins and whether an append or compatibility patch is possible. Existing saves may already contain generated chunks; use a new run to validate world-generation changes.

For items, enemies, projectiles and wands, use the entity-component workflow and identify a normal acquisition or spawn path. For an item, test pickup, inventory icon, use and discard. For an enemy, test health/damage, AI, drops and encounter placement. For a wand, test its generated deck, mana, recharge, sprite and spell compatibility. These are distinct integrations even when all are represented by entity XML.

Keep strings and art portable

The perk guide points to Noita's translation CSV format for player-facing text. Use translation keys rather than assuming English strings suffice. The Nolla Games repository has custom localization and character sprite pages; inspect their age and the installed examples before relying on a particular sprite layout. Package original art/audio and test paths after installation on a clean copy. A source file present in the development folder may be omitted from a Workshop upload.

Sources and limits