HealthPipeline module

Base tag type categorizing health adjustments.

Categorizes an adjustment or result entry as damage.

Categorizes an adjustment or result entry as healing.

Pool identity: define one subclass per pool type and set an instance as the pool's Tag. Conditional matching and result entries reference pools by it.

A context object passed through the adjustment pipeline in the scene_event to provide the instigator and contributing entities.

The health delta to apply plus categories describing the adjustment.

A slice of an adjustment as applied to one pool. Categories carries the entry's direction - damage_tag when the pool was damaged, healing_tag when it was healed - alongside the adjustment's tags.

The outcome of a processed health adjustment event.

Adjustments are scene events: senders build them and deliver with entity.SendUp; receivers (health_component) process them in OnReceive. Modifiers is the event LAYER stack, supplied by the sender (gather from contributors however your game sees fit) before the event is sent.

A health adjustment delivered as damage; cast to distinguish in OnReceive.

A health adjustment delivered as healing; cast to distinguish in OnReceive.

A pool of health that can be damaged and/or healed. Pool identifier is the Tag: define one health_pool_tag subclass per pool type (e.g. shields_pool_tag := class(health_pool_tag)) - conditional matching and result entries reference pools by that tag. Pools carry their own modifier stacks, evaluated as the pool LAYER.

The default health component: processes damage and healing scene events against an ordered array of health pools.

============================================================================== Scene Events

Senders BUILD the adjustment event themselves and deliver it with SendUp:

Event := damage_event: Context := health_adjustment_context{Instigator := option{Agent}} Entries := array{health_adjustment_entry{HealthDelta := 70.0}} Target.SendUp(Event) DealtResult := Event.Result

The event's Modifiers stack is supplied by the sender - gather modifiers from contributors however your game sees fit before sending.

OnReceive consumes the first damage_event/healing_event that reaches this component: pools are adjusted, the event's Result is set, OnDamaged or OnHealed is signaled with that result, and OnDied is signaled when the adjustments took IsAlive from succeeding to failing.

============================================================================== The Math - Layer-Factor Multiplication

Pools are processed in order; within each pool, entries are processed in order. Per (pool, entry), three modifier stack LAYERS are consulted:

1. the event's stack (Event.Modifiers, supplied by the sender) 2. the pool's stack (Pool.DamageModifiers / Pool.HealingModifiers) 3. the component's stack (DamageModifiers / HealingModifiers)

Each layer independently evaluates the REAL entry with natural semantics - a stack's modifiers chain internally, and the whole stack's output folds to ONE factor:

Factor = Stack.Evaluate(Entry).HealthDelta / Entry.HealthDelta

The layer factors MULTIPLY: Multiplier = FEvent FPool FComponent. A factor of 1.0 is naturally inert; a 0 from ANY layer zeroes the multiplier and NULLIFIES the entry (a 0-delta result entry is recorded and nothing remains to continue on); a negative factor flips the direction.

============================================================================== Application, Unwind, and Excess

Scaled = Remaining * Multiplier

The pool is first gated by its CanProcessAdjustment. The SIGN of Scaled then decides direction: in a damage_event a positive Scaled damages the pool toward 0 while a negative Scaled heals it toward MaxValue (a healing_event mirrors this). Scaled is negative when the entry's HealthDelta or the folded multiplier is negative - a negative HealthDelta entry is valid input and starts in the reversed direction. A pool with no capacity in that direction is skipped and the entry continues on unchanged.

What the pool absorbs is recorded as a result entry carrying the pool's Tag, the entry's Categories, and the direction actually applied (damage_tag or healing_tag). Overflow UNWINDS by dividing the multiplier back out - Remaining = (Scaled - Absorbed) / Multiplier - and continues to the next pool, where the layers are consulted again. Whatever survives every pool lands in Result.Excess at its unwound value.

Example: a 70 damage entry against shields at 50 carrying a 2x pool trait, with a 3x record on the event: multiplier 2 * 3 = 6, so 420 to apply; shields absorb 50; the remaining 370 unwinds to ~61.7 and continues to the next pool at THAT pool's multipliers.

Modifiers evaluate individual adjustment entries: real entry in, modified entry out (health_adjustment_entry is -constructible, so a body can build the modified entry). Evaluation state (Context/Target/Pool) is delivered through vars at the time of adjustment evaluation.

An ordered stack of health adjustment modifiers. Itself a modifier, so stacks nest; the Pre/PostEvaluate broadcasts forward evaluation state down the chain.