NexaSpawners Documentation

What is NexaSpawners?#

A lag-conscious virtual spawner platform with storage, selling, boosters, corruption, ownership, trust and admin tooling.

Who is it for?#

SMP, Lifesteal and SkyBlock servers that need scalable spawner economies.

Supported server types#

SMP, Lifesteal, SkyBlock, Prison and economy servers.

Main features#

• Virtual production
• Spawner storage
• XP and selling
• Boosters
• Corruption protection
• Ownership and trust
• Setup presets
• Admin inspection
• Product Positioning
• Implemented Core
• Virtual Spawner Engine
• Storage, Selling And Economy

Dependencies#

• Java 21
• Paper-compatible server
• Vault optional
• PlaceholderAPI optional
• MiniPlaceholders optional

Setup checklist#

1. Choose modules
2. Apply a setup preset
3. Configure storage and sell values
4. Set trust and ownership rules
5. Give player/admin permissions
6. Test place, collect and sell flows

Production notes#

• Give permissions through LuckPerms or your permission manager.
• Keep backups of YAML files and database tables.
• Use a staging server before large updates.
• Do not claim Folia or network support unless the full setup has been tested.

How to edit messages#

This product ships messages.yml. Edit the generated copy in the plugin folder, keep placeholders intact, then reload the plugin command or restart for startup-level changes.

Formatting#

<red>Error message</red>
&cLegacy color message
{player} {amount} {reason}

Admin Panel#

Staff panel for NexaSpawners administration, diagnostics and editor entry points.

• Configured title: NexaSpawners Admin
• Size: 54 slots
• Configured items: 9
• Actions: close

Boosters#

Spawner booster menu for viewing and applying production modifiers.

• Configured title: Spawner Boosters
• Size: 27 slots
• Configured items: 3

Confirm Sell#

Sell confirmation menu used before bulk-selling stored spawner drops.

• Configured title: Confirm Sell
• Size: 27 slots
• Configured items: 3
• Actions: sell_all

Corruption#

Corruption state menu for viewing and resolving special spawner risk mechanics.

• Configured title: Corruption
• Size: 27 slots
• Configured items: 4

Corruption Challenge#

Anti-AFK or corruption challenge screen used by the spawner corruption system.

• Configured title: Anti-AFK Challenge
• Size: 27 slots
• Configured items: 3

Editor#

Main in-game editor for NexaSpawners configuration areas.

• Configured title: NexaSpawners Editor
• Size: 27 slots
• Configured items: 6
• Actions: close

Editor Booster#

Admin editor for a single booster definition, including values used by the booster menu.

• Configured title: Booster:
• Size: 54 slots
• Configured items: 20
• Actions: close

Editor Boosters#

Admin list editor for configured booster definitions.

• Configured title: Editor: Boosters
• Size: 54 slots
• Configured items: 2

Editor Drop#

Admin editor for one spawner drop entry, including item, chance and value-related settings.

• Configured title: Drop:
• Size: 45 slots
• Configured items: 23
• Actions: close

Editor Drops#

Admin list editor for configured drop definitions.

• Configured title: Editor Drops:
• Size: 54 slots
• Configured items: 4

Editor Storage#

Admin editor for storage capacity, collection and output behavior.

• Configured title: Editor: Storage
• Size: 45 slots
• Configured items: 12
• Actions: close

Editor Type#

Admin editor for one spawner type, including production and display settings.

• Configured title: Editor:
• Size: 45 slots
• Configured items: 18
• Actions: close

Editor Types#

Admin list editor for available spawner type definitions.

• Configured title: Editor: Types
• Size: 54 slots
• Configured items: 2

Logs#

Spawner history menu for reviewing recent production, storage or admin activity.

• Configured title: Spawner Logs
• Size: 54 slots
• Configured items: 2

Main#

Main spawner control menu for production status, XP collection, stack actions and management entry points.

• Configured title: Spawner
• Size: 27 slots
• Configured items: 11
• Actions: collect_xp, split_stack

Setup#

Setup preset selector used to apply starting configurations such as Skyblock or Lifesteal layouts.

• Configured title: NexaSpawners Setup
• Size: 27 slots
• Configured items: 7
• Actions: setup_select:skyblock, setup_select:lifesteal, close

Setup Confirm#

Preset confirmation menu shown before applying a setup template.

• Configured title: Apply Preset?
• Size: 27 slots
• Configured items: 5
• Actions: setup_back, close

Spawner List#

Spawner list menu for browsing owned or managed spawner instances.

• Configured title: Spawner List
• Size: 54 slots
• Configured items: 5
• Actions: close

Storage#

Storage menu for collected drops, capacity state and withdraw/sell actions.

• Configured title: Spawner Storage
• Size: 54 slots
• Configured items: 5
• Actions: take_all

Trust#

Trusted players menu for viewing and managing who can interact with owned spawners.

• Configured title: Trusted Players
• Size: 36 slots
• Configured items: 6

Trust Add#

Trust menu for adding a player to a spawner's access list.

• Configured title: Add Trusted Player
• Size: 36 slots
• Configured items: 5

Trust Edit#

Trust editor for changing a trusted player's access level.

• Configured title: Edit Trusted Player
• Size: 36 slots
• Configured items: 4

Upgrades#

Spawner upgrade menu for progression choices, upgrade prices and active upgrade state.

• Configured title: Spawner Upgrades
• Size: 27 slots
• Configured items: 6

Placeholder surface#

Identifier: nexaspawners. PlaceholderAPI and MiniPlaceholders cover totals, player metrics, world/type metrics, spawner metrics, storage, value, boosters and corruption values.

Usage notes#

• Install PlaceholderAPI before using these values in scoreboards or chat formats.
• Reload PlaceholderAPI expansions after plugin updates.
• Keep placeholder identifiers lowercase exactly as shown unless the product uses a legacy mixed-case identifier.

Storage recommendation#

Use file storage for small tests and SQL storage for production economies, leaderboards and seasonal data.

Backup checklist#

• Stop the server before copying live flat files.
• Export SQL databases before updates.
• Keep plugin version and server version in backup notes.
• Test migration on a copy first.

Recommended module baseline#

virtual-engine: true gui-menus: true classic-mode: true storage: true selling: true sellwands: true boosters: true corruption: true ownership-trust: false stacking: true admin-panel: true protection: true holograms: true migrations: true api: true placeholderapi: true

These keys belong to modules.yml. The default build keeps ownership-trust disabled until claim/team rules are reviewed.

Enablement checklist#

1. Copy the generated plugins/NexaSpawners/ directory before editing.
2. Enable only systems your server will expose to players.
3. When trust is needed, set ownership-trust: true and configure trust.enabled in config.yml.
4. Restart after module changes; use /spawner reload for ordinary YAML tuning.
5. Verify the corresponding GUI, command and permission with a non-op account.

Player placement flow#

1. Give a typed item with /spawner give <player> <type> <amount> [stack].
2. Place it in an allowed world or claim. The block becomes a registered virtual spawner.
3. Open it with right-click, or sneak-right-click in classic mode when behavior.classic-mode-requires-sneak-to-open-gui is enabled.
4. Watch production use production.tick-interval-seconds, offline cap and per-cycle budgets.
5. Break it with configured Silk Touch to receive a stateful item containing storage, XP, boosters, upgrades, trust and corruption.

Engine controls#

• server.default-mode chooses VIRTUAL or CLASSIC.
• production.round-robin: true prevents early records consuming every cycle.
• production.region-dispatch: true routes location-sensitive mutations through the scheduler abstraction.
• Production, chunk and cycle caps protect large networks.
• Registered virtual spawners cancel nearby vanilla spawn output.

Type authoring workflow#

1. Copy a file such as spawners/iron_golem.yml for a controlled variant.
2. Set type id, entity data, production interval/count and drop definitions.
3. For every drop define material, min/max amount, chance and explicit sell-price when needed.
4. Set XP and capacity overrides for high-volume types.
5. Reload, give one item and validate GUI lore, hologram, storage and sale output.

Per-type controls#

• limits.type-limits.per-player and per-world override global limits.
• stacking.per-type.iron_golem can cap a specific internal stack.
• corruption.types.iron_golem.multiplier applies type-specific pressure.
• Spawn eggs can change a registered type when enabled in behavior.
• Keep type ids stable; reports, records and placeholders use them as identifiers.

Capacity design#

• storage.capacity.default-items is the base capacity.
• per-stack-bonus scales a stacked spawner.
• per-drop-capacity and per-drop prevent one item consuming all storage.
• Storage upgrades add capacity on top.
• storage.overflow.mode accepts pause, void or overfill.

storage.capacity.default-items: 25000 storage.capacity.per-stack-bonus: 5000 storage.capacity.per-drop-capacity: 10000 storage.overflow.mode: "pause"

Player actions#

1. Open storage from the main spawner GUI.
2. Use take-one-stack, take-all, drop-all or sell-all according to storage.collect.
3. Use /spawner collect for collection and XP, or /spawner sell for a normal sale.
4. Test a full inventory and verify the configured remainder behavior.
5. Reopen the menu and compare the amount with the storage log.

Economy setup#

1. Install Vault and an economy provider.
2. Configure hooks.yml price-provider order and confirm the shop plugin is loaded.
3. Set nexaspawners.sell.multiplier.<number> only for approved ranks.
4. Run one sale from the GUI and one from /spawner sell.
5. Verify pre/post result, storage mutation, Vault deposit and SQL operation status.

selling.permission-multipliers.enabled: true selling.permission-multipliers.default: 1.0 selling.permission-multipliers.max: 10.0

Tool rollout#

• /spawner givesellwand <player> [uses] [multiplier] gives the configured wand.
• /spawner givesellaxe <player> [uses] [multiplier] gives the configured axe.
• Scopes include single, chunk, radius, owner or all-loaded with target caps.
• same-owner-only and require-trust-per-spawner protect area actions.
• Use /spawner sellnotify to test personal success feedback.

Booster layers#

• Spawner boosters apply to one registered spawner from the booster GUI or item.
• Personal boosters affect the player and stack with spawner/global modifiers.
• Global boosters affect server runtime and can be listed or cleared.
• Configured types include INCREASE_SPEED, INCREASE_LOOT, INCREASE_XP, INCREASE_SELL and AUTOSELL.
• Active duration is preserved through restart and stateful break/re-place.

Admin and player commands#

/spawner givebooster <player> <booster> <amount> /spawner givepersonalbooster <player> <booster> [durationSeconds] /spawner globalbooster <booster|list|clear> [durationSeconds]

Use nexaspawners.give, nexaspawners.personalbooster, nexaspawners.globalbooster and nexaspawners.booster as separate boundaries.

Threshold model#

corruption.rate-per-production: 1 corruption.max-corruption: 100 corruption.punishments.slow-at: 50 corruption.punishments.lock-at: 100 corruption.challenge.require-at: 80

• Actions can slow, stop, lock storage, disable selling or require a challenge.
• Disabled worlds and nexaspawners.corruption.bypass must be tested.

Player and staff flow#

1. Open the corruption GUI and read level and alert.
2. Clean using Vault cost or /spawner givecleaner <player> <amount>.
3. When a challenge starts, use /spawner challenge [answer] or the challenge GUI.
4. Verify expiry, cooldown, nearby activity tracking and audit rows.
5. Inspect again after solve/fail and confirm the threshold action changed.

Upgrade configuration#

upgrades.enabled: true upgrades.cost-mode: "PER_STACK" speed.max-level: 10 loot.max-level: 10 xp.max-level: 10 storage.max-level: 10 storage.capacity-per-level: 10000

Release workflow#

1. Open the upgrades menu or use /spawner upgrade.
2. Confirm Vault withdraws the expected amount.
3. Buy one level for each type and compare production/storage/XP.
4. Reach max level and confirm no further charge.
5. Break, replace and restart; levels must remain attached.

Access model#

• Set modules.yml: ownership-trust: true and trust.enabled: true.
• Use /spawner trust <player> [actions] and /spawner untrust <player> [actions].
• Actions are open, sell, collect, boost, upgrade, break, modify and all.
• Inherited access can cover claim/island/team members; keep break/modify explicit.
• Lock with /spawner lock and /spawner unlock.

Limit and placement QA#

1. Set chunk, player and world limits under limits.
2. Test nexaspawners.limit.<number> and nexaspawners.stack.<number>.
3. Test world whitelist/blacklist, claim-only, island-only and spawn-region radius.
4. Validate the active protection plugin through /spawner hooks.
5. Retest owner, trusted, claim member, outsider and bypass accounts.

Stack rules#

stacking.enabled: true stacking.shift-right-click-adds-stack: true stacking.allow-split: true stacking.default-max-stack: 1000 stacking.chunk-max-stack: -1 stacking.per-type.iron_golem: 500

• Limits can be global, per type, per chunk and permission-based.
• Booster matching allows configured remaining-time drift.
• Split items can drop near the player if inventory is full.

Player and admin flow#

1. Place two compatible items and shift-right-click to merge.
2. Use /spawner split [amount] to remove part of the stack.
3. Confirm the split item carries storage, XP, upgrades, trust, lock, boosters and corruption.
4. Try an over-limit merge and verify the held item becomes the leftover amount.
5. Use nexaspawners.stack.split to control who may split.

Explosion policy#

• Configure block/entity explosions, TNT, creepers, withers and fireballs under protection.explosions.
• Choose whether destroyed records unregister and whether natural spawners drop Nexa items.
• Test protected and unprotected worlds; confirm no stale record remains.

Hologram policy#

• Provider order can use PacketEvents, FancyHolograms, DecentHolograms, CMI or native.
• Set refresh interval, throttle, visibility and lines in holograms.
• Use /spawner holograms on|off|refresh after provider changes.

Anti-ESP policy#

• Blocks and holograms have separate reveal/hide distances and update budgets.
• Use nexaspawners.antiesp.bypass for staff.
• Check fake materials per dimension and cross both distance thresholds.

Menu map#

• guis/main.yml links storage, XP, boosters, trust, corruption, upgrades, sell, logs, split and info.
• Storage, boosters, corruption, trust, upgrades, logs, spawner list and admin panel have focused menus.
• Confirm-sell and setup-confirm protect economic/destructive actions.
• Materials, lore, colors, model data, provider ids, PDC tags and permissions are configurable.

Editor workflow#

1. Grant nexaspawners.editor and run /spawner editor.
2. Use the editor for type, booster, storage and preset summaries.
3. Complete chat prompts for names, entity, production, drops, prices, booster duration/multiplier and capacity.
4. Reload and compare generated YAML with a backup.

Panel workflow#

1. Open /spawner panel and filter by search, owner, type, dimension or status.
2. Inspect with /spawner inspect <id> before changing a record.
3. Use teleport, logs, export, clear storage, force sell, lock/unlock or owner transfer only after checking the id.
4. For bulk work use /spawner panel bulk <clear|sell|delete|lock|unlock|export> confirm.
5. Verify affected count and action log.

Recovery tools#

/spawner export [csv|json] /spawner backup /spawner operations [list|limit] /spawner operations resolve <operationId> <completed|failed> [note] /spawner seasonreset <economy|storage|xp|corruption|boosters|all> confirm

Reserve nexaspawners.panel, nexaspawners.export, nexaspawners.seasonreset and bypass permissions for a small staff group.

Preset workflow#

1. Choose donutsmp, skyblock, lifesteal, survival or op_economy.
2. Run /spawner setup <preset> preview and review production, capacity, limits, hooks and corruption.
3. Apply with /spawner setup <preset> apply during maintenance.
4. Run player and economy smoke tests.
5. Use /spawner setup rollback for the current runtime snapshot.

Migration workflow#

1. Back up SQL and export a report.
2. Run /spawner migrate <plugin> or /spawner convert.
3. Use lifecycle simulate/export before claim/island cleanup.
4. Review owner mapping, type ids, storage and duplicates.
5. Keep source data until verification is signed off.

Economy and prices#

Configure Vault plus ShopGUIPlus, ExcellentShop, Essentials worth, Nascraft, zShop and EconomyShopGUI in hooks.yml. Test a known item, unknown item and provider outage.

Claims and islands#

Enable only active WorldGuard, GriefPrevention, ProtectionStones, Lands, Towny, Factions, HuskClaims, SuperiorSkyblock2, BentoBox or IridiumSkyblock adapters. Test placement, trust inheritance and cleanup.

Items and webhooks#

Custom item ids can come from ItemsAdder, Oraxen or Nexo. Webhooks can filter sell, admin, migration and corruption events with timeout, retry and rate limits.

Public integration surface#

• The Bukkit service exposes loaded/owned spawners, type and booster definitions, storage, XP, corruption, sell value, active boosters and hook status.
• Addon providers can register prices, migration adapters, protection resolvers, hologram providers and booster types.
• Events cover placement, break, open, production, storage, sell, boosters, corruption, migration, access checks and admin actions.
• StorageChangeEvent observes production, collect, drop, sell, autosell and admin-clear mutations.

Display setup#

1. Install PlaceholderAPI or MiniPlaceholders and enable the matching module.
2. Use global, player, world, type and single-spawner placeholders.
3. Start with %nexaspawners_player_value%, %nexaspawners_total_storage% and %nexaspawners_spawner_<id>_corruption%.
4. Test offline and unknown-id fallbacks.

Storage selection#

• SQLite uses nexaspawners.db, WAL and a configurable busy timeout.
• MySQL/MariaDB use host, port, database, username, password and SSL under database.storage.
• The async deduplicated queue batches dirty records and flushes on interval and clean shutdown.
• Schema versioning helps upgrades, but a backup is still required.

Backup runbook#

1. Enable startup and periodic backups with retention.
2. Install the configured mysqldump or mariadb-dump executable for SQL backups.
3. Run /spawner backup and confirm a readable artifact.
4. Restore a copy on staging and verify owners, storage, XP, boosters and logs.

Stage 1 — sandbox#

• Use one type, one player and SQLite.
• Test every GUI action and command with non-op accounts.
• Confirm no duplicate drops, XP or Vault deposits.

Stage 2 — pilot#

• Apply the chosen preset on a copy.
• Test 10–50 spawners across chunks, worlds and ownership states.
• Measure production queue, storage growth, database flushes and webhook limits.

Stage 3 — live#

• Use SQL and verified backups for network-scale data.
• Restrict admin/bypass and seasonal reset permissions.
• Record plugin, server, Java, hook and preset versions.

Player spawner loop#

1. Give/place a spawner and open /spawner panel or /spawner list.
2. Inspect type, amount, owner, storage, sell value and active boosters.
3. Configure trusted players with /spawner trust <player> [actions].
4. Apply an upgrade or booster and verify duration/stack behavior.
5. Sell through the panel, sell wand/axe or configured auto-sell path, then inspect logs.

Admin recovery loop#

1. Use /spawner inspect <id> before changing ownership.
2. Export the selected spawner before clear/delete/forcesell.
3. Use /spawner setowner, clearstorage or remove only with a ticket/audit reason.
4. For lifecycle actions run preview/simulate, review the filter, then apply with confirmation.

Booster baseline#

limits:
  max-active-per-spawner: 3
application:
  item-cost-mode: "PER_STACK"
global:
  enabled: true
personal:
  enabled: true
  persist: true

Economy test#

Test one storage fill, one sale, one blocked item and one economy-provider failure. Confirm items are not removed when the transaction cannot be completed and that the audit/log entry explains the result.

SkyBlock Spawners Setup#

Apply this setup by editing the related config files, assigning permissions and testing the full player workflow.

Lifesteal Economy Setup#

Use stricter cooldowns, staff visibility, abuse protection and clear player feedback for high-conflict gameplay.

Small SMP Setup#

Use conservative defaults, SQLite or simple file storage, readable messages and relaxed limits for community servers.

Seasonal Reset Setup#

Map permissions to progression tiers, test upgrades, then document reset or season migration behavior.

Network Economy Setup#

Use production SQL, unique server IDs, shared sync secrets and a controlled Redis or proxy transport.

Before asking for support#

• Test on the latest available plugin version.
• Check server version and Java version.
• Temporarily remove unrelated plugins when debugging conflicts.
• Attach changed YAML files when config is involved.