Como criar um bot para jogos Android no MAS

Este tutorial mostra como criar um bot para jogos Android no Macro Automation Studio (MAS), de um jogo instalado até um bot que roda em um agendamento, em uma conta ou em várias. Os bots do MAS trabalham a partir da tela: encontram botões por imagem, leem contadores com OCR e tocam com tempo humanizado. Ele é para quem está montando o primeiro bot, no Windows ou no Mac.

Play

How to make a bot for any game

Antes de começar

• O MAS está instalado e você fez login com o teste gratuito ou um plano. Veja Instalar o MAS.
• O jogo roda em um dispositivo que o MAS consegue controlar: um emulador neste computador, um dispositivo na nuvem ou o seu próprio celular. Veja Dispositivos.
• O dispositivo está em um grupo de dispositivos e o card dele mostra Parado, não Erro. A página Primeiros passos mostra como adicionar um.
• Para o caminho em Python, você não precisa de mais nada. O MAS traz o próprio ambiente Python com o pacote mas.

Como criar um bot para jogos Android: três caminhos

Instalar um do Marketplace

O caminho mais rápido quando alguém já montou um bot para o seu jogo.

1. Abra o Marketplace e pesquise o jogo.
2. Abra a listagem e clique em Baixar. O bot aparece em Macros.
3. Em Grupos de dispositivos, abra o seu grupo, escolha o bot no seletor Macro do dispositivo e clique em Iniciar.

O passo a passo completo com capturas de tela está em Como rodar uma macro do Marketplace. Existem bots prontos para Whiteout Survival, Kingshot e Last Asylum: Plague.

Pedir ao MAS Agent

O caminho sem código para um jogo sem listagem.

1. Abra Agent e escolha o dispositivo.
2. Descreva a rotina em uma frase, incluindo quando ela deve parar, e clique em Gerar.
3. Responda quando o agente perguntar. Ele para e pergunta em vez de adivinhar.
4. Quando a macro passar em 3 execuções de validação, clique em Adicionar às minhas macros.

Gerar a macro consome créditos de IA; rodar a macro pronta não consome nenhum. O resultado é um projeto Python normal que você pode abrir e editar. Veja MAS Agent.

Montar em Python

Controle total sobre toda decisão que o bot toma. O resto desta página é esse caminho.

Automatizar jogos Android com Python

1. Liste o que o bot precisa ver

Jogue a rotina uma vez à mão e anote toda tela que ela toca. Isso inclui o botão que você aperta, os pop-ups que interrompem, o contador que mostra a sua energia e a mensagem que significa que acabou. Cada item vira uma imagem template ou uma região de OCR. Um bot que conhece o seu estado de parada nunca roda às cegas.

2. Crie o projeto

1. Abra Macros e clique em Criar novo projeto.
2. Escolha Baseado em código, defina Dispositivo alvo como mobile, dê um nome ao projeto e clique em Criar projeto.
3. Abra o projeto. O Code Editor mostra src/app.py, o arquivo que o MAS executa.

3. Capture os templates no Asset Lab

1. Abra o jogo no dispositivo e vá até a tela com o botão.
2. No Code Editor, abra o painel Assets e clique em Abrir o Asset Helper. O Asset Lab abre com a tela ao vivo.
3. Recorte um retângulo justo em volta do botão e salve. Ele entra na sua Biblioteca de imagens com um ID numérico.
4. Repita para o botão de fechar pop-up, o botão de confirmar e a mensagem de “sem energia”.
5. De volta ao painel Assets, use Copiar ID em cada imagem e cole os IDs em mas.images no topo do seu script.

Mantenha os recortes pequenos e distintos. Uma tela inteira só corresponde àquela tela exata; um botão corresponde onde quer que o botão apareça. Os templates podem ser jpg, png, gif ou webp, com até 10 MB cada. A página Asset Lab cobre a ferramenta em detalhe.

4. Capture uma região de OCR

1. No Asset Lab, desenhe uma caixa em volta do contador que você quer ler.
2. Rode o teste de OCR ao vivo e aperte a caixa até os dígitos voltarem limpos.
3. Copie as coordenadas para uma Region(x1, y1, x2, y2) no seu script.

O guia de OCR explica os modos de segmentação e a conversão de cor se o texto for lido mal.

5. Escreva o loop

O loop abaixo é a forma que todo bot de jogo compartilha. Cada linha corresponde a uma chamada do SDK:

• find_object_retry procura o botão até total_tries=3 vezes, com time_sleep=2.0 segundos de intervalo, e retorna None quando nada corresponde.
• click(x, y, delay_ms=1000) toca no centro da correspondência e espera um segundo para o jogo reagir.
• read_text(region, psm=7) lê o contador como uma única linha.
• time.sleep(random.uniform(0.8, 2.0)) adiciona uma pausa humana entre as rodadas.
• mas.save e mas.retrieve guardam o contador de rodadas, então uma execução interrompida retoma de onde parou.
• As condições de parada encerram o loop. O exemplo usa cinco: um número máximo de rodadas, um limite de tempo, o template “sem energia”, um contador baixo e falhas demais em sequência.

6. Rode e leia os logs

Escolha o dispositivo no Code Editor e clique em Executar (F5). Toda linha de mas.log aparece no console de execução. Parar é Shift+F5. Corrija uma coisa de cada vez: quando um template não é encontrado, recorte-o de novo antes de mexer na lógica.

7. Agende

1. Abra o Agendador e clique em Criar novo agendamento.
2. Preencha o Nome, escolha a Macro e a Porta do emulador, defina Data e Hora.
3. Defina a Recorrência como Diária e clique em Criar agendamento.

O app precisa ficar aberto; o agendador roda dentro dele. Veja Agendador e Loops e agendamento.

8. Rode em um grupo de dispositivos

Adicione a instância de emulador de cada conta como um dispositivo em um grupo, atribua o bot a cada dispositivo e clique em Iniciar todos. Os valores por dispositivo, como o nome da conta, vêm de um perfil de configurações. Veja Farm multi-instância.

Um bot de exemplo completo

Troque os IDs de imagem e a região pelos que você capturou. O script farma um recurso até a energia ficar baixa, o limite de tempo passar ou trinta rodadas terminarem, e sobrevive a uma reinicialização.

import random
import sys
import time

import mas
from mas import Region

images = mas.images({
    "attack_button": 101,
    "confirm_button": 102,
    "close_popup": 103,
    "out_of_energy": 104,
})

ENERGY_REGION = Region(x1=380, y1=20, x2=520, y2=60)
TASK = "farm_bot"
MAX_ROUNDS = 30
TIME_BUDGET_S = 20 * 60
MIN_ENERGY = 10


def pause(low=0.8, high=2.0):
    time.sleep(random.uniform(low, high))


def read_energy():
    result = mas.read_text(region=ENERGY_REGION, psm=7)
    digits = "".join(ch for ch in result.text if ch.isdigit())
    return int(digits) if digits else None


def clear_popups():
    popup = mas.find_any_object([images.close_popup, images.confirm_button])
    if popup:
        mas.click(popup.x, popup.y, delay_ms=800)
        return True
    return False


def main():
    rounds = mas.retrieve(TASK).get("rounds", 0)
    misses = 0
    started = time.monotonic()
    mas.log(f"Starting at round {rounds}")

    while rounds < MAX_ROUNDS:
        if time.monotonic() - started > TIME_BUDGET_S:
            mas.log("Time budget reached", level="warning")
            break
        if clear_popups():
            continue
        if mas.find_object(images.out_of_energy):
            mas.log("Out of energy, stopping")
            break
        energy = read_energy()
        if energy is not None and energy < MIN_ENERGY:
            mas.log(f"Energy {energy} is below {MIN_ENERGY}, stopping")
            break
        button = mas.find_object_retry(images.attack_button, total_tries=3, time_sleep=2.0)
        if button is None:
            misses += 1
            mas.log(f"Attack button not found ({misses})", level="warning")
            if misses >= 5:
                mas.log("Giving up after 5 misses", level="error")
                sys.exit(2)
            continue
        misses = 0
        mas.click(button.x, button.y, delay_ms=1000)
        pause()
        rounds += 1
        mas.save(TASK, {"rounds": rounds})
        mas.log(f"Round {rounds} of {MAX_ROUNDS}")

    if rounds >= MAX_ROUNDS:
        mas.clear(TASK)
    mas.log(f"Finished with {rounds} rounds")


if __name__ == "__main__":
    main()

sys.exit(2) marca a execução como falha, então um webhook inscrito em macro.failed fica sabendo. Uma saída limpa informa macro.completed. Veja Webhooks.

Dicas que mantêm um bot estável

• Resolução. Templates e regiões pertencem à resolução e ao DPI em que você os capturou. Mantenha todo dispositivo que roda o bot na mesma configuração; os guias de emulador usam 540x960 em retrato a 240 DPI como base.
• Higiene dos templates. Recorte só o botão, nunca o fundo em volta. Recorte de novo depois que uma atualização do jogo mudar a arte. Quando um botão tem duas aparências, capture as duas e procure com find_any_object.
• Condições de parada. Todo loop precisa de pelo menos duas: um contador ou limite de tempo, e um estado de tela que significa “acabou”. Um bot sem elas roda até você perceber.
• Vá devagar. Uma pausa de um a dois segundos entre as rodadas custa pouco e parece menos mecânica.
• Registre a decisão, não o toque. mas.log("Energy 8, stopping") diz por que uma execução terminou; um log de cem cliques não diz.

O que pode dar errado

O botão nunca é encontrado

O recorte é grande demais, o limiar é rígido demais para a arte, ou o dispositivo roda em uma resolução diferente daquela em que você capturou. Recorte mais justo, depois tente threshold=0.7 na chamada. O guia de reconhecimento de imagem tem a lista completa.

O contador lê o número errado

A região inclui um ícone vizinho, ou o texto é claro sobre fundo escuro. Aperte a caixa no Asset Lab e passe color_conversion=ColorConversion.BLACK_WHITE. O guia de OCR mostra como conferir a confiança.

O bot para na hora no segundo dia

O contador guardado já está no limite. O exemplo limpa o armazenamento ao chegar em MAX_ROUNDS; se você mudou isso, chame mas.clear("farm_bot") uma vez a partir de um script de rascunho.

Os cliques caem ao lado do botão

A resolução ou o DPI do emulador mudou depois da captura, ou a janela não está em retrato. Volte a tela do emulador para a configuração da captura e capture de novo tudo o que ainda errar.

Nenhuma ferramenta de automação é 100% livre de riscos, por isso automatize com responsabilidade e a seu próprio critério.