Grims Super Spawners

Target: Paper 26.3.build.194-stable API, Java 25. Plugin name and data folder: GrimsSuperSpawners. Command: /superspawners, alias /gss. Package prefix: com.evergrims.SuperSpawners.

Commands

All commands other than limits/help require grimssuperspawners.admin. Give, status, reload, audit, and forget can run from console. Adopt's owner and give's recipient must be online. Mob identifiers use names such as zombie, cave_spider, or minecraft:cow.

Permissions

Use explicit numeric nodes; numeric wildcards are not an unlimited permission. False nodes are excluded. Each player has an individual allowance; a permission group does not share a collective pool.

Example with LuckPerms:

/lp group default permission set grimssuperspawners.limit.5 true
/lp group staff permission set grimssuperspawners.bonus.2 true

An inherited five-slot allowance plus the staff bonus gives seven slots. Alternatively, give staff grimssuperspawners.limit.7. Do not apply both approaches unless the additional bonus is intentional. Multiple inherited limits/bonuses use their highest value, not their sum. Lower explicit limits (including zero) override the configuration fallback.

Permissions are checked again for every change. A downgrade preserves existing spawners and their capacity usage; it prevents additions until there is room. Pickup remains available. The global level cap similarly blocks new placements/upgrades above the cap without deleting existing levels.

Placement and upgrades consume the spawner item even in creative mode. Normal spawner gameplay actions are unavailable in adventure/spectator mode. Pickup returns one whole-level item directly to inventory and awards no vanilla break experience.

Configuration

plugins/GrimsSuperSpawners/config.yml includes comments and every setting. Main defaults:

For spawners, mobs.allowed is an optional whitelist and mobs.denied always wins. Spawners support living, spawnable types with ordinary egg materials. Their rules do not change in this release.

For capture, capture.blacklist always wins. With capture.allow-all-except-blacklist: false, the spawner rules and the additional capture.allowed whitelist also apply; an empty capture whitelist adds no restriction. With the switch true, only the capture blacklist restricts mob species. Living spawnable types lacking an ordinary egg use a typed fallback egg. Players are never captured. Misspelled mob identifiers reject config reload and leave the previous valid settings active.

Existing 0.1.0 configs are accepted without overwriting them. Absent switches default to false. If capture.blacklist is absent, it inherits the current mobs.denied values for compatibility. Add explicit keys to the existing capture section to customize them; do not add a second capture: section.

Exact saved mobs

capture.exact-mob: true uses Paper's versioned binary entity serialization, saving full persisted entity NBT rather than selecting individual properties. This covers tame state and original owner UUID, custom name, age/variants, health, attributes and modifiers, equipment and drop settings, inventory, villager trades, potion effects, scoreboard tags, and persistent plugin data when stored in the entity. Original entity UUID and facing are retained; position/world change to the release location. Time spent in the egg does not tick the mob.

Named/tamed/equipped/inventory-carrying/plugin-data mobs are allowed in exact mode when their species is eligible. It preserves ownership; catching someone else's pet does not transfer its tame owner. Claim/custom-mob plugins can deny capture through MobCaptureEvent.

Paper cannot serialize temporary Bukkit metadata, live AI callbacks, or records kept only in another plugin's database. NPC/Mythic/custom-mob functionality beyond saved NBT needs that plugin's integration; test those plugins or cancel capture for their entities. External entity links are not silently dropped: unleash the mob and remove riders/passengers before capture in either mode.

Use an exact egg on an ordinary block to release the saved mob in the adjacent space. Both hands work. The egg is consumed even in creative. There must be room, the world must allow the action, and protection checks must pass. Cancelled/failed spawning refunds the egg after removing any partially spawned mob. Release uses native SPAWNER_EGG spawn reason and also fires the player-aware MobReleaseEvent. Using the egg on another mob, any spawner, or a dispenser is blocked with feedback so native egg behavior cannot discard or duplicate its contents. Regular eggs still convert spawners as before.

Turning exact capture off or changing the capture blacklist does not invalidate eggs already holding mobs. Release has its own permission and still respects disabled worlds and protections.

Type-only mode retains the previous exclusions for tamed mobs, mobs with contents, NPC/Mythic metadata, persistent plugin data, and scoreboard tags. It produces a fresh type egg, so original names (when explicitly allowed), equipment, attributes, age and trades are not saved. Misses and non-capture projectiles keep normal behavior; handled capture hits cancel damage and thrown-egg hatching.

Spawning and estimates

This plugin configures native Paper spawner blocks. In the default speed mode, attempts stay at base-spawn-count; minimum and maximum delays each become ceil(configured delay / level), bounded below by minimum-scaled-delay-ticks (default 20). This floor limits very high levels: level 50 with defaults has a one-second cycle, not a near-zero timer. In batch mode, attempts become level * base-spawn-count and delays remain unchanged. Only one production multiplier applies. Valid spawn conditions, nearby caps, and protection events still apply; no mobs or drops are artificially multiplied.

With the supplied 100–800 tick defaults:

The displayed estimate is:

floor(min(effective attempts, nearby-mob-cap)
      * 1200 / effective maximum delay * estimate-success-factor)

The menu uses the same effective profile as the actual block and shows its delay/attempt count. Estimates are not measured production. OFF output is zero; the menu also reports when the world mob ceiling is holding production. Actual output can be zero even while ON. These controls do not alter Minecraft's natural-spawn category caps or bypass another plugin's restrictions.

ON/OFF and physical active limits

The menu's dye button switches an owned block ON/OFF. Level 5 counts as one active block and five owned slots. Two ON level-5 blocks require an active limit of at least two and an owned allowance of at least ten. OFF blocks still consume owned slots; the switch is not a way to bypass ownership capacity. ON blocks in unloaded chunks still reserve an active allowance, even though native spawning cannot run in an unloaded chunk.

New placement/adoption starts OFF when the owner's active limit is full. Merging/upgrading/converting an OFF block keeps it OFF. Picking up an ON block frees its active allowance. Turning another block OFF does not automatically enable waiting blocks. Only the owner with toggle permission can switch it; manage-others permission does not grant toggling. Region protection checks TOGGLE actions.

Startup/reload enforce lowered active limits for offline owners and unloaded chunks too. Active records are ordered by stable block ID; excess records become OFF and an audit entry records each change. No levels or items are deleted. Zero disables all owned production. Bypass permission never bypasses this safety limit.

Persistent mobs

spawning.persistent-mobs defaults to true, including for configuration files written before this release. Every mob accepted from a managed spawner is marked persistent, so it neither despawns as players move away nor disappears when its chunk unloads and reloads. Cancelled spawn attempts are never marked, and mobs from vanilla spawners, other plugins, breeding, or released saved-mob eggs are untouched.

Setting it to false returns new managed spawns to vanilla distance despawning. Changing the setting either way and reloading also applies the new state to the loaded mobs this plugin spawned; mobs a player has named and tamed mobs are never made despawnable again, matching vanilla's own protection. Unloaded mobs keep the state they were saved with until they return and their spawner produces again.

Persistent mobs make the production brakes matter more, not less: nearby-mob-cap still stops a spawner whose area is full, and loaded-spawner-mob-limit-per-world still pauses managed production for the world. Neither culls existing mobs, so an unattended farm holds its population instead of thinning out between visits. /gss status prints the current state with both limits.

Loaded mob ceiling

New managed spawning waits when a world reaches loaded-spawner-mob-limit-per-world. Counts include tagged plugin mobs and mobs Paper identifies as spawner-born, including older/native-spawner mobs, across the whole loaded world. Moving them into a pit does not free room. Capture, removal, or chunk unloading frees room; returning loaded entities are counted again. Entity events maintain the index without a world scan for every spawn. Startup seeds it from loaded mobs, and cancelled spawn reservations are released.

Existing mobs are never culled. The limit gates this plugin's managed spawners; it does not cancel other plugins' spawning, manually released eggs, or chunk loading. Those sources can put the actual count above the configured ceiling, at which point managed production waits. This is not a server-wide hard population limit or a performance guarantee. The menu shows the count/waiting state, and console notices are limited to one per minute per world. Clear the farm's collection area to resume production. Keep native nearby limits and sensible level/owned allowances too.

Managed block settings are restored on chunk load, startup, and reload. Existing spawners whose types become denied stop spawning, retain their slots, and may still be picked up or converted to an allowed type. Trial spawners and unmanaged natural spawners are not automatically adopted.

Protection and persistence

WorldGuard 7 is checked directly at the location of the actual action. Block-place/break/interact flags and region membership are respected, including WorldGuard's own bypass state. Capture checks build/animal-damage access; saved-mob release checks build/block-place access at its destination. A broken or disabled installed WorldGuard adapter rejects affected actions and emits a severe error.

The plugin honors cancelled native placement, interaction, break, and projectile events when they reach its HIGHEST-priority handler. For other claim/protection plugins, wire the public cancellable SpawnerActionEvent, MobCaptureEvent, and MobReleaseEvent (see the integration guide), especially for menu actions and delayed actions. Do not assume every protection plugin supports these custom actions without an adapter. Do not run two competing spawner pickup/placement handlers on the same blocks.

Explosions cannot destroy managed spawners; pistons and entity block changes are blocked where they would move/replace one. Administrative world-edit commands can bypass ordinary Bukkit events: ownership data is intentionally retained when its block disappears, and the mismatch is reported instead of silently freeing capacity.

spawners.db schema 2 stores owner UUID, world UUID, coordinates, type, level, ON/OFF state, block identity, revision, and a committed transaction audit. The upgrade preserves old records and then enforces the active limit. Slot totals include all stored worlds/chunks. Spawner items contain type/level/version but no owner or unique serial, allowing matching items to stack and trade. Placement assigns ownership; pickup releases it.

captures.db schema 2 keeps each original mob's unique token, UUID, species, complete binary payload, times, spent status, and matching-data group. New stackable eggs hold the group's fingerprint; original payloads stay in the database. Equivalent eggs share a pool, and one stack unit claims one unused original record from that pool. Copies cannot release more originals than were captured; as with any copied inventory item, a copy can consume an entitlement before the legitimate holder. Groups can be traded and split normally, but remain tied to this server's database. Never use infinite shop templates for these eggs.

Capture consolidates matching eggs into the first compatible main-inventory slot (0–35), up to 64 per stack. Gameplay NBT is compared after sorting compound keys. Only root identity/location/motion/facing/world-origin/age-in-ticks/fall-position bookkeeping and our source-spawner tag are ignored for matching. Every original payload remains unchanged. Baby/adult state, health, equipment, name, tame owner, attributes/modifiers, inventories, trades, effects, scoreboard tags, and foreign persistent data still distinguish groups. Visually identical mobs with different hidden attributes will remain separate. Older individual exact eggs still release normally and are converted/consolidated when a matching mob is next captured.

Both database schemas upgrade automatically; do not downgrade without restoring the matching pre-upgrade world/player/database backup.

Captures are recorded durably before removing the original mob. Releases durably spend the token before spawning; normal failures undo spawn/payment and refund the token. A forced kill in that narrow interval can leave a spent token without a live mob. Records retain the payload for administrator recovery and are not automatically replayed. Restore a consistent backup after such an interruption; never reset spent flags without confirming the original entity is absent from all saved chunks and inventories. Do not delete or replace captures.db while saved eggs exist, or run an older plugin version while using these eggs.

Operations validate payment/capacity/protection before changing anything. A small synchronous SQLite transaction stages the record, applies inventory/block changes, and commits. A failed operation rolls back its database transaction and applied inventory/block snapshots. Unexpected failures pause all further mutations and managed spawning for administrator review.

Minecraft world/player saves and SQLite are separate persistence systems: this is not a guarantee of atomic recovery across a forced process kill or restoration of mismatched backups. Stop the server cleanly and back up the world, player data, and the entire plugins/GrimsSuperSpawners/ folder together. Preserve SQLite -wal/-shm sidecars if taking a filesystem snapshot while running; a stopped-server backup is preferred.

Errors and recovery

Normal rejections use a red action bar and a quiet sound. Severe errors use SEVERE console records prefixed [EGW][GrimsSuperSpawners], full exception traces under the new package, prominent messages to grimssuperspawners.alerts, and a louder sound. Repeated identical severe errors are grouped and counted every 30 seconds.

1. Run /gss status and read the first related error in the server log.
2. For a paused database/save failure, fix the storage/permission problem and restart cleanly. /gss reload validates settings but deliberately does not clear an error pause.
3. For a stale block, inspect its record and world location. Restore matching world/database backups when appropriate. If the original block is intentionally gone, load the chunk and use the exact forget ... confirm command to release its recorded slots.
4. An orphan marked block with no database record stays protected and cannot spawn; recover it from a consistent backup. The plugin never invents an owner or silently imports its level.
5. Do not delete the database to reset limits: the remaining marked blocks will be orphaned.

Changing this plugin's Java package does not rename an external watchdog configuration automatically. Configure AskNixie's EGW watchdog to recognize com.evergrims.SuperSpawners if it maintains an explicit package list; AskNixie itself was not modified.

Optional mob merging (0.1.4)

MOB-MERGING.md contains all new configuration and operating rules. Merging defaults OFF. The loaded world budget counts every member of each merged group, rather than only its representative. Do not downgrade while merged groups remain.

Error ranks and AskNixie

See WATCHDOG.md. Rank 1 NOTICE records action denials; rank 2 WARNING covers recoverable problems; rank 3 ERROR covers failed or blocked operations; rank 4 CRITICAL covers startup/shutdown, fatal runtime and recovery failures. Reports are never suppressed from the server log. Nixie must have the exact plugin identity enabled; rank parsing and bot routing are separate from log emission.