> For the complete documentation index, see [llms.txt](https://mdswork.gitbook.io/ragemode-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mdswork.gitbook.io/ragemode-docs/guides/custom-items.md).

# Custom items

RageMode allows you to create, append and give custom items that can be used in RageMode GUIs or for rewarding players. These items can contain enchantments, custom model data, flags, potion, book, banner and all item meta related components.

### Examples

You need to manually edit the configuration `custom-items.yml` file to create an item.

<pre class="language-yml"><code class="lang-yml">my-firework:
<strong>  item: firework_rocket
</strong>  firework:
    power: 2
    one: # Section name, can be anything
      type: star
      flicker: true
      trail: true
      colors:
        primary:
        - 155,242,174,247
        fade:
        - 72,248,107,51
</code></pre>

This will creates a firework rocket with power 2, pre-configured colours, type, flicker and trail option as well. You can mix types, colours with this firework, just create another section with a different name.

```yml
unique_pickaxe:
  item: diamond_pickaxe
  display-name: <dark_green>Pickaxe
  quantity: 1
  unbreakable: true
  lore:
  - <aqua>This pickaxe is unbreakable
  - <green>Use it wisely!
  enchantments:
  - efficiency:3
```

This will creates a diamond pickaxe item with a unique display name, lore, unbreakable state and efficiency level 3 enchantment.

***

Once you created the item, you can use this anywhere within the plugin where custom items are allowed and specify the name `my-firework` for firework or `unique_pickaxe` for diamond pickaxe to append this item.

### Item properties

If you have a small knowledge about item meta, refer to [ItemMeta](https://jd.papermc.io/paper/org/bukkit/inventory/meta/ItemMeta.html) docs page to learn what an item can contain.

#### `item` (Required)

Defines the [material](https://jd.papermc.io/paper/org/bukkit/Material.html) for this item. This is the only required option to get the item in game.

#### `display-name`

The display name text that appears for this item. Customise the [text formatting](https://docs.papermc.io/adventure/minimessage/format/) to your liking.

#### `lore`

List of lore text for ths item. Customise each line [text formatting](https://docs.papermc.io/adventure/minimessage/format/) to your liking.

#### `custom-plugin-item`

Applies a custom [supported plugin](https://mdswork.gitbook.io/ragemode-docs/getting-started.md#dependencies) item which can replace the behaviour, display name, lore and all related metadata.

```yml
name:
  custom-plugin-item: nameOfItem
```

#### `item-flags`

List of [item flags](https://jd.papermc.io/paper/org/bukkit/inventory/ItemFlag.html) to apply on this item.

<pre class="language-yml"><code class="lang-yml">name:
  item-flags:
<strong>  - hide_enchants
</strong>  - hide_attributes
</code></pre>

#### `quantity`

The total amount of this item it gives for the player.

```yml
name:
  quantity: 2
```

#### `unbreakable`

Sets [unbreakable](https://minecraft.wiki/w/Data_component_format#unbreakable) state for this item, when enabled, the item cannot lose durability when used.

```yml
name:
  unbreakable: true
```

#### `enchantments`

List of [enchantments](https://minecraft.wiki/w/Data_component_format#enchantments) with levels to apply on this item.

```yml
name:
  enchantments:
  - knockback:2
  - unbreaking:2
```

#### `firework`

Firework settings for [firework rocket](https://minecraft.wiki/w/Firework_Rocket) item.

```yml
name:
  item: firework_rocket
  power: 2
  first:
    type: ball
    flicker: false
    trail: true
    colors:
      primary:
      - red
      fade:
      - 61,271
  second:
    type: star
    flicker: true
    trail: true
    colors:
      primary:
      - green
      fade:
      - 49,287,65
      - blue
```

#### `color`

The [color](https://minecraft.wiki/w/Data_component_format#dyed_color) of the leather armour.

```yml
name:
  item: leather_leggings
  color: 225
```

#### `effects`

List of [potion effects](https://minecraft.wiki/w/Data_component_format#potion_contents) for the potion item.

```yml
name:
  item: potion
  effects:
  - regeneration amplifier=1 duration=120 particles=true ambient=true icon=true
  - speed duration=60 icon=true
```

```yml
name:
  item: potion
  data:
    base-type: healing
    color: ''
    effects:
    - regeneration amplifier=2 duration=140
    - resistance particles=false
```

#### `banner-patterns`

[Patterns](https://minecraft.wiki/w/Data_component_format#banner_patterns) designed for banner-only items.

<pre class="language-yml"><code class="lang-yml"><strong>name:
</strong><strong>  item: white_banner
</strong>  banner-patterns:
  - red diagonal_right
  - black stripe_downleft
</code></pre>

#### `max-stack`

The [maximum stack](https://minecraft.wiki/w/Item#Stacking) of the item.

```yml
name:
  item: snowball
  max-stack: 8
```

#### `item-name`&#x20;

(Paper only) Defines the [item name](https://jd.papermc.io/paper/org/bukkit/inventory/meta/ItemMeta.html#itemName\(\)) of the item. Customise the [text formatting](https://docs.papermc.io/adventure/minimessage/format/) to your liking.

```yml
name:
  item: iron_sword
  item-name: ironed sword
```

#### `use-remainder`

Replaces the item with a remainder item if its stack count has decreased after use. Read more at [wiki](https://minecraft.wiki/w/Data_component_format#use_remainder)

```yml
name:
  item: iron_axe
  use-remainder: gunpowder
```

#### `durability`

Sets the [damage](https://minecraft.wiki/w/Data_component_format#damage) (durability) of the item. `-1` for no set, can range from 0 and higher.

```yml
name:
  item: stone_sword
  durability: -1
```

#### `max-damage`

The [maximum amount of damage](https://minecraft.wiki/w/Data_component_format#max_damage) that this item can take. `-1` for not set, can range from 0 and higher.

```yml
name:
  item: iron_shovel
  max-damage: 0
```

#### `custom-model-data`

(Legacy) Sets a [custom model data](https://minecraft.wiki/w/Data_component_format#custom_model_data) value for this item.

```yml
name:
  item: diamond
  custom-model-data: 45321
```

`custom-model-data-component`

(Modern) Sets a custom model data component for this item.

```yml
name:
  item: diamond
  custom-model-data-component:
    colors:
    - red,green
    strings:
    - xx
    flags:
    - true
    floats:
    - 4
```

#### `shield-color`

Sets the [colour](https://minecraft.wiki/w/Data_component_format#base_color) of the shield item

```yml
name:
  item: shield
  shield-color: orange
```

#### `skull.texture-url`

Sets a texture for the skull item, specify an [UUID](https://minecraft.wiki/w/UUID) of a [registered player](https://textures.minecraft.net/texture/61d644761f706d31c99a593c8d5f7cbbd4372d73fbee8464f482fa6c139d97d4).

```yml
name:
  item: player_head
  skull:
    texture-url: 61d644761f706d31c99a593c8d5f7cbbd4372d73fbee8464f482fa6c139d97d4
```

#### `skull.base64`

Sets a base64 texture data for the skull item.

```yml
name:
  item: player_head
  skull:
    base64: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNTIyODRlMTMyYmZkNjU5YmM2YWRhNDk3YzRmYTMwOTRjZDkzMjMxYTZiNTA1YTEyY2U3Y2Q1MTM1YmE4ZmY5MyJ9fX0=
```

#### `skull.player-name`

Sets texture data from the defined [player name](https://minecraft.wiki/w/Player#Username) of the skull item if present.

```yml
name:
  item: player_head
  skull:
    player-name: Steve
```

#### `potion-duration-scale`

Sets a [potion duration scale](https://minecraft.wiki/w/Data_component_format#potion_duration_scale) value for the potion. `-1` for no set

```yml
name:
  item: potion
  potion-duration-scale: -1
```

#### `enchantment-storage-meta`

Sets inactive [enchantments storage](https://minecraft.wiki/w/Data_component_format#stored_enchantments) for the item. Contains a map of inactive [enchantments](https://minecraft.wiki/w/Enchantment) and their levels.

```yml
name:
  item: iron_pickaxe
  enchantment-storage-meta:
  - unbreaking:2
```

#### `book`

Creates a [writable book](https://minecraft.wiki/w/Data_component_format#writable_book_content) item with their configurations

```yml
name:
  item: writable_book
  book:
    title: "<gray>Title"
    generation: original
    author: yourName
    pages:
    - text
    - text2
```

#### `trim`

[Trim](https://minecraft.wiki/w/Data_component_format#trim) configurations for armors. Contains the trim applied to this [armor](https://minecraft.wiki/w/Armor) piece.

```yml
name:
  item: leather_leggings
  trim:
    material: emerald
    pattern: host
```

#### `bundle-contents`

The items stored inside this [bundle](https://minecraft.wiki/w/Data_component_format#bundle_contents). Define existing item names created in this file. Make sure to bring those items before this bundle item.

```yml
name:
  item: bundle
  bundle-contents:
  - itemName
  - customItemName
```

#### `glint-override`

Overrides the enchantment [glint](https://minecraft.wiki/w/Data_component_format#enchantment_glint_override) (glowing) effect on this item.

```yml
name:
  item: stone
  glint-override: true
```

#### `glider`

If enabled, this item allows living entities to [glide](https://minecraft.wiki/w/Data_component_format#glider) (as with [elytra](https://minecraft.wiki/w/Elytra)) when equipped.

```yml
name:
  item: elytra
  glider: true
```

#### `enchantable`

If this and [`minecraft:enchantments`](https://minecraft.wiki/w/Data_component_format#enchantments) are present on an item, and applicable enchantments are available, the item [can be enchanted](https://minecraft.wiki/w/Data_component_format#enchantable) in an enchanting table. A higher value allows enchantments with a higher cost to be picked.

```yml
name:
  item: elytra
  enchantable: 15
```

#### `repair-cost`

The number of experience levels to add to the base level cost when [repairing, combining, or renaming](https://minecraft.wiki/w/Data_component_format#repair_cost) this item with an anvil. `-1` to unset

```yml
name:
  item: iron_axe
  repair-cost: -1
```

#### `hide-tooltip`

Allows the [tooltips](https://minecraft.wiki/w/Data_component_format#tooltip_display) provided specifically by any given item component to be suppressed (hidden). Set to true to completely hide any tooltip whatsoever. Or use a list of [tooltip component](https://jd.papermc.io/paper/io/papermc/paper/datacomponent/DataComponentTypes.html) to be hidden.

```yml
name:
  item: chest
  hide-tooltip: true
```

```yml
name:
  item: chest
  hide-tooltip:
  - minecraft:enchantments
```

#### `tooltip-style`

The custom [tooltip style](https://minecraft.wiki/w/Data_component_format#tooltip_style) and background for this item.

```yml
name:
  item: diamond
  tooltip-style: minecraft:style
```

#### `item-model`

The [identifier](https://minecraft.wiki/w/Identifier) of an [item model definition](https://minecraft.wiki/w/Item_model_definition)

```yml
name:
  item: emerald
  item-model: minecraft:diamond
```

#### `rarity`

Sets the [rarity](https://minecraft.wiki/w/Rarity) of this item, which affects the default colour of its name

```yml
name:
  item: iron_sword
  rarity: epic
```

#### `food-component`

If present and the [`consumable`](https://minecraft.wiki/w/Data_component_format#consumable) component are also present on this item, [foxes](https://minecraft.wiki/w/Fox) consider the item as consumable [food](https://minecraft.wiki/w/Data_component_format#food).

```yml
name:
  item: steak
  food-component:
    always-eat: false
    nutrition: 0
    saturation: 0
```

#### `jukebox-song`

One [jukebox song](https://minecraft.wiki/w/Data_component_format#jukebox_playable) to play when inserted into a jukebox.

```yml
name:
  item: jukebox
  jukebox-song: pigstep
```

#### `music-instrument`

One music [instrument](https://minecraft.wiki/w/Data_component_format#instrument) to play when goat horn item is used.

```yml
name:
  item: goat_horn
  music-instrument: feel_goat_horn
```

#### `break-song`

One [server-side sound event](https://minecraft.wiki/w/Data_component_format#break_sound) to play when the item runs out of durability and breaks.

```yml
name:
  item: diamond_sword
  break-song: item.wolf_armor.break
```

#### `attributes`

A list of [attribute modifiers](https://minecraft.wiki/w/Data_component_format#attribute_modifiers) which, if present on an item, may be applied to a player or mob that has equipped the item.

`name` - Key name (`minecraft:name`) or [UUID](https://minecraft.wiki/w/UUID)

```yml
name:
  item: iron_axe
  attributes:
    attack_damage:
      operation: add_number
      equipment-slot: hand
      amount: 0.0
      name: ""
    attack_knockback:
      operation: add_number
      equipment-slot: hand
      amount: 1.0
      name: ""
```
