[Lib] PassiveEffect

Overview

Makes it easy to add passive weapon effects that only run when the weapon is equipped and powered. You define handler functions on the weapon for ModLoader/ModUtils hooks and/or modApi/modApiExt/BoardEvents events. The library wires them up and sets Pawn to the owning mech when calling your handlers.

Any issues or concerns? Join the Redacted Rice Discord and @Das Keifer

Setup

1. Inherit with PassiveSkill:new instead of Skill:new for passive only weapons.
2. Define GetSkillEffect for the weapon tooltip/preview (can be hardcoded).
3. For each hook/event, define a function named GetPassiveSkillEffect_<HookOrEvent> with the exact same signature as the hook/event.
4. Call PassiveEffect:addPassiveEffect(weaponName, hooks) during mod init (before mods finish initializing).
5. The library finalizes automatically on mods initialized (registers hooks/events, auto sets Passive on registered weapons).

Example handler name for skillBuildHook: Treeherders_Passive_WakeTheForest:GetPassiveSkillEffect_SkillBuildHook(mission, pawn, weaponId, p1, p2, skillFx)

Inside handlers, self is the weapon object. Pawn is set to the owner (like GetSkillEffect).

Tip image evaluations skip firing passive handlers. Active passives are refreshed on mission start, save/load, and save game events. Set PassiveEffect.DebugLog = true for verbose logs.

 

API

• PassiveEffect
  • addPassiveEffect
  • isPassiveActive
  • countAnyVersionOfPassiveActive

 

PassiveEffect

A library providing functionality for registering passive weapon effects that fire on hooks/events only while the weapon is powered.

 

addPassiveEffect

Argument name	Type	Description
weapon	string	Global weapon id (base name without _A / _B / _AB)
hook	string / table	(optional) Hook name ending in Hook, event name starting with on, or a table of either. Defaults to postEnvironmentHook
weaponIsNotPassiveOnly	boolean	(optional) If true, do not auto-set the weapon's Passive field. Defaults to false

Registers the weapon for the given hook(s)/event(s). The corresponding GetPassiveSkillEffect_* function must already exist on _G[weapon].

If hook is a table, each entry is registered separately (same as calling addPassiveEffect once per entry).

Hooks must end with Hook and resolve via modapiext.addX / modApi.addX (e.g. skillBuildHook -> addSkillBuildHook).

Events must start with on and be found in modApi.events, modapiext.events, or BoardEvents.

Handler naming: GetPassiveSkillEffect + _ + hook/event with first letter uppercased (e.g. skillBuildHook -> GetPassiveSkillEffect_SkillBuildHook).

Example:

PassiveEffect:addPassiveEffect(
    "Treeherders_Passive_WakeTheForest",
    {
        "skillBuildHook",
        "finalEffectBuildHook",
        "skillEndHook",
        "finalEffectEndHook",
        "queuedSkillEndHook",
        "queuedFinalEffectEndHook",
        "preEnvironmentHook",
    }
)

-- Single hook with default postEnvironmentHook omitted:
-- PassiveEffect:addPassiveEffect("MyPassiveWeapon")

-- Non-passive-only weapon (keep existing Passive field behavior):
-- PassiveEffect:addPassiveEffect("MyWeapon", "skillBuildHook", true)

 

isPassiveActive

Argument name	Type	Description
weaponName	string	Exact weapon name including upgrade suffix if any (e.g. MyPassive_A)

Returns true if any powered mech currently has this exact weapon name active.

Example:

if PassiveEffect:isPassiveActive("Treeherders_Passive_WakeTheForest_A") then
    -- upgrade A variant is powered on some mech
end

 

countAnyVersionOfPassiveActive

Argument name	Type	Description
weaponBaseName	string	Weapon base id. Matches any active weapon whose id starts with this string

Returns the number of active powered instances whose weapon id starts with weaponBaseName (covers base + _A / _B / _AB variants).

Example:

if PassiveEffect:countAnyVersionOfPassiveActive("StarWars_RebelHope") > 0 then
    -- any powered Rebel Hope variant is active
end