콜백 메시지 프로토콜

약 1118 단어약 4 분

정보

콜백 메시지는 버전 업데이트를 통해 빠르게 변경되고 있으며 이 문서는 오래된 것일 수 있습니다. 최신 콘텐츠는 C# 통합 소스 코드를 참조하세요.

콜백 함수 프로토타입

typedef void(ASST_CALL* AsstApiCallback)(AsstMsgId msg, const char* details_json, void* custom_arg);

여기서 AsstMsgId는 int32_t의 별칭입니다.

파라미터 개요

AsstMsgId msg
메시지 유형

enum class AsstMsg
{
    /* Global Info */
    InternalError     = 0,           // 내부 오류
    InitFailed        = 1,           // 초기화 실패
    ConnectionInfo    = 2,           // 연결 정보
    AllTasksCompleted = 3,           // 모든 작업 완료
    AsyncCallInfo     = 4,           // 비동기 호출 정보
    Destroyed         = 5,           // 인스턴스 소멸됨

    /* TaskChain Info */
    TaskChainError     = 10000,      // 작업 체인 실행/인식 오류
    TaskChainStart     = 10001,      // 작업 체인 시작
    TaskChainCompleted = 10002,      // 작업 체인 완료
    TaskChainExtraInfo = 10003,      // 작업 체인 추가 정보
    TaskChainStopped   = 10004,      // 작업 체인 수동 중지

    /* SubTask Info */
    SubTaskError      = 20000,       // 서브 작업 실행/인식 오류
    SubTaskStart      = 20001,       // 서브 작업 시작
    SubTaskCompleted  = 20002,       // 서브 작업 완료
    SubTaskExtraInfo  = 20003,       // 서브 작업 추가 정보
    SubTaskStopped    = 20004,       // 서브 작업 수동 중지

    /* Web Request */
    ReportRequest     = 30000,       // 보고 요청
};

const char* details
메시지 세부사항, JSON 문자열, 필드 설명 참조
void* custom_arg
호출자의 사용자 정의 인수로, AsstCreateEx 인터페이스의 custom_arg 인수가 그대로 전달됩니다. C 계열 언어에서는 이를 통해 this 포인터를 전달할 수 있습니다.

필드 설명

InternalError

details 필드는 비어 있습니다.

InitFailed

whatRequiredstring

오류 유형

whyRequiredstring

오류 원인

detailsRequiredobject

오류 상세

ConnectionInfo

whatRequiredstring

정보 유형

whyRequiredstring

정보 원인

uuidstring

장치 고유 코드(UUID) (연결 실패 시 비어 있음)

detailsRequiredobject

연결 상세 정보. 구조는 다음과 같습니다:

adb (string, required): AsstConnect 인터페이스의 adb_path 파라미터.
address (string, required): AsstConnect 인터페이스의 address 파라미터.
config (string, required): AsstConnect 인터페이스의 config 파라미터.

자주 사용되는 `What` 필드

ConnectFailed
연결 실패
Connected
연결됨, 이때 uuid 필드는 비어 있음 (다음 단계에서 획득)
UuidGot
장치 고유 코드(UUID) 획득
UnsupportedResolution
지원하지 않는 해상도
ResolutionError
해상도 획득 오류
Reconnecting
연결 끊김 (adb / 에뮬레이터 충돌), 재연결 중
Reconnected
연결 끊김 (adb / 에뮬레이터 충돌), 재연결 성공
Disconnect
연결 끊김 (adb / 에뮬레이터 충돌), 재시도 실패
ScreencapFailed
스크린샷 실패 (adb / 에뮬레이터 충돌), 재시도 실패
TouchModeNotAvailable
지원하지 않는 터치 모드
MuMuExtrasInputStatus
MuMu 터치 강화의 실제 적용 상태, details 구조:
- available (boolean, required): 적용되었는지 여부.
- deferred (boolean, required): 아직 판정되지 않았는지 여부 (연결 시 게임이 렌더링되지 않아 렌더링 시작 후 자동으로 다시 판정됨).
ResolutionGot
해상도를 획득함
ResolutionChanged
실행 중 해상도가 변경되어 연결이 무효화되고 현재 작업이 중단됨, details 구조:
- width (number, required): 현재 너비.
- height (number, required): 현재 높이.
FastestWayToScreencap
가장 빠른 스크린샷 방식을 찾음, details 구조:
- method (string, required): 가장 빠른 스크린샷 방식.
- cost (number, required): 소요 시간 (밀리초).
- alternatives (array<object>, required): 모든 후보 방식과 소요 시간.
ScreencapCost
스크린샷 소요 시간 통계 (10회마다 보고), details 구조:
- min (number, required): 최소 소요 시간 (밀리초).
- max (number, required): 최대 소요 시간 (밀리초).
- avg (number, required): 평균 소요 시간 (밀리초).
- fault_times (number): 실패 횟수 (실패가 있는 경우에만 존재).
EmulatorFPS
에뮬레이터 주사율 (1분마다 검사), details 구조:
- fps (number, required): 에뮬레이터/시스템 주사율 (FPS).
- refresh_period_ns (number, required): 프레임 주기 (나노초).

AsyncCallInfo

uuidRequiredstring

장치 고유 코드

whatRequiredstring

콜백 유형, 예: Connect | AttachWindow | Click | Screencap 등

async_call_idRequirednumber

비동기 요청 id, 즉 AsstAsyncXXX 호출 시 반환값

detailsRequiredobject

비동기 호출 상세. 구조는 다음과 같습니다:

ret (boolean, required): 실제 호출의 반환값.
cost (number, required): 소요 시간, 단위 밀리초.
error (string): 처리되지 않은 예외의 유형 (처리되지 않은 예외로 호출이 실패한 경우에만 존재).

AllTasksCompleted

taskchainRequiredstring

마지막 작업 체인

uuidRequiredstring

장치 고유 코드

finished_tasksRequiredarray<number>

이미 실행된 작업 id 목록

자주 사용되는 `taskchain` 필드

StartUp
시작 (깨우기)
CloseDown
게임 종료
Fight
이성 소모 작전
Mall
크레딧 상점 및 쇼핑
Recruit
자동 공개모집
Infrast
기반시설 교대
Award
일일 보상 수령
Roguelike
통합 전략 반복
Copilot
자동지휘
SSSCopilot
보안 파견 자동지휘
ParadoxCopilot
패러독스 시뮬레이션 자동지휘
Depot
창고 인식
OperBox
오퍼레이터 인식
Reclamation
생존 연산
Custom
사용자 정의 작업
SingleStep
단일 단계 작업
VideoRecognition
비디오 인식 작업
Debug
디버그

TaskChain 관련 메시지

TaskChainError / TaskChainStart / TaskChainCompleted / TaskChainExtraInfo / TaskChainStopped는 다음 필드를 공유합니다:

taskchainRequiredstring

현재 작업 체인

taskidRequirednumber

현재 작업 TaskId

uuidRequiredstring

장치 고유 코드

작업 체인이 처리되지 않은 예외로 중단된 경우, TaskChainError는 추가로 details 필드를 포함합니다:

error (string, required): 예외 유형, 값은 OpenCVException | OutOfMemory | GpuDeviceRemoved | UnhandledException | UnknownException 중 하나. 이 중 OutOfMemory와 GpuDeviceRemoved(GPU 추론 장치 손실, 그래픽 드라이버 업데이트 또는 GPU 리셋 등)가 발생하면 남은 작업이 모두 지워지며, 계속하려면 프로그램을 재시작해야 합니다.

TaskChainExtraInfo

기본적으로 위의 공통 필드만 포함됩니다. 통합 전략(쉐이 테마)에서 경로 계획 결과 피할 수 없는 전투가 너무 많다고 판단되어 능동적으로 재시작하는 경우, 메시지에 추가로 다음이 포함됩니다:

what (string, required): RoutingRestart로 고정.
why (string, required): TooManyBattlesAhead로 고정.
node_cost (number, required): 계획된 다음 노드의 비용.

SubTask 관련 메시지

subtaskRequiredstring

서브 작업명

classRequiredstring

서브 작업 심볼명

taskchainRequiredstring

현재 작업 체인

taskidRequirednumber

현재 작업 TaskId

detailsRequiredobject

상세 정보

uuidRequiredstring

장치 고유 코드

자주 사용되는 `subtask` 필드

ProcessTask
details 필드 내용은 다음과 같습니다:
taskRequiredstring
작업명
actionRequiredstring
동작 이름, 예: ClickSelf | DoNothing | Swipe
exec_timesRequirednumber
실행된 횟수
max_timesRequirednumber
최대 실행 횟수
algorithmRequiredstring
인식 알고리즘 이름, 예: MatchTemplate | OcrDetect | FeatureMatch | JustReturn
resultRequiredobject
이번 인식 결과, 알고리즘마다 구조가 다름. 인식 결과가 없을 경우 빈 객체.
또한, 작업 실행 횟수가 상한에 도달하면 먼저 what가 ExceededLimit인 SubTaskExtraInfo 메시지가 전송되며, details에는 task(작업명), exec_times(실행된 횟수), max_times(최대 실행 횟수)가 포함됩니다.
인식할 작업 목록에 정의되지 않은 작업명이 존재하면(작업 리소스와 프로그램 버전 불일치 등), 인식 시작 전에 SubTaskError로 전달되며 작업 체인 전체가 중지됩니다. what는 UnknownTask, details에는 tasks(문자열 배열, 정의되지 않은 작업명 목록)이 포함됩니다.
ReportToPenguinStats / ReportToYituliu
전투 드롭을 펭귄 물류 통계 / 일도류 빅데이터에 보고 (보고 실패 시 SubTaskError로 전달됨).
StartGameTask
클라이언트 실행 실패 (설정 파일과 전달된 client_type 불일치).
Todo 기타

자주 사용되는 `task` 필드

StartButton2
작전 시작
MedicineConfirm
이성 회복제 사용 확인
StoneConfirm
오리지늄 사용 확인
RecruitRefreshConfirm
공개모집 태그 갱신 확인
RecruitConfirm
공개모집 채용 확인
RecruitNowConfirm
공개모집 즉시 완료 허가증 사용 확인
InfrastDormDoubleConfirmButton
기반시설의 2차 확인 버튼, 배치할 오퍼레이터가 이미 다른 시설에 근무 중인 경우에만 나타남(MAA가 자동으로 클릭), 사용자에게 알림 필요
StartExplore
통합 전략 탐험 시작
StageTraderInvestConfirm
통합 전략 각뿔 투자 확인
StageTraderInvestSystemFull
통합 전략 투자 한도 도달
ExitThenAbandon
통합 전략 이번 탐험 포기
MissionCompletedFlag
통합 전략 전투 완료
MissionFailedFlag
통합 전략 전투 실패
StageTraderEnter
통합 전략 노드: 교활한 상인
StageSafeHouseEnter
통합 전략 노드: 안전가옥
StageEncounterEnter
통합 전략 노드: 우연한 만남/고성의 선물
StageCombatOpsEnter
통합 전략 노드: 일반 작전
StageEmergencyOps
통합 전략 노드: 긴급 작전
StageDreadfulFoe
통합 전략 노드: 험난한 길
Todo 기타

SubTaskExtraInfo

taskchainRequiredstring

현재 작업 체인

classRequiredstring

서브 작업 유형

whatRequiredstring

정보 유형

detailsRequiredobject

정보 상세

uuidRequiredstring

장치 고유 코드

자주 사용되는 `what` 및 `details` 필드

StageDrops
노드 재료 드롭 정보. details 필드 구조는 다음과 같습니다:
- drops (array, required): 이번에 식별된 드롭 재료, 배열의 각 항목:
  - itemId (string, required): 재료 ID
  - quantity (number, required): 드롭 수량
  - itemName (string, required): 재료 명칭
- stage (object, required): 노드 정보:
  - stageCode (string, required): 노드 코드
  - stageId (string, required): 노드 ID
- stars (number, required): 작전 종료 등급(별)
- stats (array, required): 이번 실행 기간 동안의 총 재료 드롭, 배열의 각 항목:
  - itemId (string, required): 재료 ID
  - itemName (string, required): 재료 명칭
  - quantity (number, required): 총 수량
  - addQuantity (number, required): 이번에 추가된 드롭 수량
- cur_times (number, optional): 결산 화면에서 인식된 연속 전투 횟수 (인식된 경우에만 존재).
- annihilation_weekly_process (array, optional): 섬멸 모드의 이번 주 획득 진행도, 형식은 [완료 수, 상한] (섬멸 노드에서만 존재).
RecruitTagsDetected
공개모집 태그를 식별했습니다. details 필드 내용은 다음과 같습니다:
tagsRequiredarray<string>
식별된 태그 목록
RecruitSpecialTag
공개모집 특수 태그를 식별했습니다. details 필드 내용은 다음과 같습니다:
tagRequiredstring
특수 태그 명칭, 예: 고급 특별 채용
RecruitPreservedTag
공개모집에서 보류 대상으로 설정된 태그를 식별했습니다. details 필드 내용은 다음과 같습니다:
tagRequiredstring
보류를 트리거한 태그 명칭, 예: 지원 기계
RecruitResult
공개모집 식별 결과. details 필드 구조는 다음과 같습니다:
- tags (array, required): 식별된 모든 태그, 현재 5개로 고정
- level (number, required): 조합의 최고 등급(별)
- result (array, required): 구체적인 조합 결과, 배열의 각 항목:
  - tags (array, required): 조합에 참여한 태그
  - level (number, required): 이 태그 조합의 등급
  - opers (array, required): 모집 가능한 오퍼레이터, 배열의 각 항목:
    - name (string, required): 오퍼레이터 명칭
    - level (number, required): 오퍼레이터 등급
RecruitTagsRefreshed
공개모집 태그를 갱신했습니다. details 필드 내용은 다음과 같습니다:
countRequirednumber
현재 슬롯 갱신 횟수
refresh_limitRequirednumber
현재 슬롯 갱신 횟수 상한
RecruitNoPermit
모집 허가증이 없습니다. details 필드 내용은 다음과 같습니다:
continueRequiredboolean
계속 갱신할지 여부
RecruitPermitReserved 현재 모집 허가증 수가 ★3 모집에 설정한 보유 수량 이하이므로 현재 슬롯을 건너뜁니다. details 필드 내용은 다음과 같습니다:
currentRequirednumber
현재 모집 허가증 수
RecruitPermitCountRecognitionFailed ★3 모집 허가증 보유 기능이 활성화된 상태에서 허가증 수량 인식에 실패하여 현재 슬롯을 건너뜁니다. details 필드는 비어 있습니다.
RecruitTagsSelected
공개모집 태그를 선택했습니다. details 필드 내용은 다음과 같습니다:
tagsRequiredarray<string>
선택한 태그 목록
RecruitError
공개모집 식별 오류. details 필드는 비어 있으며, 현재 슬롯의 갱신 횟수가 상한에 도달하여 발생한 경우 refresh_limit(슬롯 갱신 횟수 상한)가 포함됩니다
EnterFacility
기반시설 시설에 진입했습니다. details 필드 내용은 다음과 같습니다:
facilityRequiredstring
시설명
indexRequirednumber
시설 순서(인덱스)
NotEnoughStaff
기반시설 가용 오퍼레이터 부족. details 필드 내용은 다음과 같습니다:
facilityRequiredstring
시설명
indexRequirednumber
시설 순서
ProductOfFacility
기반시설 생산물. details 필드 내용은 다음과 같습니다:
productRequiredstring
생산물명
facilityRequiredstring
시설명
indexRequirednumber
시설 순서
CustomInfrastRoomKeptUnchanged
사용자 정의 기반시설 스케줄링에서 해당 방이 그대로 유지되었을 때 알립니다. details 필드는 기본적으로 facility(시설명)와 index(시설 순서)를 포함하며, 나머지 내용은 다음과 같습니다:
reasonRequiredstring
방을 유지한 이유, 값은 다음과 같습니다:
- facility_empty: 사용자 정의 설정의 rooms 배열이 비어 있음.
- room_no_intent: 방 설정은 있지만 배치 의도가 없음.
- candidates_unavailable: 후보 오퍼레이터가 모두 사용 불가. 일반적으로 후보 명단 오류(철자 오류 또는 미보유)일 가능성이 높음.
- candidates_working: 후보 오퍼레이터가 모두 다른 시설에서 근무 중.
- candidates_low_mood: 후보 오퍼레이터의 컨디션이 모두 임계값 미만.
CustomInfrastRoomsNotConfigured
사용자 정의 설정의 rooms 배열이 해당 시설을 포괄하지 않으면 해당 시설은 그대로 유지됩니다. details 필드는 기본 facility(시설명)와 index(시설 순서)만 포함합니다.
CustomInfrastTraineeNotFound
사용자 정의 기반시설 스케줄링에서 훈련 슬롯의 후보 오퍼레이터가 일치하지 않았습니다. details 필드는 기본적으로 facility(시설명)와 index(시설 순서)를 포함하며, 나머지 내용은 다음과 같습니다:
candidatesRequiredarray<string>
훈련 슬롯의 후보 오퍼레이터 목록
CustomInfrastAssistantNotFound
사용자 정의 기반시설 스케줄링에서 지원자의 후보 오퍼레이터가 일치하지 않았습니다. details 필드는 기본적으로 facility(시설명)와 index(시설 순서)를 포함하며, 나머지 내용은 다음과 같습니다:
candidatesRequiredarray<string>
지원자의 후보 오퍼레이터 목록
working_excludedOptionalarray<string>
다른 시설에서 근무 중이어서 제외된 후보 목록, 비어 있지 않을 때만 포함
low_mood_excludedOptionalarray<string>
컨디션이 임계값 미만이어서 제외된 후보 목록, 비어 있지 않을 때만 포함
CustomInfrastRoomGroupsMatchFailed
사용자 정의 기반시설 스케줄링에서 편성 그룹 매칭에 실패했습니다. details 필드는 기본적으로 facility(시설명)와 index(시설 순서)를 포함하며, 나머지 내용은 다음과 같습니다:
reasonRequiredstring
매칭 실패 이유, 값은 다음과 같습니다:
- group_not_defined: 참조된 그룹 이름이 모두 groups에 정의되어 있지 않음.
- all_unavailable: 모든 그룹의 오퍼레이터가 사용 불가.
- recognition_failed: 오퍼레이터 목록 인식에 실패.
groupsOptionalarray<string>
정의되지 않았거나 사용 불가인 그룹 이름 목록, group_not_defined와 all_unavailable일 때만 포함
CopilotPrecheckFile
다중 작업 모드에서 ｢Yituliu 데이터로 편성 지원｣이 활성화된 경우, 각 작업의 사전 매칭 전에 알립니다. details 필드 내용은 다음과 같습니다:
nav_nameRequiredstring
노드명
filenameRequiredstring
작업 파일명
StageInfo
자동 작전 노드 정보. details 필드 내용은 다음과 같습니다:
nameRequiredstring
노드명
sizeRequirednumber
맵 격자 수
StageInfoError
자동 작전 노드 식별 오류. details 필드는 비어 있습니다
DepotInfo
창고 인식 결과. details 필드 구조는 다음과 같습니다:
- done (boolean, required): 인식 완료 여부, false는 아직 인식 중임(진행 중 데이터)을 의미
- data (string, required): JSON 문자열, 형식은 {"아이템ID": 수량, ...}, 예: {"2001":18000,"31043":317}
OperBoxInfo
오퍼레이터 보관함 인식 결과. details 필드 구조는 다음과 같습니다:
- done (boolean, required): 인식 완료 여부, false는 아직 인식 중임(진행 중 데이터)을 의미
- all_opers (array, required): 전체 오퍼레이터 목록, 배열의 각 항목:
  - id (string, required): 오퍼레이터 ID
  - name (string, required): 오퍼레이터 명칭
  - name_en (string, required): 오퍼레이터 영어 명칭
  - name_jp (string, required): 오퍼레이터 일본어 명칭
  - name_kr (string, required): 오퍼레이터 한국어 명칭
  - name_tw (string, required): 오퍼레이터 번체 중국어 명칭
  - own (boolean, required): 보유 여부
  - rarity (number, required): 오퍼레이터 레어도 [1, 6]
- own_opers (array, required): 보유 중인 오퍼레이터 상세 정보 목록, 배열의 각 항목:
  - id (string, required): 오퍼레이터 ID
  - name (string, required): 오퍼레이터 명칭
  - own (boolean, required): 보유 여부
  - elite (number, required): 정예화 단계 [0, 2]
  - level (number, required): 오퍼레이터 레벨
  - potential (number, required): 오퍼레이터 잠재 [1, 6]
  - rarity (number, required): 오퍼레이터 레어도 [1, 6]
UnsupportedLevel
자동지휘, 지원하지 않는 노드명. details 필드 내용은 다음과 같습니다:
levelRequiredstring
지원하지 않는 노드명
BlackFlowStartRun
BlackFlow 시작 보상 파밍(로그라이크 모드 30003)의 진행 상황. details 필드 구조는 다음과 같습니다 (기계 번역):
- status (string, required): 현재 진행 상황, 값은 다음과 같습니다:
  - preparing: 준비 탐험 시작.
  - target_run: 목표 탐험 시작.
  - reward_missed: 지원 선택 화면에서 보상은 인식했지만 원하는 것이 없어 해당 탐험을 포기하고 준비 탐험을 다시 진행.
  - reward_picked: blackflow_start_utopia가 켜져 있고 지원 선택 화면에 원하는 보상이 나와 blackflow_start_reward_priority 순서로 보상을 고른 뒤, 1층에 들어가 实托邦인지 확인.
  - completed: 원하는 보상이 나와 테마 화면으로 나가 해당 탐험을 유지하고 작업 종료. blackflow_start_utopia가 켜져 있으면 1층이 实托邦이었음을 뜻함.
  - reward_unrecognized: 지원 선택 화면의 보상을 인식하지 못해 해당 화면에 머문 채 작업 중지.
  - reward_page_missing: 목표 탐험에서 지원 선택 화면이 나타나지 않아 작업 중지.
  - reward_recognition_failed: 준비 탐험 또는 목표 탐험에서 지원 선택 화면의 보상 선택에 실패해 작업 중지.
- rewards (array<string>, optional): 목표 탐험의 지원 선택 화면에서 인식한 보상 이름(중국어 간체), 예: 空间租赁, 金乌. reward_missed, reward_picked, completed, reward_unrecognized, reward_recognition_failed일 때만 전달되며, blackflow_start_rewards가 0이고 blackflow_start_utopia가 꺼져 있거나(보상을 인식하지 않음) 하나도 인식하지 못하면 생략됩니다.
BlackFlowScrapTradeAborted
BlackFlow 행상 거래에서 이상이 발생하여 거래를 중단합니다. details 필드 내용은 다음과 같습니다:
reasonRequiredstring
거래를 중단한 이유
itemRequiredstring
중단을 유발한 거래 아이템 이름

ReportRequest

이 필드는 주로 코어 모듈이 UI 계층에 네트워크 요청 정보를 전달하는 데 사용되며, UI가 구체적인 HTTP 보고(Report) 작업을 수행합니다

urlRequiredstring

요청 전체 URL, 예: https://penguin-stats.io/PenguinStats/api/v2/report

headersRequiredobject

요청 헤더 키-값 쌍 (Content-Type 미포함, UI 계층에서 자동 추가)

bodyRequiredstring

요청 본문 내용 (일반적으로 JSON 형식의 문자열)

subtaskRequiredstring

서브 작업명, 구체적인 상보 임무 식별, 예: ReportToPenguinStats, ReportToYituliu