How to Make a Relic

OFTRelics lets you build your own relics entirely from config, with no code and no compiling. Every relic is a single YAML file describing what it looks like, how it's crafted, what it does while equipped, how it levels up, and where it drops. This page walks you through creating one from scratch and explains every option you can set.

Quick start

1. Open the OFTRelics/relics/ folder in your server files.

2. Create a new file, e.g. sunfire_band.yml. The file name becomes the relic's ID.

3. Paste in a relic config (copy _example.yml as a starting point; it documents every field).

4. Run /oftrelics reload.

5. Give it to yourself with /oftrelics give <your name> sunfire_band.

6. Equip it in /relics and check that the effects, lore and model look right.

Naming and IDs

The file name (without .yml) is the relic's ID. So sunfire_band.yml has the ID sunfire_band.

That ID is what you use in commands (/oftrelics give <player> sunfire_band), in slot supports: lists (relic:sunfire_band), and in the item lookup system as oftrelics:sunfire_band, so the relic can be a recipe ingredient, shop item or reward in any eco plugin.

The structure of a relic

A config has six logical parts, top to bottom:

Here's a complete example with everything in place:

# === General ===
name: "&6Magmatic Ring" # Fallback name, used when item.name isn't set
type: ring # Free-form; a slot accepts it with "supports: [type:ring]"
max-active: 1 # How many copies of THIS relic one player may have equipped at once
soulbound-on-equip: false # Bind on equip (see The Gameplay)
# exclude-from-commands: true # Hide the id from /oftrelics give tab completion
# drop-on-death: true # Overrides relics-gui.drop-on-death for this relic

# === Item: what the player sees ===
item:
  item: gold_nugget unbreaking:1 hide_enchants # eco item lookup string, the base item
  name: "&6Magmatic Ring"
  texture: item/magmatic_ring # Resource-pack texture (see Resource Pack)
  texture-parent: generated
  lore:
    - ""
    - "&7A ring forged in the heart of a volcano."
    - ""
    - "&c⚔ &f+%dmg% Attack Damage" # %dmg% comes from leveling.placeholders
    - "%leveling%" # Expands to the level/xp block from leveling.format

# === Crafting ===
crafting:
  enabled: true
  recipes:
    type: crafting_table
    give-amount: 1
    permission: oftrelics.craft.magmatic_ring
    shapeless: false
    recipe:
      - ""
      - blaze_rod 16
      - ""
      - blaze_rod 16
      - netherite_ingot 1
      - blaze_rod 16
      - ""
      - blaze_rod 16
      - ""

# === Effects: what the relic does while equipped ===
effects:
  - id: permanent_potion_effect
    args:
      effect: fire_resistance
      level: 1
      particles: false
      icon: false
  - id: attack_damage
    args:
      damage: "2 + (%level% - 1) * 0.5" # Scales with the relic's level

conditions: [ ] # When the relic may work while equipped ([ ] = always)

# === Leveling (optional) ===
leveling:
  xp-formula: "(2 ^ %level%) * 25"
  max-level: 5
  xp-sources:
    - trigger: melee_attack
      value: "5"
  level-up-sound: entity_player_levelup
  placeholders:
    dmg: "2 + (%level% - 1) * 0.5"

# === Loot tables: where it drops ===
loot-tables:
  - id: minecraft:chests/bastion_bridge
    chance: 0.05
  - id: minecraft:entities/blaze
    chance: 0.01

The rest of this page covers each part in detail.

General

name: "&6Magmatic Ring" # Fallback display name; item.name wins when set, then this, then the id
type: ring # Free-form type; must match a slot's supports list to be equippable. Defaults to "relic"
max-active: 1 # (Optional) Copies of this relic one player may wear at once, across all slots. Defaults to 1
soulbound-on-equip: false # (Optional) The first player to equip a copy becomes its only possible wearer. Defaults to false
exclude-from-commands: false # (Optional) Hides the id from /oftrelics give tab completion; typing it in full still works
drop-on-death: true # (Optional) Overrides relics-gui.drop-on-death for this relic; omit to use the global setting

Types are compared in lowercase. The type also groups relics into categories in the admin menu; category names come from admin-gui.categories in lang.yml.

Item

item:
  item: gold_nugget unbreaking:1 hide_enchants # eco item lookup string for the base item
  name: "&6Magmatic Ring" # Display name; supports colour codes, hex colours and placeholders

  # Resource-pack model: all optional, pick at most one
  texture: item/magmatic_ring # A PNG you provide; a model is generated from it
  texture-parent: generated # Parent for the generated model: generated (default), handheld, or a full model id
  # model: item/magmatic_ring # An existing model JSON under pack/assets/<namespace>/models/
  # definition: # A raw Minecraft item definition, written as-is
  #   model:
  #     type: minecraft:model
  #     model: oftrelics:item/magmatic_ring

  lore: # Lore lines; colour codes and eco/PlaceholderAPI placeholders work
    - "&7Any lore you want."
    - "%leveling%" # Only meaningful with a leveling: section

The base item is looked up with the item lookup system, so enchantments, flags and items from other plugins all work. If the lookup is invalid, the console warns and the relic shows as a barrier.

If the relic has a resource-pack model, the item gets that model and players with the pack see your texture; players without it, or relics whose texture file is missing, keep the base item's look. See the Resource Pack page for how texture, model and definition become pack files. If both texture and model are set, model wins and the console warns.

Lore is rebuilt every time the item is displayed, so placeholders and level values are always current. If the relic's own conditions aren't met, each condition's not-met-lines are added at the bottom.

Crafting

crafting:
  enabled: true # (Optional) Defaults to true whenever crafting.recipes is set
  recipes:
    type: crafting_table # (Optional) Defaults to crafting_table
    give-amount: 1 # (Optional) Output stack size, defaults to 1
    permission: oftrelics.craft.magmatic_ring # (Optional) Required to see and use the recipe
    shapeless: false # (Optional, crafting_table only) Defaults to false
    recipe: # (crafting_table only) 9 entries, left to right, top to bottom; "" is an empty slot
      - ""
      - blaze_rod 16 # An item lookup, optionally with an amount
      - ""

Ingredients are item lookups, so other relics (oftrelics:frost_cube) and items from other plugins can be ingredients. blaze_rod 16 means 16 blaze rods in that slot.

Other recipe types replace shapeless and recipe with their own keys. give-amount and permission work for every type:

For example, a smithing recipe:

crafting:
  recipes:
    type: smithing_table
    permission: oftrelics.craft.magmatic_ring
    template: netherite_upgrade_smithing_template
    base: gold_ingot
    addition: blaze_rod

Effects

This is the heart of the relic, i.e. what it actually does while equipped.

effects:
  - id: attack_damage # Which effect to run
    args:
      damage: 2 # Effect strength; use %level% to scale with level

conditions: [ ] # Restrict when the relic works ([ ] = always while equipped)

Each effect has an id (what it does), args (how strongly) and, for triggered effects, triggers (when it fires). Effects without triggers, like attack_damage above, are active the whole time the relic is equipped. Effects can carry their own conditions, as well as filters and mutators.

conditions restrict when the whole relic is allowed to work. An empty list [ ] means "always, while equipped". A relic whose conditions aren't met stays in its slot but does nothing until they are.

Leveling

The optional leveling: section turns the relic into a progression item: how much xp each level needs, how it earns xp, what it shows in lore, and what happens on level up. It has its own page: Leveling.

Loot tables

loot-tables:
  - id: minecraft:chests/bastion_bridge # A loot table id: vanilla, or from a datapack
    chance: 0.05 # 0 to 1; values outside are clamped and a warning is logged. Defaults to 1
    amount: 1 # (Optional) Stack size, defaults to 1
  - id: minecraft:entities/blaze # Mob loot tables work too
    chance: 0.01
    require-player-kill: true # (Optional, mobs only) Only drop when a player landed the kill. Defaults to true
    looting-bonus: 0.005 # (Optional, mobs only) Added to chance per Looting level. Defaults to 0

Each entry is rolled on its own every time the matching loot table generates, so a relic can be listed under several loot tables at different chances. With looting-bonus: 0.005 and a 0.01 chance, Looting III rolls at 0.025.

require-player-kill stops mob farms (lava, cramming, fall damage) from producing relics. An unknown loot table id logs a warning but is kept, in case a datapack adds it later.

Internal placeholders

These placeholders are provided by OFTRelics:

The lines inside leveling.format have their own placeholders (%level%, %bar%, %progress%, %xp%, %xp-required%); see Leveling.

Where to go next

• Default configs: the Default Relics are real, working examples, and their files are in OFTRelics/relics/.

• Make it level up: the Leveling guide.

• Give it a custom look: the Resource Pack page.

• Effects reference: the Configuring an Effect guide for everything the effects section can do.