Gameplay content

Perks

Add perks to the player's perk tree, what they give while owned, and how your scenes ask for them.

The player spends perk points (the perks stat of ul_Base) on a perk tree shown on the map HUD's Perks page (the bolt on the left rail). The tree is mod data: every Perks/*.ulperk of every enabled mod adds to it.

A perk can give stat bonuses while it is owned. Anything else it does is up to your mod: your scenes, actions and ticks ask Game:hasPerk(id).

A perk file: `Perks/*.ulperk`

json{
	"branches": [
		{ "id": "night", "name": "Night", "icon": "star" }
	],
	"perks": [
		{ "id": "mymod_night_owl", "name": "Night Owl", "branch": "night", "tier": 1,
		  "text": "+5 energy after midnight, and bars warm to you.",
		  "stats": { "interpersonal": 2 } },
		{ "id": "mymod_last_orders", "name": "Last Orders", "branch": "night", "tier": 2, "cost": 3,
		  "text": "Never thrown out before closing.", "requires": [ "mymod_night_owl" ] }
	]
}

Field	Meaning
`branches[].id`, `name`	A column of the tree. `icon` is a glyph of `Map/Icons/UI`. A branch named by a perk but not declared is created with the id as its name.
`perks[].id`	Unique across all mods: prefix it with your mod's name. A later mod with the same id replaces the perk.
`name`, `text`	Shown on the Perks page
`branch`	The branch's id. Perks without one are listed under "Other".
`tier`	1 is the root. A perk of tier N needs one perk of tier N-1 in the same branch.
`cost`	Perk points; defaults to the tier
`requires`	Perk ids that must be owned first, on top of the tier rule
`stats`	Stat bonuses while owned, applied as the stat modifier `perk:<id>` (see Stats)

Branches and perks from several files and mods are merged in load order.

From a scene

luaif Game:hasPerk("mymod_night_owl") then
	Player:ModifyStat("energy", 5)
end

Player:ModifyStat("perks", 2)                  -- give points (a milestone, a mentor)
local ok, why = Game:buyPerk("mymod_last_orders") -- as the Perks page does; why = the refusal
Game:grantPerk("mymod_night_owl")              -- free, ignoring cost and tier (a quest reward)
local back = Game:resetPerks()                 -- every perk back, paid points refunded

for _, perk in ipairs(Game:getPerks()) do
	-- { id, name, text, branch, tier, cost, owned, why, mod }; why is nil when it can be bought now
end

perkUnlocked(id, mod) fires when a perk is bought or granted, and perksReset(points) after a reset (see Events).

Owned perks and the points paid for them are saved with the game.

Perks

#A perk file: Perks/*.ulperk

#From a scene

A perk file: `Perks/*.ulperk`

From a scene