파이썬 OCR 매크로: 게임 봇이 Tesseract로 숫자 읽기

템플릿 매칭은 안드로이드 게임 봇에 버튼이 화면에 있는지 알려 줍니다. 파이썬 OCR 매크로는 카운터가 무엇을 말하는지 알려 줍니다: 에너지 50 중 8, 00:42인 타이머, 레벨 숫자. 이 가이드는 파이썬 OCR 매크로의 핵심인 mas.read_text를 Asset Lab에서 그린 영역부터 에너지가 한계 아래로 떨어지면 멈추는 매크로까지 다룹니다. 에뮬레이터, 클라우드 기기 또는 휴대폰에서 Macro Automation Studio(MAS) 매크로를 파이썬으로 쓰는 분을 위한 가이드입니다.

시작하기 전에

• Code Editor에 Code-Based 프로젝트가 열려 있고 기기가 선택된 상태. 시작하기를 참고하세요.
• 앱이나 게임이 읽고 싶은 텍스트를 계속 유지할 해상도로 표시하고 있는 상태.
• 이미지 인식 가이드를 읽었거나 Region이 무엇인지 아는 상태.

안드로이드 게임 봇에서 Tesseract OCR이 동작하는 방식

read_text는 스크린샷, 또는 영역 안의 일부를 앱 안의 Tesseract OCR로 보냅니다. 엔진이 읽은 것을 반환합니다.

def read_text(
    region: Region | None = None,
    screenshot: Screenshot | None = None,
    model: str = "eng_best",
    psm: int = 7,
    color_conversion: ColorConversion = ColorConversion.NONE,
    timeout_ms: int = 30000,
) -> TextRecognitionResult

결과는 세 필드가 있는 TextRecognitionResult입니다: text(문자열), confidence(0.0부터 1.0까지), region(읽은 위치). 화면 전체를 읽어도 되지만, 좁은 영역이 더 빠르고 훨씬 정확하므로 첫 단계는 언제나 영역입니다.

Asset Lab에서 OCR 영역 고르기

1. 기기를 카운터가 있는 화면으로 가져옵니다.
2. Code Editor에서 Assets 패널을 열고 Open Asset Helper를 클릭합니다. Asset Lab이 실제 화면 위에 열립니다.
3. 텍스트 주위에 상자를 그립니다. 약간의 여백은 넣되 아이콘, 테두리, 옆의 숫자는 넣지 마세요.
4. 실시간 OCR 테스트를 실행합니다. 텍스트가 깨끗하게 읽힐 때까지 상자를 조정하세요. 테스트는 스크립트와 같은 엔진을 씁니다.
5. 네 좌표를 Region(x1, y1, x2, y2)에 복사합니다.

import mas
from mas import Region

ENERGY = Region(x1=380, y1=20, x2=520, y2=60)

result = mas.read_text(region=ENERGY)
print(repr(result.text), result.confidence)

조정하는 동안에는 repr로 출력하세요. print가 숨기는 잡스러운 공백과 줄바꿈을 보여 줍니다. 영역은 캡처 해상도 기준 픽셀 좌표이므로 모든 기기를 그 해상도로 유지하세요. Asset Lab을 참고하세요.

모델 선택

model이 Tesseract 데이터를 고릅니다. "eng_best"가 기본값이며 가장 정확하고, "eng_fast"는 깨끗한 텍스트에서 정확도 대신 속도를 얻고, "eng"은 표준 영어 세트입니다. 기본값으로 시작하고 반복문이 분당 수십 번 읽을 때만 바꾸세요.

페이지 분할 모드 고르기

psm은 Tesseract에 어떤 형태의 텍스트를 기대할지 알려 줍니다. 잘못된 모드가 빈 결과나 깨진 결과의 가장 흔한 원인입니다.

level = mas.read_text(region=Region(x1=20, y1=20, x2=90, y2=60), psm=8)
dialog = mas.read_text(region=Region(x1=60, y1=300, x2=480, y2=600), psm=6)

값은 0부터 13까지 있지만 이 네 가지가 거의 모든 매크로를 다룹니다. 한 줄 영역이 아무것도 반환하지 않으면 8을 먼저, 그다음 6을 시도하세요.

어두운 배경 위의 밝은 텍스트 고치기

Tesseract는 밝은 배경 위의 어두운 텍스트를 기대합니다. 게임 카운터는 보통 반대입니다. 어두운 바 위의 흰 숫자이고, 색 있는 외곽선이 있을 때가 많습니다. color_conversion이 OCR 전에 잘라낸 부분을 전처리합니다.

from mas import ColorConversion

energy = mas.read_text(
    region=ENERGY,
    psm=7,
    color_conversion=ColorConversion.BLACK_WHITE,
)

• ColorConversion.NONE(기본값)은 픽셀을 그대로 보냅니다.
• ColorConversion.BLACK_WHITE는 회색조로 바꾸고 자동 임계값을 적용해 순수한 흑백을 만듭니다. 지저분하거나 색 있는 배경 위의 고대비 텍스트에 가장 먼저 시도할 옵션입니다.
• ColorConversion.BGR_TO_GRAY 또는 RGB_TO_GRAY는 단순 회색조를 주며, BLACK_WHITE의 임계값이 가는 획을 지워 버릴 때 도움이 됩니다.

각 옵션을 Asset Lab에서 실제 화면으로 테스트하세요. GRAYSCALE 멤버는 없습니다. 위 이름 중 하나를 쓰세요.

타임아웃 설정

timeout_ms의 기본값은 30000입니다. psm=7의 좁은 영역은 1초 안에 돌아오고, 복잡한 화면의 전체 psm=11 읽기는 더 오래 걸립니다. 반응성을 유지해야 하는 반복문에서는 타임아웃을 낮추고, 느린 읽기가 실행을 끝내지 않도록 호출을 감싸세요.

try:
    result = mas.read_text(region=ENERGY, timeout_ms=5000)
except mas.RPCError as e:
    mas.log(f"OCR failed: {e}", level="warning")
    result = None

텍스트에서 숫자 파싱

result.text는 문자열이며 때로 공백, 쉼표, 슬래시, 잡스러운 글자가 섞입니다. 정규식으로 파싱하고 “숫자 없음”을 실제 결과로 다루세요.

import re

def first_int(text: str) -> int | None:
    cleaned = text.replace(",", "").replace("O", "0").replace("l", "1")
    m = re.search(r"\d+", cleaned)
    return int(m.group()) if m else None

def current_and_max(text: str) -> tuple[int | None, int | None]:
    m = re.search(r"(\d+)\s*/\s*(\d+)", text.replace(",", ""))
    return (int(m.group(1)), int(m.group(2))) if m else (None, None)

first_int("Energy 1,250")은 1250을, current_and_max("8/50")은 (8, 50)을 줍니다. O와 l 치환은 가장 흔한 숫자 오독 두 가지를 고칩니다. 숫자만 담긴 영역에만 적용하세요.

신뢰도 활용

confidence는 Tesseract가 찾은 단어 전체에 대해 0.0부터 1.0까지입니다. 깨끗한 카운터는 0.9 이상으로 읽힙니다. 떨어지면 값을 쓰기 전에 다시 읽고, 나중에 패턴을 볼 수 있도록 둘 다 기록하세요.

for attempt in range(3):
    result = mas.read_text(region=ENERGY, psm=7)
    value = first_int(result.text)
    if value is not None and result.confidence >= 0.8:
        break
    mas.log(f"Low confidence {result.confidence:.2f} for {result.text!r}", level="warning")

스크린샷 하나 재사용

모든 read_text는 넘겨주지 않는 한 새 프레임을 캡처합니다. 반복문이 여러 영역을 한 번에 읽을 때는 스크린샷 하나를 찍어 각 호출에 넘기세요. 그러면 값들이 같은 순간에 속합니다.

shot = mas.take_screenshot()
energy = mas.read_text(region=ENERGY, screenshot=shot)
gold = mas.read_text(region=GOLD, screenshot=shot)

파이썬으로 안드로이드 에뮬레이터의 텍스트 읽기: 완전한 예제

스크립트는 에너지 카운터가 한계 아래로 떨어지거나 시간 예산이 지날 때까지 버튼을 탭합니다. 영역, 이미지 ID, 한계를 본인 것으로 바꾸세요.

import random
import re
import sys
import time

import mas
from mas import ColorConversion, Region

images = mas.images({"attack_button": 101})

ENERGY = Region(x1=380, y1=20, x2=520, y2=60)
MIN_ENERGY = 10
TIME_BUDGET_S = 15 * 60


def read_energy() -> int | None:
    for _ in range(3):
        result = mas.read_text(
            region=ENERGY,
            psm=7,
            color_conversion=ColorConversion.BLACK_WHITE,
            timeout_ms=5000,
        )
        m = re.search(r"\d+", result.text.replace(",", "").replace("O", "0"))
        if m and result.confidence >= 0.7:
            return int(m.group())
        mas.log(f"Unclear energy {result.text!r} ({result.confidence:.2f})", level="warning")
        time.sleep(1)
    return None


def main():
    started = time.monotonic()
    unreadable = 0

    while time.monotonic() - started < TIME_BUDGET_S:
        energy = read_energy()
        if energy is None:
            unreadable += 1
            if unreadable >= 5:
                mas.log("Energy unreadable five times, stopping", level="error")
                sys.exit(2)
            continue
        unreadable = 0
        if energy < MIN_ENERGY:
            mas.log(f"Energy {energy} is below {MIN_ENERGY}, done")
            break

        button = mas.find_object_retry(images.attack_button, total_tries=3, time_sleep=2.0)
        if button is None:
            mas.log("Attack button not found", level="warning")
            continue
        mas.click(button.x, button.y, delay_ms=1000)
        time.sleep(random.uniform(0.8, 2.0))

    mas.log("Finished")


if __name__ == "__main__":
    main()

탭마다 먼저 읽으면 매크로가 정직해집니다. 볼 수 없는 에너지는 쓰지 않습니다. unreadable 카운터는 깨진 영역을 실패한 실행으로 바꾸며, macro.failed 웹훅이 이를 보고할 수 있습니다. 반복과 예약 실행을 참고하세요. 직접 쓰기보다 작업을 설명하고 싶다면 MAS Agent가 영역을 측정하고 이 코드를 대신 써 줍니다.

문제 해결

OCR이 빈 문자열을 반환함

영역이 텍스트를 놓치거나, 모드가 틀렸거나, 텍스트가 어두운 배경 위의 밝은 글자입니다. Asset Lab에서 영역을 확인하고, 숫자 하나면 psm을 8로, 블록이면 6으로 바꾸고, color_conversion=ColorConversion.BLACK_WHITE를 추가하세요. 아주 작은 텍스트도 아무것도 없는 것으로 읽힙니다. 숫자가 몇 픽셀 높이밖에 안 되면 에뮬레이터 디스플레이 설정에서 해상도를 올리고 모든 영역을 다시 캡처하세요.

숫자를 잘못 읽음

0이 글자 O로, 1이 l로, 8이 B로 읽히거나 쉼표가 사라집니다. 먼저 아이콘이 숫자에 닿지 않도록 영역을 조이세요. 그다음 BLACK_WHITE를 시도하고, 획이 끊어지면 대신 BGR_TO_GRAY를 쓰세요. 마지막으로 코드에서 정규화하세요: 숫자만 있는 영역에서 O를 0으로, l을 1로 바꾸고, 쉼표를 제거하고, 읽기 사이에 크게 튀는 값은 거부하세요.

OCR이 느림

psm=11과 eng_best로 화면 전체를 읽는 것이 느린 경우입니다. 화면이 아니라 영역을 읽고, psm=7 또는 8을 쓰고, screenshot 하나를 여러 호출에 넘기세요. 깨끗한 텍스트에는 model="eng_fast"가 도움이 됩니다. 그래도 읽기가 몇 초 걸리면 영역이 아마 너무 클 것입니다. 카운터에는 기껏해야 너비 몇백 픽셀의 상자면 됩니다.

100% 안전한 자동화 도구는 없으므로, 책임감을 가지고 본인의 판단에 따라 자동화하세요.