Battle Event

Battle events describe observable occurrences such as skill execution, damage, healing, and status changes. Each event contains:

• event_type: the stable discriminator used to select the event shape
• description: human-readable display text
• data: structured facts for that event type

Use structured data

Use event_type and data for application logic. Do not parse description. Its wording may change without changing the event contract.

For example, an action_missed event identifies the action, source, configured target scope, and chance. It has no resolved target ID because the chance check happens before target resolution:

{
  "event_type": "action_missed",
  "description": "Heavy hit did not trigger.",
  "execution_id": "heavy_strike_f1_s0_t1_ft1",
  "action_execution_id": "heavy_strike_f1_s0_t1_ft1_a0",
  "data": {
    "source_id": "fighter-1",
    "source_name": "Attacker",
    "action_source": {
      "type": "active_skill",
      "skill_id": "heavy-strike",
      "skill_name": "Heavy Strike",
      "active_skill_index": 0,
      "used_fallback_skill": false,
      "action_index": 0
    },
    "action_name": "Heavy hit",
    "action_type": "attack",
    "target_type": "enemy",
    "configured_chance": 0.8
  }
}

Looking for exact fields?

Use the OpenAPI reference for every field available on each event. This page focuses on meaning and common client uses.

Skill and action events

Event type	Meaning	Typical client use
execute_skill	An active or fallback skill was selected. For an active skill, its energy cost was applied.	Start the skill animation and update energy when an active skill runs.
execute_passive_action	A passive trigger is executing one of its actions.	Show the passive source before its effects.
skill_missed	The selected skill failed its chance check.	Show a skill-level miss and skip its actions.
action_missed	One action failed its single chance check before targets were resolved.	Show one action-level miss. Later actions may continue.
action_no_effect	A status action passed its chance check, but its target was already knocked out.	Keep the skill replay in sequence without changing status state.

execute_passive_action is distinct from execute_skill: it identifies the passive trigger and action that caused the subsequent effects.

Direct damage, healing, missed actions, and no-effect actions include action_source. Its type distinguishes active_skill (including fallback skills) from passive_trigger. Use the skill identity or runtime trigger identity to connect an effect to its origin.

Events emitted during an active or fallback skill execution, or during a passive trigger's actions, carry an execution_id. Events for one attempted action also carry an action_execution_id. Both IDs are top-level event fields. Use them to group related events, including an action affecting multiple targets. Independent lifecycle events, such as apply_passive_trigger, DOT ticks, regeneration, and natural status expiry, have no execution context and may omit these IDs.

Source metadata adds stable zero-based positions such as active_skill_index, passive_skill_index, trigger_index, and action_index, so clients do not have to infer configuration identity from names or optional, non-unique skill IDs. A fallback source uses active_skill_index: null and used_fallback_skill: true.

When an active skill continues after knocking out its opponent, later actions still produce replayable events. Attacks and heals use their normal event types with an applied amount of 0. Applying or removing a status produces action_no_effect with reason: "target_knocked_out". A failed chance check is resolved first and produces action_missed instead.

Damage, healing, and shield events

Event type	Meaning	Typical client use
deal_damage	Direct attack damage was resolved.	Animate the hit and update health and shields.
dot_damage	A damage-over-time status damaged its target.	Animate the status tick and health change.
heal	A skill or modifier restored health or energy.	Animate restoration and update the resource.
shield_changed	Shield contributions changed through application, replacement, removal, or damage absorption.	Update individual shields and the combined shield bar.
energy_regeneration	End-of-turn energy regeneration was applied.	Update energy from turn_end.events.
health_regeneration	End-of-turn health regeneration was applied.	Update health from turn_end.events.

Note

There is no separate receive_damage event. deal_damage and dot_damage already identify the target and resulting health change.

For dot_damage, damage_calculated is the whole-number damage after DOT reduction and rounding. damage_applied is the health actually lost, bounded by remaining health. Use the applied amount to update the health bar.

For shield_changed, data.trigger.type explains why the shield changed. data.statuses records each affected runtime status and its nested shield_contribution transition. data.aggregate_shield gives the combined before, change, and after values. Apply this transition once, even when a later deal_damage event also reports the amount absorbed by shields.

Status and passive events

Event type	Meaning	Typical client use
apply_passive_trigger	A passive trigger was applied during preparation.	Add its passive indicator.
apply_status	A buff or debuff was applied.	Add the new status instance and update the displayed stack count.
apply_status_rejected	A stack-policy status was rejected because it was already at maximum stacks.	Show rejection without changing the existing statuses.
replace_status	A replace-policy status replaced an existing same-name instance.	Replace the old status identity with the new one.
remove_status	A status was removed, expired, or depleted, or a removal action found no matching status.	Branch on the outcome and cause before updating statuses.

apply_passive_trigger identifies the trigger's owner with owner_id and owner_name. Applying a trigger does not itself target a fighter with an action.

Status identities matter during replay. Use the IDs in structured data rather than matching display names or descriptions.

For replace_status, data.reason: "replace_policy" identifies replacement by the active same-name group's policy.

For remove_status, branch on data.outcome first. When the outcome is removed, use data.cause to distinguish removal_action, duration_expired, or shield_depleted. Natural expiry events use cause: "duration_expired" and appear in turns[].turn_end.events.

An action with no eligible status reports no_removable_status_matched in data.outcome. It does not change status state. An empty type_to_remove is rejected by request validation before a battle starts.

Where events appear

Battle events are grouped by when they occur:

Event array	What it contains
preparation[].events	Effects applied while preparing one fighter
turns[].events	Skill, action, damage, healing, status, shield, and passive events processed before turn end
turns[].turn_end.events	Energy regeneration, health regeneration, and natural status expiry processed at turn end

Process each array in its returned order. Within a turn, process events first, followed by turn_end.events. Then reconcile the fighter snapshots in turn_end.state.

See Understanding BattleResult for the replay order and the difference between battle_turn and actor_turn.

---