HiroMacro 스크립트 공식 매뉴얼

기초 문법부터 조건 분기, 색상 감지, 하드웨어 연동까지 모든 기능을 상세히 안내합니다.

1. 시작하기 및 UI 안내

HiroMacro는 누구나 손쉽게 강력한 터치와 제스처 자동화를 구축할 수 있는 전문 오토터치 도구입니다. 앱은 다음과 같은 5가지 주요 화면으로 구성되어 있습니다:

  • 홈 대시보드: 매크로 서비스 시작/정지, 현재 실행 상태, 활성화된 키맵/플로팅 버튼 현황을 한눈에 확인합니다.
  • 스크립트 탐색기: 내장 스크립트 및 기기 저장소의 매크로 파일(.txt)을 탐색, 생성, 수정, 삭제합니다.
  • 키맵핑 설정: 스마트폰 볼륨 버튼, 블루투스 리모컨, 게임패드 키에 단일/더블/롱클릭 매크로를 지정합니다.
  • 플로팅 버튼: 화면 어디에나 띄워둘 수 있는 둥근 오버레이 버튼의 위치, 색상, 동작을 관리합니다.
  • 환경설정: 8개 국어 언어 설정, 화면 켜짐 유지(WakeLock), 스포이드 디버그 좌표 등을 설정합니다.
접근성 권한 안내: HiroMacro를 처음 실행할 때 시스템 설정의 접근성(Accessibility) 메뉴에서 HiroMacro 서비스를 활성화해야 터치 이벤트와 하드웨어 키 입력을 처리할 수 있습니다.

2. 스크립트 기본 문법

HiroMacro는 직관적인 줄(Line) 단위 인터프리터 언어인 HScript를 사용합니다. 규칙은 매우 간단합니다:

  • 한 줄에 하나의 명령: 각 줄마다 명령어가 하나씩 순차적으로 실행됩니다.
  • 공백(Space) 구분: 명령어와 파라미터는 하나 이상의 공백으로 구분합니다.
  • 주석(Comment): 줄의 시작에 //를 적으면 해당 줄은 주석으로 처리되어 실행되지 않습니다.
  • 대소문자: 명령어는 기본적으로 대소문자를 구분하지 않지만, 소문자 작성을 권장합니다.
HScript 
// 화면 (500, 1000) 좌표 터치
touchPress 0 500 1000

// 1초간 대기 (1000ms = 1초)
sleep 1000

3. 터치 및 제스처 명령

화면 상의 좌표에 탭, 드래그, 스와이프, 멀티터치 제스처를 전달합니다.

3.1. touchPress finger x y

터치 다운과 터치 업을 한 번에 실행하는 가장 편리한 탭 명령입니다.

파라미터설명기본값 / 범위
finger터치 손가락 인덱스 (멀티터치 시 0, 1, 2...)0
x클릭할 화면의 X 좌표 (픽셀)0 ~ 화면 가로폭
y클릭할 화면의 Y 좌표 (픽셀)0 ~ 화면 세로폭
HScript 
// 0번 손가락으로 (300, 500) 위치 1회 탭
touchPress 0 300 500

3.2. touchDown finger x y

화면의 지정된 좌표를 손가락으로 누른 상태를 유지합니다. 드래그나 길게 누르기(롱탭)의 시작점으로 사용됩니다.

3.3. touchMove finger x y

touchDown 이후 누른 상태에서 지정된 좌표로 손가락을 이동합니다.

3.4. touchUp finger

누르고 있던 손가락을 화면에서 뗍니다. touchDown과 항상 짝을 이루어야 합니다.

드래그 & 스와이프 예제 
// (500, 1200)에서 터치 시작
touchDown 0 500 1200
sleep 50

// 위로 드래그 (500, 400)
touchMove 0 500 800
sleep 50
touchMove 0 500 400
sleep 50

// 손 떼기 (스와이프 완료)
touchUp 0

4. 하드웨어 및 키보드 명령

4.1. keyPress / keyDown / keyUp code

안드로이드 하드웨어 키 또는 소프트웨어 키보드 이벤트를 발생시킵니다.

HScript 
// 뒤로가기 키(KEYCODE_BACK = 4) 1회 누름
keyPress 4

// 엔터 키(KEYCODE_ENTER = 66) 1회 누름
keyPress 66

4.2. 주요 안드로이드 키코드(KeyCode) 표

키 코드 번호상수 이름설명
3KEYCODE_HOME홈 버튼
4KEYCODE_BACK뒤로가기 버튼
24KEYCODE_VOLUME_UP볼륨 증가
25KEYCODE_VOLUME_DOWN볼륨 감소
66KEYCODE_ENTER엔터 / 확인
67KEYCODE_DEL백스페이스 (한 글자 지우기)
111KEYCODE_ESCAPEESC 키

5. 시간, 변수 및 연산

5.1. sleep ms

지정된 밀리초(ms) 동안 스크립트 실행을 잠시 멈춥니다. 1000은 1초입니다.

HScript
// 0.5초 대기
sleep 500

// 2초 대기
sleep 2000

5.2. var / set 변수 지정

변수는 숫자 또는 문자열을 저장하며, 접두사 #(숫자 변수) 또는 $(문자열 변수)를 사용합니다.

HScript
// 숫자 변수 정의 및 초기화
var #count 0
var #targetX 540

// 변수 값 변경
set #count 10

5.3. calc 사칙연산

변수를 이용한 덧셈, 뺄셈, 곱셈, 나눗셈 연산을 수행합니다.

HScript
// 간편 계산식
calc #count = #count + 1
calc #delay = #baseDelay * 2

5.4. rand #var min max

min부터 max 사이의 임의의 정수(랜덤값)를 생성하여 변수에 저장합니다. 기계적인 매크로 감지를 방지할 때 유용합니다.

HScript
// 500ms ~ 1200ms 사이의 랜덤 대기
rand #randomSleep 500 1200
sleep #randomSleep

6. 흐름 제어 및 조건문

6.1. if / elseif / else / endif

변수의 값이나 화면 색상 조건에 따라 분기 처리를 수행합니다.

HScript
if #count > 10
    toast "10회 완료!"
    goto :finish
elseif #count == 5
    toast "50% 진행됨"
else
    sleep 100
endif

6.2. goto :label 및 라벨 정의

스크립트의 특정 위치로 점프하여 무한 반복 또는 특정 구간 건너뛰기를 구현합니다.

HScript
:loop_start
touchPress 0 500 1000
sleep 1000

// 다시 :loop_start로 이동하여 무한 반복
goto :loop_start

:finish
exit

7. 색상 감지 (Pixel/RGB)

7.1. getColor #var x y

화면의 (x, y) 좌표에 있는 픽셀 색상값(정수형 컬러)을 읽어와 변수에 저장합니다.

HScript
// (300, 450) 위치의 색상 가져오기
getColor #screenColor 300 450

// 색상 조건문: 해당 좌표의 색상이 목표 색상(예: #FF0000 = 16711680)과 일치하면 터치
if #screenColor == 16711680
    touchPress 0 300 450
endif

7.2. 화면 스포이드 도구 활용법

설정 메뉴에서 색값 좌표 디버그 또는 스포이드 오버레이를 활성화하면, 실시간으로 화면의 원하는 픽셀을 짚어 좌표(X, Y)와 RGB 10진수/16진수 색상 코드를 클립보드로 복사할 수 있습니다.

8. 앱 및 시스템 유틸리티

8.1. runApp / waitApp / killApp packageName

외부 앱을 패키지명으로 직접 실행하거나, 앱이 화면에 뜰 때까지 대기하고 강제 종료합니다.

HScript
// 특정 앱 실행
runApp com.example.game

// 앱이 실행되어 화면에 나타날 때까지 대기
waitApp com.example.game

8.2. screenLock / toast / log / exit

  • screenLock: 화면 터치 입력을 소프트웨어적으로 잠그거나 해제합니다.
  • toast "메시지": 화면 하단에 안드로이드 토스트 팝업을 표시합니다.
  • log "메시지": HiroMacro 내부 로그 콘솔에 기록을 남깁니다.
  • exit: 매크로 실행을 즉시 정상 종료합니다.

9. 키맵 & 플로팅 버튼 제어

HiroMacro에서는 스크립트를 작성하지 않아도 편리하게 제어할 수 있는 다양한 기능이 탑재되어 있습니다:

  • 플로팅 오버레이 버튼: 앱 내 [플로팅 버튼] 메뉴에서 버튼을 추가하면 게임 화면 위에 둥근 캡슐/원형 버튼이 표시됩니다. 원하는 스크립트를 연결하여 원클릭으로 토글할 수 있습니다.
  • 하드웨어 키맵 삼중 제어: 볼륨 다운 키에 1회 누름(재생/정지), 더블 클릭(특정 던전 매크로), 길게 누름(긴급 정지)을 자유롭게 조합할 수 있습니다.

10. 실전 예제 모음

예제 1: 단순 초고속 연타 매크로

초고속_화면연타.txt
// 500, 1000 좌표를 0.1초 간격으로 무한 연타
:repeat_tap
touchPress 0 500 1000
sleep 100
goto :repeat_tap

예제 2: 출석 체크 및 보상 버튼 탐색

출석체크_자동수령.txt
// 보상 수령 버튼 위치 (600, 1400)의 색상 확인
:check_reward
getColor #col 600 1400

// 황금색 버튼(#FFD700)이 활성화되었는지 확인
if #col == 16766720
    toast "출석 보상 버튼 발견! 수령합니다."
    touchPress 0 600 1400
    sleep 2000
    exit
else
    sleep 500
    goto :check_reward
endif

예제 3: 화면 무한 자동 스크롤

화면_자동스크롤.txt
:scroll_loop
// 화면 아래쪽(1400)에서 위쪽(600)으로 부드럽게 스와이프
touchDown 0 540 1400
sleep 50
touchMove 0 540 1000
sleep 50
touchMove 0 540 600
sleep 50
touchUp 0

// 3초간 콘텐츠 읽기 대기
sleep 3000
goto :scroll_loop