SMPWeapons Wiki

Overview

What SMPWeapons does

SMPWeapons turns YAML weapon definitions into usable in-game items. Each weapon can define item metadata, material fallbacks, legacy matching rules, commands, cooldowns, triggers, abilities, passive effects, projectiles, particle shapes, temporary blocks, and menus.

Config-driven weapons

Weapons live under the configured weapons folder. Bundled files include default, more, client-requested, custom, and examples.

Ability engine

Built-in ability types cover dash, lift, slam, zoom, poison, projectile, self-buff, timeline, inventory passive, totem pop, and shield block flows.

Server-friendly controls

Cooldowns, optional per-weapon permissions, region denial through SMPRegions, menu click throttling, virtual block caps, and engine limits are configured centrally.

Quick start

Installation

Place the SMPWeapons jar in your server plugins/ folder.
Start the server once so default files generate.
Edit plugins/SMPWeapons/config.yml, menus.yml, messages.yml, and files under weapons/.
Run /smpweapons reload.
Use /smpweapons menu, /smpweapons get <weapon>, or dynamic menu commands such as /ffaweapons when enabled.

# Basic admin flow
/smpweapons list
/smpweapons get dash_sword
/smpweapons give Steve rocket_spear 1
/smpweapons reload

Production rule: keep custom weapons in weapons/custom-weapons.yml or your own extra file. Do not edit defaults unless you are fine with replacing them during updates.

Compatibility

Requirements and compatibility

Server platform

The plugin descriptor targets Bukkit-family servers with api-version: 1.13 and declares folia-supported: true. Material aliases let one config use modern and fallback materials.

Optional hook

SMPRegions is listed as a soft dependency. When enabled, weapon use can be denied in regions where PvP is denied or in explicit blacklisted regions.

# plugin.yml highlights
commands:
  smpweapons:
    aliases: [smpweapon, weapons]
softdepend:
  - SMPRegions
folia-supported: true

Commands

Admin and player commands

Command	Purpose	Permission
`/smpweapons help`	Show command help.	`smpweapons.use`
`/smpweapons menu [menu]`	Open a configured weapon menu. Defaults to the configured default menu.	`smpweapons.menu`
`/smpweapons list`	List enabled weapons loaded from the weapons folder.	`smpweapons.list`
`/smpweapons get <weapon> [amount]`	Give yourself a weapon by id.	`smpweapons.get`
`/smpweapons give <player> <weapon> [amount]`	Give another player a weapon.	`smpweapons.give`
`/smpweapons create <weapon>`	Save the item in your hand into the custom weapons file.	`smpweapons.create`
`/smpweapons delete <weapon>`	Remove a custom weapon entry.	`smpweapons.delete`
`/smpweapons cooldown [player] [weapon\|all]`	Reset all cooldowns or one weapon cooldown.	`smpweapons.cooldown`
`/smpweapons debug item\|blocks\|restoreblocks\|validate`	Inspect identity, temporary blocks, restoration, and config validity.	`smpweapons.debug`
`/smpweapons reload`	Reload config, menus, messages, and weapons.	`smpweapons.reload`

Permissions

Permission reference

Most permissions default to operator in the plugin descriptor. Enable settings.require-use-permission when every weapon use should be permission-gated.

Permission	Meaning
`smpweapons.use`	Base access to /smpweapons.
`smpweapons.admin`	Administrative umbrella permission.
`smpweapons.menu`	Open weapon menus.
`smpweapons.menu.admin`	Open the admin weapon menu.
`smpweapons.menu.ffa`	Open the FFA weapons menu.
`smpweapons.command.ffaweapons`	Use the dynamic FFA menu command when registered.
`smpweapons.list`	List enabled weapons.
`smpweapons.get`	Get weapons for yourself.
`smpweapons.give`	Give weapons to other players.
`smpweapons.create`	Create custom weapon entries from held items.
`smpweapons.delete`	Delete custom weapon entries.
`smpweapons.cooldown`	Reset cooldowns.
`smpweapons.reload`	Reload plugin files.
`smpweapons.debug`	Use debug/admin inspection tools.
`smpweapons.bypasscooldown.*`	Bypass weapon cooldowns when cooldown bypass is enabled.
`smpweapons.weapon.*.use`	Use all weapons when per-weapon use permission is required.
`smpweapons.weapon.<id>.use`	Use one weapon when per-weapon use permission is required.
`smpweapons.weapon.*.get`	Get all weapons where per-weapon get permission is checked.
`smpweapons.weapon.*.give`	Give all weapons where per-weapon give permission is checked.

Configuration

Config file map

`config.yml`

Main settings, menu defaults, weapon folder, cooldown behavior, item protection, hooks, sounds, engine limits, virtual/real block behavior, material compatibility, dynamic command registration, and tab completion.

`menus.yml`

Admin and FFA menu layouts, titles, permissions, command registration, filler items, weapon slots, click actions, and pagination.

`messages.yml`

MiniMessage-ready player/admin messages, help text, cooldown notices, menu titles, and errors.

`weapons/*.yml`

Weapon definitions. Loaded from the configured folder, sorted by filename. Duplicate ids require override: true.

Important main settings

settings:
  default-menu: admin
  weapons-folder: weapons
  custom-weapons-file: weapons/custom-weapons.yml
  give-created-weapons-pdc-identity: true
  detect-legacy-items: true
  require-sneak-for-default-abilities: true
  require-use-permission: false
  cooldown-bypass-enabled: false
commands:
  register-dynamic-commands: true
  intercept-unknown-menu-commands: true
  update-tab-completion: true

Weapon YAML

Weapon definition format

A weapon id must be normalized as lowercase letters, numbers, and underscores. Each weapon should define enabled state, display id, item metadata, optional legacy matchers, commands, cooldowns/triggers, and either a built-in ability type or timeline DSL.

weapons:
  dash_sword:
    enabled: true
    display-id: 'Dash Sword'
    item:
      material: [NETHERITE_SWORD, DIAMOND_SWORD]
      name: '<gradient:#D2DBF1:#75777A><bold>Dash Sword</bold></gradient>'
      lore:
        - '<gray>Shift + right click to dash forward.'
      custom-model-data: 23425
      enchants: ['DAMAGE_ALL:5', 'DURABILITY:3']
    legacy:
      custom-model-data: 23425
      names-contains: ['Dash Sword']
    commands:
      get: ['getdashsword']
    trigger:
      type: SNEAK_RIGHT_CLICK
      cooldown: 30
    ability:
      type: DASH_AOE
      upward: 0.5
      forward: 2.5
      burst-radius: 3.0
      damage: 2.0

Activation

Triggers, conditions, cooldowns

The source supports a legacy single trigger block and a modern multi-trigger triggers block. Use the modern structure when a weapon needs multiple actions, named cooldowns, bow/crossbow events, totem pop events, or alternate left/right click behavior.

Common events

RIGHT_CLICK, LEFT_CLICK, BOW_SHOOT, TOTEM_POP, DAMAGE_DEALT, HIT, SHIELD_BLOCK, and INVENTORY_TICK appear in bundled configs.

Common conditions

SNEAKING, NOT_SNEAKING, MAIN_HAND, FULL_ATTACK_COOLDOWN, and HAS_PERMISSION:node are used by active or example flows.

cooldowns:
  primary: { seconds: 30 }
  alternate: { seconds: 10 }
triggers:
  primary:
    events: [RIGHT_CLICK]
    conditions: [SNEAKING, MAIN_HAND]
    cooldown: primary
    timeline: cast_projectile
  quick_left:
    events: [LEFT_CLICK]
    conditions: [SNEAKING, MAIN_HAND]
    cooldown: alternate
    timeline: quick_burst

Ability DSL

Timeline DSL

ability.type: TIMELINE lets you schedule actions by tick. Keys can be a single tick or a range expression such as '10..30 step 5'. Timeline actions run on the owning player/entity scheduler path.

Visuals

sound, particle, particle_shape, beam, message, actionbar, title.

Combat

velocity, damage, raw_damage, damage_once, explosion, potion, clear_effect, pull.

World / projectile

temporary_block, virtual_block, shape_block_wave, clear_blocks, spawn_projectile, remove_projectile, sync_block, restore_block.

ability:
  type: TIMELINE
  timeline:
    0:
      - sound: { target: caster, name: ENTITY_PLAYER_ATTACK_SWEEP, volume: 1.0, pitch: 1.0 }
      - velocity: { target: caster, mode: LOOK, forward: 1.5, upward: 0.35 }
      - fall_protection: { target: caster, enabled: true }
    8:
      - temporary_block: { origin: target_block, mode: fake, block: COBWEB, ttl-ticks: 40 }
    '10..30 step 5':
      - damage_once: { selector: { type: nearby_living, radius: 3, include-caster: false }, amount: 2.0, mode: RAW_HEALTH }

Command items

Command-run weapons

Use the timeline command action when you want a right-click item that only runs a command, such as /sell all. The command can run as console or as the player. Do not include the leading slash unless you prefer it; the engine strips it before dispatching.

weapons:
  sell_wand:
    enabled: true
    display-id: 'Sell Wand'
    item:
      material: [BLAZE_ROD, STICK]
      name: '<gold><bold>Sell Wand</bold></gold>'
      lore:
        - '<gray>Right click to sell all items.'
    commands:
      get: ['getsellwand']
    trigger:
      type: RIGHT_CLICK
      cooldown: 3
    ability:
      type: TIMELINE
      timeline:
        0:
          - command:
              sender: player
              value: 'sell all'
          - actionbar:
              text: '<green>Selling inventory...'

Security: use sender: console only for trusted admin-made weapons. Console commands can bypass normal player permission checks.

Bundled pack

Built-in weapons

Search the loaded default, more, client, and example weapon definitions extracted from the source resources. Disabled entries are examples, not active weapons.

No weapons match your filters.

Ability families detected

COBWEB_PROJECTILEDASH_AOEEXPLOSIVE_MACE FLOW_SPEARFORCE_BOW_DASHGRAVITY_LIFT PASSIVE / PROJECTILEROCKET_LIFTSELF_BUFF SLAM_MACETIDE_TRIDENTTIMELINE VENOM_DASHZOOM_MACE

Menus

Weapon menus

Menus are configured in menus.yml. The bundled admin menu shows all weapons, while the FFA menu registers a dynamic command and lists selected legendary weapons.

menus:
  ffa:
    enabled: true
    title: '<dark_gray>ʟᴇɢᴇɴᴅᴀʀɪᴇs'
    size: 36
    permission: smpweapons.menu.ffa
    command-permission: smpweapons.command.ffaweapons
    register-command: true
    open-commands:
      - ffaweapons
    weapons:
      - dash_sword
      - dash_mace
      - wind_spear
      - venom_sword
    weapon-slots: [10,12,14,16,19,21,23,25]
    click-actions:
      - GET

Compatibility

Item identity and legacy matching

SMPWeapons can identify modern plugin-created items through persistent identity metadata and can also recover legacy/custom items through material aliases, display-name matching, custom model data, and lore matching.

compatibility:
  prefer-modern-item-data: true
  legacy-name-match: true
  legacy-custom-model-data-match: true
  legacy-lore-match: true
  allow-material-fallbacks: true
legacy:
  custom-model-data: 23425
  names-contains: ['Dash Sword']

Hooks

SMPRegions hook

When hooks.smp-regions.enabled is true and SMPRegions is installed, SMPWeapons can deny ability use in disallowed PvP areas or explicit blacklisted regions.

hooks:
  smp-regions:
    enabled: true
    deny-when-pvp-denied: true
    blacklist-regions: []
    debug: false

Support

Troubleshooting

Weapon does nothing

Check enabled: true, material aliases, trigger type, sneak condition, cooldown, region denial, and settings.require-use-permission.

Weapon is not detected

Use /smpweapons debug item. Verify persistent identity, legacy display name, custom model data, and material alias fallbacks.

Menu command not opening

Check commands.register-dynamic-commands, menus.<id>.register-command, open-commands, and the command permission.

Temporary blocks remain

Run /smpweapons debug restoreblocks. Keep engine.restore-real-blocks-on-disable and restore-real-blocks-on-reload enabled for safety.

Ability weapons without messy server glue.

What SMPWeapons does

Config-driven weapons

Ability engine

Server-friendly controls

Installation

Requirements and compatibility

Server platform

Optional hook

Admin and player commands

Permission reference

Config file map

config.yml

menus.yml

messages.yml

weapons/*.yml

Important main settings

Weapon definition format

Triggers, conditions, cooldowns

Common events

Common conditions

Timeline DSL

Visuals

Combat

World / projectile

Command-run weapons

Built-in weapons

Ability families detected

Weapon menus

Item identity and legacy matching

SMPRegions hook

Troubleshooting

Weapon does nothing

Weapon is not detected

Menu command not opening

Temporary blocks remain

`config.yml`

`menus.yml`

`messages.yml`

`weapons/*.yml`