Modding: Making a custom perk

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

Making a new perk is relatively simple, assuming you have gone through the Modding: Basics and have a mod directory set up.

Create & register your perk

  1. Add a new file to your mod (eg. files/perk_list.lua), where you define all your custom perks by appending to the perk_list table provided by the base game, repeating this code for each perk you want to add:
        id = "MY_CUSTOM_PERK",
        ui_name = "My Custom Perk Name",
        ui_description = "A Fancy Description",
        ui_icon = "data/ui_gfx/perk_icons/electricity.png",  -- Change this to your own
        perk_icon = "data/items_gfx/perks/electricity.png",  -- Change this to your own
        game_effect = "PROTECTION_ELECTRICITY",  -- Hardcoded game effect, change or remove this
        usable_by_enemies = false,
        not_in_default_perk_pool = false, --set to true to not include it in the default perk pool
        func = function( entity_perk_item, entity_who_picked, item_name )
          -- Any code that you want to run upon perk pickup goes here.
    -- if you have more perks to add
        id = "MY_CUSTOM_PERK_TWO",
        -- etc
  2. Add the following line to the very beginning of your init.lua, referencing the file you just created:
    ModLuaFileAppend("data/scripts/perks/perk_list.lua", "mods/<MY_AWESOME_MOD>/files/perk_list.lua")
  3. That's it! Your perk should now be included in the game.


The game_effects are generally hardcoded in-engine effects, which are not customizable via Lua. We can only string them together, or leave them out and make our own effects via custom code (or both!).

For a list of valid effects you can use, see GAME_EFFECTS or data/scripts/perks/perk_list.lua.

Spawning and picking up a perk

If you want to load the perk via script (and not rely only on holy mountains), you can spawn & pickup the perk with the following snippet:

-- NOTE: If in init.lua, do this *after* the ModLuaFileAppend line and after
-- the player has spawned, for instance in the OnPlayerSpawned callback
function OnPlayerSpawned(player_entity)
    -- Simply spawn the entity in world at the player's location
    local x, y = EntityGetTransform(player_entity)
    local perk = perk_spawn(x, y, "MY_CUSTOM_PERK")
    -- To pick up the perk instantly, you can continue:
    perk_pickup(perk, player_entity, EntityGetName(perk), false, false)

Checking for active perks

The default perk_pickup() adds every picked up perk as a "run flag", with the string format of PERK_PICKED_<PERK_ID>. Thus you can use the following function for easily testing if a perk is active or not:

function has_perk(perk_id)
  return GameHasFlagRun("PERK_PICKED_" .. perk_id)

Further reading

  • You can find list of all base game perks in data/scripts/perks/perk_list.lua
  • You can find the base implementation of perks in data/scripts/perks/perk.lua
    • Most importantly the functions: perk_spawn() and perk_pickup()