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’s import Statement.

import scapi            # Importiere die Scapi Funktionsdate
from scapi import Scapi # Importiere Scapi's Bot Klasse

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:

Bot = Scapi.Bot(username="username", token="bottoken", host="1.2.3.4", port=1234)

In dieser Tabelle siehst du alle verfügbaren Argumente mit ihrer Bedeutung

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)

Damit der Bot sich im Server auch einloggt, musst du noch eine wichtige Funktion hinzufügen

Bot.login()

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:

Bot.flag_handler(print_recv_msg=True, enable_user_input=True)

In dieser Tabelle siehst du alle verfügbaren Flags mit ihrer Bedeutung

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:

Bot.permission_handler(custom_list=["julian"], owner="julian")

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 anschauen

@Bot.command(name="test", arg_count=1, required_permissions=Scapi.Bot.PermissionLevel.CUSTOM)
def test_command(username: str, args: list):
    Bot.send_message(f"""
        Username: {username}
        Args: {args}"""
        )

Um klarzustellen, wofür was steht, ist hier nun eine detalierte Erklärung:

Code	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 reine on_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)

def Commands():
    while True:
        try:
            message = Bot.recv_message(raw=True)
        
            if message.startswith("!hello"):
                Bot.send_message(f"Hello, world!")
                    
        except: 
            Bot.logger(
                f"{scapi.RED}An unknown exception occured{scapi.RESET}",
                type=Scapi.LogLevel.ERROR
                )

            break

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ßt on_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:

@Bot.event
def on_ready():
    Bot.logger(
            f"{scapi.BLUE}{Bot.username} started successfully!{scapi.RESET}",
            type=Scapi.LogLevel.INFO
            )

Den Bot starten

Um den Bot zu starten musst du zuerst darauf achten, welche Command Methode du verwendest.

Bot.run(on_ready)

BotThread = threading.Thread(target=Bot.run, args=(on_ready,))
CommandThread = threading.Thread(target=Commands)

BotThread.start()
CommandThread.start()

Beispielbot (Stable v1.0)

Dieser Beispielbot gilt nur für Scapi Legacy v1.0.0 (stbmv1)

import scapi                # Dies importiert Scapi
from scapi import Scapi

import yaml                 # Importiere YAML für die Konfiguration
from yaml import SafeLoader

with open("default.yml", encoding="utf-8") as config_file:
    config = yaml.load(config_file, Loader=SafeLoader) # Lade die Konfigurationsdatei

# Definiere einige wichtige Variablen für die Reibungslose Verwendung des Bots
username    = config["bot"]["username"]     
token       = config["bot"]["token"]
host        = config["server"]["host"]
port        = config["server"]["port"]
prefix      = config["bot"]["prefix"]

Bot = Scapi.Bot(username=username, token=token, host=host, port=port) # Definiere den Bot
Bot.login() # Anmelden ins System
Bot.flag_handler(print_recv_msg=True, enable_user_input=True) # Setze ein paar nützliche Flags

Bot.permission_handler(custom_list=["your_name"], owner="your_name") # Verwalte deine Bot Berechtigungen

# Standard Bot Command
@Bot.command(name="test", arg_count=1, required_permissions=Scapi.Bot.PermissionLevel.CUSTOM)
def test_command(username: str, args: list):
    Bot.send_message(f"""
        Username: {username}
        Args: {args}"""
        )

# Bot on_ready Event
@Bot.event
def on_ready():
    print(f"{Bot.log_msg}{scapi.BLUE}{Bot.username} started successfully!{scapi.RESET}")

# Starte den Bot
Bot.run(on_ready)

import scapi
from scapi import Scapi

import yaml
from yaml import SafeLoader
import threading

with open("default.yml", encoding="utf-8") as config:
    conf = yaml.load(config, Loader=SafeLoader)

username    = conf["bot"]["username"]
token       = conf["bot"]["token"]
host        = conf["server"]["host"]
port        = conf["server"]["port"]
prefix      = conf["bot"]["prefix"]

Bot = Scapi.Bot(username=username, token=token, host=host, port=port)
Bot.login()
Bot.flag_handler(print_recv_msg=True, enable_user_input=True)


def Commands():
    while True:
        try:
            message = Bot.recv_message(raw=True)
        
            if message.startswith("!hello"):
                Bot.send_message(f"Hello, world!")
                    
        except: 
            Bot.logger(f"{scapi.RED}An unknown exception occured{scapi.RESET}", type=Scapi.LogLevel.ERROR)
            break


@Bot.event
def on_ready():
    print(f"{Bot.log_msg}{scapi.BLUE}{Bot.username} started successfully!{scapi.RESET}")
    
BotThread = threading.Thread(target=Bot.run, args=(on_ready,))
CommandThread = threading.Thread(target=Commands)

BotThread.start()
CommandThread.start()

Dies ist ein Beispiel wie eine Konfiguration in YAML aussehen könnte:

bot:
  id: 12345678
  username: "username"
  token: "token"
  prefix: "!"

server:
  host: "1.2.3.4"
  port: 1234

flags:
  enableUserInput: true
  printReceivedMessagesToTerminal: true

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:

Bot = Scapi.Bot(username="username", token="bottoken", host="1.2.3.4", port=1234)

In dieser Tabelle siehst du alle verfügbaren Argumente mit ihrer Bedeutung

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ügbar

Das Argument prefix ist erst seit Scapi v0.13.1b2 verfügbar

Damit der Bot sich im Server auch einloggt, musst du noch eine wichtige Funktion hinzufügen

Bot.login()

Flags

Bot.flag_handler(print_recv_msg=True, enable_user_input=True)

In dieser Tabelle siehst du alle verfügbaren Flags mit ihrer Bedeutung

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

Bot.permission_handler(custom_list=["julian"], owner="julian")

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 werden

@Bot.command(name="test", arg_count=1, required_permissions=Scapi.Bot.PermissionLevel.CUSTOM)
def test_command(username: str, args: list):
    Bot.send_message(f"""
        Username: {username}
        Args: {args}"""
        )

Um klarzustellen, wofür was steht, ist hier nun eine detalierte Erklärung:

Code	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

Hier findest du noch weitere Commands

Direktnachrichten

@Bot.command(name="dm", arg_count=1)
def send_dm_command(username: str, args: list):
    Bot.send_direct_message(username, " ".join(args))

Chat verlassen

@Bot.command(name="exit",
            required_permissions=Scapi.Bot.PermissionLevel.OWNER)
def exit_command(username: str, args: list):
    Bot.exit()

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 an

Events

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:

# Python-Dekorator zum definieren des Nachrichtenevents
@Bot.on_message(message="Hello")
# Definierung der Funktion, um sie nachher automatisch auszuführen
def on_hello_message(username: str): 
    # Der Code der Funktion, also das was ausgeführt werden soll [...]
    Bot.send_message(f"Hello {username}!") 

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

Dieses Feature dient aktuell nur dazu, um z.B. ein normales Wort eines Nutzers zu verarbeiten, und darauf zu antworten.

@on_ready Event

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:

@Bot.event
def on_ready():
    Bot.logger(
            f"{scapi.BLUE}{Bot.username} started successfully!{scapi.RESET}",
            type=Scapi.LogLevel.INFO
            )

Den Bot starten

Um den Bot zu starten musst du zuerst darauf achten, welche Command Methode du verwendest.

Bot.run(on_ready)

BotThread = threading.Thread(target=Bot.run, args=(on_ready,))
CommandThread = threading.Thread(target=Commands)

BotThread.start()
CommandThread.start()

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

Du kannst Scapi (@json-communication/@main) hier erhalten. Die folgenden Code-Stücke zeigen dir wie du einen einfachen Bot mit Scapi (stbmv2) erstellen kannst.

import scapi
from scapi import Scapi

import yaml
from yaml import SafeLoader

with open("default.yml", encoding="utf-8") as config_file:
    config = yaml.load(config_file, Loader=SafeLoader)

username    = config["bot"]["username"]
token       = config["bot"]["token"]
host        = config["server"]["host"]
port        = config["server"]["port"]
prefix      = config["bot"]["prefix"]

Bot = Scapi.Bot(username=username, token=token, host=host, port=port, json=True)
Bot.login()
Bot.flag_handler(print_recv_msg=True, enable_user_input=True)

Bot.permission_handler(custom_list=["julian"], owner="julian")

@Bot.command(name="test", arg_count=1, required_permissions=Scapi.Bot.PermissionLevel.CUSTOM)
def test_command(username: str, args: list):
    Bot.send_message(f"""
        Username: {username}
        Args: {args}"""
        )

@Bot.event
def on_ready():
    Bot.logger(f"{scapi.BLUE}{Bot.username} started successfully!{scapi.RESET}", type=Scapi.LogLevel.INFO)
    
Bot.run(on_ready)

import scapi
from scapi import Scapi

import yaml
from yaml import SafeLoader

with open("default.yml", encoding="utf-8") as config_file:
    config = yaml.load(config_file, Loader=SafeLoader)

username    = config["bot"]["username"]
token       = config["bot"]["token"]
host        = config["server"]["host"]
port        = config["server"]["port"]
prefix      = config["bot"]["prefix"]

Bot = Scapi.Bot(username=username, token=token, host=host, port=port, json=True)
Bot.login()
Bot.flag_handler(print_recv_msg=True, enable_user_input=True)

Bot.permission_handler(custom_list=["julian"], owner="julian")

# Neue on_message Methode, um "Plain" Nachrichten vom Nutzer zu verarbeiten
@Bot.on_message(message="Hello")
def on_hello_message(username: str):
    Bot.send_message(f"Hello {username}!")    

# Commands Methode
@Bot.command(name="test", arg_count=1, required_permissions=Scapi.Bot.PermissionLevel.CUSTOM)
def test_command(username: str, args: list):
    Bot.send_message(f"""
        Username: {username}
        Args: {args}"""
        )

@Bot.event
def on_ready():
    Bot.logger(f"{scapi.BLUE}{Bot.username} started successfully!{scapi.RESET}", type=Scapi.LogLevel.INFO)
    
Bot.run(on_ready)

# WARNUNG: Diese Methode ist veraltet
# WIR ARBEITEN AN EINER BESSEREN VERSION DIESER METHODE

import scapi
from scapi import Scapi

import yaml
from yaml import SafeLoader
import threading

with open("default.yml", encoding="utf-8") as config:
    conf = yaml.load(config, Loader=SafeLoader)

username    = conf["bot"]["username"]
token       = conf["bot"]["token"]
host        = conf["server"]["host"]
port        = conf["server"]["port"]
prefix      = conf["bot"]["prefix"]

Bot = Scapi.Bot(username=username, token=token, host=host, port=port)
Bot.login()
Bot.flag_handler(print_recv_msg=True, enable_user_input=True)


def Commands():
    while True:
        try:
            message = Bot.recv_message(raw=True)
        
            if message.startswith("!hello"):
                Bot.send_message(f"Hello, world!")
                    
        except: 
            Bot.logger(f"{scapi.RED}An unknown exception occured{scapi.RESET}", type=Scapi.LogLevel.ERROR)
            break


@Bot.event
def on_ready():
    print(f"{Bot.log_msg}{scapi.BLUE}{Bot.username} started successfully!{scapi.RESET}")
    
BotThread = threading.Thread(target=Bot.run, args=(on_ready,))
CommandThread = threading.Thread(target=Commands)

BotThread.start()
CommandThread.start()

Das Ändern des zugewiesenen Wertes von json zu False aktiviert den Kompatiblitätsmodus. Beachte das dies noch nicht vollständig entwickelt wurde.

Einstieg

Strawberry Chat

Strawberry Communication Standard

SCAPI

spkg

Strawberry ID

Verwendung

Scapi installieren

Verwendung von scapi in deinem Code

Schreibe deinen ersten Bot (stbmv1)

Die ersten Schritte

Flags

Berechtigungen

Commands (`@commands` Modul)

Commands (Originale Methode)

Events

Den Bot starten

Beispielbot (Stable v1.0)

Schreibe deinen ersten Bot (stbmv2)

Die ersten Schritte

Flags

Berechtigungen

Commands (Commands Modul)

Commands (Originale Methode)

Events

@on_message Event

@on_ready Event

Den Bot starten

Beispielbot (v0.12.0 oder höher)

​Scapi installieren

​Verwendung von scapi in deinem Code

​Schreibe deinen ersten Bot (stbmv1)

​Die ersten Schritte

​Flags

​Berechtigungen

​Commands (@commands Modul)

​Commands (Originale Methode)

​Events

​Den Bot starten

​Beispielbot (Stable v1.0)

​Schreibe deinen ersten Bot (stbmv2)

​Die ersten Schritte

​Flags

​Berechtigungen

​Commands (Commands Modul)

​Commands (Originale Methode)

​Events

​@on_message Event

​@on_ready Event

​Den Bot starten

​Beispielbot (v0.12.0 oder höher)

Scapi installieren

Verwendung von scapi in deinem Code

Schreibe deinen ersten Bot (stbmv1)

Die ersten Schritte

Flags

Berechtigungen

Commands (`@commands` Modul)

Commands (Originale Methode)

Events

Den Bot starten

Beispielbot (Stable v1.0)

Schreibe deinen ersten Bot (stbmv2)

Die ersten Schritte

Flags

Berechtigungen

Commands (Commands Modul)

Commands (Originale Methode)

Events

@on_message Event

@on_ready Event

Den Bot starten

Beispielbot (v0.12.0 oder höher)