# Command-Sichtbarkeit

Das `permissions`-Modul filtert die Befehlsliste, die der Client für die Tab-Vervollständigung nutzt: Spieler sehen nur noch die Commands, die sie mit ihren Permissions auch wirklich benutzen dürfen. Zusätzlich verschwinden Namespace-Varianten wie `bukkit:tp`, `minecraft:gamemode` oder `coreengine:home` aus der Vorschlagsliste. Wer noch strenger filtern will, schaltet den Whitelist-Modus ein: Dann sehen Spieler ausschließlich die Commands, die für ihre Gruppe freigegeben sind. Das Modul ist standardmäßig deaktiviert und wird in `plugins/CoreEngine/modules/permissions.yml` eingeschaltet.

> **Hinweis:** Die Permission-Filterung ist optisch, sie betrifft Tab-Vervollständigung und Befehls-Einfärbung im Client. Ob ein Command ausgeführt werden darf, entscheidet weiterhin die Permission-Prüfung des jeweiligen Commands. Ausnahmen: Einträge aus `always-hidden` und im Whitelist-Modus alle nicht gelisteten Commands werden mit `block-hidden-execution` auch bei der Ausführung blockiert.

## Funktionsweise

- Beim Login und bei jeder Aktualisierung der Befehlsliste prüft das Modul für jeden Command die Permission des Spielers. Commands ohne Berechtigung erscheinen nicht in der Tab-Vervollständigung.
- Commands, die keine Permission deklarieren oder deren Permission jeder Spieler hat (das legt das jeweilige Plugin fest), bleiben bei der Permission-Filterung sichtbar. Beispiel: CoreProtect liefert `/co` mit einer Permission aus, die standardmäßig jeder Spieler hat, deshalb sehen auch normale Spieler `/co` in der Vorschlagsliste. Solche Commands blendet man über `always-hidden` gezielt aus, oder man nutzt den Whitelist-Modus.
- Die einzige feste Permission des Moduls ist `commandvisibility.bypass` (Standard: OP): Wer sie hat, ist von allen Einschränkungen des Moduls ausgenommen, sieht also alles und darf alles ausführen.

## Namespace-Varianten (bukkit:, minecraft:, plugin:)

Denselben Command gibt es oft mehrfach: einmal in der einfachen Form (`/tp`) und einmal mit Namespace (`minecraft:tp`, `bukkit:tp`). `hide-namespaced` steuert, was davon sichtbar ist:

| Modus | Verhalten |
|---|---|
| `all` (Standard) | Jede Namespace-Variante wird ausgeblendet, solange eine einfache Form desselben Namens sichtbar ist. Niemand sieht `bukkit:plugins`, solange `/plugins` existiert. Fehlt die einfache Form komplett, bleibt die Namespace-Form sichtbar, damit jeder Command mindestens einen erreichbaren Namen behält. |
| `duplicates` | Eine Namespace-Variante verschwindet nur, wenn die sichtbare einfache Form wirklich derselbe Command ist. Registrieren zwei Plugins denselben Namen, bleiben beide Formen sichtbar. |
| `off` | Namespace-Varianten werden nie ausgeblendet. |

Einzelne Namespace-Formen lassen sich über `always-visible` (z. B. `coreprotect:core`) gezielt sichtbar halten.

## Whitelist-Modus: nur gelistete Commands anzeigen

Mit `whitelist.enabled: true` dreht sich die Logik um: Statt Unerwünschtes auszublenden, sehen Spieler NUR noch die Commands, die in den Listen ihrer Gruppen stehen. Alles andere verschwindet aus der Tab-Vervollständigung und wird mit `block-hidden-execution` auch bei der Ausführung blockiert. Das ist der einzige Weg, Commands anderer Plugins zu verstecken, die keine oder eine für alle freigegebene Permission deklarieren (wie `/co` von CoreProtect).

So funktionieren die Gruppen:

- Die Gruppe `default` gilt für JEDEN Spieler.
- Jede weitere Gruppe gilt für Spieler mit der Permission `commandvisibility.group.<name>`. Beispiel: Die Gruppe `vip` greift bei allen Spielern mit `commandvisibility.group.vip`, vergeben z. B. über LuckPerms mit `/lp group vip permission set commandvisibility.group.vip true`.
- Ein Spieler darf die ZUSAMMENGELEGTEN Listen aller seiner Gruppen sehen und benutzen.
- Spieler mit `commandvisibility.bypass` (Standard: OP) sehen weiterhin alles.

Wichtig beim Befüllen der Listen:

- Aliase zählen als eigene Namen: Wer `/msg` und `/r` erlauben will, listet beide.
- Klickbare Chat-Buttons führen echte Commands aus. Erlaubt man `/tpa`, gehören `tpaccept` und `tpdeny` mit auf die Liste, sonst funktionieren die Annehmen/Ablehnen-Buttons nicht.
- Ein gelisteter Command bleibt trotzdem permission-geprüft: `fly` auf der Liste zeigt `/fly` nur Spielern, die auch `util.fly` haben.
- CoreEngines interne Bestätigungs-Commands (`coreconfirm`, `shopconfirm`, `shopcancel`, `shopedit`) funktionieren immer, auch ohne Listung. Sie bleiben nur unsichtbar. Shop-Käufe und Bestätigungs-Dialoge laufen also ungestört weiter.

## Versteckte Commands auch blockieren

`always-hidden`-Einträge und im Whitelist-Modus alle nicht gelisteten Commands verschwinden nicht nur aus der Tab-Vervollständigung: Mit `block-hidden-execution: true` (Standard) wird auch die Ausführung blockiert. Der Spieler bekommt die Meldung `permissions.command-blocked` aus der `messages.yml`, die wie die normale Unbekannter-Befehl-Meldung aussieht, der Command verrät seine Existenz also nicht. Ein einfacher Eintrag wie `plugins` blockiert automatisch auch alle Namespace-Formen (`bukkit:plugins`). Spieler mit `commandvisibility.bypass` sind ausgenommen, die Konsole ist nie betroffen.

## Namenskonflikte mit anderen Plugins

Registrieren zwei Plugins denselben Befehlsnamen, bekommt das zuerst geladene Plugin den einfachen Namen, das später geladene ist nur über seinen Namespace erreichbar. CoreEngine weicht solchen Konflikten aus: Das Web-Interface heißt bewusst `/cweb`, weil CoreProtect den Namen `/core` belegt. Trifft ein anderes Plugin doch einen CoreEngine-Befehlsnamen, bleibt der CoreEngine-Command immer über `/coreengine:<name>` erreichbar.

## LuckPerms-Live-Aktualisierung

Ändert sich eine Permission in LuckPerms, egal ob direkt am Spieler oder an einer Gruppe, aktualisiert CoreEngine die Befehlsliste aller betroffenen Spieler sofort. Verliert die Gruppe `default` z. B. per `/lp group default permission set warps.use false` das Warp-Recht, verschwindet `/warp` bei allen Mitgliedern augenblicklich aus der Tab-Vervollständigung, ganz ohne Relog. Wird das Recht wieder vergeben, taucht der Command genauso schnell wieder auf. Das gilt auch für die Whitelist-Gruppen: Bekommt ein Spieler `commandvisibility.group.vip`, sieht er die VIP-Commands sofort.

## Konfiguration

```yaml
# Hauptschalter des Moduls, standardmäßig deaktiviert
enabled: false

permissions:
  # Umgang mit Namespace-Varianten: all, duplicates oder off (siehe oben)
  hide-namespaced: all
  # Blockiert die Ausführung versteckter Commands (always-hidden und im
  # Whitelist-Modus alles Ungelistete), nicht nur die Anzeige. Bypass über
  # die Permission commandvisibility.bypass.
  block-hidden-execution: true
  # Commands, die immer ausgeblendet (und blockiert) werden. Namen ohne
  # Schrägstrich, Einträge wie bukkit:plugins sind ebenfalls erlaubt.
  always-hidden: []
  # Commands, die immer sichtbar bleiben, auch wenn Permission,
  # Namespace-Modus oder Whitelist sie ausblenden würden.
  always-visible: []
  # Whitelist-Modus: Spieler sehen nur die Commands ihrer Gruppen.
  whitelist:
    enabled: false
    groups: {}
```

## Komplette Beispiel-Config

```yaml
# Schaltet das Modul für permission-basierte Command-Sichtbarkeit ein oder aus.
enabled: true

permissions:
  # Keine bukkit:/minecraft:-Varianten in der Tab-Vervollständigung.
  hide-namespaced: all
  # Versteckte Commands sind auch nicht ausführbar.
  block-hidden-execution: true
  # Diese Commands deklarieren keine Permission und werden hier von Hand
  # ausgeblendet und blockiert (ohne Whitelist-Modus).
  always-hidden:
    - plugins
    - icanhasbukkit
  # /spawn bleibt immer sichtbar.
  always-visible:
    - spawn
  # Nur gelistete Commands anzeigen: jeder sieht die default-Liste,
  # Spieler mit commandvisibility.group.vip zusätzlich die vip-Liste.
  whitelist:
    enabled: true
    groups:
      default:
        - help
        - spawn
        - home
        - sethome
        - warp
        - warps
        - tpa
        - tpaccept
        - tpdeny
        - msg
        - r
        - team
        - jobs
        - cweb
      vip:
        - fly
        - hat
```