Skip to content

[Lib] DamageModifierLib

Jump to bottom
DasKeifer edited this page Oct 6, 2026 · 2 revisions

Overview

This library lets mods mutate weapon SpaceDamage during skill builds and during Board:IsDeadly preview checks. It walks skill/final effect lists (via modApiExt), tracks pawn moves and pushes so targetPawn stays accurate, then dispatches priority events so subscribers can change each SpaceDamage or emit derived follow-up effects.

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

API

 

DamageModifierLib

A library providing priority events and helpers for modifying weapon damage during skill builds and deadly checks.

Prefer the events for skill effect mutation. Use the helpers when you need deadly preview math or position tracking during a walk.

Requires modApiExt for the skill effect walk (onSkillBuild/onFinalEffectBuild). Board:IsDeadly hooks still work without it.

Priority guidance

Lower priority runs first:

Priority Guidance
INTERNAL_PRIORITY (0) Framework use only
30–50 Early transformations/blocks
80 Additive bonuses after doubling interactions
100 Default (DEFAULT_PRIORITY)
150 Near-final finishers (e.g. kill shot)
180–200 Late follow ups/post pass (onSkillEffectEvaluated)

subscribe(fn, priority) returns a subscription. Call subscription:unsubscribe() to remove it.

 

GetModifiedDamage

Argument name Type Description
spaceDamage SpaceDamage Damage being evaluated
attackingPawn Pawn Attacking/acting pawn

Runs onEvaluatingDeadly against a copy of spaceDamage and returns the resulting iDamage. Safe for preview math. Does not mutate the original.

Example:

local modified = DamageModifierLib:GetModifiedDamage(spaceDamage, attackingPawn)

 

GetDamageDelta

Argument name Type Description
spaceDamage SpaceDamage Damage being evaluated
attackingPawn Pawn Attacking / acting pawn

Same as GetModifiedDamage, but returns modifiedDamage - originalDamage.

Example:

local delta = DamageModifierLib:GetDamageDelta(spaceDamage, attackingPawn)

 

GetPawnSpace

Argument name Type Description
pawn Pawn Pawn to locate

During a skill effect walk, returns the tracked position after pending pushes/moves. Outside a walk, falls back to pawn:GetSpace().

Example:

local loc = DamageModifierLib:GetPawnSpace(attackingPawn)

 

GetPawnAt

Argument name Type Description
loc Point Board location

During a skill effect walk, returns the tracked pawn at loc after pending pushes/moves (or nil). Outside a walk, falls back to Board:GetPawn(loc).

Example:

local target = DamageModifierLib:GetPawnAt(spaceDamage.loc)

 

events

onSkillEffectModify

Argument name Type Description
fn function Callback invoked per non-movement SpaceDamage
priority number (optional) Subscriber priority. Defaults to DEFAULT_PRIORITY (100)

fn has the following signature: fn(spaceDamage, attackingPawn, targetPawn, phase)

Argument name Type Description
spaceDamage SpaceDamage Mutable entry from the skill effect
attackingPawn Pawn Pawn building the skill effect
targetPawn Pawn/nil Pawn currently on spaceDamage.loc after push/move tracking
phase number One of DamageModifierLib.PHASE_*

Fired once per non-movement SpaceDamage during skill/final builds (including queued lists). Mutate spaceDamage in place (e.g. iDamage).

Returns a subscription. Call subscription:unsubscribe() to remove it.

Example:

DamageModifierLib.events.onSkillEffectModify:subscribe(function(spaceDamage, attackingPawn, targetPawn, phase)
    if not targetPawn or not targetPawn:IsEnemy() then
        return
    end
    if spaceDamage.iDamage > 0 and spaceDamage.iDamage ~= DAMAGE_ZERO then
        spaceDamage.iDamage = spaceDamage.iDamage + 1
    end
end, 80)

 

onSkillEffectEvaluated

Argument name Type Description
fn function Callback invoked after a skill effect pass finishes
priority number (optional) Subscriber priority. Defaults to DEFAULT_PRIORITY (100)

fn has the following signature: fn(phase, outEffects)

Argument name Type Description
phase number One of DamageModifierLib.PHASE_*
outEffects table Mutable array. Append SpaceDamage entries to queue for the skill effect

Fired once after all SpaceDamages in a pass have been processed. Use this to emit aggregated/derived effects after seeing the full list (e.g. one heal for N kills). Derived effects are modifier processed and collected until the chain settles, then added to the skill effect.

Priority alone is not enough for post pass aggregation - use this event.

Returns a subscription. Call subscription:unsubscribe() to remove it.

Example:

DamageModifierLib.events.onSkillEffectEvaluated:subscribe(function(phase, outEffects)
    if killsThisPass > 0 then
        local heal = SpaceDamage(attackerLoc, -killsThisPass)
        table.insert(outEffects, heal)
    end
end, 180)

 

onEvaluatingDeadly

Argument name Type Description
fn function Callback invoked during deadly/modified damage evaluation
priority number (optional) Subscriber priority. Defaults to DEFAULT_PRIORITY (100)

fn has the following signature: fn(spaceDamage, attackingPawn, targetPawn)

Argument name Type Description
spaceDamage SpaceDamage Mutable copy - mutate this
attackingPawn Pawn Pawn passed to Board:IsDeadly
targetPawn Pawn/nil Pawn on spaceDamage.loc

Fired from Board:IsDeadly/GetModifiedDamage. Keep this free of side effects (no icons, no sScript, etc.) - it only adjusts preview/deadly math.

Returns a subscription. Call subscription:unsubscribe() to remove it.

Example:

DamageModifierLib.events.onEvaluatingDeadly:subscribe(function(spaceDamage, attackingPawn, targetPawn)
    if targetPawn and targetPawn:IsEnemy() and spaceDamage.iDamage > 0 then
        spaceDamage.iDamage = spaceDamage.iDamage + 1
    end
end, 80)

 

Constants

PHASE_*

Phase values align with [Lib] WeaponPreview STATE_* numbers for easy conversion (see also [Lib] PlusHelper convertPhase).

Field Type Description
PHASE_NONE number 0 - No active skill-effect walk
PHASE_SKILL_EFFECT number 1 - Primary skill effect build
PHASE_TARGET_AREA number 2 - Target area (reserved / aligned)
PHASE_QUEUED_SKILL number 3 - Queued skill effect
PHASE_SECOND_TARGET_AREA number 4 - Second target area (reserved / aligned)
PHASE_FINAL_EFFECT number 5 - Two-click final effect
PHASE_QUEUED_FINAL_EFFECT number 6 - Queued final effect

 

DEFAULT_PRIORITY

Field Type Description
DEFAULT_PRIORITY number 100 - Used when subscribe is called without a priority

 

INTERNAL_PRIORITY

Field Type Description
INTERNAL_PRIORITY number 0 - Reserved for framework subscribers. Mod code should use higher values

 

Clone this wiki locally