WeaponsUltimate

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.

Requirements

• Bukkit, Spigot, Paper, Purpur or Folia, Minecraft 1.21 up to 26.2
• 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:

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

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

Commands

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.