Scapi installieren
Unsere Scapi Hauptdatei kann hier gefunden werden. Platziere diese Datei einfach in dem Ordner, wo du den Bot programmieren willst. Du kannst herausfinden wie du Scapi in deinem Code einbinden kannst indem du dir den Code unten anschaust. Wir empfehlen dir das du außerdem mal einen Blick in unserem Scapi Bot Ordner verschaffst um zu verstehen wie ein Bot aufgebaut ist und funktioniert.Verwendung von scapi in deinem Code
Scapi wird mit jedem Update einfacher. Um Scapi in deinem Code einzubinden, verwende Python’simport
Statement.
Wir empfehlen YAML für die Konfigurationsdateien zu verwenden. Du kannst YAML mithilfe von
pip
installieren. (pip install pyyaml
)Schreibe deinen ersten Bot (stbmv1)
Dieser Dokumentationsteil gilt nur für Scapi Legacy v1.0.0 (stbmv1) oder höher
Die ersten Schritte
Um die Basics deines Bots aufzubauen, benötigst du ein Bot-Objekt. Dieses kannst du mithilfe unserer Bot-Objektklasse erstellen:Flag | Erklärung |
---|---|
username | Der Nutzername des Bots |
token | Der Token (Passwort) des Bots |
host | Remote-Server, wo der Bot sich mit verbinden soll |
port | Der Port des Remote-Servers |
enable_user_input | Aktiviere die Nachrichteneingabe innerhalb der Konsole (Auch als Flag verfügbar) |
print_recv_msg | Gebe empfangende Nachrichten in die Bot-Logs aus (Konsole) (Auch als Flag verfügbar) |
Flags
Flags sind ein wichtiger Teil beim Programmieren deines Scapi-Bots. Du benötigst Flags um z.B. festzulegen ob du Nachrichten von Nutzern in deinen Bot-Logs sehen willst, oder ob du die Nachrichteneingabe innerhalb der Konsole aktivieren willst. Die Definierung deiner Flags könnte so aussehen:Flag | Erklärung |
---|---|
print_recv_msg | Gebe empfangende Nachrichten in die Bot-Logs aus (Konsole) |
enable_user_input | Aktiviere die Nachrichteneingabe innerhalb der Konsole |
log_msg | Ändere das Format der Log-Nachrichten |
Berechtigungen
Ein weiterer Teil deines Bots sind Berechtigungen. Diese überprüfen ob der Nutzer, der einen Command ausgeführt hat, auch die nötigen Berechtigungen besitzt. Außerdem kannst du auch festlegen, wer der Bot-Owner ist. In Scapi gibt es eine Funktion, welche benutzerdefinierte Werte für die Berechtigungsverwaltung annimmt. Mithilfe dieser Funktion kannst du den Bot-Owner festlegen, oder eine Custom-Liste erstellen, und diese anschließend auch innerhalb von Commands verwenden. Das festlegen des Owners und einer Custom-Liste kann wie folgt vorgenommen werden:Commands (@commands
Modul)
Damit der Bot auch ein Sinn und Zweck hat, braucht der Bot Commands. Ein einfacher Commands sieht wie folgt aus:
Scapi hat 2 verschiedene Methoden um einen Bot zu schreiben. Eine Methode ist neuer und sauberer ist allerdings noch nicht vollständig entwickelt. Diese Methode heißt
Commands
.
Dieser Teil erklärt wie du einen Command mithilfe des Command-Modules schreiben kannst.Für die andere Methode kannst du dir diesen Dokumentationsteil anschauenCode | Erklärung |
---|---|
name | Steht für den Command-Namen, welcher anschließend in der Registry eingefügt wird. Du kannst den Command dann mithilfe des Prefixes und dann den Namen aufrufen (z.B. !test ) |
arg_count | Anzahl der Argumente, die der Befehl annimmt und mindestens benötigt. Es kann auch eine niedrigere Zahl angegeben werden und mehr Argumente trotzdem angenommen werden |
required_permissions | Benötigte Berechtigung für den Command. Hier muss ein Wert der Scapi-Klasse übergeben werden. Scapi.Bot.PermissionLevel.CUSTOM für die Custom-Liste, die du hier definiert hast |
username | Der Nutzername, des Benutzers, der den Command ausgeführt hat |
args | Die Argumente, die beim Ausführen des Commands übergeben wurden. Wird in einer Liste gespeichert (["first", "second", "third"] ) |
send_message(...) | Funktion um eine Nachricht zu senden |
Commands (Originale Methode)
Wie du hier erfahren hast, besitzt Scapi 2 verschiedene Methoden um ein Bot-Command zu schreiben. Dieser Teil zeigt dir, wie du die andere Methode verwendest. Diese ist etwas mehr schwierig, kann aber mehr angepasst werden. Diese Methode wird weiterhin für reineon_message
Events verwendet um reine Nachrichten zu akzeptieren & zu verarbeiten.
Wir empfehlen die Verwendung der Commands-Methode da diese mehr Features besitzt & mehr Support bietet als die Originale Methode (z.B. Berechtigungen)
Code | Erklärung |
---|---|
Commands() | Erstellt eine Funktion für das allgemeine verarbeiten der empfangenden Nachrichten & Commands |
while True | Eine Schleife die nie endet, um immer die Nachrichten zu empfangen |
Bot.recv_message(raw=True) | Empfängt die Nachrichten in einem rohen Format (Ohne Farben) |
if message.startswith("!hello") | Kontrolliert, ob die empfangende Nachricht mit !hello startet |
send_message(...) | Funktion um eine Nachricht zu senden |
Events
Es gibt bestimmte Events, die der Bot bei etwas bestimmten aufrufen kann. Einer dieser Events heißton_ready
.
Dieses Event wird aufgerufen, wenn du den Bot startest. Du musst nur bei der Bot.run()
Funktion als Argument die on_ready
Funktion übergeben.
Ein on_ready
Event kann so aussehen:
Den Bot starten
Um den Bot zu starten musst du zuerst darauf achten, welche Command Methode du verwendest.Beispielbot (Stable v1.0)
Dieser Beispielbot gilt nur für Scapi Legacy v1.0.0 (stbmv1)
Schreibe deinen ersten Bot (stbmv2)
Dieser Dokumentationsteil gilt nur für Scapi v0.12.0 (stbmv2) oder höher
Die ersten Schritte
Um die Basics deines Bots aufzubauen, benötigst du ein Bot-Objekt. Dieses kannst du mithilfe unserer Bot-Objektklasse erstellen:Flag | Erklärung |
---|---|
username | Der Nutzername des Bots |
token | Der Token (Passwort) des Bots |
host | Remote-Server, wo der Bot sich mit verbinden soll |
prefix | Der Prefix des Bots, worauf er hören soll (z.B. !help ) |
port | Der Port des Remote-Servers |
enable_user_input | Aktiviere die Nachrichteneingabe innerhalb der Konsole (Auch als Flag verfügbar) |
print_recv_msg | Gebe empfangende Nachrichten in die Bot-Logs aus (Konsole) (Auch als Flag verfügbar) |
json | Aktiviert oder deaktiviert den Kompatiblitätsmodus für alte Server |
Das Argument
json
ist erst seit Scapi v0.12.1 verfügbarDas Argument
prefix
ist erst seit Scapi v0.13.1b2 verfügbarFlags
Flags sind ein wichtiger Teil beim Programmieren deines Scapi-Bots. Du benötigst Flags um z.B. festzulegen ob du Nachrichten von Nutzern in deinen Bot-Logs sehen willst, oder ob du die Nachrichteneingabe innerhalb der Konsole aktivieren willst. Die Definierung deiner Flags könnte so aussehen:Flag | Erklärung |
---|---|
print_recv_msg | Gebe empfangende Nachrichten in die Bot-Logs aus (Konsole) |
enable_user_input | Aktiviere die Nachrichteneingabe innerhalb der Konsole |
log_msg | Ändere das Format der Log-Nachrichten |
ignore_capitalization | Aktiviert oder deaktiviert das ignorieren von Großbuchstaben für die on_message Methode (Nur verfügbar ab Scapi v0.13) |
Berechtigungen
Ein weiterer Teil deines Bots sind Berechtigungen. Diese überprüfen ob der Nutzer, der einen Command ausgeführt hat, auch die nötigen Berechtigungen besitzt. Außerdem kannst du auch festlegen, wer der Bot-Owner ist. In Scapi gibt es eine Funktion, welche benutzerdefinierte Werte für die Berechtigungsverwaltung annimmt. Mithilfe dieser Funktion kannst du den Bot-Owner festlegen, oder eine Custom-Liste erstellen, und diese anschließend auch innerhalb von Commands verwenden. Das festlegen des Owners und einer Custom-Liste kann wie folgt vorgenommen werden:Commands (Commands Modul)
Damit der Bot auch ein Sinn und Zweck hat, braucht der Bot Commands. Ein einfacher Commands sieht wie folgt aus:Scapi hat 2 verschiedene Methoden um einen Bot zu schreiben. Eine Methode ist neuer und sauberer ist allerdings noch nicht vollständig entwickelt. Diese Methode heißt
Commands
.
Dieser Teil erklärt wie du einen Command mithilfe des Command-Modules schreiben kannst.Die ältere Methode ist seit Scapi v0.12.1 veraltet und sollte daher auch nicht mehr verwendet werdenCode | Erklärung |
---|---|
name | Steht für den Command-Namen, welcher anschließend in der Registry eingefügt wird. Du kannst den Command dann mithilfe des Prefixes und dann den Namen aufrufen (z.B. !test ) |
arg_count | Anzahl der Argumente, die der Befehl annimmt und mindestens benötigt. Es kann auch eine niedrigere Zahl angegeben werden und mehr Argumente trotzdem angenommen werden |
required_permissions | Benötigte Berechtigung für den Command. Hier muss ein Wert der Scapi-Klasse übergeben werden. Scapi.Bot.PermissionLevel.CUSTOM für die Custom-Liste, die du hier definiert hast |
username | Der Nutzername, des Benutzers, der den Command ausgeführt hat |
args | Die Argumente, die beim Ausführen des Commands übergeben wurden. Wird in einer Liste gespeichert (["first", "second", "third"] ) |
send_message(...) | Funktion um eine Nachricht zu senden |
Direktnachrichten
Direktnachrichten
Chat verlassen
Chat verlassen
Commands (Originale Methode)
Die Offizielle Unterstützung für die Originale Methode wurde seit Scapi 0.12.1 abgeschafft.Zur Weiterverwendung der Originalen Methode empfehlen wir die neue
@on_message
Methode (Seit v0.13). Bei fehlender Funktionalität bitte ein Issue auf unserem GitHub öffnenFalls du trotzdem aus was auch immer welchen Gründen diese Methode verwenden möchtest, schaue dir bitte diesen Teil der Dokumentation anEvents
Es gibt bestimmte Events, die der Bot bei etwas bestimmten aufrufen kann.@on_message Event
Ab Scapi v0.13 haben wir eine verbesserte Version der Originalen Message-Methode hinzugefügt. Diese verwendet unseren modernen Python-Standard und Python-Dekoratoren. Die Implementierung in deinem Bot-Code ist sehr einfach. Du benötigst nur mindestens Scapi v0.13 oder höher. Ein Bot-Message-Event kann so aussehen:Nicht alle Funktionen der alten Originalen Methode konnten übernommen werden, daher ist die
@on_message
Methode mehr eingeschränkt.Folgende Funktionen konnten bis jetzt nicht implementiert werden (Aber könnten in Zukunft in einer anderen Form auftreten):- Nutzung von .startswith()
- Das erkennen von spezifischen Wörtern innerhalb der Nachricht
@on_ready Event
Dieses Event wird aufgerufen, wenn du den Bot startest. Du musst nur bei derBot.run()
Funktion als Argument die on_ready
Funktion übergeben.
Ein on_ready
Event kann so aussehen:
Den Bot starten
Um den Bot zu starten musst du zuerst darauf achten, welche Command Methode du verwendest.Beispielbot (v0.12.0 oder höher)
Dieser Beispielbot gilt nur für Scapi v0.12.0 (stbmv2) oder höher
Die Offizielle Unterstützung für die Originale Methode wurde seit Scapi v0.12.1 abgeschafft.
Du kannst hier mehr darüber lesen
@json-communication
/@main
) hier erhalten.
Die folgenden Code-Stücke zeigen dir wie du einen einfachen Bot mit Scapi (stbmv2) erstellen kannst.
json
zu False
aktiviert den Kompatiblitätsmodus. Beachte das dies noch nicht vollständig entwickelt wurde.