> For the complete documentation index, see [llms.txt](https://wiki.dyroxplays.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.dyroxplays.de/buyperms/konfiguration/eigene-items.md).

# Eigene Items & Ränge

In diesem Guide lernst du, wie du eigene kaufbare Berechtigungen (Permissions) und Ränge in der Shop-GUI deines **BuyPerms**-Plugins erstellst und konfigurierst.

***

## Grundlagen des Shop-GUI

Die Shop-GUI ist seiten- und slotbasiert aufgebaut. Du kannst für jede Seite das Layout und die kaufbaren Angebote genau bestimmen.

* **Seiten-Index:** Beginnt bei `1`. Du kannst unbegrenzt viele Seiten anlegen (`items.1`, `items.2` etc.).
* **Slot-Index:** Jede Zeile im Inventar hat 9 Slots (0-8 für Zeile 1, 9-17 für Zeile 2 usw.). Die maximal konfigurierbaren Slots hängen von der `guisize` in der `config.yml` ab.

***

## Konfigurations-Struktur

Jedes Verkaufs-Item wird in der `config.yml` unter dem Abschnitt `items` folgendermaßen deklariert:

```yaml
items:
  '<Page>':
    '<Slot>':
      item: 'MATERIALNAME'   # Minecraft-Material (z.B. GOLD_INGOT oder DIAMOND)
      name: 'Anzeigename'     # Anzeigename des Items im Menü
      price: 100             # Preis in Tokens (oder Geld, falls usevault=true)
      mode: 'MODUS'          # Zuweisungs-Modus (addpermcmd, addgroupcmd, setgroupcmd)
      
      # Modus-spezifische Keys (nur einer wird benötigt):
      perm:                  # Benötigt bei mode: addpermcmd
        - 'permission.name'  # Liste der zuzuweisenden Permissions
      group: 'Rangname'      # Benötigt bei mode: addgroupcmd / setgroupcmd
      extra: 'lifetime'      # Optionaler Parameter (z. B. Dauer oder Welt)
      
      lore:                  # Beschreibungstext des Items im Menü
        - '&7Zeile 1'
        - '&7Zeile 2'
```

***

## Die drei Kaufmodi

Das Plugin führt bei einem Kauf einen der vordefinierten Befehle aus der `config.yml` aus. Je nach gewähltem `mode` werden unterschiedliche Platzhalter ersetzt:

### 1. `addpermcmd` (Zuweisen von Permissions)

Vergibt eine oder mehrere Berechtigungen an den Spieler.

* **Ersetzter Befehl:** `%perm%` wird durch die Liste der Berechtigungen unter `perm` ersetzt. `%extra%` wird mit dem Wert aus `extra` befüllt.
* **Beispiel-Befehl:** `pex user %player% add %perm% %extra%`

### 2. `addgroupcmd` (Hinzufügen zu einer Gruppe/Rang)

Fügt den Spieler einer Rechtegruppe hinzu (z. B. als Zweitgruppe).

* **Ersetzter Befehl:** `%group%` wird durch den Wert unter `group` ersetzt. `%extra%` wird mit dem Wert aus `extra` befüllt.
* **Beispiel-Befehl:** `pex user %player% group add %group% %extra%`

### 3. `setgroupcmd` (Setzen eines Haupt-Rangs)

Überschreibt den aktuellen Rang des Spielers und setzt die neue Gruppe als Hauptgruppe.

* **Ersetzter Befehl:** `%group%` wird durch den Wert unter `group` ersetzt. `%extra%` wird mit dem Wert aus `extra` befüllt.
* **Beispiel-Befehl:** `pex user %player% group set %group% %extra%`

***

## Schritt-für-Schritt-Anleitung: Neuen Rang hinzufügen

Hier siehst du, wie du beispielsweise einen VIP-Rang für 500 Tokens zum Kauf anbietest.

{% stepper %}
{% step %}

#### Slot im GUI bestimmen

Wir wollen den VIP-Rang auf Seite **1** im Slot **20** (mittlere Reihe) platzieren.
{% endstep %}

{% step %}

#### Material & Namen festlegen

Als Symbol wählen wir ein `GOLD_INGOT`. Der Anzeigename soll in goldener Farbe erstrahlen: `&6&lVIP Rang`.
{% endstep %}

{% step %}

#### Preis & Modus konfigurieren

Der Preis beträgt `500` Tokens. Da es sich um eine Gruppen-Zuweisung handelt, setzen wir den Modus auf `addgroupcmd` und verweisen auf die Gruppe `VIP`. Als Extra-Parameter übergeben wir `lifetime` (für unbegrenzte Dauer).
{% endstep %}

{% step %}

#### YAML in config.yml eintragen

Füge folgenden Block unter `items` in deiner `config.yml` hinzu:

```yaml
items:
  '1':
    '20':
      item: GOLD_INGOT
      name: '&6&lVIP Rang kaufen'
      price: 500
      mode: addgroupcmd
      group: VIP
      extra: lifetime
      lore:
        - '&7Erhalte dauerhaften Zugriff'
        - '&7auf alle VIP-Vorteile!'
        - ''
        - '&7Preis: &e500 Tokens'
```

{% endstep %}
{% endstepper %}