Neue Plugin-Module erstellen (docs/CreatingNewPluginModules.md)¶

Unser Framework verwendet ein leistungsstarkes Auto-Discovery-System zum Laden von Regelmodulen. Dadurch ist das Hinzufügen neuer Befehlssätze einfach und sauber, ohne dass jede neue Komponente manuell registriert werden muss. In diesem Leitfaden wird erläutert, wie Sie Ihre eigenen benutzerdefinierten Module erstellen, strukturieren und verwalten.

Das Kernkonzept: Ordnerbasierte Module¶

Ein Modul ist einfach ein Ordner im Verzeichnis „config/maps/“. Das System durchsucht dieses Verzeichnis automatisch und behandelt jeden Unterordner als ladbares Modul.

Schritt-für-Schritt-Anleitung zum Erstellen eines Moduls¶

Befolgen Sie diese Schritte, um ein neues Modul zu erstellen, um beispielsweise Makros für ein bestimmtes Spiel zu speichern.

1. Navigieren Sie zum Kartenverzeichnis Alle Regelmodule befinden sich im Ordner „config/maps/“ des Projekts.

2. Erstellen Sie Ihren Modulordner Erstellen Sie einen neuen Ordner. Der Name sollte beschreibend sein und Unterstriche anstelle von Leerzeichen verwenden (z. B. „my_game_macros“, „custom_home_automation“).

3. Sprachunterordner hinzufügen (kritischer Schritt) In Ihrem neuen Modulordner müssen Sie Unterordner für jede Sprache erstellen, die Sie unterstützen möchten.

Namenskonvention: Die Namen dieser Unterordner müssen gültige Sprachcodes sein. Das System verwendet diese Namen, um die richtigen Regeln für die aktive Sprache zu laden.
Korrekte Beispiele: „de-DE“, „en-US“, „en-GB“, „pt-BR“.
Warnung: Wenn Sie einen nicht standardmäßigen Namen wie „german“ oder „english_rules“ verwenden, ignoriert das System den Ordner entweder oder behandelt ihn als separates, nicht sprachspezifisches Modul.

4. Fügen Sie Ihre Regeldateien hinzu Platzieren Sie Ihre Regeldateien (z. B. „FUZZY_MAP_pre.py“) im entsprechenden Unterordner der Sprache. Der einfachste Einstieg besteht darin, den Inhalt eines vorhandenen Sprachmodulordners zu kopieren und als Vorlage zu verwenden.

Beispiel einer Verzeichnisstruktur¶

config/
└── maps/
    ├── standard_actions/      # An existing module
    │   ├── de-DE/
    │   └── en-US/
    │
    └── my_game_macros/        # <-- Your new custom module
        └── de-DE/             # <-- Language-specific rules
            └── FUZZY_MAP_pre.py

        ├── __init__.py        # <-- Important: This Empty File must be in every Folders!!
            

Module in der Konfiguration verwalten¶

Das System ist so konzipiert, dass nur eine minimale Konfiguration erforderlich ist.

Module aktivieren (Standard)¶

Module sind standardmäßig aktiviert. Solange ein Modulordner in „config/maps/“ vorhanden ist, wird das System ihn finden und seine Regeln laden. Sie müssen Ihrer Einstellungsdatei keinen Eintrag hinzufügen, um ein neues Modul zu aktivieren.

Module deaktivieren¶

Um ein Modul zu deaktivieren, müssen Sie einen Eintrag dafür im Wörterbuch „PLUGINS_ENABLED“ in Ihrer Einstellungsdatei hinzufügen und seinen Wert auf „False“ setzen.

(Optional) Für Wahr/Falsch können Sie auch 1/0 verwenden. Dies ist jedoch ungewöhnlich und kann die Lesbarkeit beeinträchtigen.

Beispiel (config/settings.py):

# A dictionary to explicitly control the state of modules.
# The key is the path to the module relative to 'config/maps/'.
PLUGINS_ENABLED = {
    "empty_all": False,

    # This module is explicitly enabled.
    "git": True,

    # This module is also enabled. Second Parameter is per default True. Not False means True.
    # "wannweil": False,

    # This module is explicitly disabled.
    "game": False,

    # This module is disabled by other rule
    "game/game-dealers_choice": True,

    # This module is disabled by other rule
    "game/0ad": True,
}

Wichtige Designhinweise¶

Standardverhalten: Kein Eintrag ist gleich „True“ Wenn ein Modul nicht im Wörterbuch „PLUGINS_ENABLED“ aufgeführt ist, gilt es standardmäßig als aktiv. Durch dieses Design bleibt die Konfigurationsdatei sauber, da Sie nur die Ausnahmen auflisten müssen.
Abkürzung für Enabling Ihr Konfigurationssystem versteht auch, dass die Auflistung eines Modulschlüssels ohne Wert bedeutet, dass er aktiviert ist. Beispielsweise ist das Hinzufügen von „wannweil“ zum Wörterbuch dasselbe wie das Hinzufügen von „wannweil“: True“. Dies bietet eine praktische Abkürzung zum Aktivieren von Modulen.

(Optional) Für Wahr/Falsch können Sie auch 1/0 verwenden. Dies ist jedoch ungewöhnlich und kann die Lesbarkeit beeinträchtigen.

Deaktivieren übergeordneter Module: Das beabsichtigte Verhalten besteht darin, dass die Deaktivierung eines übergeordneten Moduls sein sollte Deaktivieren Sie automatisch alle untergeordneten Module und Sprachunterordner. Beispielsweise sollte die Einstellung „standard_actions“: False verhindern, dass sowohl „de-DE“ als auch „en-US“ geladen werden. (27.10.’25 Mo)
Ziel Ziel ist es, dieses System weiter zu verbessern. Beispielsweise bieten wir eine Möglichkeit, die Einstellungen untergeordneter Module auch dann zu berücksichtigen, wenn das übergeordnete Modul deaktiviert ist, oder führen komplexere Vererbungsregeln ein. (27.10.’25 Mo)

t1- Es ist in der Tat wesentlich benutzerfreundlicher und komfortabler, die Steuerung über die Sprachbefehle direkt in diesem Dokumentationsabschnitt hervorzuheben [1].

t2- Wir erweitern den Entwurf um eine klare Beschreibung der Tasten- bzw. Sprachsteuerungsbefehle (wie „Aura, Lernmodus einschalten / ausschalten“) und erklären kurz, wie toggle_learning.py das Aus- und Einkommentieren automatisiert [2].

Aktivieren des Lernmodus (unübertroffenes Training)¶

Damit Ihr benutzerdefiniertes Modul automatisch unbekannte Phrasen lernen kann, wenn der „Lernmodus“ aktiv ist, können Sie ganz unten an Ihrer „FUZZY_MAP_pre“-Liste eine Sammelregel anhängen.

Diese Regel ruft das nicht übereinstimmende Trainings-Plugin auf, wenn keine andere spezifische Regel in Ihrer Datei übereinstimmt:

    # --- Training-Plugin (dynamically toggled by the learning mode) ---
    (f'{str(__file__)}', r'^(.*)$', 10, {
        'on_match_exec': [SL5NET_AURA_PROJECT_ROOT / 'config' / 'maps' / 'plugins' / '1_collect_unmatched_training' / 'collect_unmatched.py']
    }),

Das Trainings-Plugin verwendet „f’{str(file)}“, um Ihre Datei zu finden und die nicht erkannte Phrase automatisch an die erste verfügbare Regelgruppe (wie Ihre Hauptbefehlsgruppe) anzuhängen.

Umschalten des Lernmodus über Sprachbefehle¶

Anstatt Dateien manuell zu bearbeiten, lässt sich diese Funktion am bequemsten über integrierte Sprachbefehle verwalten:

Zur Aktivierung: Sagen Sie „Aura, Lernmodus ein“ oder „Aura, Lernmodus starten“.
Zum Deaktivieren: Sagen Sie „Aura, Lernmodus aus“ oder „Aura, Lernmodus stoppen“.

Diese Befehle lösen hinter den Kulissen „toggle_learning.py“ aus, das die Catch-All-Zeilen in Ihren aktiven Kartendateien automatisch kommentiert oder auskommentiert.

Tipp: Nachdem Sie Ihre Regex-Muster definiert haben, führen Sie „python3 tools/map_tagger.py“ aus, um automatisch durchsuchbare Beispiele für die CLI-Tools zu generieren. Weitere Informationen finden Sie unter Map Maintenance Tools.