⚔️ PSword

PSword lets you create custom swords with their own effects and abilities. Effects bring every hit to life with particles, sounds and lightning. Abilities change the fight: potion effects on you, your target or everyone around you, and lightning strikes that deal real damage, each with its own cooldown. Define your swords in a single config file and hand them out with a command.

Requires ParticleEngineLibrary - https://github.com/puckypucky0/ParticleEngineLibrary/tree/main

✨ Features

• Custom swords: name and lore with full MiniMessage support (gradients, rainbow, bold…)
• 3 effect types (visual)
  • 🌀 Particle: any vanilla particle, with adjustable amount
  • 🔊 Sound: any vanilla sound, with volume and pitch
  • ⚡ Lightning: visual only, deals no damage and starts no fires
• 5 ability types (gameplay)
  • 🧪 Self effect: give yourself a potion effect (Speed, Strength, Absorption…)
  • 🎯 Target effect: give your target a potion effect (Poison, Blindness, Slowness…)
  • 🌪️ Radius effect: give everyone around you a potion effect (not you)
  • ⚡ Lightning bolt: strike your target with lightning for extra damage
  • 🌩️ Radius lightning: strike everyone around you with lightning
• Per-ability cooldowns: every ability has its own cooldown, shown on the action bar with its name and remaining time
• 5 triggers
  • ON_DAMAGE_DEAL: when you hit something
  • ON_HIT_CRIT: when you land a critical hit
  • ON_KILL: when you kill something
  • ON_DAMAGE_RECEIVE: when another player hits you
  • RIGHT_CLICK: when you right-click (abilities only), so you can use active abilities whenever you want
• Smart right-click: optionally ignore right-clicks on chests, doors, buttons and other interactive blocks
• Unlimited effects and abilities per sword: mix and match any type with any trigger
• Players-only mode: limit effects and abilities to PvP, or let them work on mobs too
• Safe config: typos and invalid values are reported in the console with the sword's name, and a sensible default is used instead of breaking the plugin
• Durable identity: swords keep working after taking damage, being repaired or renamed
• Live reload: change the config and apply it with /psword reload, no restart needed
• Ready-made examples: the default config has one example sword for every effect and ability

📜 Example

swords:
  "thunder_blade":
    name: "<b><gradient:#5BC0EB:#2E4057>Thunder Blade"
    lore:
      - "<gray>Right-click to call the storm."
    material: NETHERITE_SWORD
    effects:
      - type: PARTICLE
        trigger: ON_HIT_CRIT
        particle_type: soul
        multiplier: 1.5
      - type: SOUND
        trigger: ON_HIT_CRIT
        sound: item.trident.thunder
        volume: 0.7
        pitch: 1.2
    abilities:
      - type: LIGHTNING_BOLT_RADIUS
        name: "<yellow>⚡ Storm"
        trigger: RIGHT_CLICK
        cooldown_millis: 20000
        lightning_damage: 4.0
        radius: 5
      - type: EFFECT_SELF
        name: "<red>Fury"
        trigger: ON_KILL
        cooldown_millis: 10000
        effect_type: strength
        duration_seconds: 5
        level: 1

🛠️ Commands & Permissions

/ps works as a shorter alias.

📦 Requirements

• Paper 1.21.4 minimum
• Java 21

🗺️ Roadmap

• More active abilities (dash, blink…)
• Colored particles (dust), block and item particles

💬 Source & Support

PSword is open source under the MIT license. Source code, documentation and bug reports: GitHub