Combat attributes and status runtime

This subsystem connects registered attributes, Data Attributes mappings, PlayerEx damage functions and status-effect lifecycle hooks. Its helpers are internal implementation surfaces; the player attribute guide and effect catalogue cover gameplay outcomes.

What it does

IsekaiAttributes registers tracked native attributes. Bundled Data Attributes resources define downstream mappings, entity defaults and metadata overrides. CombatAttributeUtil, the energy/shield components and the status hooks consume those values; registration alone does not give an attribute a combat effect.

IsekaiDamageCondition registers functions through ExAPI.registerDamageModification. IsekaiEffects and IsekaiMagicEffects register the effect catalogue. Spell Power owns spell-school evaluation and vulnerabilities; PlayerEx owns the downstream primary and critical stats.

Runtime model

Native attributes and supplied metadata

These are the Java declarations, before Data Attributes overrides or entity-specific defaults. Every entry is tracked.

The following supplied files under data/isekaiexpansion/attributes/overrides/ declare different metadata. In particular, native maximum energy is 10000 while its data maximum is 5000, and native evasion is unbounded up to Double.MAX_VALUE while its data maximum is 0.5. Keep these layers distinct when diagnosing the status screen.

Each override supplies the following fields explicitly. This table describes the bundled declarations; the dependency owns parsing, reload and missing-field behaviour.

entity_types.json supplies player and simple-clone defaults. Both have maximum energy 30, energy recovery 0.5, maximum gauge 75 and gauge recovery 2; their listed combat and wrapper bonuses start at 0. The player entry additionally lists social attributes. Healing Amplification is absent from this JSON but is included by the player attribute-builder hook, with native default 0.

functions.json declares ADDITION forwarding with these coefficients:

The JSON nesting is values → source attribute → target attribute; each target object contains string behaviour and numeric value. properties.json uses values → attribute → display-property string: percentage, float and integer are presentation declarations, not an alternative combat normalisation function. The wrapper critical/evasion percentages use 100.0, while Spell Power critical chance uses 1.0.

Energy and shield state

Both components tick on the server and synchronise through CCA. NBT reads use the primitive zero/false fallback and do not validate every intermediate timer.

Energy recovers 1 per (int)(20 / regen) ticks, at most once per tick. Removal clamps current energy to 0, starts a 20-tick lock and synchronises. Direct setEnergy is not clamped; addEnergy only caps its upper result, and caller-supplied negative amounts are not rejected. The lock timer advances only while below maximum, so a lock can remain set while the reserve is full.

Shield capacity is max(0, round(baseGauge × shieldPowerMultiplier)); recovery amount is max(1, round(5 × shieldPowerMultiplier)), with interval max(1, round(20 / regen)) or 20 for nonpositive regen. A block pauses recovery for 40 ticks. A pulse may exceed maximum until the next tick. Cooldown ticks return early and do not regenerate.

For blocked damage above the shield’s normal limit but within its maximum, add up to the base cost proportionally, then divide by Shield Power and round with minimum 1. Damage strictly above the maximum breaks immediately; exhausted gauge also breaks. Shield statistics and fallback constants are owned by IsekaiCore, so the component does not hard-code a universal shield profile.

Contracts

Damage stages and percentages

Expansion registers its damage functions in this order: class-discipline halving, class combat rules, effective elements, ineffective elements, Energy Inefficiency, starvation/drowning replacement, environmental resistance, spell talents, melee talents, ranged talents and outgoing combat attributes. This states Expansion’s registration order, not a universal order relative to every other mod.

Element classification first resolves a registered spell school; other damage uses the local damage-key classifier. Only mobs with nonempty Core element data are affected. Effective and ineffective matches are counted separately and both multipliers apply; the element table records all registrations. The duplicate Water/melee registration is a set duplicate, not a Wind/melee resistance.

normalizePercent(v) returns v / 100 only when abs(v) > 1; otherwise it returns v. The boundary is discontinuous: 1 means a full ratio while values just above 1 are percentage points. Do not apply this helper to critical forwarding or haste merely because the UI shows a percent sign.

Here N means the normalisation above. Omnivamp is based on the event argument, not observed health loss, and calls the normal healing path. The common PlayerEx evasion callback in this mod is empty; the counter invocation documented here is in the dodge-status immunity hook. Do not promise counters for every third-party evasion result.

The dodge-status hook excludes explosions, fire, falls, falling blocks/anvils/stalactites, void and armour-bypassing damage. Magic immunity accepts ordinary/indirect magic or any resolved school. OtherImmuneEffect compares the stored DamageSource object by identity, not by damage-type equality.

Death prevention tries the Rakshasa path before the generic Guts/Death Defiance path. The generic path rejects void, sickness and potion sickness. Without Death Defiance it needs finite positive pre-hit health above 25% of maximum; success sets health to 1. The surrounding hook falls back to current health plus incoming damage if its captured pre-hit context is unavailable.

Status application and removal

The server addStatusEffect wrapper first applies harmful team protection, then accuracy for a different living source, then tenacity duration adjustment. It records fear’s source before calling the original application so the fear goal can resolve it during onApplied. A failed new fear application clears that remembered source if no fear remains.

Tenacity’s control set is CC effects plus Slowness, Weakness, Mining Fatigue, Blindness, Levitation and Nausea. Other harmful categories may roll accuracy without losing duration.

IsekaiStatusEffect defaults to category COMMON; constructor clearability and IIsekaiEffect.isPersistent() are separate flags. Milk preserves unclearable effects through the specialised clear path. General clearStatusEffects preserves persistent effects. Harmful-only cleansing rejects beneficial, unclearable and persistent effects. These are not interchangeable operations.

addExtraAttributeModifier allows another modifier for an already-used attribute. On apply it removes the template UUID then installs the adjusted modifier; on removal it removes every extra UUID before the superclass path. Use distinct stable UUIDs. Spirit Mantle overrides amount adjustment to ignore amplifier; do not infer that override for every custom effect.

applyStatusEffectTicks rejects null inputs and nonpositive duration, and clamps negative amplifier to 0. applyStackedEffectTicks rejects nonpositive additions/caps, converts amplifier to stack count, clamps to the maximum and submits a new instance with amplifier stacks - 1. The older applyStackedEffect parameter is in seconds. The separate StatusEffectUtil.addStatusEffect directly mutates the active map and invokes lifecycle callbacks; it bypasses the ordinary application wrapper and is not a substitute for it.

removeOneClearableHarmful selects the greatest amplifier, then duration, then translation key. clearHarmful(cap) currently collects a matching effect before testing its cap, so a nonpositive cap can still remove an effect. Callers needing zero removals must guard that case.

Periodic and dependency boundaries

Evasion counters play IsekaiPlayerAnimations.REACTION_EVASION_RIPOSTE at REACTION_PRIORITY on the server-player defender. KitsuneLossOfSpiritEffect uses ActionDisabler.restrained(2 * 20): item use, movement and jumping are restricted for 40 ticks (2 seconds), while the action gate leaves attacks available. It also plays REACTION_SPIRIT_DRAIN_STAGGER at SKILL_PRIORITY on the server player.

DamageOverTimeEffect pulses only on a live server entity when remaining duration is a positive multiple of its interval. Its settlement helper applies at least 1 pulse up to the caller’s maximum, attributes an optional attacker and returns the sum of requested damage for successful calls, not measured health loss. It does not remove the status instance.

Spell vulnerability definitions currently call a single-school setter twice. The inspected Spell Power source retains the last call; its power multiplier is additive to 1. The effect catalogue records the resulting values and the inspected dependency revision. Preserve this distinction when fixing or upgrading the integration; do not silently document the discarded first-school tuple as active.

IsekaiSpellSchools reuses a pre-existing school with the same ID. Newly created custom school attributes have base/minimum 0 and maximum 2048; physical melee binds to isekaiexpansion:physical_melee while other custom schools use their Spell Power damage IDs. IsekaiMagicAttribute derives its UUID from mod ID, school ID and operation, so multiple values for that same school/operation are not independent modifier identities.

Extending it

For an internal attribute, register its ID, attach it to the relevant entity, define its data metadata/mappings and add a concrete consumer. Keep the unit convention explicit at that consumer. For an effect, choose vanilla category, mod category, clearability and persistence independently; implement symmetric apply/remove cleanup and register the ID in the appropriate catalogue.

Add an extra modifier through addExtraAttributeModifier when another operation already targets the same attribute. For crowd control, retain source context and use the existing goal-control lifecycle. Mutate gameplay state on the server; client shader, outline and sound presentation belongs in the corresponding client bridge.

Verifying

Compare native and data-driven values, including evasion’s metadata maximum, wrapper critical coefficients and exactly 1 versus values just above 1. Exercise all damage categories, positive/negative health fractions, penetration with toughness, generic versus school resistance and repeated same-tick healing.

Save/reload all component timers, spend at full and empty reserves, interrupt recovery, switch shields and test damage exactly at and above the crushing limit. Check milk, general clear, harmful cleanse and natural expiry independently.

Test effect replacement and removal with extra modifiers, source-less harmful effects, friendly sources, fear application failure and ordinary versus direct-map insertion. For vulnerability upgrades, test every registered school at amplifier 0 and a higher amplifier against the configured dependency. The documentation checks do not execute these gameplay scenarios.

Related

• Attributes and effects
• Status effects
• Spell integration
• Progression runtime