Level 2 – Chatbefehle

API: `core.register_chatcommand`

Mit core.register_chatcommand kannst du eigene Chatbefehle wie /platform registrieren. Ein Chatbefehl ist ein kurzer Text, den der Spieler in den Chat schreibt, um eine Funktion auszuführen – zum Beispiel eine Plattform unter sich zu erzeugen oder Informationen anzuzeigen.

1. Grundsyntax

Die Funktion hat immer dieselbe Form:

Grundform von core.register_chatcommand

core.register_chatcommand(name, {
    params      = <string>,      -- (optional) Syntax-Hinweis für /help
    description = <string>,      -- Kurzbeschreibung für /help
    privs       = <tabelle>,     -- (optional) benötigte Privilegien
    func        = function(name, param)
        -- <dein Code>
        -- Rückgabewert: true/false, "Nachricht an Spieler"
    end,
})

Parameter:

name – der Befehl ohne Slash, z. B. "platform" für /platform
params – kurzer Hinweis, wie der Befehl benutzt wird (wird in /help angezeigt)
description – verständliche Beschreibung des Befehls
privs – Tabelle der benötigten Privilegien, z. B. { interact = true }
func(name, param) – Funktion, die ausgeführt wird, wenn der Befehl aufgerufen wird

Die Funktion func kann bis zu zwei Werte zurückgeben:

1. Wert – true oder false, ob der Befehl erfolgreich war
2. Wert – Text, der dem Spieler im Chat angezeigt wird

Didaktik-Hinweis

Für Einsteiger reicht oft der Satz: „Ein Chatbefehl ist wie eine kleine Zauberformel – wenn du sie richtig schreibst, führt der Server einen Lua-Codeblock aus.“

2. Einfaches Beispiel: Echo-Befehl

Dieses Beispiel registriert /echo. Der Befehl gibt einfach zurück, was der Spieler dahinter schreibt:

Beispiel: /echo

core.register_chatcommand("echo", {
    params      = "<text>",
    description = "Gibt den Text zurück, den du eingibst.",
    privs       = { interact = true },

    func = function(name, param)
        if param == nil or param == "" then
            return false, "Bitte gib einen Text an."
        end

        return true, "Du hast geschrieben: " .. param
    end,
})

Wenn ein Spieler /echo Hallo Welt eingibt, sieht er im Chat: „Du hast geschrieben: Hallo Welt“.

3. Vorbereitung: Spielerposition und Koordinaten

Für den Plattform-Befehl brauchst du:

den Spielernamen (name – wird automatisch übergeben),
das Spielerobjekt via core.get_player_by_name(name),
die gerundete Spielerposition (x, y, z),
und eine Schleife, um mehrere Blöcke zu setzen.

Diese Themen sind in den Grundlagen-Seiten Coordinates & Positions und Mod Folder Structure ausführlicher erklärt.

4. Komplettes Beispiel: `/platform`

Der folgende Chatbefehl erzeugt eine 3×3-Plattform aus Stein direkt unter dem Spieler. Er gehört in die init.lua deines Mods (zum Beispiel school_platform):

Kompletter Chatbefehl /platform

-- init.lua in school_platform

core.register_chatcommand("platform", {
    params      = "",
    description = "Erzeugt eine kleine Steinplattform unter dir.",
    privs       = { interact = true },

    func = function(name, param)
local player = core.get_player_by_name(name)
        if not player then
            return false, "Fehler: Spieler nicht gefunden."
        end

        -- Spielerposition holen
        local pos = player:get_pos()

        -- Auf ganze Blöcke runden
        pos.x = math.floor(pos.x + 0.5)
        pos.y = math.floor(pos.y + 0.5)
        pos.z = math.floor(pos.z + 0.5)

        -- 3×3-Plattform erzeugen (eine Ebene unter dem Spieler)
        for dx = -1, 1 do
            for dz = -1, 1 do
                core.set_node(
                    { x = pos.x + dx, y = pos.y - 1, z = pos.z + dz },
                    { name = "default:stone" }
                )
            end
        end

        return true, "Plattform erstellt!"
    end,
})

Nach einem Neustart des Spiels und Aktivierung des Mods kannst du im Chat /platform eingeben. Stehst du dabei in der Luft, erscheint unter dir eine kleine Plattform aus Stein.

Didaktik-Hinweis

Hier lässt sich gut differenzieren: Schwächere Schüler:innen können nur verstehen, dass eine Plattform entsteht. Stärkere analysieren die Schleifen und Koordinaten und erklären mit eigenen Worten, warum genau 9 Blöcke gesetzt werden.

5. Fehlerbehandlung und Rückgabewerte

Beachte die Rückgabe am Ende von func:

true bedeutet: „Befehl erfolgreich ausgeführt“.
false bedeutet: „Fehler oder falsche Benutzung“.
Der zweite Wert ist immer die Chat-Nachricht für den Spieler.

Beispiel für eine einfache Parameterprüfung:

Beispiel: Parameter prüfen

core.register_chatcommand("sethp", {
    params      = "<wert>",
    description = "Setzt deine Lebenspunkte auf <wert>.",
    privs       = { interact = true },

    func = function(name, param)
        local value = tonumber(param)
        if not value then
            return false, "Benutzung: /sethp <zahl>"
        end

        local player = core.get_player_by_name(name)
        if not player then
            return false, "Spieler nicht gefunden."
        end

        player:set_hp(value)
        return true, "HP auf " .. value .. " gesetzt."
    end,
})

6. Mini-Aufträge für Schüler:innen

Erzeuge im eigenen Mod einen einfachen Befehl /hello, der „Hallo <Spielername>!“ zurückgibt.
Erweitere den Befehl so, dass er optional einen Namen als Parameter akzeptiert: /hello Anna soll „Hallo Anna!“ anzeigen.
Passe den Befehl /platform so an, dass er einen Parameter für die Blockart hat, z. B. /platform default:glass.
Überlege dir einen eigenen „Werkzeug“-Befehl, der im Unterricht nützlich sein könnte (z. B. /spawnlab für einen Laborraum).

7. Wie geht es weiter?

Du kennst nun die Grundlagen von core.register_chatcommand und kannst eigene Chatbefehle schreiben. Als Nächstes kannst du:

die komplette Beispiel-Mod-Seite Example: Platform under Player anschauen,
oder zu den Grundlagen der Koordinaten zurückspringen: Coordinates & Positions .

API: core.register_chatcommand