Andre Mertes | MZEssentials

Über das Plugin

MZEssentials ist ein Plugin für PaperMC Minecraft-Server, das die notwendigstenen Funktionen wie Login, Währung, Ränge, Verwaltung der Welten, uvm. bereitstellt.

Voraussetzungen

check_circle Java 21 JDK
check_circle PaperMC 1.21.4+

Installation

1. MZEssentials-1.0.0.jar in plugins/ kopieren
2. Serverstart erzeugt plugins/MZEssentials/config.yml
3. Datenbank (SQLite oder MySQL) sowie weitere Einstellungen des Plugins in config.yml konfigurieren
4. Server neu starten

Direkt nach dem ersten Start sollte unbedingt von der Konsole aus der erste Spieler zum Inhaber gemacht werden:
mzadmin setrank <deinName> INHABER

Datenbank konfigurieren


                          	database:

  							  type: sqlite

							  sqlite:

							    file: database.db   # liegt in plugins/MZEssentials/

SQLite ist standardmäßig eingestellt, in diesem Fall ist kein Setup notwendig. Es empfiehlt sich jedoch, bei Servern mit einer größeren Spieleranzahl auf eine MySQL-Datenbank umzusteigen!

MySQL-Datenbank


                          	database:

  							  type: mysql

                              mysql:

							    host: localhost

    						    port: 3306

    						    database: mzessentials   # Datenbank muss vorher existieren

    						    username: mc_user

    						    password: "sicheresPasswort"

    						    params:

      						      useSSL: "false"

      						      serverTimezone: "UTC"

      						      characterEncoding: "utf8"

      						      allowPublicKeyRetrieval: "true"

      						      autoReconnect: "true"

    						      pool_size: 3 # 2–5 empfohlen

MySQL-Datenbank anlegen


                            CREATE DATABASE mzessentials CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

							CREATE USER 'mc_user'@'localhost' IDENTIFIED BY 'sicheresPasswort';

							GRANT ALL PRIVILEGES ON mzessentials.* TO 'mc_user'@'localhost';

							FLUSH PRIVILEGES;

Das Plugin erstellt alle Tabellen beim ersten Start automatisch.

Konfiguration (config.yml)


                            auth:

						  	  login_timeout_seconds: 60     # Kick nach X Sekunden ohne Login

  							  max_login_attempts: 5         # Fehlversuche → Jail + Sperre

	  						  min_password_length: 6        # Mindestlänge Passwort

  							  reset_token_expiry_minutes: 10

							economy:

  							  starting_balance: 500.0       # Startgeld für neue Spieler

  							  currency_symbol: "€"

							plot:

  							  sell_refund_percent: 50       # % des Kaufpreises beim Grundstücks-Verkauf (0–100)

							ranks:

	 	 					  INHABER:

    						    prefix: "<gold>[Inhaber]</gold>"   # MiniMessage-Format!

    						    color: "<gold>"

4. Command-Referenz

Authentifizierung

Command	Beschreibung
`/register <pw> <pw>`	Account erstellen (sofort eingeloggt)
`/login <passwort>`	Einloggen
`/logout`	Ausloggen (Inventar gespeichert, geleert)
`/changepassword <alt> <neu>`	Passwort ändern
`/deleteaccount <passwort>`	Account löschen
`/forgotpassword`	Reset-Code im Chat anzeigen
`/resetpassword <code> <neuPw>`	Passwort mit Code zurücksetzen

Vergessen-Ablauf:
/forgotpassword → 8-stelliger Code erscheint im Chat (nur für dich sichtbar) → /resetpassword XY12AB34 neuesPw → fertig.
Der Code läuft nach 10 Minuten ab.

Wirtschaft

Command	Beschreibung
`/balance` (Alias: `/bal`, `/konto`)	Kontostand anzeigen
`/pay <spieler> <betrag>`	Überweisung an anderen Spieler

Grundstücke

Command	Beschreibung
`/plot list`	Kaufbare Grundstücke anzeigen
`/plot buy <name>`	Grundstück kaufen
`/plot sell`	Grundstück verkaufen
`/plot info`	Infos und Verkaufswert anzeigen

Kistenshop

Command	Beschreibung
`/shop create <preis>`	Kistenshop erstellen
`/shop remove`	Shop entfernen
`/shop info`	Shop-Informationen anzeigen

Post

Command	Beschreibung
`/mail send <spieler> <text>`	Brief senden
`/mail read`	Briefe lesen
`/mail setbox`	Briefkasten setzen
`/mail removebox`	Briefkasten entfernen

Teleport

Command	Beschreibung
`/tpa <spieler>`	Teleport-Anfrage senden
`/tpaccept`	Anfrage annehmen
`/tpdeny`	Anfrage ablehnen
`/warps`	Alle Warps anzeigen
`/warp <name>`	Zu Warp teleportieren

Hilfe

Command	Beschreibung
`/mzhelp [seite]`	Alle Befehle anzeigen

Admin-Handbuch

Das Auswahl-Werkzeug


/mztool get
→ Magischer Stick ins Inventar

Rechtsklick auf Block → Pos1
Linksklick auf Block  → Pos2
/mztool sel           → Aktuelle Auswahl anzeigen

Gebiete definieren


# Anti-Grief-Zone
/mztool define region Spawn-Schutz

# Kaufbares Grundstück
/mztool define plot Grundstück-A1 500

# Gefängniszelle
/mztool define jailcell Zelle-1

# Warp-Punkt
/mztool define warp Spawn

# Poststelle
/mztool define postoffice Hauptpost

# Portal → andere Welt
/mztool define portal City-Portal city 0 65 0 90

Admin-Befehle


/mzadmin setrank <spieler> INHABER|BEWOHNER|GAST
/mzadmin jail <spieler> [zelle] [minuten]
/mzadmin unjail <spieler>
/mzadmin resetpw <spieler>
/mzadmin kick <spieler> [grund]
/mzadmin balance <spieler>
/mzadmin give <spieler> <betrag>
/mzadmin take <spieler> <betrag>

Implementierungs-Erklärungen

Authentifizierung & Inventar-Swap


Beitritt  → Inventar sofort leeren
/login    → BCrypt-Verify → Inventar laden
/logout   → Inventar speichern → Inventar leeren
Abgang    → automatisch wie /logout

Nicht eingeloggte Spieler besitzen immer ein leeres Inventar. Dadurch sind klassische Item-Exploits ausgeschlossen.

Portal-System / Multi-Welt

Portale bestehen aus frei definierbaren Quader-Bereichen. Beim Betreten prüft ein Listener automatisch den Bereich und teleportiert den Spieler nach einem kurzen Cooldown.

Sicherheitskonzept

Bedrohung	Maßnahme
SQL-Injection	PreparedStatements
Passwort-Klartext	BCrypt + Salt
Brute-Force Login	5 Fehlversuche → Jail + Sperre
Item-Exploits	Inventar sofort leeren
Portal-Spam	3-Sekunden-Cooldown

Migrations-System

Das Plugin versioniert automatisch das Datenbankschema über eine schema_version-Tabelle.


1. schema_version-Tabelle anlegen
2. Aktuelle Version lesen
3. Fehlende Migrationen ausführen
4. Version aktualisieren

Bekannte Limitierungen & Hinweise

info /pay: Überweisungen funktionieren nur bei Online-Spielern.
info SQLite: Bei vielen gleichzeitigen Spielern wird MySQL empfohlen.
info AsyncPlayerChatEvent: Veraltet, funktioniert aber weiterhin.
info Portal-Welten: Zielwelten müssen bereits existieren.

Datenbankschema


players              – Accounts, Rollen, Guthaben
player_inventories   – Gespeicherte Inventare
password_reset_tokens– Reset-Codes
plots                – Grundstücke
protected_regions    – Anti-Grief-Zonen
jail_cells           – Gefängniszellen
warps                – Warp-Punkte
mails                – Briefe
chest_shops          – Kistenshops
mailboxes            – Briefkästen
post_offices         – Poststellen
portals              – Multi-Welt-Portale
schema_version       – Migrations-Versionen