AutoTigrinho/README.md

AutoTigrinho 🤖

Sistema de cliques automáticos baseado em reconhecimento de imagem. O bot detecta visualmente um botão na tela e clica nele em intervalos configuráveis, respeitando horários e períodos definidos pelo usuário.

---

Requisitos

• Python 3.10+
• Ambiente gráfico (DISPLAY) — em servidores headless o script usa Xvfb automaticamente

---

Instalação

./iniciar.sh

O iniciar.sh executa automaticamente:

1. Verifica/cria o ambiente virtual (venv/)
2. Instala/atualiza as dependências do requirements.txt
3. Verifica a existência do .env e da imagem do botão
4. Configura Xvfb se não houver ambiente gráfico
5. Inicia o programa

---

Configuração

Edite o arquivo .env para ajustar o comportamento:

Intervalos de clique

Variável	Descrição	Padrão
INTERVALO_MINIMO_CLIQUE	Tempo mínimo entre cliques durante uma sessão (s)	10
INTERVALO_MAXIMO_CLIQUE	Tempo máximo entre cliques durante uma sessão (s)	30
INTERVALO_PRIMEIRO_CLIQUE	Espera antes do primeiro clique de uma sessão (s)	10
INTERVALO_ENTRE_SESSOES	Tempo de espera entre o fim de uma sessão e o início da próxima (s)	60
INTERVALO_CLIQUE_GLOBAL	Intervalo para clique de keep-alive em qualquer estado (s)	900 (15 min)

Controle de sessões

Variável	Descrição	Padrão
MAXIMO_CLIQUES_POR_SESSAO	Número de cliques por sessão antes da pausa	20
MAXIMO_FALHAS	Limite de falhas de detecção antes de encerrar	5
CONFIANCA	Confiança mínima da correspondência de imagem (0.0 a 1.0)	0.8

Períodos de funcionamento

Até 10 períodos podem ser configurados. Fora desses intervalos o sistema permanece ativo mas não executa sessões, apenas cliques de keep-alive.

PERIODO_1_INICIO=09:00
PERIODO_1_FIM=12:00

PERIODO_2_INICIO=14:00
PERIODO_2_FIM=18:00

PERIODO_3_INICIO=    ← deixe vazio para desativar
PERIODO_3_FIM=

Aparência

Variável	Descrição	Padrão
LARGURA_TERMINAL	Largura da interface em caracteres	60

---

Como funciona

Sessões

Uma sessão é um bloco de até MAXIMO_CLIQUES_POR_SESSAO cliques consecutivos. Quando esse limite é atingido:

1. A sessão é finalizada e contabilizada
2. O sistema entra em modo de espera por INTERVALO_ENTRE_SESSOES segundos
3. A cada INTERVALO_CLIQUE_GLOBAL segundos durante essa espera, um clique de keep-alive é executado
4. Ao terminar a espera, uma nova sessão é iniciada automaticamente

Clique de keep-alive (global)

Independentemente do estado — dentro ou fora dos períodos, durante espera entre sessões — o sistema executa um clique de manutenção a cada INTERVALO_CLIQUE_GLOBAL segundos. Isso evita timeout de sessão em aplicações que exigem atividade contínua.

Detecção de botão

O sistema usa OpenCV com template matching (TM_CCOEFF_NORMED) para encontrar a posição do botão na tela. O template deve ser fornecido como botaoparaclicar.png na raiz do projeto. Quando o botão não é encontrado, o sistema re-tenta automaticamente a cada INTERVALO_MINIMO_CLIQUE segundos até conseguir detectar e clicar.

Controle de horário

• Dentro de um período configurado → sessões são executadas normalmente
• Fora de todos os períodos → aguarda INTERVALO_CLIQUE_GLOBAL segundos, executa um clique de keep-alive e volta a verificar

Modo headless (sem DISPLAY)

Em servidores ou máquinas sem ambiente gráfico, o iniciar.sh tenta instalar e usar o Xvfb (X virtual framebuffer) automaticamente, sem necessidade de sudo.

---

Estrutura de arquivos

AutoTigrinho/app/
├── main.py               # Código principal
├── iniciar.sh            # Script de inicialização e setup
├── .env                  # Configurações
├── botaoparaclicar.png   # Imagem do botão (template)
├── requirements.txt      # Dependências Python
├── log.txt               # Log de execução
└── venv/                 # Ambiente virtual Python

---

Log de execução

Todas as ações são registradas em log.txt com timestamp:

[2026-09-09 15:00:00] Sessão 1 iniciada
[2026-09-09 15:00:10] Clicando em (450, 320)...
[2026-09-09 15:01:15] Aguardando 15s até o próximo ciclo...
[2026-09-09 15:05:00] Sessão 1 finalizada: 20 cliques
[2026-09-09 15:05:00] Aguardando 900s até a Sessão 2...
[2026-09-09 15:20:00] [Espera] Clicando em (450, 320)...

---

Interromper

Pressione CTRL+C para parar o programa a qualquer momento. O total de cliques realizados é exibido no encerramento.

---

Dicas

• A imagem botaoparaclicar.png deve ser um recorte apenas do botão, sem fundo ou com fundo transparente (PNG com canal alpha é suportado)
• Ajuste CONFIANCA conforme necessário: valores mais baixos detectam com menos precisão, valores mais altos exigem correspondência exata
• Use INTERVALO_MINIMO_CLIQUE e INTERVALO_MAXIMO_CLIQUE para simular comportamento humano (intervalos aleatórios)
• O pyautogui.FAILSAFE está ativado: mova o mouse para um dos cantos da tela para abortar imediatamente