新しいプラグインモジュールの作成¶

私たちのフレームワークは、強力な自動検出システムを使用してルールモジュールを読み込みます。これにより、すべての新しいコンポーネントを手動で登録する必要がなく、新しいコマンドセットの追加が簡単かつクリーンになります。このガイドでは、独自のカスタムモジュールを作成、構造、管理する方法について説明します。

中心となる概念: フォルダーベースのモジュール¶

モジュールは単に「config/maps/」ディレクトリ内のフォルダーです。システムはこのディレクトリを自動的にスキャンし、各サブフォルダーを読み込み可能なモジュールとして扱います。

モジュール作成のステップバイステップガイド¶

たとえば、特定のゲームのマクロを保持するための新しいモジュールを作成するには、次の手順に従います。

1.マップディレクトリに移動します すべてのルールモジュールは、プロジェクトの config/maps/ フォルダーに存在します。

2.モジュールフォルダーを作成します 新しいフォルダーを作成します。名前はわかりやすいものにし、スペースの代わりにアンダースコアを使用する必要があります (例: 「my_game_macros」、「custom_home_automation」)。

3.言語サブフォルダーの追加 (重要なステップ) 新しいモジュールフォルダー内に、サポートする言語ごとにサブフォルダーを作成する必要があります。

命名規則: これらのサブフォルダーの名前は 有効な言語ロケールコードである必要があります。システムはこれらの名前を使用して、アクティブな言語の正しいルールをロードします。
正しい例: de-DE、en-US、en-GB、pt-BR
警告: german や english_rules などの標準以外の名前を使用すると、システムはフォルダーを無視するか、別の非言語固有モジュールとして扱います。

4.ルールファイルを追加します ルールファイル (例: FUZZY_MAP_pre.py) を適切な言語サブフォルダー内に配置します。最も簡単な開始方法は、既存の言語モジュールフォルダーの内容をコピーしてテンプレートとして使用することです。

ディレクトリ構造の例¶

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!!
            

構成内のモジュールの管理¶

このシステムは、最小限の構成が必要となるように設計されています。

モジュールの有効化 (デフォルト)¶

モジュールはデフォルトで有効になっています。モジュールフォルダーが config/maps/ に存在する限り、システムはそれを見つけてそのルールをロードします。 新しいモジュールを有効にするために設定ファイルにエントリを追加する必要はありません。

モジュールの無効化¶

モジュールを無効にするには、設定ファイル内の PLUGINS_ENABLED 辞書にそのモジュールのエントリを追加し、その値を False に設定する必要があります。

例 (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,
}

重要な設計上の注意事項¶

デフォルトの動作: エントリなしは「True」に相当します モジュールが「PLUGINS_ENABLED」辞書にリストされていない場合、デフォルトではアクティブとみなされます。この設計では、例外をリストするだけで済むため、構成ファイルがクリーンな状態に保たれます。
イネーブルの略語 構成システムは、値を指定せずにモジュールキーをリストすると、それが有効であることを意味することも理解します。たとえば、辞書に "wannweil" を追加することは、"wannweil": True を追加することと同じです。これは、モジュールを有効にするための便利な省略表現を提供します。
親モジュールの無効化: 意図された動作では、親モジュールを無効にするには
すべての子モジュールと言語サブフォルダーを自動的に無効にします。たとえば、"standard_actions": False を設定すると、de-DE と en-US の両方がロードされなくなります。 (27.10.’25 月)
目標目標は、このシステムをさらに強化することです。たとえば、親が無効になっている場合でも子モジュールの設定が尊重される方法を提供したり、より複雑な継承ルールを導入したりできます。 (27.10.’25 月)

新しいプラグイン モジュールの作成¶