Giveaway Action Scripts

✨DCV3 exklusiv

Diese Funktion ist nur in DCV3 verfügbar.

Übersicht

Diese Dokumentation beschreibt, wie Giveaway-Action-Scripts konfiguriert werden können, um automatisch Actions auszuführen, wenn ein Spieler ein Giveaway gewinnt.

Die Action-Scripts werden in der Datei giveaway_action_scripts.json im Config-Ordner definiert.

Wichtig: Verknüpfung mit Giveaway

Bei der Giveaway-Erstellung muss folgendes beachtet werden:

reward_type: Der Wert von reward_type beim Erstellen des Giveaways muss exakt dem action_name des gewünschten Scripts entsprechen.
- Beispiel: reward_type: "1m" → führt das Action-Script mit "action_name": "1m" aus
is_verified: Muss auf true gesetzt werden, wenn das Action-Script Minecraft-Daten benötigt (%winner_uuid%, %winner_name%).
- Actions wie OfflineMsgAction und OfflinePayAction funktionieren nur mit verifizierten Usern!

Beispiel Giveaway-Erstellung:

reward_type: "1m"
is_verified: true

Dies würde das Action-Script "action_name": "1m" ausführen und nur verifizierte User können teilnehmen.

Nur für Giveaways mit "Verifizierung erforderlich" = Ja

Wenn der User nicht verifiziert ist, stehen die Variablen %winner_uuid% und %winner_name% nicht zur Verfügung. Alle Actions, die diese Variablen benötigen, werden in diesem Fall übersprungen.

Aufbau eines Action-Scripts

Ein Action-Script besteht aus einem Action-Namen und einer Liste von Actions, die ausgeführt werden, wenn ein Gewinner ermittelt wird.

Grundstruktur

{
  "giveaway_action_scripts": [
    {
      "action_name": "scriptname",
      "actions": [
        {
          "actionname": "ActionTyp",
          "actiondisplayname": "Beschreibung",
          "minimalReqVersion": 1,
          "data": {
            // Action-spezifische Daten
          }
        }
      ]
    }
  ]
}

Felder erklärt

Feld	Beschreibung
`action_name`	Eindeutiger Name des Scripts (wird beim Erstellen des Giveaways angegeben)
`actions`	Array mit allen Actions, die nacheinander ausgeführt werden
`actionname`	Typ der Action (siehe Liste unten)
`actiondisplayname`	Beschreibung der Action (zur besseren Lesbarkeit)
`minimalReqVersion`	Minimale Version (normalerweise `1`)
`data`	Action-spezifische Daten/Parameter

Verfügbare Variablen

Actions können Variablen nutzen, um dynamische Werte einzusetzen. Variablen werden mit %variablenname% referenziert.

Giveaway-Variablen

Variable	Beschreibung	Beispiel
`%winner_discord_id%`	Discord-ID des Gewinners	`123456789012345678`
`%action_type%`	Name des Action-Scripts	`1m`, `tokens`, `geld`
`%winner_verified%`	Ob der User verifiziert ist	`true` oder `false`
`%winner_uuid%`	Minecraft-UUID des Gewinners*	`550e8400-e29b-41d4-a716-446655440000`
`%winner_name%`	Minecraft-Name des Gewinners*	`Steve`

Hinweis: Die Variablen %winner_uuid% und %winner_name% sind nur verfügbar, wenn der Gewinner verifiziert ist (%winner_verified% = true).

System-Variablen

Zusätzlich stehen alle System-Variablen zur Verfügung (z.B. Datum, Uhrzeit, etc.).

Verfügbare Action-Typen

Client Actions

CloseCurrentGuiAction - Schließt das aktuelle GUI
KeyBoardAction - Simuliert Tastatureingaben
RandomMessageFromListAction - Sendet eine zufällige Nachricht aus einer Liste
MessageWithDelayAction - Sendet eine Nachricht mit Verzögerung
JoinerStatusAction - Ändert den Joiner-Status
HotBarAction - Setzt den Hotbar-Slot
QuitServerAction - Verlässt den Server
QuitClientAction - Beendet den Client

Chat & Message Actions

ChatMessageAction - Sendet eine Chat-Nachricht
PrivateMessageAction - Sendet eine private Nachricht
DisplayMessageInChatAction - Zeigt eine Nachricht im Chat an

Command Actions

CommandAction - Führt einen Befehl aus
CommandDelayAction - Führt einen Befehl mit Verzögerung aus
CommandHoloAction - Führt einen Holo-Befehl aus

Discord Actions

SendSimpleMessageWebhookAction - Sendet eine einfache Webhook-Nachricht
EmbedDiscordAction - Sendet ein Discord-Embed
SendImageToDiscord - Sendet ein Bild zu Discord

Offline Actions

OfflineMsgAction - Erstellt eine Offline-Nachricht für den Spieler
OfflinePayAction - Überweist Geld an einen Offline-Spieler

Output Actions

SystemPrintOutAction - Gibt eine Nachricht in der Konsole aus

Block Actions

BlockInteractAction - Interagiert mit einem Block

Velo Actions

VeloItemVerkauf - Triggert einen Velo-Verkauf
VeloStatusAction - Ändert den Velo-Bot-Status

Variable Operations

SetBoolean - Setzt eine Boolean-Variable
SetDelayedBoolean - Setzt eine Boolean-Variable mit Verzögerung
SetInt - Setzt eine Integer-Variable
AddToInt - Addiert zu einer Integer-Variable
RemoveFromInt - Subtrahiert von einer Integer-Variable
IntPP - Erhöht eine Integer-Variable um 1
IntMM - Verringert eine Integer-Variable um 1
SetLong - Setzt eine Long-Variable
SetString - Setzt eine String-Variable

Beispiel: "1m" Giveaway

Dieses Beispiel zeigt ein vollständiges Action-Script für ein Giveaway, bei dem der Gewinner 1.000.000$ erhält:

{
  "action_name": "1m",
  "actions": [
    {
      "actionname": "SystemPrintOutAction",
      "actiondisplayname": "Custom Log",
      "minimalReqVersion": 1,
      "data": {
        "message": "Giveaway 1m gewonnen: %winner_discord_id% - %action_type% - uuid: %winner_uuid% - name: %winner_name% - verify: %winner_verified%"
      }
    },
    {
      "actionname": "SendSimpleMessageWebhookAction",
      "actiondisplayname": "SendSimpleMessageWebhookAction",
      "minimalReqVersion": 1,
      "data": {
        "content": "1m Giveaway Ausgeführt: \n Action: %action_type% \n User: %winner_name% \n UUID: %winner_uuid% \n id: %winner_discord_id% \n veri: %winner_verified%",
        "webhookUrl": "https://discord.com/api/webhooks/IHRE_WEBHOOK_URL"
      }
    },
    {
      "actionname": "OfflineMsgAction",
      "actiondisplayname": "OfflineMsgAction",
      "minimalReqVersion": 1,
      "data": {
        "player": "%winner_name%",
        "uuid": "%winner_uuid%",
        "message": "HGW zum Giveaway, du hast 1m gewonnen!"
      }
    },
    {
      "actionname": "OfflinePayAction",
      "actiondisplayname": "OfflinePayAction",
      "minimalReqVersion": 1,
      "data": {
        "player": "%winner_name%",
        "uuid": "%winner_uuid%",
        "betrag": "1000000"
      }
    }
  ]
}

Erklärung der Actions

SystemPrintOutAction: Gibt eine Log-Nachricht in der Konsole aus mit allen Gewinner-Informationen
SendSimpleMessageWebhookAction: Sendet eine Benachrichtigung an Discord über den Webhook
OfflineMsgAction: Erstellt eine Offline-Nachricht für den Gewinner (wird angezeigt, wenn er sich einloggt)
OfflinePayAction: Überweist 1.000.000$ an den Gewinner

Variablen-Nutzung

In diesem Beispiel werden folgende Variablen verwendet:

%winner_discord_id% - Discord-ID des Gewinners
%action_type% - Gibt "1m" zurück (der Name des Scripts)
%winner_uuid% - UUID des Minecraft-Accounts (nur wenn verifiziert)
%winner_name% - Minecraft-Name (nur wenn verifiziert)
%winner_verified% - true wenn verifiziert, sonst false

Wichtig: Actions, die %winner_uuid% oder %winner_name% benötigen (wie OfflineMsgAction und OfflinePayAction), funktionieren nur, wenn der Gewinner verifiziert ist!

Weitere Beispiele

Beispiel: Geld-Giveaway

{
  "action_name": "10mio",
  "actions": [
    {
      "actionname": "DisplayMessageInChatAction",
      "actiondisplayname": "Gewinner-Nachricht Geld",
      "minimalReqVersion": 1,
      "data": {
        "message": "§7Der User %winner_name% hat 10mio gewonnen!"
      }
    },
    {
      "actionname": "OfflinePayAction",
      "actiondisplayname": "Geld überweisen",
      "minimalReqVersion": 1,
      "data": {
        "player": "%winner_name%",
        "uuid": "%winner_uuid%",
        "betrag": "10000000"
      }
    }
  ]
}

Tipps & Best Practices

Verifizierung prüfen: Wenn Actions Minecraft-Daten benötigen (%winner_uuid%, %winner_name%), stelle sicher, dass nur verifizierte User teilnehmen können.
Logging: Nutze SystemPrintOutAction oder SendSimpleMessageWebhookAction, um nachvollziehen zu können, wann und an wen Preise vergeben wurden.
Offline-Actions: Nutze OfflineMsgAction und OfflinePayAction, damit Gewinner ihre Preise auch erhalten, wenn sie offline sind.
Eindeutige Namen: Wähle eindeutige action_name-Werte, um Verwechslungen zu vermeiden.
Testen: Teste neue Action-Scripts gründlich, bevor du sie in produktiven Giveaways verwendest.

Fehlerbehandlung

Wenn eine Action fehlschlägt, wird eine Warnung geloggt, aber die nachfolgenden Actions werden trotzdem ausgeführt.
Wenn keine verifizierten Daten verfügbar sind, werden %winner_uuid% und %winner_name% nicht ersetzt und bleiben leer.
Stelle sicher, dass die giveaway_action_scripts.json valides JSON ist, sonst kann die Config nicht geladen werden.

Support

Bei Fragen oder Problemen:

Überprüfe die Logs auf Fehlermeldungen Prüfe ob die jeweiligen Logger und DebugLog aktiviert ist
Stelle sicher, dass die JSON-Syntax korrekt ist
Teste mit einfachen Actions (z.B. nur SystemPrintOutAction)
Prüfe, ob alle benötigten Variablen verfügbar sind

Debug-Logging aktivieren

Für detaillierte Debug-Logs müssen die entsprechenden Logger in der mainconfig.json aktiviert werden:

{
  "debug": true,
  "logger": "GIVEAWAY,ACTION,VARIABLES"
}

Logger-Typen:

GIVEAWAY - Zeigt alle Giveaway-bezogenen Logs an
ACTION - Zeigt Action-Ausführungen an
VARIABLES - Zeigt Variablen-Ersetzungen an

Hinweis: Mehrere Logger können kommagetrennt angegeben werden. Nach Änderung der Config muss das Plugin/der Bot neu gestartet werden.

Übersicht​

Wichtig: Verknüpfung mit Giveaway​

Beispiel Giveaway-Erstellung:​

Nur für Giveaways mit "Verifizierung erforderlich" = Ja​

Aufbau eines Action-Scripts​

Grundstruktur​

Felder erklärt​

Verfügbare Variablen​

Giveaway-Variablen​

System-Variablen​

Verfügbare Action-Typen​

Client Actions​

Chat & Message Actions​

Command Actions​

Discord Actions​

Offline Actions​

Output Actions​

Block Actions​

Velo Actions​

Variable Operations​

Beispiel: "1m" Giveaway​

Erklärung der Actions​

Variablen-Nutzung​

Weitere Beispiele​

Beispiel: Geld-Giveaway​

Tipps & Best Practices​

Fehlerbehandlung​

Support​

Debug-Logging aktivieren​