Modding: Making a custom perk

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:

   table.insert(perk_list,
     {
       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.
       end,
     }
   )
   -- if you have more perks to add
   table.insert(perk_list,
     {
       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.

Note:

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
dofile_once("data/scripts/perks/perk.lua")
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)
end

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)
end

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()