> For the complete documentation index, see [llms.txt](https://mossuh.gitbook.io/projects/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mossuh.gitbook.io/projects/plugins/mopets/pet-format.md).

# Pet Format

## Pet Format

```yml
A custom code to identify the pet
Example: MagicApple
```

### Tags

Tags are used to categorize pets.

```yml
tags: Magic, Apple
```

> Tags can later be checked using PlaceholderAPI or local variables

### Booster Identifier (Coming Soon...)

When using **MoBoosters**, a pet can define a booster identifier.

```yml
booster-identifier: ExampleBoost
```

> This ensures only one booster with the same identifier is applied.

### Variables

Variables allow storing custom information inside each pet.

```yml
Format: <variable> -> <value>

variables:
  - damage -> 15
  - rarity -> legendary
```

{% hint style="info" %}
Variables can be useful for adding new information or using them for new functions with actions. For example, you can add a counter for the number of kills the player has made, and once they reach a certain number of kills, they will unlock a new ability.
{% endhint %}

#### Example

```yml
variables:
  - 'kills -> 0'
  - 'regeneration_ability -> no'
actions:
  default:
    KillsCounter:
      event: PLAYER_KILLS
      rewards:
        - '[CHANCE -> 100] SET_VARIABLE -> kills::%math_%variable_{kills}%+1%'
    RegenerationAbilityChecker:
      event: PLAYER_ATTACK
      requirements:
        - '[EVAL] %variable_{regeneration_ability}% equals no'
        - '[EVAL] %variable_{kills}% >= 1000'
      rewards:
        - '[CHANCE -> 100] SET_VARIABLE -> regeneration_ability::yes && MESSAGE -> &a&lUNLOCKED! &eUnlocked regeneration ability.'
    RegenerationAbility:
      event: PLAYER_KILLS
      requirements:
        - '[EVAL] %variable_{regeneration_ability}% equals yes'
      rewards:
        - '[CHANCE -> 50] EFFECT -> REGENERATION::3.5::2 && MESSAGE -> &a&lABILITY! &aRegeneration ability activated.'
      
```

### Upgrade System

Each pet may define its own progression.

```yml
upgrades:
  max-level: 10
  cost-per-level: 100
  message:
    progress:
      - '&7Progress: %progress%'
    maxed-progress:
      - '&aMAX LEVEL'
```

#### Options

| Option           | Description                                  |
| ---------------- | -------------------------------------------- |
| `max-level`      | Maximum level the pet can reach.             |
| `cost-per-level` | Upgrade cost formula.                        |
| `progress`       | Displayed while leveling.                    |
| `maxed-progress` | Displayed once the maximum level is reached. |

### Item Information

Every pet is represented by an item.

| Option         | Description                        |
| -------------- | ---------------------------------- |
| `material`     | Minecraft material or custom head. |
| `data`         | Legacy durability/data value.      |
| `name`         | Item display name.                 |
| `lore`         | Item description.                  |
| `unbreakable`  | Makes the item unbreakable.        |
| `enchantments` | Item enchantments.                 |
| `flags`        | Item flags.                        |

```yml
# Example

item-info:
  material: GOLDEN_APPLE
  data: 0
  name: '&6Magic Apple'
  lore:
    - '&7A magical pet.'
  unbreakable: true
  enchantments:
    - LUCK:2
  flags:
    - HIDE_ENCHANTS
```

### Pet Actions

Every pet may define one or more actions.

```yml
actions:
  # This is the supoort with MoBoosters it won't work
  # if you don't have it in your server.
  boosters:
    mine_experience:
      multiplier: BOOST_PER_LEVEL
      type: PERSONAL
      applicator: MINECRAFT
      boosted: EXPERIENCE
      boost: 0.01
  # This is the default rewards that no depend from another plugin to work.
  default:
    SpeedBoost:
      event: PLAYER_KILLS
      cooldown: 5
      cooldown_bypass: false
      cooldown_message: "&cWait %cooldown_formatted%!"
      requirements:
        - '[EVENT] ZOMBIE'
      rewards:
        - '[CHANCE -> 50] EFFECT -> SPEED:5:1'
      else:
        - '[CHANCE -> 100] MESSAGE -> &cRequirements not met.'
```

#### Available Default Options

| Option             | Description                                      |
| ------------------ | ------------------------------------------------ |
| `event`            | Minecraft event that triggers the action.        |
| `cooldown`         | Cooldown in seconds.                             |
| `cooldown_bypass`  | Executes rewards even if the cooldown is active. |
| `cooldown_message` | Message shown while on cooldown.                 |
| `requirements`     | Conditions required before executing rewards.    |
| `rewards`          | Rewards executed when requirements succeed.      |
| `else`             | Rewards executed when requirements fail.         |
| `cancel_action`    | Cancels the current action when enabled.         |

```yml
SpeedBoost:
  event: PLAYER_KILLS
  cancel_action: true
  cooldown: 5
  cooldown_bypass: false
  cooldown_message: "&cWait %cooldown_formatted%!"
  requirements:
    - '[EVENT] ZOMBIE'
  rewards:
    - '[CHANCE -> 50] EFFECT -> SPEED:5:1'
  else:
    - '[CHANCE -> 100] MESSAGE -> &cRequirements not met.'
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://mossuh.gitbook.io/projects/plugins/mopets/pet-format.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.