# Recibos e códigos de motivo

> O recibo de cada comando traz um código de status e um código de motivo. Eles são a base para Bots e agentes se corrigirem sozinhos: transformam “por que não deu certo” em um número legível por máquina.

Fonte: https://war3ai.com/pt/docs/reason-codes/

```python
r = g.train(barracks, "hfoo")
bool(r)        # False
r.status       # 1              -> rejected
r.verdict      # 3              -> comida insuficiente
r.reason       # 'rejected（人口不够）'  (= comida insuficiente)
r.exec_us      # quantos microssegundos este comando levou na thread do jogo
```

`if r:` equivale a `r.status == 0` (o motor aceitou).

## Código de status `status`

| Código | Nome | Significado | Causas comuns |
|---|---|---|---|
| 0 | `accepted` | O motor aceitou | — (mas aceito ≠ concluído; veja abaixo) |
| 1 | `rejected` | Rejeitado pelo motor | Veja `verdict` |
| 2 | `bad_unit` | A unidade não existe ou o handle não confere | A unidade já morreu; objeto de unidade desatualizado |
| 3 | `not_owner` | Não é sua unidade | Comandar unidades de outro jogador com a identidade `player` |
| 4 | `fault` | Exceção durante a execução (o runtime contém o erro; o jogo não cai) | Relate com os passos para reproduzir |
| 5 | `bad_args` | Parâmetro errado | Coordenada, índice de slot ou código de quatro caracteres errado |
| 6 | `unsupported` | Não suportado | Esta versão do runtime não tem essa capacidade |
| 7 | `bad_target` | Alvo inválido | O alvo já sumiu; tipo de alvo errado |
| 8 | `forbidden` | O papel da via não permite | Dar ordens com a identidade `observer` |
| 97 | `cancelled` | Exceção dentro do bloco de lote; o lote inteiro não foi enviado | Erro no código dentro do bloco `with g.batch():` |
| 98 | `held` | A unidade está presa por uma camada de prioridade maior; o comando não foi enviado | A camada reflexa do cérebro de referência ou uma ordem manual do console está segurando a unidade |
| 99 | `timeout` | Tempo esgotado | Com o jogo pausado / travando, o prazo passou (comandos vencidos não são executados depois) |

## Código de motivo `verdict`

Quando um comando é rejeitado, o runtime usa a própria verificação de viabilidade do motor para explicar o motivo. Você também pode perguntar antes, sem dar a ordem: `g.can_do(unidade, código)` retorna o mesmo código.

| Código | Significado | O que fazer |
|---|---|---|
| 0 / 220 | Pode | — |
| 3 | Comida insuficiente | Erga construções de comida; use `g.production(b).blocked` para perceber antes |
| 8 | Ouro insuficiente | Espere o dinheiro; antes de dar a ordem, use `g.can_afford(code)` |
| 9 | Madeira insuficiente | Mande mais gente cortar madeira |
| 32 | Fila de treino cheia (7 vagas) | Deixe só 1 na fila: coloque o próximo quando `g.queue(b)` esvaziar |
| 183 | Falta tecnologia / construção pré-requisito | Construa o pré-requisito primeiro, suba de tier |
| 185 | Construção ocupada | O altar está revivendo um herói; o edifício principal não pode ser melhorado enquanto a fila estiver ocupada |
| 221 | Item inexistente / em construção / em melhoria / já existe | O herói já existe (se morreu, use `revive`); esta loja não vende isso |
| 89 | A loja ainda não tem estoque | No início, o item só aparece após o tempo de estoque da tabela de itens; numa loja recém-construída, a contagem começa quando ela fica pronta |
| 1001 | Alvo não visível | O alvo está na névoa de guerra ou na máscara preta; use `attack_move` na posição dele |

## Aceito ≠ concluído

O recibo só diz que “o motor aceitou o comando”, lido de volta no mesmo frame. O que acontece depois está fora do alcance dele:

| Comando | Pode falhar mesmo depois de aceito | Como confirmar |
|---|---|---|
| Construir | Um ponto numa floresta também é aceito na hora; a falha só vem quando o trabalhador chega | Use `build_near` (acompanha se a fundação aparece) ou espere `production.done` |
| Lançar feitiço | Interrompido, sem mana | No tick seguinte, veja se `g.cooldown(u, habilidade)` entrou em recarga |
| Treinar | Entra na fila, mas falta comida e nunca começa | `g.production(b).blocked` |
| Mover / atacar | Alterado por outra lógica (ou por uma camada de prioridade maior) | `g.current_target(u)`, `g.order_of(u)` |

## APIs de consulta

As APIs abaixo não dão ordens, só consultam o motor; o resultado também vai no `value` do recibo (o SDK retorna o valor direto):

| API | Retorna |
|---|---|
| `g.can_do(u, code)` / `g.can_do_many([(u, code), ...])` | O código de motivo da tabela acima |
| `g.tech(code, player=None)` / `g.tech_many([...])` | Nível de pesquisa / número de construções prontas (incluindo a cadeia de melhorias) |
| `g.visible(x, y)` | Se este ponto está visível para o seu lado |
| `g.gold_left(mine)` | Quanto ouro resta na mina |
| `g.enemy_ai_plan(tropa_inimiga)` | Para onde o capitão do computador vai levar as tropas (só vale para a IA do computador) |