Skip to content

Add documentation for SpawnsMerger plugin #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
FrostyxAlien wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add documentation for SpawnsMerger plugin #1

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 39 additions & 51 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,51 +1,39 @@
# PAUSED - CURRENTLY WORKING ON OTHER THINGS


// Welche Versionen wurden benutzt?

Minecraft Version 1.21.5
JavaJDK 21 - auf Paper

APIs
- NBTApi


// Was kann das Plugin?

-Mob-Spawner mit begrenzten Spawnanzahl der Mobs
-Mob-Spawner zusammenführen zu einem mit rechte und linke Hand (Spawner mit 5 Spawns + Spawner mit 20 Spawns = 25 Spawns Spawner des gleichen Mobtyps)

// Wird noch hinzugefügt oder geändert
- GUI (hinzugefügt - wird noch überarbeitet)
- Hologram über platziertem Spawner
- Code wird überarbeitet

// Konzept Stand 16.08.2025
- GUI für Spawner-Verwaltung
Spawner fusionieren
Spawner einfrieren
Spawnrate anpassen
Spawner Statistik
Spawner Level Upgrade

- Spawner einfrieren
Visueller Effekt: Eisblaue Partikel & Eisblock-Hülle um den Spawner
Mit Redstone einfrieren oder mit einem Schneeball

- Spawner zusammenführen / fusionieren (Merge-System)
Zwei gleiche Spawner im gleichen Level im GUI kombinieren für mehr Spawns

- Spawn-Raten-Anpassung (In der Config die maximale Rate einstellen um Laggs zu vermeiden)

- Spawner Upgrades (vorerst bis Level 5)
Level 1: Standard (1 Mob / 20s)
Level 2: 2 Mobs / 18s
Level 3: +5% Dropchance auf seltene Items
Level 4: Mobs mit Custom Effekt + 8% Dropchance auf seltene Items
Level 5: 3 Mobs / 15s + 10% Dropchance auf seltene Items + 5% XP-Multiplikator (mehr XP pro Mob)

- Custom Mobs Spawner (kann in der Config deaktiviert werden)

// Permissions
- frostyspawner.use - Grundlegende Nutzung - mit GUI
- frostyspawner.admin - Administrative Funktionen
# SpawnsMerger

SpawnsMerger is a Paper plugin that introduces limited-use mob spawners and a simple merging system. Players can generate spawners with a fixed number of remaining spawns, place them, and combine compatible spawners through a GUI to extend their lifespan.

## Features
- **Limited spawner items:** `/givespawner` creates a spawner item tagged with a mob type and a remaining spawn count using the NBT-API library.
- **Placement support:** When a tagged spawner is placed, the block is configured to the stored mob type and the remaining count is saved in the spawner's persistent data container.
- **Spawn consumption:** Each spawn reduces the remaining counter; when it reaches zero the spawner block is removed.
- **Hologram feedback:** Right-clicking a spawner shows an armor-stand hologram with the mob type and remaining spawns, which is updated after each spawn and automatically cleared after a short delay.
- **Silk Touch drops:** Breaking a limited spawner with Silk Touch drops an item preserving the mob type and remaining spawns.
- **Merge GUI:** `/mergespawner` opens a 27-slot GUI with two input slots. Inserting two limited spawners of the same type combines their remaining counts into a single item.

## Requirements
- Paper (or compatible) server targeting Minecraft 1.21.x
- Java 21 runtime
- [NBT-API](https://www.spigotmc.org/resources/nbt-api.7939/) plugin present on the server (declared as a dependency in `plugin.yml`)

## Installation
1. Build the plugin: `./gradlew build`
2. Copy the generated JAR from `build/libs/` into your server's `plugins` folder.
3. Ensure NBT-API is installed, then start or reload the server.

## Commands
| Command | Description | Usage |
|---------|-------------|-------|
| `/givespawner <MobType> <Spawns>` | Gives the executing player a spawner item for the specified mob type with the given remaining spawn count. Only valid, spawnable mobs are accepted. | `/givespawner ZOMBIE 20` |
| `/mergespawner` | Opens the merge GUI. Place two compatible limited spawners into the left/right slots and click the anvil to combine them. Items are returned automatically if the GUI is closed. | `/mergespawner` |

## Gameplay Notes
- The hologram is anchored above the spawner block and fades automatically; breaking the spawner also clears the hologram.
- Spawners without the plugin's NBT tags behave like normal spawners and cannot be merged.
- Using Silk Touch is required to retrieve a placed limited spawner as an item; otherwise it breaks without drops.

## Development Overview
- **Entry point:** `SpawnsMerger` registers commands and listeners on enable/disable.
- **Command executors:** `SpawnerCommand` creates tagged spawner items; `SpawnerMergeCommand` opens the GUI for players.
- **Listeners:** `SpawnerListener` handles placement, interaction, spawning, and breaking logic, including hologram management. `SpawnerMergeGUI` manages the merge inventory interactions.

Contributions and bug reports are welcome! Feel free to open issues or pull requests for enhancements.