Understanding BattleResult

The BattleResult object is returned by /api/battle/start and summarises the outcome of the battle. It contains fighter details, turn-by-turn logs, and the winner.

Fields to know:

• total_turn – number of turns in the battle.
• fighter_id / opponent_id – identifiers of the participants.
• winner_id – ID of the winning fighter.
• battle_event_logs – detailed event logs.

Interpreting battle_event_logs

Battle logs are captured in the battle_event_logs field. Every action, status change, and outcome in the battle — so you can replay, animate, or analyze the fight in your game.

Battle logs are returned as a nested JSON object. Each section represents a phase or turn in the battle, and every event is timestamped and categorized for easy parsing.

3 Phases of battle

A battle log is organized into 3 distinct phases, each representing a key stage in the battle lifecycle:

Preparation

Turn 0. The initial phase before combat begins. This includes passive skills and effects applied to each fighter, setting up the conditions for the battle.

Battle Start

The main phase where the battle unfolds turn by turn. Each turn records all actions, status changes, damage, healing, and other events performed by the fighters.

Iterate through each numbered key in battle_start. Inside each battle turn, you'll find:

• turn_start and turn_end: Each contains passive statuses, statuses, event type, description, and a list of fighter_events at the current turn.
• fighter_events: Fine-grained actions (damage, healing, skill execution, etc.)

Battle End

The final phase summarizing the outcome of the battle, including the winner, reason for victory, and any concluding events.

Info

This structure ensures that every aspect of the battle is captured in a clear, chronological sequence, making it easy to replay, analyze, or visualize the entire encounter.

Example (Simplified)

Here’s a typical battle log structure:

{
  "id": "1755340138.214681",
  "total_turn": 12,
  "fighter_id": "warrior_001",
  "fighter_name": "Warrior",
  "opponent_id": "assassin_001",
  "opponent_name": "Assassin",
  "battle_started": "2025-08-16T10:28:58.231978",
  "battle_end": "2025-08-16T10:28:58.231978",
  "status": "completed",
  "winner_id": "assassin_001",
  "battle_event_logs": {
    "events": {
      "preparation": {
        "0": [
          {
            "fighter_id": "warrior_001",
            "events": {
              "apply_passive_status": [...]
            },
            "timestamp": "2025-08-16T10:28:58.231689"
          },
          {
            "fighter_id": "assassin_001",
            "events": {
              "apply_passive_status": [...]
            },
            "timestamp": "2025-08-16T10:28:58.231697"
          }
        ]
      },
      "battle_start": {
        "1": [ ...turn 1 events... ],
        "2": [ ...turn 2 events... ],
        // ...more turns...
      },
      "battle_end": {
        "description": "Battle ended. Warrior has 0 HP. Winner: assassin_001."
      }
    }
  }
}

Info

For full schema details, see OpenAPI BattleResult.

Fighter's Event Types

Battle logs use event types to categorize what happened. These are found in the event_type field of each fighter's event.

Event Type	Description
action_missed	Skill action chance not triggered
apply_passive_status	Passive skill effect applied during preparation
apply_status	Status effect applied (buff/debuff)
deal_damage	Fighter deals damage
dot_damage	Damage over time applied
energy_regeneration	Energy regenerated at turn end
execute_skill	Skill executed
health_regeneration	Health regenerated at turn end
heal	Fighter heals
receive_damage	Fighter receives damage
replace_status	Status effect replaced
remove_status	Status effect removed
shield_absorption	Shield absorbs damage
shield_update	Shield value changes (gain/loss)
skill_missed	Skill chance not triggered

Event Description Format

Every event in the battle log includes a description field. It summarizes what happened, intended for display to fighters or further process it programmatically to show in the game and logging.

Description Patterns

Descriptions may look like:

• "Assassin executes Basic Attack."
• "Assassin dealt 165 damage to Warrior (Critical Hit) [835/1000]"
• "Assassin regenerated 16 health."
• "Battle ended. Warrior has 0 HP. Winner: assassin_001."

Event Description Reference

See Event Type and Description for the full event type and the description format.

Practical Use Cases for Event Types

Event Type	Practical Use Case / Example UI Action
action_missed	Show "Miss" text, play dodge/evasion animation and sound effect
apply_passive_status	Show passive icon/badge, apply persistent stat display (e.g. +DEF)
apply_status	Display status icon with duration and stat changes (e.g. Attack Up)
deal_damage	Update HP bar, play hit animation, show floating damage value
dot_damage	Apply periodic HP reduction, show DOT icon and damage ticks
energy_regeneration	Update energy bar, show small particle/number (+value) over fighter
execute_skill	Play skill animation/VFX, show skill name and targeting highlight
heal	Update HP bar, play heal animation and show floating heal value (+N)
health_regeneration	Increment HP over time UI, small regen animation and text feedback
receive_damage	Flash character, subtract HP and show source/amount (hit SFX)
replace_status	Swap status icons, animate replacement effect and tooltip update
shield_absorption	Animate shield absorbing damage, show absorbed numeric value
shield_update	Update shield bar/overlay and show gain/loss animation
skill_missed	Show "Miss" text, play miss animation and optional taunt/sfx
remove_status	Remove status icon, play expire animation and revert visible stat delta

Tip

• Parse the logs turn by turn to synchronize game visuals with the actual battle sequence.
• Use event types to trigger specific animations or sound effects.
• Leverage status and passive status fields to show buffs/debuffs visually.
• The logs are designed to be replayable and deterministic — you can show the same battle multiple times with consistent results.

---