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

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

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

モジュールは単に「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`):**
```python
# 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 月)