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.
- 01Captura
- 02Percepción
- 03Decisión
- 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.
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 imagegrab_clientL354–363macOS 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
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–106Es 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)
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–110El 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.
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–225Convierte 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.
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–199Usa 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)
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–86matching_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.
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–171Las 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
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–308Se 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.
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–60Decision 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.
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_monstersHorizontalHuntRunner._monsters_for_frameL155–166Suprimir 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.