PowerWeave Wiki

PowerWeave is a Paper plugin for attaching configurable gameplay abilities to existing Nexo item IDs. Nexo handles item visuals and resource packs; PowerWeave handles ability bindings, triggers, conditions, targets, cooldowns, actions, editing, and diagnostics.

Requirements

• Paper server.
• Minecraft/Paper 1.21.4 or newer within the supported compatibility range.
• Nexo installed separately.
• Java 21 for Paper 1.21.x.
• Java 25 for Paper 26.x.

Installation

1. Stop the server.
2. Install a compatible Nexo jar in the server plugins folder.
3. Install the PowerWeave jar in the server plugins folder.
4. Start the server once to generate configuration files.
5. Confirm PowerWeave loads without errors in the console.
6. Use /powerweave about to confirm the detected Nexo version and catalog status.

Generated Files

PowerWeave creates files under plugins/PowerWeave.

• config.yml controls debug defaults, GUI limits, safety limits, disabled worlds, cooldown feedback defaults, passive trigger checks, and bound-item death retention.
• messages.yml controls player-facing MiniMessage text.
• ui.yml is reserved for GUI presentation settings.
• bindings.yml maps Nexo item IDs to ability IDs.
• abilities/*.yml stores one ability definition per file.

Fresh installations also include unbound passive templates: example-equipped-armor-ward.yml and example-equipped-sword-aura.yml. Bind either template to a suitable Nexo item ID before testing it.

On startup, PowerWeave checks bundled YAML config files for missing keys and appends missing defaults automatically. Existing keys are not modified or reformatted, so admin changes are preserved.

Passive Trigger Checks

Passive abilities are checked at a fixed interval while players are online. The default is once per second (20 ticks), configured in config.yml:

passive-triggers:
  enabled: true
  update-interval-ticks: 20

Use a cooldown on passive abilities to control how often their actions run. A zero-duration cooldown permits actions on every check, which is usually only appropriate for lightweight effects. Each Nexo item ID is evaluated once per player and passive trigger type per check, even if multiple copies of that item are present.

Cooldown Display

Cooldown display is based on Nexo items held in either hand. If either held item has a bound ability with an active cooldown, PowerWeave can show the most recently acquired active cooldown through action bar, boss bar, PlaceholderAPI, or any configured combination.

Passive EQUIPPED and INVENTORY abilities still use cooldowns to throttle their execution, but their cooldowns are never shown through action bars, boss bars, or PowerWeave PlaceholderAPI cooldown placeholders.

Global cooldown display settings live in config.yml:

cooldown-feedback:
  enabled: true
  modes:
    - ACTION_BAR
  update-interval-ticks: 5
  boss-bar:
    color: YELLOW
    overlay: SOLID

Supported modes:

Mode	What It Does
ACTION_BAR	Shows cooldown text above the hotbar while holding an item with an active cooldown.
BOSS_BAR	Shows one boss bar per player while holding an item with an active cooldown.

Cooldown display text is configured in messages.yml:

messages:
  cooldown.action-bar: "<yellow>{ability}</yellow> <gray>ready in</gray> <gold>{remaining_seconds}s</gold>"
  cooldown.boss-bar: "{ability} {remaining_seconds}s"

Available placeholders in those messages:

Placeholder	Meaning
{item}	Held Nexo item ID.
{ability}	Ability display name using the ability's display-name value.
{ability_id}	Raw ability ID.
{remaining_ms}	Remaining cooldown in milliseconds.
{remaining_seconds}	Remaining cooldown in seconds, rounded up.
{percent}	Remaining cooldown percent from 0 to 100.

PlaceholderAPI

PlaceholderAPI is optional. If it is installed, PowerWeave registers placeholders on startup.

Held-item placeholders:

Placeholder	Meaning
%powerweave_held_item_id%	Current held Nexo item ID, or empty if none.
%powerweave_held_cooldown_ability%	Plain-text ability display name selected for the held item's active cooldown display.
%powerweave_held_cooldown_ability_id%	Raw ability ID selected for the held item's active cooldown display.
%powerweave_held_cooldown_remaining_ms%	Remaining held-item cooldown in milliseconds.
%powerweave_held_cooldown_remaining_seconds%	Remaining held-item cooldown in seconds, rounded up.
%powerweave_held_cooldown_percent%	Remaining held-item cooldown percent from 0 to 100.
%powerweave_held_cooldown_ready%	true when no held-item cooldown is active, otherwise false.

Aggregate placeholders for displaying every held-item cooldown in one formatted value are planned for later.

Permissions

Permission	Purpose
powerweave.admin	Grants all PowerWeave administrative permissions.
powerweave.reload	Allows /powerweave reload.
powerweave.edit	Allows editor, ability create/delete, bind, and unbind operations.
powerweave.inspect	Allows item listing and held-item inspection.
powerweave.debug	Allows toggling debug traces for players.
powerweave.about	Allows viewing plugin and runtime status.
powerweave.diagnostics	Allows checking orphaned items and missing ability references.

Operators receive these permissions by default through the plugin permission defaults.

Commands

The main command is /powerweave. The alias is /weave.

Command	Permission	Description
/powerweave editor	powerweave.edit	Opens the item browser GUI.
/powerweave items [search]	powerweave.inspect	Lists Nexo catalog items, optionally filtered by ID or display name.
/powerweave inspect	powerweave.inspect	Identifies the held Nexo item and lists bound abilities.
/powerweave ability list	powerweave.edit	Lists loaded abilities.
/powerweave ability create <id>	powerweave.edit	Creates a basic ability shell. IDs must match [a-z0-9_-]+.
/powerweave ability delete <id> --confirm	powerweave.edit	Deletes an ability after explicit confirmation.
/powerweave ability validate [id]	powerweave.edit	Validates one ability or all abilities.
/powerweave bind <nexo-id> <ability-id>	powerweave.edit	Binds an ability to a Nexo item ID.
/powerweave unbind <nexo-id> <ability-id>	powerweave.edit	Removes an ability binding from a Nexo item ID.
/powerweave reload	powerweave.reload	Reloads PowerWeave configuration safely.
/powerweave debug <player>	powerweave.debug	Toggles activation debug traces for a player.
/powerweave diagnostics	powerweave.diagnostics	Reports orphaned Nexo IDs and bindings that reference missing abilities.
/powerweave help [page]	None	Shows paginated command help configured through messages.yml.
/powerweave about	powerweave.about	Shows version, server, Java, Nexo, catalog, ability, binding, orphan, and reload status.

Configuring Command Help

Help page size, entry order, and every displayed line are configured in messages.yml:

help:
  page-size: 6
  entries:
    - help.entry.editor
    - help.entry.items
    - help.entry.inspect

messages:
  help.header: "{prefix} <yellow>PowerWeave help</yellow> <gray>({page}/{pages})</gray>"
  help.entry.editor: "{prefix} <yellow>/{label} editor</yellow> <gray>- Open the item editor.</gray>"
  help.footer: "{prefix} <gray>Use</gray> <yellow>/{label} help <page></yellow> <gray>to change pages.</gray>"

The help.entries list contains message keys, so administrators can reorder, remove, or add help lines without changing the plugin.

Validation And Diagnostics

/powerweave ability validate [id] and /powerweave reload report every malformed ability file and identify the failing condition, target, or numbered action where possible. A failed reload does not replace the previous valid ability or binding snapshot.

/powerweave diagnostics checks loaded bindings separately and reports:

• Nexo item IDs missing from the current catalog.
• Ability IDs referenced by bindings but missing from the active ability registry.

Diagnostics never delete orphaned bindings. This allows temporarily unavailable Nexo items or abilities to return later without losing configuration.

How To Bind An Ability To A Nexo Item

1. Find the Nexo item ID.
   • Hold the item and run /powerweave inspect, or
   • Run /powerweave items [search].
2. Confirm the ability exists with /powerweave ability list.
3. Bind it with /powerweave bind <nexo-id> <ability-id>.
4. Run /powerweave inspect while holding the item to confirm the binding.
5. Test the item in-game using the ability trigger.

How To Create A Basic Ability Shell

1. Run /powerweave ability create <id>.
2. Open plugins/PowerWeave/abilities/<id>.yml.
3. Edit trigger, cooldown, target, conditions, and actions as needed.
4. Validate with /powerweave ability validate <id>.
5. Reload with /powerweave reload.
6. Bind it with /powerweave bind <nexo-id> <id>.

How To Use The Editor GUI

1. Run /powerweave editor.
2. Browse generated Nexo items.
3. Click an item to open its details.
4. Bind an existing ability, unbind an ability, or create a basic ability shell.
5. Open the ability summary to review enabled state, trigger, cooldown, and default target.

The current GUI is a first milestone editor. Complex action and condition editing is still YAML-based.

How To Debug An Ability

1. Run /powerweave debug <player>.
2. Trigger the ability in-game.
3. Read the activation trace in chat.
4. Run /powerweave debug <player> again to disable traces.

Debug traces are rate-limited to reduce chat spam.

Ability YAML Basics

Each ability lives in its own file under plugins/PowerWeave/abilities.

config-version: 3
id: thunder-strike
display-name: "<yellow>Thunder Strike"
enabled: true
allow-empty-targets: false

trigger:
  type: RIGHT_CLICK

cooldown:
  duration-millis: 8000
  scope: PLAYER_ABILITY

conditions: []

default-target:
  type: LOOKED_AT_LOCATION
  range: 24.0

actions:
  - type: LIGHTNING
    effect-only: true

allow-empty-targets controls what happens when an action resolves no valid targets.

• false preserves strict behavior: the ability stops with NO_VALID_TARGET, cooldown is not consumed, and no actions run.
• true allows activation anyway: cooldown is consumed, actions with valid targets run, and actions with no targets are skipped.

Use allow-empty-targets: true for abilities where some effects are optional. For example, a lightning ability can always strike the looked-at location and only damage nearby entities if any exist.

Cooldown scope options:

Scope	Behavior
PLAYER_ABILITY	One cooldown per player and ability. This is the default.
PLAYER_ITEM	One cooldown per player and Nexo item ID. All abilities on that item share it.
PLAYER_ITEM_ABILITY	One cooldown per player, Nexo item ID, and ability.

Binding YAML Basics

Bindings live in plugins/PowerWeave/bindings.yml.

config-version: 3

items: {}

Add bindings with /powerweave bind <nexo-id> <ability-id> or by editing this file. Missing Nexo item IDs are preserved and reported as orphaned bindings. PowerWeave does not delete them automatically.

Bindings may also define runtime enchantments for the bound Nexo item ID:

config-version: 3

items:
  example:storm_bow:
    abilities:
      - explosive-arrow-impact
    keep-on-death: true
    enchantments:
      display-in-lore: true
      glint: true
      hide-vanilla-tooltip: true
      entries:
        - type: power
          level: 4
        - type: flame
          level: 1

Key	Meaning
keep-on-death	Optional item override. true keeps this bound item, false allows it to drop, and an absent key follows the global setting.
display-in-lore	Adds configured enchantments to the item lore using messages.enchantment.lore-line.
glint	Controls the enchantment glint with Bukkit's item glint override.
hide-vanilla-tooltip	Hides vanilla enchantment tooltip lines so admins can use lore instead.
entries[].type	Minecraft enchantment key, such as power, sharpness, loyalty, or minecraft:flame.
entries[].level	Enchantment level. PowerWeave applies it unsafely so admins can configure custom levels.

PowerWeave applies these enchantments to item instances at runtime when players join, switch held items, interact, move inventory items, or run /powerweave reload. Nexo remains responsible for item model, name, and base lore configuration.

Keeping Bound Items On Death

The global default is configured in config.yml:

items:
  keep-bound-on-death: false

When enabled, every item whose Nexo ID has a PowerWeave binding is kept in the player's inventory on death instead of appearing in the death drops. Unbound items are unaffected. Vanilla or plugin-driven full inventory retention still takes precedence.

Use keep-on-death under a specific item in bindings.yml to override the global value in either direction:

items:
  example:guardian_shield:
    abilities:
      - shield-ward
    keep-on-death: true

  example:temporary_relic:
    abilities:
      - relic-burst
    keep-on-death: false

An omitted override inherits items.keep-bound-on-death. Existing keys are preserved by the startup config updater.

Supported Triggers

Every ability has exactly one trigger in this milestone.

trigger:
  type: RIGHT_CLICK
  click-targets:
    - AIR
    - BLOCK
    - ENTITY

Trigger	What It Does	Typical Use
RIGHT_CLICK	Runs when the player right-clicks while holding the bound Nexo item.	Wands, tools, instant effects, utility items.
SNEAK_RIGHT_CLICK	Runs when the player is sneaking and right-clicks while holding the bound Nexo item.	Alternate item modes, stronger variants, admin-only tools.
MELEE_HIT	Runs when the player hits an entity with the bound Nexo item. The hit entity becomes the direct target.	Weapons, lifesteal, fire blades, knockback effects.
EQUIPPED	Runs while the bound Nexo item is in the main hand, off-hand, or any armour slot.	Worn armour bonuses, held relic effects, shield auras.
INVENTORY	Runs while the bound Nexo item is in player storage or a hotbar slot. Armour and off-hand slots are excluded.	Backpack charms, carried keys, passive utility items.
PROJECTILE_HIT_ENTITY	Runs when a PowerWeave-launched projectile from a bound item hits an entity. The hit entity becomes the direct target.	Impact damage, lightning on projectile hit, debuffs.
PROJECTILE_HIT_BLOCK	Runs when a PowerWeave-launched projectile from a bound item hits a block. The hit location is exposed to location-based targets.	Impact particles, block-hit sounds, area effects.
PROJECTILE_HIT_ALL	Runs for either projectile entity hits or projectile block hits. Entity hits expose a direct target; both hit kinds expose an impact location.	Shared projectile impact effects.

Right-Click Target Filters

For RIGHT_CLICK and SNEAK_RIGHT_CLICK, admins can choose which right-click target kinds are allowed.

Both right-click triggers use the hand reported by Paper, so bound items can activate from the main hand or off-hand. This includes shields: bind a right-click ability to a Nexo shield and raising the shield can activate it. MELEE_HIT intentionally uses only the main-hand item. If both hands contain bound items, each genuine hand interaction is evaluated against the item used for that event.

Click Target	What It Means
AIR	The player right-clicked without targeting a block or entity.
BLOCK	The player right-clicked a block.
ENTITY	The player right-clicked an entity.

If click-targets is omitted, all three are allowed for backward compatibility.

Allow air, blocks, and entities:

trigger:
  type: RIGHT_CLICK
  click-targets:
    - AIR
    - BLOCK
    - ENTITY

Allow only air and blocks:

trigger:
  type: RIGHT_CLICK
  click-targets:
    - AIR
    - BLOCK

Allow only entity right-clicks:

trigger:
  type: RIGHT_CLICK
  click-targets:
    - ENTITY

MELEE_HIT, PROJECTILE_HIT_ENTITY, PROJECTILE_HIT_BLOCK, and PROJECTILE_HIT_ALL ignore click-targets because they are not right-click triggers.

EQUIPPED and INVENTORY also ignore click-targets. They are state-based triggers and run on the passive-triggers.update-interval-ticks schedule. A selected main-hand item is eligible for both EQUIPPED and INVENTORY; these are independent trigger types, so use only the intended passive trigger on a given ability.

PowerWeave listens to right-click block, air, and entity events even when another plugin has pre-cancelled the Bukkit interaction event. This is intentional so Nexo custom items can still activate abilities while Nexo or vanilla logic suppresses normal interaction behavior.

For air or block right-clicks, PowerWeave also checks whether the player is looking directly at an entity hitbox. If a visible entity is found before a blocking block, the interaction is treated as ENTITY for click-targets, the entity is exposed as the direct target, and LOOKED_AT_LOCATION uses the entity hit location instead of the block behind it. The maximum distance for this check is configured in config.yml:

trigger:
  entity-line-of-sight-range: 24.0

Trigger Examples

Right-click ability:

trigger:
  type: RIGHT_CLICK
  click-targets:
    - AIR
    - BLOCK
    - ENTITY

Sneak-right-click ability:

trigger:
  type: SNEAK_RIGHT_CLICK
  click-targets:
    - AIR
    - BLOCK

Melee-hit ability:

trigger:
  type: MELEE_HIT

Projectile entity-hit ability:

trigger:
  type: PROJECTILE_HIT_ENTITY

Projectile block-hit ability:

trigger:
  type: PROJECTILE_HIT_BLOCK

Projectile any-hit ability:

trigger:
  type: PROJECTILE_HIT_ALL

Equipped passive ability:

trigger:
  type: EQUIPPED

Inventory passive ability:

trigger:
  type: INVENTORY

Supported Targets

Targets decide where an action applies. An ability can define a default-target, and each action can override it with its own target block.

default-target:
  type: SELF

actions:
  - type: MESSAGE
    message: "<gray>This goes to the default target.</gray>"

  - type: DAMAGE
    target:
      type: DIRECT_TARGET
    amount: 4.0

SELF

Targets the player who activated the ability.

Use this for self-healing, feedback sounds, messages, action bars, self velocity, or potion effects.

default-target:
  type: SELF

DIRECT_TARGET

Targets the entity already provided by the trigger context. This is useful with MELEE_HIT, PROJECTILE_HIT_ENTITY, and entity impacts matched through PROJECTILE_HIT_ALL, where the direct target is the entity that was hit.

trigger:
  type: MELEE_HIT

default-target:
  type: DIRECT_TARGET

If no direct target exists, the action fails with NO_VALID_TARGET and the cooldown is not consumed.

LOOKED_AT_ENTITY

Targets the entity the player is looking at within a configurable range.

default-target:
  type: LOOKED_AT_ENTITY
  range: 16.0

Use this for targeted spells or effects that require aiming at an entity.

LOOKED_AT_LOCATION

Targets the block, entity hitbox location, or air point the player is looking at within a configurable range.

default-target:
  type: LOOKED_AT_LOCATION
  range: 24.0

Use this for lightning, particles, sounds, or area effects centered around a looked-at point. If the trigger context already has an interaction location, such as a projectile impact or promoted entity hitbox, this target uses that location before ray-tracing blocks.

NEARBY_ENTITIES

Targets entities near the activation point. Results are ordered nearest-first before maximum-targets is applied.

When NEARBY_ENTITIES is used as an action-level target override and the ability has a location-based default-target, PowerWeave uses that default location as the center of the nearby search. This is the common pattern for “strike the looked-at location, then affect entities around that point.”

target:
  type: NEARBY_ENTITIES
  radius: 3.0
  include-self: false
  players-only: false
  living-only: true
  maximum-targets: 8
  line-of-sight-required: false

Options:

Option	Type	Meaning
radius	Number	Search radius in blocks.
include-self	Boolean	Whether the activating player can be included.
players-only	Boolean	Whether only players can be targeted.
living-only	Boolean	Whether only living entities can be targeted.
maximum-targets	Integer	Maximum number of targets after sorting.
line-of-sight-required	Boolean	Whether the actor must have line of sight to each target.

Example using the ability default looked-at location as the area center:

allow-empty-targets: true

default-target:
  type: LOOKED_AT_LOCATION
  range: 24.0

actions:
  - type: LIGHTNING
    effect-only: true

  - type: DAMAGE
    target:
      type: NEARBY_ENTITIES
      radius: 3.0
      include-self: false
      living-only: true
      maximum-targets: 8
    amount: 6.0

Supported Conditions

Conditions decide whether an ability may continue. Conditions run before cooldown consumption, so failed conditions do not consume cooldown.

conditions:
  - type: SNEAKING
    value: true

PERMISSION

Requires the activating player to have a Bukkit permission.

conditions:
  - type: PERMISSION
    permission: "powerweave.use.special"

Use this to restrict specific abilities separately from admin permissions.

WORLD

Requires the activating player to be in a specific world.

conditions:
  - type: WORLD
    world: "world"

Use this for arena-only, dungeon-only, or lobby-disabled abilities.

ACTIVATION_CHANCE

Runs the ability only when a random roll succeeds.

conditions:
  - type: ACTIVATION_CHANCE
    chance: 0.25

chance is a decimal from 0.0 to 1.0. For example, 0.25 means a 25% chance.

ACTOR_HEALTH

Requires the activating player's health to be within a range.

conditions:
  - type: ACTOR_HEALTH
    min: 6.0
    max: 20.0

Use this to prevent activation at low health or to create low-health effects by setting only max.

TARGET_HEALTH

Requires the direct target's health to be within a range. This is most useful with MELEE_HIT or another setup that provides a direct living target.

conditions:
  - type: TARGET_HEALTH
    max: 10.0

If the direct target is missing or is not a living entity, the condition fails.

SNEAKING

Requires the activating player to be sneaking or not sneaking.

conditions:
  - type: SNEAKING
    value: true

Use value: false to require that the player is not sneaking.

Supported Actions

Actions do the actual work after trigger, conditions, target resolution, and cooldown checks pass. Each action uses the ability's default-target unless it defines its own target block.

actions:
  - type: SOUND
    target:
      type: SELF
    sound: "entity.experience_orb.pickup"
    volume: 1.0
    pitch: 1.0

POTION_EFFECT

Applies a Bukkit potion effect to living targets.

- type: POTION_EFFECT
  target:
    type: SELF
  effect: "speed"
  duration-ticks: 200
  amplifier: 1
  ambient: false
  particles: true
  icon: true

Options:

Option	Type	Meaning
effect	String	Potion effect key, such as speed, strength, or regeneration.
duration-ticks	Integer	Duration in ticks. 20 ticks is about 1 second.
amplifier	Integer	Potion amplifier. 0 is level I, 1 is level II.
ambient	Boolean	Whether the effect is ambient.
particles	Boolean	Whether particles are shown.
icon	Boolean	Whether the effect icon is shown.

DAMAGE

Damages living targets. PowerWeave uses the actor as the damage source where supported by the platform API.

- type: DAMAGE
  target:
    type: DIRECT_TARGET
  amount: 6.0

amount is damage points. Two damage points equal one heart.

HEAL

Heals living targets up to their maximum health.

- type: HEAL
  target:
    type: SELF
  amount: 4.0

amount is health points. Two health points equal one heart.

FIRE

Sets targets on fire for a duration.

- type: FIRE
  target:
    type: DIRECT_TARGET
  duration-ticks: 100

duration-ticks uses Minecraft ticks. 20 ticks is about 1 second.

KNOCKBACK

Applies knockback to living targets.

- type: KNOCKBACK
  target:
    type: DIRECT_TARGET
  strength: 1.2

Use this for weapon impact effects or defensive pushback abilities.

VELOCITY

Sets target velocity. It can use an explicit vector or the actor's facing direction.

Actor-facing velocity:

- type: VELOCITY
  target:
    type: SELF
  actor-facing: true
  strength: 1.5

Explicit vector velocity:

- type: VELOCITY
  target:
    type: SELF
  x: 0.0
  y: 1.0
  z: 0.0

LIGHTNING

Strikes lightning at location targets. It defaults to effect-only behavior for safety.

- type: LIGHTNING
  target:
    type: LOOKED_AT_LOCATION
    range: 24.0
  effect-only: true

Set effect-only: false only when you intentionally want real lightning behavior.

PARTICLE

Spawns particles at location targets.

- type: PARTICLE
  target:
    type: LOOKED_AT_LOCATION
    range: 16.0
  particle: "ELECTRIC_SPARK"
  count: 24

count is validated against safety limits from config.yml.

SOUND

Plays a sound at location targets.

- type: SOUND
  target:
    type: SELF
  sound: "entity.lightning_bolt.thunder"
  volume: 1.0
  pitch: 1.0

volume and pitch are validated to reject unreasonable values.

volume is bounded by safety.max-sound-volume. Pitch must remain between 0.0 and 2.0.

MESSAGE

Sends a MiniMessage chat message to command-sender targets, usually the activating player.

- type: MESSAGE
  target:
    type: SELF
  message: "<yellow>Your item hums with energy.</yellow>"

This message is ability-authored content and is configured in the ability YAML.

ACTION_BAR

Sends a MiniMessage action bar message to player targets.

- type: ACTION_BAR
  target:
    type: SELF
  message: "<gray>Ability activated.</gray>"

Use this for lightweight feedback that should not fill chat.

PROJECTILE

Launches one or more vanilla Bukkit projectiles from the activating player and tags them as PowerWeave-created projectiles. Tagged projectiles can activate PROJECTILE_HIT_ENTITY, PROJECTILE_HIT_BLOCK, and PROJECTILE_HIT_ALL abilities bound to the same original Nexo item ID.

Supported projectile values:

Value	Notes
ARROW	Supports damage, critical, and pickup.
SNOWBALL	Lightweight utility projectile.
FIREBALL	Supports yield and incendiary; defaults are safe.
SMALL_FIREBALL	Supports yield and incendiary; defaults are safe.
TRIDENT	Supports arrow-style pickup/damage options where Bukkit exposes them.

Options:

Option	Meaning
projectile	Projectile type. Defaults to ARROW.
count	Number of projectiles to launch. Bounded by safety.max-projectile-count.
velocity	Launch speed. Bounded by safety.max-velocity.
spread-degrees	Randomized spread. Bounded by safety.max-projectile-spread-degrees.
gravity	Whether the projectile has gravity. Defaults to true.
fire-ticks	Fire duration applied to the projectile.
damage	Arrow/trident damage when supported. Bounded by safety.max-damage.
critical	Arrow/trident critical state when supported.
pickup	Arrow/trident pickup status: DISALLOWED, ALLOWED, or CREATIVE_ONLY.
yield	Fireball explosion yield. Defaults to 0.
incendiary	Whether fireballs create fire. Defaults to false.

Relevant safety limits in config.yml:

safety:
  max-radius: 32.0
  max-targets: 32
  max-particle-count: 256
  max-damage: 100.0
  max-healing: 100.0
  max-fire-ticks: 1200
  max-velocity: 5.0
  max-projectile-count: 8
  max-projectile-spread-degrees: 20.0
  max-projectile-yield: 4.0
  max-sound-volume: 4.0

Example:

default-target:
  type: SELF

actions:
  - type: PROJECTILE
    projectile: ARROW
    count: 1
    velocity: 2.2
    spread-degrees: 0.0
    damage: 5.0
    critical: true
    pickup: DISALLOWED

Projectile Hit Abilities

Projectile hit behavior is modeled as separate abilities. When a player throws or shoots a Nexo-backed projectile item, PowerWeave tags that launched projectile. The PROJECTILE action also tags projectiles it launches. When a tagged projectile hits, PowerWeave reads the projectile tag and dispatches projectile-hit triggers through the normal binding pipeline.

There are two supported setup styles:

• Use vanilla/Nexo projectile behavior, such as throwing a Nexo trident item, and bind a PROJECTILE_HIT_ENTITY, PROJECTILE_HIT_BLOCK, or PROJECTILE_HIT_ALL ability to that same Nexo item ID.
• Use a RIGHT_CLICK ability with a PROJECTILE action to launch a projectile, then bind separate projectile-hit abilities to the same Nexo item ID.

Do not put a PROJECTILE launch action inside a projectile-hit ability unless you intentionally want the impact to launch another projectile.

Entity-hit example:

config-version: 3
id: trident-impact
display-name: "<yellow>Trident Impact"
enabled: true
allow-empty-targets: false

trigger:
  type: PROJECTILE_HIT_ENTITY

cooldown:
  duration-millis: 0
  scope: PLAYER_ABILITY

conditions: []

default-target:
  type: DIRECT_TARGET

actions:
  - type: LIGHTNING
    target:
      type: LOOKED_AT_LOCATION
    effect-only: true

  - type: DAMAGE
    amount: 4.0

Block-hit example:

config-version: 3
id: trident-block-impact
display-name: "<yellow>Trident Block Impact"
enabled: true
allow-empty-targets: false

trigger:
  type: PROJECTILE_HIT_BLOCK

cooldown:
  duration-millis: 0
  scope: PLAYER_ABILITY

conditions: []

default-target:
  type: LOOKED_AT_LOCATION

actions:
  - type: PARTICLE
    particle: ELECTRIC_SPARK
    count: 16

  - type: SOUND
    sound: "entity.lightning_bolt.thunder"
    volume: 0.6
    pitch: 1.4

Projectile hit abilities currently run immediately on impact. Delayed projectile chains, homing projectiles, and projectile-specific branching graphs are still deferred.

Complete Example: Area Lightning Strike

This ability right-clicks a looked-at location, shows lightning, damages nearby living entities, and plays a sound to the actor.

config-version: 3
id: thunder-strike
display-name: "<yellow>Thunder Strike"
enabled: true
allow-empty-targets: true

trigger:
  type: RIGHT_CLICK
  click-targets:
    - AIR
    - BLOCK
    - ENTITY

cooldown:
  duration-millis: 8000
  scope: PLAYER_ABILITY

conditions: []

default-target:
  type: LOOKED_AT_LOCATION
  range: 24.0

actions:
  - type: LIGHTNING
    effect-only: true

  - type: DAMAGE
    target:
      type: NEARBY_ENTITIES
      radius: 3.0
      include-self: false
      living-only: true
      maximum-targets: 8
    amount: 6.0

  - type: SOUND
    target:
      type: SELF
    sound: "entity.lightning_bolt.thunder"
    volume: 1.0
    pitch: 1.0

Message Customization

Edit plugins/PowerWeave/messages.yml to customize player-facing plugin text. Messages use MiniMessage formatting and support placeholders such as {prefix}, {ability}, {item}, {player}, and {count} depending on the message key.

Ability-authored MESSAGE and ACTION_BAR action text lives in ability YAML because it is part of the ability design, not global plugin UI text.

Current Limitations

• No full visual node editor yet.
• Projectile launch and projectile-hit triggers exist, but delayed projectile chains, homing projectiles, and branching projectile graphs are not implemented yet.
• No delayed or repeating action chains yet.
• No custom mobs or persistent areas yet.
• No database storage yet.
• No per-item-instance ability data yet beyond binding-level runtime enchantment presentation metadata.
• No public extension API yet.