okya for MapleStory
Español
English한국어日本語简体中文繁體中文EspañolPortuguêsไทยTiếng Việt
Contenido del artículo⌄
okya for MapleStory›Cómo funciona

Notas de ingeniería · Python / OpenCV

Cómo funciona

Descubre cómo Classic MapleStory Bot convierte imágenes de pantalla en decisiones mediante 10 fragmentos esenciales y diagramas de visión.

Píxeles → observaciones → decisiones → entrada

El cliente lee imágenes visibles. La percepción estima posiciones y estado, el planificador elige una acción y el entorno de ejecución coordina las teclas locales. Detectar un monstruo no pulsa una tecla; enviar una tecla tampoco confirma que el juego la haya aceptado.

  1. 01Captura
  2. 02Percepción
  3. 03Decisión
  4. 04Entrada local

01Capturar el área del juego#

La rama Windows de grab_client localiza el área cliente, captura el rectángulo con ImageGrab y lo convierte a RGB. Las dimensiones inválidas generan un error en vez de alimentar la visión con una imagen vacía.

Python · vitals.py
window = find_client_origin(title)
if window is None:
    raise RuntimeError(active_translate("error_game_window_not_found", title=title))
left, top, width, height = window
if width <= 1 or height <= 1:
    raise RuntimeError(active_translate("error_game_capture_unavailable"))
image = ImageGrab.grab((left, top, left + width, top + height)).convert("RGB")
if image.width <= 1 or image.height <= 1:
    raise RuntimeError(active_translate("error_empty_game_capture_retry"))
return image
grab_clientL354–363

macOS utiliza captura nativa y recorte propios. OpenCV trabaja después con matrices BGR: al pasar desde Pillow hay que respetar el orden de los canales.

02Limitar la búsqueda con una ROI#

El detector empieza en una zona acotada de la esquina superior izquierda. Convierte a gris, aplica Canny y busca contornos; los centros de marcadores limitan los rectángulos candidatos.

Buscar solo en la región pertinente

Imagen del juego

Recorte del minimapa

La captura incluida y su minimapa ilustran una región de interés (ROI). El recorte es un ejemplo, no una medición del detector. Reducir la búsqueda elimina candidatos irrelevantes.
Python · map_position.py
if frame_bgr.size == 0 or frame_bgr.ndim != 3:
    return previous or generic_minimap_definition()
search = frame_bgr[:min(frame_bgr.shape[0], 420), :min(frame_bgr.shape[1], 430)]
edges = cv2.Canny(cv2.cvtColor(search, cv2.COLOR_BGR2GRAY), 45, 135)
contours, _ = cv2.findContours(edges, cv2.RETR_LIST, cv2.CHAIN_APPROX_SIMPLE)

marker_centers = [
    (x + width / 2.0, y + height / 2.0)
    for x, y, width, height, _ in _marker_components(search, player_pixels)
]
if not marker_centers:
    return previous or generic_minimap_definition()
detect_minimap_definitionL95–106

Es el inicio, no toda la clasificación de rectángulos. Una imagen inválida o sin marcadores conserva la definición anterior o una provisional, que no equivale a una detección recién validada.

03Localizar al personaje por correlación#

match_player_feature convierte imagen y plantilla pequeña a gris y aplica TM_CCORR_NORMED. La máscara opcional excluye píxeles transparentes de la comparación.

Comparar la plantilla en cada posición

Plantilla · T

Mapa de puntuación · S(x, y)

Esquema: cada posición recibe una similitud y la celda brillante representa un máximo local. No son mediciones reales de esta captura. Una correlación normalizada no es una probabilidad.
Python · vision.py
def match_player_feature(image_bgr: np.ndarray, template_bgr: np.ndarray,
                         mask: np.ndarray | None) -> np.ndarray:
    """Match normal player feature templates with tolerant grayscale correlation."""
    screen_gray = cv2.cvtColor(image_bgr, cv2.COLOR_BGR2GRAY)
    template_gray = cv2.cvtColor(template_bgr, cv2.COLOR_BGR2GRAY)
    return cv2.matchTemplate(
        screen_gray,
        template_gray,
        cv2.TM_CCORR_NORMED,
        mask=mask,
    )
match_player_featureL100–110

El código llamante elimina valores no finitos y aplica un umbral al máximo. El 0.995 de esta versión es una configuración, no un porcentaje de aciertos. Captura rasgos estables en ambas orientaciones.

04Convertir puntuaciones en objetivos#

Esta rama de detect_template procesa plantillas opacas. Rechaza las mayores que la imagen de búsqueda y recoge posiciones cuya puntuación alcanza el umbral configurado.

Python · vision.py
if image_bgr.shape[0] < template.shape[0] or image_bgr.shape[1] < template.shape[1]:
    return []
scores = cv2.matchTemplate(image_bgr, template, cv2.TM_CCOEFF_NORMED)
ys, xs = np.where(scores >= threshold)
targets = [Target(int(x + template.shape[1] / 2),
                  int(y) + top_to_feet if top_to_feet is not None else feature_center_to_feet(int(y), template.shape[0]),
                  float(scores[y, x]))
           for y, x in zip(ys, xs)]
return _non_maximum(targets, 15)
detect_templateL217–225

Convierte la esquina superior izquierda en centro horizontal y pies calibrados, y elimina duplicados. Las plantillas transparentes usan otra rama con máscara y un método de correlación distinto.

05Combinar detecciones repetidas#

_non_maximum ordena por confianza y conserva candidatos suficientemente alejados de todos los ya aceptados. Así reduce coincidencias repetidas de posiciones vecinas o poses del mismo monstruo.

Python · vision.py
def _non_maximum(points: list[Target], min_distance: int) -> list[Target]:
    kept: list[Target] = []
    for point in sorted(points, key=lambda item: item.confidence, reverse=True):
        if all(abs(point.center_x - other.center_x) > min_distance or abs(point.feet_y - other.feet_y) > min_distance for other in kept):
            kept.append(point)
    return kept
_non_maximumL194–199

Usa distancia x/y, no IoU de cajas. Una distancia excesiva fusiona enemigos distintos; una demasiado pequeña deja duplicados y altera el recuento.

06Separar el marcador con HSV#

Primero se intenta una coincidencia BGR exacta. Sin componentes válidos, esta alternativa usa HSV con el rango del perfil del servidor y mayor tolerancia de saturación.

Separar por color y comprobar la forma

RGB → HSV → Máscara binaria

Componente → Posición local (x, y)

Esquema: un rango de color crea una máscara y agrupa píxeles vecinos en componentes. También se comprueban ancho, alto y área; no todo píxel amarillo es el jugador.
Python · map_position.py
hsv = cv2.cvtColor(image_bgr, cv2.COLOR_BGR2HSV)
hue_low, saturation_low, value_low = player_pixels.activity_hsv_lower
lower = np.asarray(
    (hue_low, max(0, saturation_low - 40), value_low), dtype=np.uint8,
)
upper = np.asarray(player_pixels.activity_hsv_upper, dtype=np.uint8)
tolerant_mask = cv2.inRange(hsv, lower, upper)
return matching_components(tolerant_mask, exact_area=False)
_marker_componentsL79–86

matching_components filtra ancho, alto y área. Tolera diferencias de gestión de color sin aceptar cualquier forma amarilla; los límites pertenecen al perfil de cada servidor.

07Obtener coordenadas locales#

Se recorta según los límites del minimapa y se añade el desplazamiento de pies del servidor. Solo se devuelve una posición con exactamente un candidato.

Python · map_position.py
right = min(frame_bgr.shape[1], minimap.end_x + 1)
bottom = min(frame_bgr.shape[0], minimap.end_y + 1)
if minimap.start_x >= right or minimap.start_y >= bottom:
    return None
image = frame_bgr[minimap.start_y:bottom, minimap.start_x:right]
candidates: list[tuple[int, int]] = []
for x, y, _, _, _ in _marker_components(image, player_pixels):
    # Each server profile maps the matched component's origin to the
    # marker's standing point with its own vertical foot offset.
    candidates.append((x, y + player_pixels.foot_offset))
if len(candidates) != 1:
    return None
x, foot_y = candidates[0]
source_width = max(1, right - minimap.start_x)
source_height = max(1, bottom - minimap.start_y)
source_x = min(source_width - 1, x)
source_y = min(source_height - 1, foot_y)
return float(source_x), float(source_y)
detect_minimap_playerL154–171

Las coordenadas son locales al recorte, no al escritorio. Los límites se ajustan a la imagen; cero o varios candidatos devuelven None para no inventar una posición ambigua.

08Medir HP/MP por votos de color#

bar es la barra RGB recortada, pixels su acceso a píxeles y valid_columns empieza vacío. Predominio rojo vota por HP y azul por MP; cada columna exige suficientes filas coincidentes.

Medir longitud, no leer números

100 × (x_last + 1) / width

Barra de estado → Última columna válida

Esquema: suficientes píxeles coincidentes validan una columna. La última columna válida estima el llenado. Se mide la región configurada, no el texto numérico de HP/MP.
Python · vitals.py
valid_columns: list[int] = []
for column in range(bar.width):
    matches = 0
    for row in range(bar.height):
        red, green, blue = pixels[column, row]
        if kind == "hp":
            colored = red >= 130 and red >= green * 1.5 and red >= blue * 1.5
        else:
            colored = blue >= 110 and blue >= red * 1.25 and blue >= green * 1.15
        matches += int(colored)
    if matches >= max(2, int(bar.height * 0.2)):
        valid_columns.append(column)
if not valid_columns:
    return 0.0
percent = 100 * (valid_columns[-1] + 1) / bar.width
return 100.0 if percent >= 95 else round(percent, 1)
_bar_percent_from_imageL293–308

Se usa la última columna válida, no la proporción de píxeles coloreados. Sin columnas devuelve cero; esta versión redondea desde 95 a 100. Comprueba recorte y ruido antes de activar recuperación.

09Separar visión y planificación#

HorizontalHuntPlanner recibe Observation, no capturas. Filtra por tolerancia de altura de pies y elige el objetivo horizontal más próximo: atacar, acercarse o patrullar si no hay ninguno.

Python · horizontal_hunt.py
def decide(self, observation: Observation) -> Decision:
    targets = self.same_line_targets(observation)
    if targets:
        target = min(targets, key=lambda m: abs(m.center_x - observation.player_x))
        delta = target.center_x - observation.player_x
        if abs(delta) <= self.config.target_distance:
            return Decision(HuntState.ATTACK, "attack_burst", "right" if delta >= 0 else "left", target)
        return Decision(HuntState.APPROACH, "move_pulse", "right" if delta > 0 else "left", target)
    return Decision(HuntState.PATROL, "move_pulse")
HorizontalHuntPlanner.decideL52–60

Decision expresa intención y no envía teclas. Posiciones artificiales permiten probar distancias y direcciones sin abrir el juego.

10Espaciar las comparaciones costosas#

El entorno separa la frecuencia de reconocimiento de monstruos del seguimiento más rápido de rutas. time.monotonic controla cuándo actualizar; entre actualizaciones se reutiliza el último resultado.

Python · hunt_runtime.py
def _monsters_for_frame(self, frame: np.ndarray) -> tuple:
    """Run expensive monster matching at a lower rate than route tracking."""
    if self._monster_detection_suppressed():
        self.last_detected_monsters = ()
        self.last_monster_detection_at = 0.0
        return ()
    now = time.monotonic()
    if (self.last_monster_detection_at <= 0.0
            or now - self.last_monster_detection_at >= self.MONSTER_DETECTION_INTERVAL_SECONDS):
        self.last_detected_monsters = tuple(self._detect_monsters(frame))
        self.last_monster_detection_at = time.monotonic()
    return self.last_detected_monsters
HorizontalHuntRunner._monsters_for_frameL155–166

Suprimir detección vacía la caché para no conservar objetivos antiguos. Un dato almacenado no demuestra visibilidad actual. La parada y liberación de teclas siguen siendo responsabilidad del entorno.

De la detección a un sistema fiable#

Prueba la visión con capturas fijas, la planificación con Observation artificiales y el modo de diagnóstico antes de enviar entradas. Una puntuación alta no demuestra que la detección sea correcta. Gestiona datos antiguos, oclusiones y marcadores ambiguos. El entorno de ejecución libera las teclas al detenerse o salir del bucle. Este artículo no garantiza compatibilidad ni autoriza automatizar un juego.