# Additional Resources



# Item Syntax

BattleArena has an item format that is used for creating items in config. A few examples of where this format is used is in the [Classes](https://docs.bplug.in/books/modules-and-other-tools/page/classes) module, as well as for the [Give Item](https://docs.bplug.in/books/user-guide/page/action-reference) Action, among other places.

### Item Options

<table border="1" id="bkmrk-name-description-typ" style="border-collapse: collapse; width: 100%; height: 439.8px;"><colgroup><col style="width: 33.3333%;"></col><col style="width: 33.3333%;"></col><col style="width: 33.3333%;"></col></colgroup><tbody><tr style="height: 29.8px;"><td style="height: 29.8px;">**Name**  
</td><td style="height: 29.8px;">**Description**  
</td><td style="height: 29.8px;">**Type**  
</td></tr><tr style="height: 46.6px;"><td style="height: 46.6px;">color  
</td><td style="height: 46.6px;">The color of the item, mainly for leather armor, banners, etc.  
</td><td style="height: 46.6px;">Color:

\- #&lt;hex&gt; or &lt;rrr,ggg,bbb&gt;

</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">custom-model-data  
</td><td style="height: 29.8px;">The custom model data to use.  
</td><td style="height: 29.8px;">&lt;number&gt;  
</td></tr><tr style="height: 46.6px;"><td style="height: 46.6px;">damage  
</td><td style="height: 46.6px;">How much damage (or durability) should be applied to the item.  
</td><td style="height: 46.6px;">&lt;number&gt;  
</td></tr><tr style="height: 52.2px;"><td style="height: 52.2px;">display-name  
</td><td style="height: 52.2px;">The display name of the item (supports [MiniMessage](https://docs.advntr.dev/minimessage/index.html)).  
</td><td style="height: 52.2px;">&lt;string&gt;  
</td></tr><tr style="height: 46.6px;"><td style="height: 46.6px;">enchants  
</td><td style="height: 46.6px;">Enchants to put on the item.  
</td><td style="height: 46.6px;">Enchantment list:

\- \[&lt;enchant name&gt;:&lt;amount&gt;...\]

</td></tr><tr style="height: 46.6px;"><td style="height: 46.6px;">item-flags  
</td><td style="height: 46.6px;">The item flags to apply. See [ItemFlag](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/inventory/ItemFlag.html).  
</td><td style="height: 46.6px;">Item Flag list:

-\[&lt;item flag name&gt;...\]

</td></tr><tr style="height: 52.2px;"><td style="height: 52.2px;">lore  
</td><td style="height: 52.2px;">The lore of the item (supports [MiniMessage](https://docs.advntr.dev/minimessage/index.html)).  
</td><td style="height: 52.2px;">Lore list:

\[&lt;line&gt;...\]

</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">amount  
</td><td style="height: 29.8px;">How amount of the item.  
</td><td style="height: 29.8px;">&lt;number&gt;  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">unbreakable  
</td><td style="height: 29.8px;">Whether the item is unbreakable.  
</td><td style="height: 29.8px;">&lt;true|false&gt;  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">effects  
</td><td style="height: 29.8px;">The potion effects to apply to the item.  
</td><td style="height: 29.8px;">Potion effect list:

\- \[&lt;[potion effect](https://docs.bplug.in/books/user-guide/page/potion-effect-format)&gt;...\]

</td></tr></tbody></table>

### Single-line Format

This is the most common use of items in BattleArena, and follows a very similar format to that seen in the [Action Reference](https://docs.bplug.in/books/user-guide/page/action-reference). Note that options are separated using the semicolon (**;**).

##### Examples:

```yaml
items:
  - stone{amount=32}
  - bow{unbreakable=true}
  - arrow{amount=64}
  - diamond_sword{display-name=<yellow>Mob Slayer;lore=[Kills every mob in it''s way!];enchantments=[sharpness:10]}
```

### Configuration Node Format

While less common, this format may be seen to represent items as well. Rather than the item properties existing on a single line, they are defined over a configuration node. Here is an example of how that may look:

```yaml
my-item:
  item: golden_apple
  amount: 32
  display-name: Yummy Apple
  lore: 
    - Legends say this apple is delicious!
    - Try it for yourself!
```

# Time Format

In many places in BattleArena, a duration is specified a configuration option. Time durations are abbreviated and multiple can be chained together.

### Duration Abbreviations

- **y**: Years
- **M (uppercase):** Months
- **w:** Weeks
- **d:** Days
- **h:** Hours
- **m (lowercase):** Minutes
- **s:** Seconds

### Examples

```yaml
phases:
  countdown:
    ...
    countdown-time: 1m30s # 1 minute 30 seconds
  victory:
    ...
    duration: 5s # 5 seconds
```

# Potion Effect Format

BattleArena has an potion effect format that is used for in both creating items and applying effects to players.

### Effect Options

<table border="1" id="bkmrk-name-description-typ" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3333%;"></col><col style="width: 33.3333%;"></col><col style="width: 33.3333%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Description**  
</td><td>**Type**  
</td></tr><tr><td>duration  
</td><td>The amount of time (in ticks) to apply the effect for.  
</td><td>&lt;number&gt;  
</td></tr><tr><td>amplifier  
</td><td>How strong the effect is.  
</td><td>&lt;number&gt;  
</td></tr><tr><td>ambient  
</td><td>Whether the effect is ambient (less intrusive)  
</td><td>\[true|false\] (default: false)  
</td></tr><tr><td>particles  
</td><td>Whether the effect should show particles or not.  
</td><td>\[true|false\] (default: true)  
</td></tr></tbody></table>

### Examples

```yaml
events:
  on-start:
    - give-effects{effects=[speed{duration=300;amplifier=1},jump_boost{duration=300;amplifier=2}]}

...

events:
  on-respawn:
    - give-item{item=splash_potion{effects=[speed{duration=300;amplifier=1}]}}
```