Criando novos módulos de plug-in¶

Nossa estrutura usa um poderoso sistema de descoberta automática para carregar módulos de regras. Isso torna a adição de novos conjuntos de comandos simples e limpa, sem a necessidade de registrar manualmente cada novo componente. Este guia explica como criar, estruturar e gerenciar seus próprios módulos personalizados.

O conceito central: módulos baseados em pastas¶

Um módulo é simplesmente uma pasta dentro do diretório config/maps/. O sistema verifica automaticamente esse diretório e trata cada subpasta como um módulo carregável.

Guia passo a passo para criar um módulo¶

Siga estas etapas para criar um novo módulo, por exemplo, para armazenar macros de um jogo específico.

1. Navegue até o Diretório de Mapas Todos os módulos de regras residem na pasta config/maps/ do projeto.

**2. Crie a pasta do seu módulo ** Crie uma nova pasta. O nome deve ser descritivo e usar sublinhados em vez de espaços (por exemplo, my_game_macros, custom_home_automation).

3. Adicionar subpastas de idiomas (etapa crítica) Dentro da pasta do novo módulo, você deve criar subpastas para cada idioma que pretende oferecer suporte.

Convenção de nomenclatura: Os nomes dessas subpastas devem ser códigos de localidade de idioma válidos. O sistema utiliza esses nomes para carregar as regras corretas para o idioma ativo.
Exemplos corretos: de-DE, en-US, en-GB, pt-BR
Aviso: Se você usar um nome não padrão como german ou english_rules, o sistema irá ignorar a pasta ou tratá-la como um módulo separado, não específico do idioma.

4. Adicione seus arquivos de regras Coloque seus arquivos de regras (por exemplo, FUZZY_MAP_pre.py) dentro da subpasta de idioma apropriada. A maneira mais fácil de começar é copiar o conteúdo de uma pasta de módulo de idioma existente para usar como modelo.

Exemplo de estrutura de diretório¶

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

Gerenciando Módulos na Configuração¶

O sistema foi projetado para exigir configuração mínima.

Habilitando Módulos (O Padrão)¶

Os módulos estão ativados por padrão. Enquanto existir uma pasta de módulo em config/maps/, o sistema irá encontrá-la e carregar suas regras. Você não precisa adicionar uma entrada ao seu arquivo de configurações para ativar um novo módulo.

Desativando Módulos¶

Para desabilitar um módulo, você deve adicionar uma entrada para ele no dicionário PLUGINS_ENABLED em seu arquivo de configurações e definir seu valor como False.

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

Notas importantes de design¶

Comportamento padrão: Nenhuma entrada é igual a True Se um módulo não estiver listado no dicionário PLUGINS_ENABLED, ele será considerado ativo por padrão. Este design mantém o arquivo de configuração limpo, pois você só precisa listar as exceções.
Abreviação de Habilitação Seu sistema de configuração também entende que listar uma chave de módulo sem valor implica que ela está habilitada. Por exemplo, adicionar "wannweil" ao dicionário é o mesmo que adicionar "wannweil": True. Isso fornece um atalho conveniente para habilitar módulos.
Desabilitando Módulos Pai: O comportamento pretendido é que desabilitar um módulo pai deve
desabilita automaticamente todos os seus módulos filhos e subpastas de idioma. Por exemplo, definir "standard_actions": False deve impedir o carregamento de de-DE e en-US. (27.10.’25 seg)
meta O objetivo é aprimorar ainda mais esse sistema. Por exemplo, fornecer uma maneira de respeitar as configurações do módulo filho mesmo se o pai estiver desabilitado ou introduzir regras de herança mais complexas. (27.10.’25 seg)