# Documentação Técnica: Scripting LUA (Max Control Automator)

Esta documentação fornece os parâmetros técnicos e funções disponíveis para a criação de scripts LUA compatíveis com o motor de automação do **Max Control Automator v3.0**. O motor LUA foi projetado para ser compatível com a lógica do Logitech G-Hub, permitindo a criação de macros complexas, automações de precisão e automações de interface.

---

## 1. Estrutura Principal: `OnEvent`

Todo script deve (ou pode) implementar a função `OnEvent` para reagir a entradas do usuário ou mudanças de estado do sistema.

```lua
function OnEvent(event, arg, family)
    -- Lógica aqui
end
```

### Eventos Disponíveis

| Evento | Parâmetro (`arg`) | Família (`family`) | Descrição |
| :--- | :--- | :--- | :--- |
| `PROFILE_ACTIVATED` | -1 | - | Disparado quando o script é iniciado. |
| `PROFILE_DEACTIVATED` | -1 | - | Disparado quando o script é parado. |
| `MOUSE_BUTTON_PRESSED` | 1, 2, 3, 4, 5 | `mouse` | Botão do mouse pressionado. |
| `MOUSE_BUTTON_RELEASED` | 1, 2, 3, 4, 5 | `mouse` | Botão do mouse solto. |
| `KEYBOARD_PRESSED` | nome_da_tecla | `keyboard` | Tecla do teclado pressionada. |
| `KEYBOARD_RELEASED` | nome_da_tecla | `keyboard` | Tecla do teclado solta. |

#### IDs de Botões do Mouse (`arg`)
* **1**: Botão Esquerdo (Left Click)
* **2**: Botão Direito (Right Click)
* **3**: Botão do Meio (Scroll Click)
* **4**: Botão Lateral 1 (X1)
* **5**: Botão Lateral 2 (X2)

---

## 2. Funções Globais Disponíveis

Estas funções podem ser chamadas em qualquer lugar do seu script LUA.

### Controle de Mouse
* `MoveMouseRelative(dx, dy)` ou `MoveR(dx, dy)`: Move o mouse relativamente à posição atual. Útil para automações de precisão.
* `PressMouseButton(button)`: Pressiona um botão do mouse (1, 2 ou 3).
* `ReleaseMouseButton(button)`: Solta um botão do mouse (1, 2 ou 3).
* `IsMouseButtonPressed(button)`: Retorna `true` se o botão físico estiver pressionado.

### Controle de Teclado
* `PressKey(key_name)`: Pressiona virtualmente uma tecla.
* `ReleaseKey(key_name)`: Solta virtualmente uma tecla.
* `IsModifierPressed(modifier)`: Verifica se uma tecla modificadora (ctrl, alt, shift) está pressionada.
* `IsKeyLockOn(key_name)`: Verifica o estado de `capslock`, `numlock` ou `scrolllock`.

### Sistema e Utilidades
* `Sleep(ms)`: Pausa a execução do script por X milissegundos.
* `GetRunningTime()`: Retorna o tempo de execução do sistema em milissegundos.
* `OutputLogMessage(format, ...)`: Envia uma mensagem para o console de log da aplicação. Aceita `%s` para formatação.
* `ClearLog()`: Limpa o console de logs da aplicação.
* `EnablePrimaryMouseButtonEvents(bool)`: Habilita ou desabilita a captura do botão esquerdo para o OnEvent.

---

## 3. Mapeamento de Teclas (Key Names)

O sistema normaliza os nomes das teclas automaticamente (converte para minúsculas e remove underscores). Abaixo estão os nomes técnicos que devem ser usados nas funções `PressKey`, `ReleaseKey`, `IsModifierPressed`, etc.

### Teclas Alfanuméricas e Símbolos
* Letras: `"a"` até `"z"`
* Números: `"0"` até `"9"`
* Teclado Numérico: `"num0"` até `"num9"`, `"multiply"`, `"add"`, `"subtract"`, `"decimal"`, `"divide"`

### Teclas de Função
* `"f1"` até `"f12"`

### Teclas de Controle
* `"ctrl"`, `"lctrl"`, `"rctrl"`, `"control"`
* `"shift"`, `"lshift"`, `"rshift"`
* `"alt"`, `"lalt"`, `"ralt"`, `"alt_gr"`
* `"enter"`, `"tab"`, `"space"`, `"backspace"`, `"escape"` (ou `"esc"`)
* `"lwin"`, `"rwin"`

### Teclas de Navegação e Edição
* `"left"`, `"right"`, `"up"`, `"down"`
* `"pageup"` (ou `"pgup"`, `"page_up"`)
* `"pagedown"` (ou `"pgdn"`, `"page_down"`)
* `"home"`, `"end"`, `"insert"` (ou `"ins"`), `"delete"` (ou `"del"`)
* `"printscreen"`, `"pause"`

### Teclas de Trava (Locks)
* `"capslock"` (ou `"caps"`, `"caps_lock"`)
* `"numlock"` (ou `"num_lock"`)
* `"scrolllock"` (ou `"scroll_lock"`)

---

## 4. Notas Técnicas Importantes

1. **Sensibilidade a Maiúsculas/Minúsculas**: O motor LUA do Max Control é tolerante, mas recomenda-se o uso de letras minúsculas para nomes de teclas para garantir compatibilidade futura.
2. **Normalização**: Nomes como `page_up`, `PageUp` e `pgup` são todos convertidos internamente para `pageup`.
3. **Loop Infinito**: Evite loops `repeat/until` ou `while` sem a função `Sleep(ms)`, pois isso pode travar a aplicação ou causar alto uso de CPU. O uso de `Sleep(1)` a `Sleep(10)` é altamente recomendado dentro de loops de repetição.
4. **Thread Safety**: O motor LUA roda em uma thread dedicada para garantir que a interface do usuário permaneça responsiva mesmo durante execuções pesadas.