WeaponsUltimate

Sixteen custom weapons that actually do something, and an effect library of 69 types to build your own.

---

A weapon here is an item, a few triggers and a list of effects. Hit something, get hit, kill something, right click, sneak and right click, fire a bow, land a projectile - each of those can start an ability, and an ability is any number of effects in a row, with delays, chances and repeats. Chain lightning that jumps three times, a meteor that takes a second to land, a black hole that drags everyone in, a dome that pushes attackers away: all of it is YAML, none of it is code.

Drop the jar in and you have the full arsenal, its recipes and the arsenal GUI. Write ten lines and you have your own weapon. Reload with /wu reload and it is live.

---

!The arsenal, every weapon and every recipe

Requirements

• Bukkit, Spigot, Paper, Purpur or Folia, Minecraft 1.21 up to 26.3
• Java 17 or newer

One jar for all of them. The plugin is built against the plain Bukkit API and never touches Adventure or any Paper only class, so the same file runs on Spigot. Folia is detected while the server boots and every task then goes to the region or entity thread that owns the affected chunk, which is why teleports, timers and area effects behave the same there.

What was tested, and how:

Server	What ran
Paper 1.21.1	all 16 weapons, every trigger, GUI, recipes
Paper 1.21.11	all 16 weapons, every trigger, GUI, recipes
Folia 1.21.11	all 16 weapons, every trigger, GUI, recipes
Paper 26.2	start, weapon loading, commands, reload, recipes

The first three were driven by a bot that equips every weapon, hits, right clicks, sneaks, shoots and opens the menu, with the console log checked for errors afterwards. On 26.2 the same bot cannot log in yet because its protocol library stops at 26.1, so that column is the server side only, on top of a compile run against the 26.2 API.

The arsenal

Weapon	Item	Abilities
Voidreaper	Netherite sword	Void Mark, Rift Step, Collapse
Stormbreaker	Netherite axe	Arc Chain, Thunderclap
Frostbite	Diamond sword	Deep Chill, Glacial Prison
Emberlash	Iron sword	Searing Cut, Falling Ember, Pyre
Gravewalker	Netherite hoe	Rot, Soul Harvest, Grave Tribute
Tempest	Bow	Triple Gale, Burst Arrow
Siphon Blade	Iron sword	Siphon, Backlash
Bulwark	Shield	Aegis Dome, Repel
Riftpiercer	Trident	Seeking Throw, Rift Pull
Thunderhoof	Mace	Desperate Might, Skyward, Ground Zero
Wraithfang	Iron sword	Fang Strike, Shadowstep
Sunflare	Crossbow	Flare Volley, Flashburn
Titanbreaker	Diamond axe	Sunder, Seismic Slam
Serpent's Kiss	Golden sword	Venom, Venom Bloom
Gale Edge	Diamond sword	Tailwind, Gale Dash, Updraft
Nullblade	Netherite sword	Nullify, Null Field, Cleanse

Every weapon has its own crafting recipe, its own permission and appears in the arsenal GUI.

Commands

Command	Permission	Description
/wu	weaponsultimate.gui	Opens the arsenal
/wu give <weapon> [player] [amount]	weaponsultimate.give	Hands out a weapon
/wu list	weaponsultimate.use	Lists every loaded weapon
/wu info <weapon>	weaponsultimate.use	Shows item, permission and abilities
/wu effects	weaponsultimate.admin	Lists every available effect type
/wu reload	weaponsultimate.reload	Reloads config, weapons, messages and recipes
/wu clear-cooldowns [player]	weaponsultimate.admin	Clears running cooldowns

Aliases: /weaponsultimate, /weapons, /arsenal.

Per weapon access is granted with weaponsultimate.weapon.<id>, for example weaponsultimate.weapon.voidreaper. weaponsultimate.admin bypasses all of them.

Building a weapon

weapons:
  example-blade:
    material: DIAMOND_SWORD
    name: '&b&lExample Blade'
    lore:
      - '&8Written in ten lines.'
    enchantments:
      sharpness: 2
    unbreakable: true
    damage-bonus: 1.5
    recipe:
      shape:
        - ' D '
        - ' D '
        - ' S '
      ingredients:
        D: DIAMOND
        S: STICK
    triggers:
      attack:
        name: 'Frost Cut'
        description:
          - 'Slows whoever it touches.'
        cooldown: 3
        effects:
          - type: potion
            effect: SLOWNESS
            duration: 60
            amplifier: 1
          - type: particle
            target: victim
            particle: SNOWFLAKE
            amount: 12
      right-click:
        name: 'Leap'
        cooldown: 8
        effects:
          - type: dash
            power: 1.4
          - type: slow-fall
            duration: 60

Triggers: attack, attacked, kill, death, right-click, left-click, sneak-right-click, sneak-left-click, shoot, projectile-hit, hold.

Every effect understands target, radius, angle, max-targets, players-only, delay, chance, repeat and period on top of its own keys. The complete list of effect types with all their parameters is in EFFECTS.md.

Configuration

config.yml holds the server wide switches: world black or whitelist, per weapon permissions, crafting, anvil protection, the feedback channel for cooldown and ability names, the lore generator, the GUI layout and a global damage scale for quick balancing.

messages.yml holds every string the plugin sends, including the trigger names used in the generated lore. & colour codes and &#RRGGBB hex colours are supported.

API

Weapon weapon = WeaponsUltimateApi.weapon("voidreaper");
ItemStack item = WeaponsUltimateApi.item("voidreaper");
Weapon inHand = WeaponsUltimateApi.weaponOf(player.getInventory().getItemInMainHand());

// Own effect types, registered before the next reload
WeaponsUltimateApi.effects().register("my-effect", section -> {
    double power = section.getDouble("power", 1.0);
    return context -> context.caster().setVelocity(context.caster().getVelocity().multiply(power));
});

Building from source

mvn clean package

The jar lands in target/WeaponsUltimate-<version>.jar.

License

GNU General Public License v3.0, see LICENSE.

Author

Made by LucasTHCR. Questions, ideas and bug reports: dc.gg/paperstream.