> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opigno.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Start a new battle

In scope of gamification features, Opigno Enterprise API provides endpoints to implement **Battles**.
A battle consists of a predefined sequence of random questions related to the selected domain,
presented in the same order to both participants. Each question must be answered within a specified time limit.

Participants earn points based on the correctness of their answers, and (if such option is enabled in the backoffice) on the time spent.
The winner is a participant with the higher number of correct answers.
In case when the number of earned points is the same for both users, the rival who spent less time wins the battle.

## Create a battle

To start a new battle, the `createBattle` mutation should be executed. It accepts two **required** arguments:

| Argument                  | Type | Description                                                                                                                                                                                                                                      |
| :------------------------ | :--- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `domainId`                | `ID` | ID of a domain term associated with the battle. The list of the questions will be randomly generated based on the selected domain. To get the list of available options, call the [`getPossibleBattleOpponents`](#get-possible-opponents) query. |
| `opponentUserContextUuid` | `ID` | UUID of a user context associated with an opponent. To get the list of available options, call the [`getBattleDomains`](#get-available-domains) query.                                                                                           |

Here is an example of the mutation execution:

<CodeGroup>
  ```filename GraphQL Create battle mutation theme={null}
  mutation createBattle {
    createBattle(opponentUserContextUuid: "a1b2c3d4-e5f6-7890-abcd-ef1234567890", domainId: 2) {
      errors
      response {
        id
        attempt {
          cta {
            actionId
            title
            arguments {
              key
              value
            }
          }
        }
      }
    }
  }
  ```

  ```File Create battle mutation result [expandable] theme={null}
  {
    "data": {
      "createBattle": {
        "errors": [],
        "response": {
          "id": "1",
          "attempt": {
            "cta": [
              {
                "actionId": "NEXT_BATTLE_QUESTION",
                "title": "Next question",
                "arguments": [
                  {
                    "key": "battleId",
                    "value": "1"
                  }
                ]
              }
            ]
          }
        }
      }
    }
  }
  ```
</CodeGroup>

After the mutation is successfully executed, a [`Battle`](/OpignoEnterpriseAPI/Battle/GetBattle#battle-object) object will be returned.

<Note>
  The initiator's [attempt](/OpignoEnterpriseAPI/Battle/RespondToBattle#battleattempt-object) will be created automatically when a new battle is created.
  This means that the user can immediately proceed with the [take battle](/OpignoEnterpriseAPI/Battle/TakeBattle) flow.
</Note>

## Get available domains

To get the list of allowed domains that contain an appropriate number of questions,
the `getBattleDomains` query should be executed. The query returns the list of `TaxonomyTerm`
objects, sorted according to their weight configured in the backoffice:

<CodeGroup>
  ```filename GraphQL Domains query theme={null}
  query getBattleDomains {
    getBattleDomains {
      id
      name
    }
  }
  ```

  ```File Domains query result [expandable] theme={null}
  {
    "data": {
      "getBattleDomains": {
        [
          "id": "1",
          "name": "History"
        ],
        [
          "id": "2",
          "name": "Geography"
        ],
        [
          "id": "3",
          "name": "Math"
        ]
      }
    }
  }
  ```
</CodeGroup>

## Get possible opponents

A battle can be initiated only between two user contexts assigned to the same hierarchy level.
The list of possible opponents can be retrieved by calling the `getPossibleBattleOpponents` query.
Results will be returned with the pagination, sorted by the user context label,
and possibility to change the order (default sort order is ascending).

The following arguments can be used:

| Argument  | Type      | Description                                                                                                                                                   | Default |
| :-------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------ |
| `after`   | `Cursor`  | Returns results that come after the specified cursor. Should be used together with `first` parameter. Cannot be used if `before` is set.                      | —       |
| `before`  | `Cursor`  | Returns results that come before the specified cursor. Should be used together with `last` parameter. Cannot be used if `after` is set.                       | —       |
| `first`   | `Int`     | Returns up to the first N elements from the list. Required if `after` parameter is set. Cannot be used together with `last`.                                  | —       |
| `last`    | `Int`     | Returns up to the first N elements from the list. Required if `before` parameter is set. Cannot be used together with `first`.                                | —       |
| `name`    | `String`  | Allows to search by the user context label. It makes sense to use it only if the real names are sent to the API during the user context data synchronization. | —       |
| `reverse` | `Boolean` | Allows to reverse the order of the underlying list (default order is ascending).                                                                              | `false` |

The query returns a paginated list of `BattleRival` objects:

<CodeGroup>
  ```filename GraphQL Opponents query theme={null}
  query getPossibleBattleOpponents {
    getPossibleBattleOpponents(first: 10, name: "John") {
      edges {
        node {
          id
          uuid
          displayName
        }
      }
      totalItems
    }
  }
  ```

  ```File Opponents query result [expandable] theme={null}
  {
    "data": {
      "getPossibleBattleOpponents": {
        "edges": [
          "node": {
            "id": "1",
            "uuid": "1234abcd-5e67-8900-123b-92f88908df44",
            "displayName": "John Doe"
          },
          "node": {
            "id": "14",
            "uuid": "0abc1de2-3f35-6789-012b-01a23456bc67",
            "displayName": "John Raynolds"
          }
        ],
        "totalItems": 2
      }
    }
  }
  ```
</CodeGroup>

## Related Features

<CardGroup cols={2}>
  <Card title="Pagination" icon="arrow-right" href="/OpignoEnterpriseAPI/PaginatingCatalogItems">
    Learn how to efficiently navigate through large sets of items using cursor-based pagination.
  </Card>

  <Card title="Take a battle" icon="arrow-right" href="/OpignoEnterpriseAPI/Battle/TakeBattle">
    Now, when the initiator's attempt is created, the user can take the battle.
  </Card>
</CardGroup>