​

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

​

Schreibe deinen ersten Bot (stbmv1)

​

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

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

​

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:

@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:

​

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.

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

​

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)

​

Beispielbot (Stable v1.0)

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)

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)

​

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

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

​

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:

@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:

Hier findest du noch weitere Commands

​

Commands (Originale Methode)

​

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}!") 

​

@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)

​

Beispielbot (v0.12.0 oder höher)

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)

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