Getting started

First steps

Give yourself a bundled item, change its numbers in game, hand items to players, and write a first item of your own.

This page takes a fresh install to a working item in a few minutes. It assumes the plugin started cleanly — see Installation.

Try a bundled item

Open the admin menu

Run /specialsadmin as an operator. The main screen has seven buttons: Special items, Tools, Trackers, Duel arenas, Your cooldowns, Settings and Reload.

Take an item

Open Special items and left-click Freeze. It lands in your inventory with 3 uses, shown in its name as [3/3].

Use it

Stand near another player and right-click. Everyone within 5 blocks is frozen for 3 seconds, one use is spent and a 30-second cooldown starts, shown on the action bar. With nobody in range the item says so and nothing is spent.

Change its numbers

Right-click Freeze in the item list instead. The item screen shows its limit, cooldown and features, and a Settings button. It opens a form with every value the item exposes — cooldown, uses, radius, frozen seconds — each checked against its own minimum and maximum. Save, and the item file is rewritten and the items reloaded. The lore follows the numbers: an item's lore is built from the same values its ability reads.

Items already in players' hands follow the new values at once. Only the number of uses an item started with stays as it was: a new uses value applies to items given from then on.

Hand items to players

/specialsadmin give item freeze Steve          one freeze, its default uses
/specialsadmin give item freeze Steve 5        five of them
/specialsadmin give item freeze Steve 1 USES 10   one, with 10 uses
/specialsadmin give item freeze Steve 1 TIMED 3600  one that expires in an hour
/specialsadmin giveall item freeze             one for everybody online

The console can run all of these, which is what a store or a crate should call. A full inventory does not lose the item: it waits and is handed over when the player next joins. See Commands.

Write an item of your own

Create plugins/ExyliaSpecials/lang/en/items/lightning_rod.yml (use the folder of your language):

settings:
  cooldown: {value: 20, min: 1, max: 300, name: 'Cooldown (seconds)'}
  damage: {value: 6, min: 1, max: 20, name: 'Damage'}
 
item:
  material: LIGHTNING_ROD
  name: '{primary}&lLIGHTNING ROD &8[{success}%uses%&8/{warning}%max_uses%&8]'
  display-name: '{primary}LIGHTNING ROD'
  lore:
    - ''
    - '{letters}Strikes the player you look at'
    - '{letters}for {info}${damage} {letters}damage.'
    - ''
  glow: true
  max-stack-size: 1
 
limit:
  type: USES
  amount: 5
 
cooldown:
  seconds: '${cooldown}'
 
features:
  - type: ability
    trigger: RIGHT_CLICK
    actions:
      - action: target_look
        range: 30
      - action: require
        check: '%targets_found% >= 1'
        message: '%prefix% {error}Look at a player first.'
      - action: damage
        damage: '${damage}'
      - action: play
        at: targets
        effects:
          - '[LIGHTNING]'

Run /specialsadmin reload, then /specialsadmin give item lightning_rod. Right-click while looking at a player: they take 6 damage under a lightning bolt, a use is spent and the cooldown starts. Look at nobody and the require step stops the chain — nothing is spent.

The file format is on Special items, every step on Action language, and the 70 bundled files are the best examples there are: see Bundled items.

See how items read the combat tag, now in ExyliaCombat: Combat.
Tune special item cooldowns and the action bar: Cooldowns.
Build an arena for the 1v1 item: Duels.

Something missing on this page? Tell us on Discord