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: | 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 [player] [amount]` | `weaponsultimate.give` | Hands out a weapon | | `/wu list` | `weaponsultimate.use` | Lists every loaded weapon | | `/wu info ` | `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.`, for example `weaponsultimate.weapon.voidreaper`. `weaponsultimate.admin` bypasses all of them. ## Building a weapon ```yaml 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](https://codeberg.org/LucasTHCR/WeaponsUltimate/src/branch/main/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 ```java 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-.jar`. ## License GNU General Public License v3.0, see [LICENSE](https://codeberg.org/LucasTHCR/WeaponsUltimate/src/branch/main/LICENSE). ## Author Made by **LucasTHCR**. Questions, ideas and bug reports: [dc.gg/paperstream](https://dc.gg/paperstream).