From 3882ba15fbc680019a3483a7495afc5f147125ad Mon Sep 17 00:00:00 2001 From: Mads Buvik Sandvei Date: Fri, 2 Feb 2024 20:10:25 +0100 Subject: [PATCH] Rework documentation of skill used/level up handlers. --- files/data/scripts/omw/skillhandlers.lua | 55 +++++++++++------------- 1 file changed, 24 insertions(+), 31 deletions(-) diff --git a/files/data/scripts/omw/skillhandlers.lua b/files/data/scripts/omw/skillhandlers.lua index 30188f2341..f6a8ec4248 100644 --- a/files/data/scripts/omw/skillhandlers.lua +++ b/files/data/scripts/omw/skillhandlers.lua @@ -41,32 +41,6 @@ local Skill = core.stats.Skill -- @field #string Trainer trainer -- @field #string Usage usage ---- --- Table of valid handler signatures --- @type HandlerSignatures --- - ---- Signature of the skillLevelUp handler --- @function [parent=#HandlerSignatures] skillLevelUpHandler --- @param #string skillid The ID of the skill being leveled up --- @param #SkillLevelUpSource source The source of the skill level up --- @param #table params Modifiable skill level up values as a table. These values are calculated based on vanilla mechanics. Setting any value to nil will cause that mechanic to be skipped. By default contains these values: --- --- * `skillIncreaseValue` - The numeric amount of skill levels gained. --- * `levelUpProgress` - The numeric amount of level up progress gained. --- * `levelUpAttribute` - The string identifying the attribute that should receive points from this skill level up. --- * `levelUpAttributeIncreaseValue` - The numeric amount of attribute increase points received. This contributes to the amount of each attribute the character receives during a vanilla level up. --- * `levelUpSpecialization` - The string identifying the specialization that should receive points from this skill level up. --- * `levelUpSpecializationIncreaseValue` - The numeric amount of specialization increase points received. This contributes to the icon displayed at the level up screen during a vanilla level up. - ---- Signature of the skillUsed handler --- @function [parent=#HandlerSignatures] skillUsedHandler --- @param #string skillid The ID of the skill being progressed --- @param #SkillUseType useType The use type the skill progression --- @param #table params Modifiable skill progression value. By default contains the single value --- --- * `skillGain` - The numeric amount of skill progress gained, normalized to the range 0 to 1, where 1 is a full level. - local skillUsedHandlers = {} local skillLevelUpHandlers = {} @@ -118,12 +92,12 @@ local function skillUsed(skillid, useType, scale) local skillGain = skillGainUnorm / skillProgressRequirementUnorm -- Put skill gain in a table so that handlers can modify it - local parameters = { + local options = { skillGain = skillGain, } for i = #skillUsedHandlers, 1, -1 do - if skillUsedHandlers[i](skillid, useType, parameters) == false then + if skillUsedHandlers[i](skillid, useType, options) == false then return end end @@ -150,7 +124,7 @@ local function skillLevelUp(skillid, source) levelUpAttributeIncreaseValue = core.getGMST('iLevelUpMajorMultAttribute') end - local parameters = + local options = { skillIncreaseValue = 1, levelUpProgress = levelUpProgress, @@ -161,7 +135,7 @@ local function skillLevelUp(skillid, source) } for i = #skillLevelUpHandlers, 1, -1 do - if skillLevelUpHandlers[i](skillid, source, parameters) == false then + if skillLevelUpHandlers[i](skillid, source, options) == false then return end end @@ -199,13 +173,32 @@ return { version = 0, --- Add new skill level up handler for this actor + -- If `handler(skillid, source, options)` returns false, other handlers (including the default skill level up handler) + -- will be skipped. Where skillid and source are the parameters passed to @{SkillProgression#skillLevelUp}, and options is + -- a modifiable table of skill level up values, and can be modified to change the behavior of later handlers. + -- These values are calculated based on vanilla mechanics. Setting any value to nil will cause that mechanic to be skipped. By default contains these values: + -- + -- * `skillIncreaseValue` - The numeric amount of skill levels gained. + -- * `levelUpProgress` - The numeric amount of level up progress gained. + -- * `levelUpAttribute` - The string identifying the attribute that should receive points from this skill level up. + -- * `levelUpAttributeIncreaseValue` - The numeric amount of attribute increase points received. This contributes to the amount of each attribute the character receives during a vanilla level up. + -- * `levelUpSpecialization` - The string identifying the specialization that should receive points from this skill level up. + -- * `levelUpSpecializationIncreaseValue` - The numeric amount of specialization increase points received. This contributes to the icon displayed at the level up screen during a vanilla level up. + -- -- @function [parent=#SkillProgression] addSkillLevelUpHandler - -- @param #function handler The handler, see #skillLevelUpHandler. + -- @param #function handler The handler. addSkillLevelUpHandler = function(handler) skillLevelUpHandlers[#skillLevelUpHandlers + 1] = handler end, --- Add new skillUsed handler for this actor + -- If `handler(skillid, useType, options)` returns false, other handlers (including the default skill progress handler) + -- will be skipped. Where skillid and useType are the parameters passed to @{SkillProgression#skillUsed}, + -- and options is a modifiable table of skill progression values, and can be modified to change the behavior of later handlers. + -- By default contains the single value: + -- + -- * `skillGain` - The numeric amount of skill progress gained, normalized to the range 0 to 1, where 1 is a full level. + -- -- @function [parent=#SkillProgression] addSkillUsedHandler -- @param #function handler The handler. addSkillUsedHandler = function(handler)