Skip to content

Quick Start

Welcome to Cowculator! This guide will walk you through running your first battle simulation in just a few minutes.

The /api/battle/start endpoint allows you to simulate a battle between two fighters. Each fighter has attributes, skills, and passive effects that influence the battle outcome.

  • Endpoint: POST /api/battle/start
  • Purpose: Start a new battle and retrieve a detailed BattleResult.

For technical details and full request/response schemas, see the OpenAPI Reference.

Step 1: Define Fighters

Each fighter must include required attributes and their skills.

Example Fighter 1

{
  "fighter1": {
    "fighter_id": "cow_001",
    "name": "Mighty Cow",
    "health": 1200,
    "attack": 100,
    "speed": 10,
    "skills": [
      {
        "skill_id": "1001",
        "name": "Headbutt",
        "energy_cost": 0,
        "actions": [
          {
            "action": {
              "type": "attack",
              "damage_value": 1,
              "damage_type": "normal"
            },
            "chance": 1,
            "target_type": "enemy"
          }
        ]
      }
    ],
    "default_skill": {
      "skill_id": "1000",
      "name": "Basic Attack",
      "energy_cost": 0,
      "actions": [
        {
          "action": {
            "type": "attack",
            "damage_value": 1,
            "damage_type": "normal"
          },
          "chance": 1,
          "target_type": "enemy"
        }
      ]
    }
  }
}

Example Fighter 2

{
  "fighter2": {
    "attack": 120,
    "critical_damage": 1.8,
    "critical_rate": 0.8,
    "critical_resistance": 0.1,
    "damage_multiplier": 1,
    "damage_reduction": 0.1,
    "default_skill": {
      "actions": [
        {
          "action": {
            "damage_type": "normal",
            "damage_value": 1,
            "type": "attack"
          },
          "chance": 1,
          "name": "Basic Attack",
          "target_type": "enemy"
        }
      ],
      "chance": 1,
      "energy_cost": 0,
      "name": "Basic Attack",
      "skill_id": "1000"
    },
    "defence": 3,
    "dot_reduction": 0,
    "energy": 120,
    "energy_regen_1": 0.08,
    "energy_regen_2": 0.08,
    "fighter_id": "002_wonder_dog",
    "health": 800,
    "health_regen_1": 0.01,
    "health_regen_2": 0.01,
    "name": "Wonder Dog",
    "passive": [
      {
        "name": "Vengeance",
        "passive_status": [
          {
            "chance_effect": [
              {
                "action": {
                  "damage_type": "normal",
                  "damage_value": 1.5,
                  "type": "attack"
                },
                "chance": 0.35,
                "name": "Vengeance Strike",
                "target_type": "enemy"
              },
              {
                "action": {
                  "status_to_apply": {
                    "allow_multiple": false,
                    "duration": 1,
                    "effect": {
                      "stat_data": [
                        {
                          "stat": "attack",
                          "value": 0.8
                        }
                      ],
                      "status_type": "debuff",
                      "type": "stats_down"
                    },
                    "max_stacks": 1,
                    "name": "Attack Break",
                    "removable": true,
                    "target_type": "enemy"
                  },
                  "type": "apply_status"
                },
                "chance": 0.5,
                "name": "Attack Break",
                "target_type": "enemy"
              }
            ],
            "name": "Vengeance",
            "passive_buff_type": "chance",
            "target_type": "self"
          }
        ],
        "skill_id": "2006"
      }
    ],
    "skills": [
      {
        "actions": [
          {
            "action": {
              "damage_type": "normal",
              "damage_value": 1,
              "type": "attack"
            },
            "chance": 1,
            "name": "Basic Attack",
            "target_type": "enemy"
          }
        ],
        "chance": 1,
        "energy_cost": 0,
        "name": "Basic Attack",
        "skill_id": "1000"
      },
      {
        "actions": [
          {
            "action": {
              "status_to_apply": {
                "allow_multiple": false,
                "duration": 2,
                "effect": {
                  "damage_type": "curent_health_percent",
                  "status_type": "debuff",
                  "type": "dot",
                  "value": 0.1
                },
                "max_stacks": 1,
                "name": "Poison Venom",
                "removable": true,
                "target_type": "enemy"
              },
              "type": "apply_status"
            },
            "chance": 1,
            "name": "Poison Venom",
            "target_type": "enemy"
          }
        ],
        "chance": 1,
        "energy_cost": 40,
        "name": "Poison Venom",
        "skill_id": "1005"
      }
    ],
    "speed": 12
  }
}

Step 2: Make the POST Request

Send both fighters in the body of the POST request:

curl -X POST "https://api.cowculator.dev/api/battle/start" \
     -H "Content-Type: application/json" \
     -d '{
           "fighter1": {...},
           "fighter2": {...}
         }'

Step 3: Read the BattleResult

The API will return a BattleResult object containing:

  • total_turn: Number of turns in the battle
  • winner_id: Fighter who won the battle
  • battle_event_logs: Detailed turn-by-turn log of actions, statuses, and passive

Example Response

{
  "id": "battle_123",
  "total_turn": 5,
  "fighter_id": "001_mighty_cow",
  "fighter_name": "Mighty Cow",
  "opponent_id": "002_wonder_dog",
  "opponent_name": "Wonder Dog",
  "battle_started": "2025-09-13T01:00:00Z",
  "battle_end": "2025-09-13T01:02:00Z",
  "status": "completed",
  "winner_id": "001_mighty_cow",
  "battle_event_logs": {
    "preparation": {...},
    "battle_start": {...},
    "battle_end": {...}
  }
}

Step 4: Interpreting Logs

Check out the battle_event_logs field to see what's happend during the battle.

Next Step

For full details on the request and response structure, see the OpenAPI /api/battle/start documentation.