poweritemcomponent

Power Item

This page documents the "poweritem" configuration used in items (items/*.yml) and how those keys map to RareSpawns' PowerItemComponent.

Table of Contents

• What PowerItems are
• Top-level keys and mapping to PowerItemComponent
• Behavioral notes & integrations
• Examples
• Authoring tips & best practices
• Troubleshooting
• Mapping quick table (config -> PowerItemComponent)
• Testing checklist
• Additional developer notes

What PowerItems are

• PowerItems are special custom items that perform one of a small set of actions when used:
  • BREAKER — break allowed blocks instantly (optionally drop them)
  • REDSTONE — power/activate supported redstone-related blocks (lamps, rails, powerable)
  • TROWEL — place a random block from the user's hotbar onto the targeted face (great for landscaping/texturing)
• PowerItems are configured per-item in items/*.yml under the poweritem: section. The plugin loads these into PowerItemComponent instances at runtime.

https://youtu.be/1eWUQvz_gJI

RareSpawns-PowerItem.mp4

Top-level keys and mapping to PowerItemComponent

• type (required)

  • YAML: type: 'BREAKER' (string)
  • Meaning: selects the behaviour. Valid values: BREAKER, REDSTONE, TROWEL (case-insensitive in configs, canonicalized by parser).
  • Java: PowerItemType type — used to choose which handler to execute.

• consumable

  • YAML: consumable: true/false
  • Meaning: whether the item is consumed on use (one charge consumed).
  • Java: Boolean consumable — when true and the player is not in Creative, the plugin reduces the amount in-hand by 1 when the effect succeeds.

• blocks

  • YAML: list of material names (Minecraft Material enum), e.g.:
    • BEDROCK
    • VAULT
  • Meaning:
    • For BREAKER: which blocks the breaker can break.
    • For REDSTONE: which blocks the redstone tool may power.
    • For TROWEL: not normally used.
  • Notes:
    • Use Bukkit Material names (see template and helpch.at links in template.yml).
    • Values are matched with Material.valueOf(...). Be careful with typos and case (use uppercase enum names).
  • Java: List blocks — read at runtime and iterated to check compatibility.

• worlds

  • YAML: list of world names or wildcards:
    • 'worldName'
    • '*_nether'
    • '*_the_end'
  • Meaning: allow-list of world names where this power-item may be used.
  • Behavior:
    • If the list is empty or missing, the power-item is allowed everywhere (subject to server/global config).
    • *_nether and *_the_end are dimension wildcards: they apply to any world whose environment is NETHER / THE_END.
    • Matching is case-insensitive for world names.
  • Java: List worlds — checked by isWorldBlacklisted() helper. The method treats the list as an allow-list; if the current world isn't found in the list, the item is blocked.

• drops (BREAKER-only)

  • YAML: drops: true/false
  • Meaning: when BREAKER removes a block, should the plugin drop the block's natural drops?
    • true: mimic natural drops (or drop the block type if block.getDrops() is empty)
    • false: suppress drops
  • Java: Boolean drops — used in BreakerEvent when deciding how to handle block.getDrops().

• ominous (BREAKER-only)

  • YAML: ominous: true/false
  • Meaning: require that certain special blocks be in their "ominous" state to be affected (applies to Vault/TrialSpawners).
  • Use case: Vault or Trial Spawner blocks have an "ominous" bit — set ominous:true to only allow poweritems to affect the ominous variant or false to require non-ominous.
  • Java: Boolean ominous — checked specifically for Vault and TrialSpawner types in BreakerEvent.

• trowel-delay (TROWEL-only)

  • YAML: trowel-delay: 100
  • Meaning: delay in milliseconds between successive placements while right-click is held. Controls the per-player cooldown for TROWEL usage.
  • Java: Integer trowelDelay — used to populate the plugin's per-player cooldown map. Default (if missing) is 100ms from the component class.

• trowel-cost / trowel-cost (durability cost)

  • YAML: trowel-cost: 1
  • Meaning: how much durability (Damageable) the used item will take per placement. If item supports durability, this amount is applied on use.
  • Java: Integer trowelDurabilityCost — applied when the event is a PlayerInteractEvent and the item in hand implements Damageable.

• permission

  • YAML: permission: template.use
  • Meaning: permission node a player must have to use the power-item. If set and the player lacks it, the plugin denies use and sends the configured lang message.
  • Java: String permission — checked in HandleEvent before executing any PowerItem logic.

• sound

  • YAML: sound: BLOCK_END_PORTAL_FRAME_FILL:1.0:1.0
  • Meaning: optional activation sound played at the action location. Format:
    • EITHER enum-style: SOUND_ENUM:volume:pitch
      • e.g. ENTITY_EVOKER_CAST_SPELL:1.0:1.0
    • OR namespaced full key: minecraft:block.anvil.place:1.0:1.0
  • Notes:
    • If only a key is provided (no volume/pitch) the code assumes volume=1.0 and pitch=1.0.
    • The PowerItemComponent accepts strings and parses them into a Sound object (Sound.parse) or you can configure via tool that writes the Sound object directly.
  • Java: Sound sound — optional; if non-null it's played via SFX.Play when an action succeeds.

Behavioral notes & integrations

• WorldGuard
  • Before executing any power item, RareSpawns checks WorldGuard via worldguard.canBuild(player). If that returns false, the action is aborted.
• GriefPrevention
  • When GriefPrevention is present, the plugin checks whether the player is inside a claim and requires Build trust to use PowerItems in that claim. If the player lacks trust, the action is aborted.
• mcMMO
  • Blocks placed or modified by PowerItems are marked ineligible for mcMMO skill checks via mcmmo.setBlockIneligible(block) when the mcMMO hook exists.
• Nexo/ItemsAdder/Oraxen
  • TROWEL supports placing Nexo note-block papers: if the chosen hotbar item is PAPER and carries the Nexo block id tag, RareSpawns will place a NOTE_BLOCK with the Nexo block data and play the Nexo place sound. No additional poweritem config is required for this behavior — it requires Nexo to be installed and the paper to carry the proper tag.
• Permissions & messages
  • If a player lacks the configured permission the plugin sends the configured lang key poweritem-no-permission prefixed with prefix. If the configured item is missing or invalid the plugin removes it from the player's inventory and sends poweritem-no-exist.

Examples

• BREAKER example (breaks specific blocks, suppresses drops, consumable)

poweritem:
 type: BREAKER
 consumable: true
 blocks:
  - STONE
  - OAK_LOG
  - VAULT
 drops: false
 ominous: false
 permission: template.use
 sound: BLOCK_DRIPSTONE_BREAK:1.0:1.0

• REDSTONE example (powers lights/rails)

poweritem:
 type: REDSTONE
 consumable: false
 blocks:
  - LIGHT
  - REDSTONE_WIRE
  - POWERED_RAIL
 worlds:
  - survival_world
  - '*_the_end'
 permission: staff.use
 sound: BLOCK_NOTE_BLOCK_PLING:1.0:1.0

• TROWEL example (places blocks from hotbar, 200ms delay)

poweritem:
 type: TROWEL
 consumable: true
 trowel-delay: 200
 trowel-cost: 1
 worlds:
  - world
  - '*_nether'
 permission: template.trowel
 sound: BLOCK_GRASS_PLACE:0.8:1.0

Authoring tips & best practices

• Use explicit Material enums in blocks: and verify them against the server version you run.
• Keep trowel-delay reasonable for large servers. Very small delays can be abused to place many blocks quickly.
• If you want to avoid accidental world grief, list the specific worlds instead of leaving worlds empty.
• Test BLOCKS rules in a staging world for all affected Minecraft versions (some materials are renamed between versions).
• For consumable tools, consider stacking/amount semantics — if you want the item to act as single-use charges consider using amount = 1 and consumable: true.

Troubleshooting

• PowerItem does nothing when used:
  • Check console logs for RareSpawns messages.
  • Confirm the player has the required permission (if set).
  • Verify the action location is not blocked by WorldGuard or GriefPrevention.
  • Verify the world is allowed by the worlds list (isWorldBlacklisted logic treats the list as an allow-list).
• TROWEL fails to place any blocks:
  • Ensure hotbar contains placeable block materials (not tools or player heads).
  • Papers are allowed for Nexo note-block behavior only if Nexo is installed and the paper carries the required tag.
• BREAKER doesn't drop blocks:
  • Check drops: setting. Also note the code checks block.getDrops() — some block types return empty drops in certain server states.
• Sound doesn't play:
  • Verify the sound key exists in your server's Minecraft version. If using namespaced strings, ensure you use the correct namespace and sound path.

Mapping quick table (config -> PowerItemComponent)

• type -> PowerItemComponent.type (PowerItemType)
• consumable -> consumable (Boolean)
• blocks -> blocks (List)
• drops -> drops (Boolean)
• ominous -> ominous (Boolean)
• trowel-delay -> trowelDelay (Integer, ms)
• trowel-cost -> trowelDurabilityCost (Integer)
• worlds -> worlds (List)
• permission -> permission (String)
• sound -> sound (Sound) via Sound.parse(string)

Testing checklist

1. Add/modify the item file under items/ and set poweritem: section.
2. Restart the server (or use plugin reload if available).
3. Give the item to a test player (use /rarespawns.item or your preferred method).
4. Test the behavior in an allowed world and in a denied world (if using worlds).
5. Test inside and outside protected regions (WorldGuard/GriefPrevention) and confirm the plugin respects protections.
6. Check console log lines and any player messages for debug info.

Additional developer notes

• PowerItemComponent defaults: the Java class uses reasonable defaults (e.g., trowelDelay = 100ms, consumable default false) — omitting keys will fallback to those defaults or plugin-wide defaults.
• Sound parsing: PowerItemComponent.setSound(String) calls Sound.parse(String) — follows the same compact format used elsewhere in the plugin.