Skip to content

Staffs

Jump to bottom
Lyof429 edited this page Jul 14, 2026 · 23 revisions

< Back to homepage

Staffs are a new tiered tool type added to the game. They serve as a middle ground between full on melee (swords) and ranged (bows and crossbows) combat, by shooting an instantaneous, gravityless ray inflicting magic damage.

They have a limited range and the higher tier ones can pierce through multiple foes, but go on a cooldown after they are used.

Staffs can be set to require and consume various resources to be used. Most of the default ones use experience, but a lot more options are available. Read this page for more info.

Sortilege adds several enchantments that can be applied to staffs. Look at this page to learn more.

Cosmetic

Staffs can be died in a crafting table, just like leather armor. Dyed staffs will display a small colored socket on their handle, and their beam will be colored.

This color overrides any color enchantments would provide.

Staffs tagged as sortilege:staffs/no_dye_overlay will not have their texture altered.

Overcharge

As said above, staffs consume durability and possibly other resources when used. As a player, if you do not want to play this way, you can use a feature called overcharging.

In your inventory, right clicking with lapis lazuli on a staff (like how you would put items in a bundle) will add charges to it. When a staff is used, if it has any charge left, it will first consume it, negating other types of costs.

Overcharging configs can be set on a per staff basis. Any staff that does not provide custom overcharging logic will fall back to the following defaults:

Field Type Description
max int Maximum overcharge stored.
bar_color string, representing an hexadecimal number Color of the overcharge bar.
ignore_durability boolean Prevent durability loss while overcharged.
ignore_cost boolean Prevent the normal firing cost while overcharged.
required boolean Is overcharge required to fire. Using this, you can technically create a custom mana system.
ingredients object{string: int} Map of item ids to integers. Items whose id is in this will be usable to overcharge staffs, and the associated number is how much overcharge they give.

Configuration

1. Config file

With the default configs, you will have access to staffs made of wood, stone, iron, gold, diamond and netherite. You can add or remove any staff by using the staff configuration file, with the following format (such an object must be added to the entries * list).

This allows you to add, edit or remove any staffs you want. Staffs will be added to creative tabs according to their sort_index, in ascending order. Please feel absolutely free to obliterate the default staffs to make your own. They are how I personally play, but I am aware some people would want staffs made of amethyst, lapis and emerald, for instance.

{
  // Staff id. Must only contain lowercase letters and underscores. Used for registry, make sure all staffs are unique or the game will fail to load!
  "id": "example_staff",
  // Used to sort staffs in the creative inventory. Lower values means they'll be put sooner in the list. Leaving this blank will force the staff to be last.
  "sort_index": 42,
  // Staff type. Defines resource used as well as some other available parameters and behavior. Read [this](Staff-Configuration) for avalaible types.
  //   Can be a string representing a staff type, or an array of such strings. If an array is used, the first existing type will be used.
  "type": "sortilege:experience",
  // A mod id which must be loaded for this staff to be registered. Leaving this blank defaults to always loaded.
  "dependency": "sortilege",
  
  // Main properties. Required.
  "properties": {
    // Defines a parent vanilla tier to pull fireproof, durability, repair_material and enchantability from. Optional.
    "parent": "GOLD",
    
    // If true, the staff item will be immune to fire like Netherite items. Defaults to false.
    "fireproof": false,
    // Number of uses before the staff breaks. Required, unless you set a parent tier.
    "durability": 112,
    // An item id or tag id for this staff's repair material. Defaults to none, or the parent's if set.
    "repair_material": "minecraft:obsidian",
    // Higher values mean higher chances to get good enchantments in a table.
    "enchantability": 18,
    
    // Half hearts of damage dealt when hitting an entity with the staff's beam. Can be decimal.
    "damage": 4,
    // Maximal number of entities that can be hit in a single shot.
    "piercing": 3,
    // Range for the staff's beam, in blocks.
    "range": 12,
    // Number of ticks RMB must be held to fire. Can't be lower than 1.
    "charge_time":1,
    // Number of ticks to wait between shots.
    "cooldown": 30
  },
  
  // Defines custom cost and overcharge behavior. Optional, unless the staff type requires it.
  "cost": {
    // Custom overcharge logic. Follows the same rules and keys as the default overcharge option.
    //   If absent, the defaults will be used. If empty, prevents overcharge for this staff. If contains at least a key, partly overrides the defaults for this staff.
    "overcharge": {
      "bar_color": "#ff0000"
    },
    // This field is required by the sortilege:experience staff type.
    "value": 4
  },
  
  // Defines custom effects and behavior. Optional.
  "effects": {
    // Optional, and every command is too
    "commands": {
      // Command to fire when the staff is used, @s being the user.
      "on_shoot": "/give @s minecraft:diamond",
      // Command to fire every time an entity is hit by the beam, @s being the user.
      "on_hit_self": "/effect give @s minecraft:regeneration",
      // Command to fire every time an entity is hit by the beam, @s being the target.
      "on_hit_target": "/tp @s ~ ~2 ~"
    },
    
    // Sets built in enchantments for this staff. Values must be formatted as "namespace:enchantment": level. Optional.
    "enchants": {
      "sortilege:push": 2
    }
  },
  
  // Defines cosmetic effects. Optional.
  "display": {
    // Sets the particle used for the beam. Do keep in mind colors and velocity are the same thing according to minecraft, so be sure to set colors to #000000 if you use a non colorable particle. Optional, defaults to "sortilege:wisp".
    "particle": "sortilege:wisp",
    // Sets the sound played when the staff is used. Optional, defaults to "minecraft:block.amethyst_block.hit".
    "sound": "minecraft:block.amethyst_block.hit",
    // Sets custom beam colors for the staff. Each entry must be formatted as an hexadecimal color, and each particle will use a random one from the list.
    "colors": [
      "#ff0000",
      "#ffff00"
    ]
  },
  
  // List of recipe ids which should be disabled if the staff fails to load (be it for a missing dependency or other error). Only useful to prevent log spam.
  "recipes": [
    "sortilege:staff/example_staff"
  ]
}

Properties

The properties object controls a staff's base item stats and beam behavior.

Field Type Description
parent string, one of WOOD, STONE, IRON, GOLD, DIAMOND, NETHERITE (optional) Copies default values from a vanilla tool tier.
fireproof boolean, optional (defaults to false) Whether the staff is immune to fire and lava destruction.
durability int, required if parent is not set Maximum durability.
repair_material string, either an item or tag id Item or tag used to repair the staff.
enchantability int, required if parent is not set Vanilla enchantability value.
damage float, required if parent is not set Staff beam damage.
piercing int, required Number of targets the beam can pierce.
range int, required Beam range.
charge_time int, optional (defaults to 1) Use duration before the staff fires.
cooldown int, required Cooldown after firing.

Cost

The cost object controls what the staff consumes when fired.

Overcharge settings can also be overriden for this staff only by providing an overcharge object. Making this object empty ({}) disables overcharge for this staff.

Effects

Commands
Field Type Description
commands.on_shoot string, optional Command to fire when the staff is used, @s being the user.
commands.on_hit_self string, optional Command to fire every time an entity is hit by the beam, @s being the user.
commands.on_hit_target string, optional Command to fire every time an entity is hit by the beam, @s being the target.
Command placeholders

The following placeholders may be used in any command field. They are replaced with code values before the command is executed.

Placeholder Description
{direction.x} X component of the shooter's look direction.
{direction.y} Y component of the shooter's look direction.
{direction.z} Z component of the shooter's look direction.
Enchants
Field Type Description
enchants object{string: int} Built-in enchantments applied to the staff.

Display

Field Type Description
particle string, representing a particle id Beam particle.
sound string, representing a sound id Firing sound.
colors list{string}, each element representing an hexadecimal number Beam color list.
rarity string, one of COMMON, UNCOMMON, RARE, EPIC Item rarity override.

Here is an example of entries keeping the netherite staff, changing the beam color of the diamond one to be blue, and adding one made of amethyst:

"entries": [
  {
    "id": "diamond_staff",
    "sort_index": 50,
    "type": "sortilege:experience",
    "properties": {
      "parent": "DIAMOND",
      "damage": 5,
      "piercing": 2,
      "range": 12,
      "cooldown": 20
    },
    "cost": {
      "value": 3
    },
    "display": {
      "colors": [
        "#0000ff"
      ]
    },
    "recipes": [
      "sortilege:staff/diamond_staff"
    ]
  },
  {
    "id": "amethyst_staff",
    "sort_index": 45,
    "type": "sortilege:experience",
    "properties": {
      "durability": 351,
      "repair_material": "minecraft:amethyst_shard",
      "enchantability": 26,
      "damage": 5,
      "piercing": 2,
      "range": 10,
      "cooldown": 25
    },
    "cost": {
      "value": 4
    },
    "recipes": [
      "sortilege:staff/amethyst_staff"
    ]
  },
  {
    "id": "netherite_staff",
    "sort_index": 60,
    "type": "sortilege:experience",
    "properties": {
      "parent": "NETHERITE",
      "damage": 6,
      "piercing": 3,
      "range": 16,
      "cooldown": 25,
      "fireproof": true
    },
    "cost": {
      "value": 4
    },
    "recipes": [
      "sortilege:staff/netherite_staff"
    ]
  }
]

2. Assets

From version 7.0 and upwards, you only need to provide Sortilege with the texture of your staffs. Models and translations will be handled automatically, but you can make custom ones if you want your staffs to look or read differently from the defaults.

To give your staff a texture, create a new resource pack, and then add the following file at the specified location. Replace instances of example_staff with your staff's id (as defined in the configs):

assets/sortilege/textures/item/example_staff.png

Here goes the texture for your staff. It can be any size you want, but should stay a power of 2. Minecraft uses 16x16 for its textures, so I recommend using the same size.

You are allowed to take the texture of one of the base staffs and edit it, including in a public modpack, as long as you do not claim the texture your own.

Optional:

assets/sortilege/models/item/example_staff.json

Here goes the item model. The following will make it look the same way as the default staffs, and is what is used if you do not make such a file:

{
  "parent": "item/handheld",
  "textures": {
    "layer0": "sortilege:item/example_staff"
  }
}

assets/sortilege/lang/en_us.json

In case you want to give your staff a custom name. If not precised, this will simply default to the staff's id, but properly capitalized.

{
  "item.sortilege.example_staff": "Example Staff"
}

If you have several staffs, all the translations go in the same file. Just add more entries like the one above.

3. Data

This is required only if you want to make your staff obtainable in survival. Any implementation goes, so do whatever you prefer for this one. Here is a basic recipe like the ones used by the default staffs, with obsidian as the material.

data/sortilege/recipes/example_staff.json

{
  "type": "minecraft:crafting_shaped",
  "group": "staff/example",
  "pattern": [
    " SM",
    " SS",
    "M  "
  ],
  "key": {
    "M": {
      "item": "minecraft:obsidian"
    },
    "S": {
      "item": "minecraft:stick"
    }
  },
  "result": {
    "item": "sortilege:example_staff"
  }
}

Clone this wiki locally