본문으로 건너뛰기

Tasks 스키마

2025년 3월 16일약 2 분

Tasks 스키마

주의: JSON 형식은 주석을 지원하지 않으므로 아래의 예시에서 주석은 제거해주시기 바랍니다.

resource/tasks.json의 사용법 및 각 필드 설명

개요

{
    "작업이름": {                          // 작업 이름

        "baseTask": "xxx",                  // 작업의 템플릿으로 사용될 xxx 작업을 지정합니다. 특수 작업 유형인 경우 아래의 템플릿 작업에 대한 설명을 참조하세요.

        "algorithm": "MatchTemplate",       // 선택 사항, 인식 알고리즘 유형을 나타냅니다.
                                            // 입력하지 않으면 기본값은 MatchTemplate입니다.
                                            // - JustReturn: 인식 없이 작업을 직접 실행합니다.
                                            // - MatchTemplate: 이미지 매칭
                                            // - OcrDetect: 텍스트 인식
                                            // - Hash: 해시 계산

        "action": "ClickSelf",              // 선택 사항, 인식 후 작업 유형을 나타냅니다.
                                            // 입력하지 않으면 기본값은 DoNothing입니다.
                                            // - ClickSelf: 인식된 위치를 클릭합니다 (인식된 대상 범위 내에서 무작위 점).
                                            // - ClickRand: 화면 전체에서 무작위 위치를 클릭합니다.
                                            // - ClickRect: 지정된 영역을 클릭합니다. specificRect 필드에 해당합니다. 이 옵션은 권장하지 않습니다.
                                            // - DoNothing: 아무 작업도 수행하지 않습니다.
                                            // - Stop: 현재 작업을 중지합니다.
                                            // - Swipe: 슬라이드, specificRect 및 rectMove 필드와 관련이 있습니다.

        "sub": [ "SubTaskName1", "SubTaskName2" ],
                                            // 선택 사항, 서브 작업 목록입니다. 현재 작업이 실행된 후에 각 서브 작업을 순차적으로 실행합니다.
                                            // 서브 작업은 재귀적으로 정의할 수 있습니다. 그러나 무한 루프에 빠지지 않도록 주의하세요.

        "subErrorIgnored": true,            // 선택 사항, 서브 작업 오류를 무시할지 여부를 나타냅니다.
                                            // 입력하지 않으면 기본값은 false입니다.
                                            // false인 경우, 서브 작업에 오류가 발생하면 이후 작업을 실행하지 않고 현재 작업이 오류로 간주됩니다.
                                            // true인 경우, 서브 작업의 오류 여부와는 무관하게 이후 작업 실행에 영향을 미치지 않습니다.

        "maxTimes": 10,                     // 선택 사항, 작업이 최대로 실행될 수 있는 횟수를 나타냅니다.
                                            // 입력하지 않으면 무한히 실행됩니다.
                                            // 최대 횟수에 도달하면 exceededNext 필드가 존재한다면 exceededNext 작업이 실행되며, 그렇지 않으면 현재 작업이 중지됩니다.

        "next": [ "OtherTaskName1", "OtherTaskName2" ],
                                            // 선택 사항, 현재 작업 및 서브 작업 실행 후에 실행될 다음 작업을 나타냅니다.
                                            // 리스트의 맨 앞부터 순서대로 인식되며, 첫 번째로 일치하는 작업이 실행됩니다.
                                            // 입력하지 않으면 현재 작업 실행 후에 중지됩니다.
                                            // 동일한 작업에 대해 두 번째 인식부터는 첫 번째 인식 이후에 다시 인식되지 않습니다.
                                            // JustReturn 유형의 작업은 마지막 아이템에 위치하지 않도록 주의하세요.

        "exceededNext": [ "OtherTaskName1", "OtherTaskName2" ],
                                            // 선택 사항, 최대 실행 횟수에 도달했을 때 실행할 작업을 나타냅니다.
                                            // 입력하지 않으면 최대 실행 횟수에 도달하면 중지됩니다. 입력했을 경우, next 대신 여기서 실행됩니다.

        "onErrorNext": [ "OtherTaskName1", "OtherTaskName2" ],
                                            // 선택 사항, 실행 중 오류가 발생한 경우에 실행될 이후 작업을 나타냅니다.

        "preDelay": 1000,                   // 선택 사항, 인식된 후 작업이 실행될 때까지 대기하는 시간을 밀리초로 나타냅니다. 입력하지 않으면 기본값은 0입니다.
        "postDelay": 1000,                  // 선택 사항, 실행된 후 다음 인식까지 지연되는 시간을 밀리초로 나타냅니다. 입력하지 않으면 기본값은 0입니다.

        "roi": [ 0, 0, 1280, 720 ],         // 선택 사항, 인식 범위를 나타냅니다. 포맷은 [ x, y, width, height ]입니다.
                                            // 자동으로 1280 * 720으로 확장됩니다. 입력하지 않으면 기본값은 [ 0, 0, 1280, 720 ]입니다.
                                            // 가능한 한 많이 작성하고 인식 범위를 축소하면 성능 소비가 줄어들고 인식 속도가 빨라질 수 있습니다.

        "cache": false,                      // 선택 사항, 작업이 캐싱을 사용하는지 여부를 나타냅니다. 기본값은 false입니다.
                                            // 최초 인식 이후에는 해당 위치만 인식하며, 성능을 크게 개선할 수 있습니다.
   

 // 단, 대상 인식 위치가 절대로 변하지 않을 작업에만 사용하세요. 대상 인식 위치가 항상 변하는 경우 false로 설정하세요.

        "rectMove": [ 0, 0, 0, 0 ],         // 선택 사항, 인식 후 대상 이동을 나타냅니다. Auto-scaling으로 기준은 1280 * 720입니다.
                                            // 예를 들어 A가 인식되지만 클릭해야 할 실제 위치는 A 아래 10 픽셀 5 * 2 영역의 어딘가에 있을 경우
                                            // [ 0, 10, 5, 2 ]를 채우고 가능한 경우 바로 클릭할 위치를 인식합니다. 이 옵션은 권장하지 않습니다.
                                            // 추가적으로, action이 Swipe인 경우 유효하고 필수입니다. 슬라이드의 끝점을 나타냅니다.

        "reduceOtherTimes": [ "OtherTaskName1", "OtherTaskName2" ],
                                            // 선택 사항, 다른 작업의 실행 횟수를 줄이기 위해 실행합니다.
                                            // 예를 들어 정신약을 먹으면 마지막으로 파란색 시작 동작 버튼을 클릭한 효과가 없으므로 파란색 시작 동작이 -1됩니다.

        "specificRect": [ 100, 100, 50, 50 ],
                                            // action이 ClickRect인 경우 유효하고 필수입니다. 지정된 클릭 위치를 나타냅니다 (범위 내의 무작위 점).
                                            // action이 Swipe인 경우 유효하고 필수입니다. 슬라이드의 시작점을 나타냅니다.
                                            // Auto-scaling으로 기준은 1280 * 720입니다.
                                            // algorithm이 "OcrDetect"일 경우, specificRect[0]과 specificRect[1]은 그레이스케일의 상한선과 하한선 임계값을 나타냅니다.

        "specialParams": [ int, ... ],      // 일부 특수 인식기에 필요한 매개변수를 나타냅니다.
                                            // 추가 옵션, action이 Swipe인 경우 [0]은 지속 시간, [1]은 추가 슬라이드 여부를 나타냅니다.

        /* 다음 필드들은 algorithm이 MatchTemplate인 경우에만 유효합니다. */

        "template": "xxx.png",              // 선택 사항, 이미지 매칭에 사용할 이미지 파일의 이름을 나타냅니다.
                                            // 기본값은 "작업이름.png"입니다.

        "templThreshold": 0.8,              // 선택 사항, 이미지 템플릿 매칭 점수의 임계값을 나타냅니다. 이 점수 이상인 경우 이미지가 인식되었다고 판단합니다.
                                            // 기본값은 0.8입니다. 실제 점수는 로그에서 확인할 수 있습니다.

        "maskRange": [ 1, 255 ],            // 선택 사항, 흑백 마스크 범위를 나타냅니다.
                                            // 예를 들어 인식할 필요가 없는 이미지 부분은 검은색으로 칠해질 수 있습니다 (0의 흑백 값).
                                            // 그러면 "maskRange"를 [ 1, 255 ]로 설정하면 검은색 처리된 부분은 즉시 무시됩니다.


        "colorScales": [                    // method가 HSVCount 또는 RGBCount일 때 유효하고 필수, 색상 마스크 범위.
            [                               // list<array<array<int, 3>, 2> | array<int, 2>>
                [23, 150, 40],              // 구조는 [[lower1, upper1], [lower2, upper2], ...]
                [25, 230, 150]              //     내측이 int일 경우는 그레이스케일,
            ],                              //       array<int, 3>일 경우는 삼채널 색상으로, method에 따라 RGB 또는 HSV로 결정됩니다;
            ...                             //     중간 층의 array<*, 2>는 색상(또는 그레이스케일)의 하한과 상한:
        ],                                  //     외층은 다른 색상 범위를 나타내며, 식별할 영역은 템플릿 이미지에서 이들의 마스크의 합집합입니다.

        "colorWithClose": true,             // 선택 사항, method가 HSVCount 또는 RGBCount일 때 유효, 기본값은 true
                                            // 색상 수를 세는 동안 마스크 범위에 먼저 닫힘 연산을 적용할지 여부.
                                            // 닫힘 연산은 작은 검은 점을 메울 수 있으며, 일반적으로 색상 수 세기 매칭 효과를 향상시키지만 이미지에 텍스트가 포함된 경우 false로 설정하는 것이 좋습니다

        "method": "Ccoeff",                 // 선택 사항, 템플릿 매칭 알고리즘, 목록 형태일 수 있음
                                            // 지정하지 않을 경우 기본값은 Ccoeff
                                            //      - Ccoeff:       색상에 민감하지 않은 템플릿 매칭 알고리즘, cv::TM_CCOEFF_NORMED에 해당
                                            //      - RGBCount:     색상에 민감한 템플릿 매칭 알고리즘,
                                            //                      먼저 마스크 범위에 따라 매칭 영역과 템플릿 이미지를 이진화하고,
                                            //                      RGB 색 공간 내의 유사도를 F1-score를 지표로 계산한 후,
                                            //                      결과를 Ccoeff 결과와 점곱합니다
                                            //      - HSVCount:     RGBCount와 유사하지만 색상 공간을 HSV로 변경

        /* 다음 필드들은 algorithm이 OcrDetect인 경우에만 유효합니다. */

        "text": [ "接管作战", "代理指挥" ],  // 필수 사항, 인식할 텍스트 내용을 나타냅니다. 어떤 항목이 일치하면 인식되었다고 판단합니다.

        "ocrReplace": [                     // 선택 사항, 자주 오인식되는 텍스트를 대체할 내용입니다 (정규표현식 지원).
            [ "千员", "干员" ],
            [ ".+击干员", "狙击干员" ]
        ],

        "fullMatch": false,                 // 선택 사항, 텍스트 인식이 모든 단어를 일치시키는지 여부를 나타냅니다. 기본값은 false입니다.
                                            // false인 경우, 부분 문자열인 경우 인식됩니다. 예를 들어 text: [ "시작" ]이면 실제 인식에서 "시작 작업"도 인식됩니다.
                                            // true인 경우, "시작"만 인식되어야 합니다.

        "isAscii": false,                   // 선택 사항, 인식할 텍스트 내용이 ASCII 문자인지 여부를 나타냅니다.
                                            // 기본값은 false입니다.

        "withoutDet": false                 // 선택 사항, 탐지 모델을 사용하지 않을지 여부를 나타냅니다.
                                            // 기본값은 false입니다.

        /* 다음 필드들은 algorithm이 Hash인 경우에만 유효합니다. */
        // 이 알고리즘은 아직 미성숙하며, 특수한 경우에만 사용되므로 현재는 권장되지 않습니다.
        // Todo
    }
}

특수 작업 유형

템플릿 작업(@ 유형 작업)

템플릿 작업과 기반 작업을 함께 템플릿 작업이라고 합니다.

작업 "A"를 템플릿으로 사용하고 "B@A"로 표기하여 "A"를 통해 생성된 작업을 나타낼 수 있습니다.

합니다). 나머지 매개변수는 "A" 작업과 동일합니다. 즉, 작업 "A"에 다음과 같은 매개변수가 있는 경우:

    "A": {
        "template": "A.png",
        ...,
        "next": [ "N1", "N2" ]
    }

이는 다음과 같이 정의한 것과 동일합니다.

    "B@A": {
        "template": "A.png",
        ...,
        "next": [ "B@N1", "B@N2" ]
    }

기반 작업

기반 작업과 템플릿 작업을 함께 템플릿 작업이라고 합니다.

baseTask 필드가 있는 작업은 기반 작업입니다.

기반 작업은 템플릿 작업보다 우선합니다. 즉, "B@A": { "baseTask": "C", ... }는 작업 A와 관련이 없습니다.

명시적으로 정의되지 않은 모든 매개변수는 해당 작업이 접두사 없이 기반 작업의 매개변수를 사용하며, template은 명시적으로 정의되지 않은 경우에는 여전히 "작업이름.png"입니다.

멀티 파일 Task

나중에 로드된 작업 파일 (예: 글로벌 서버의 tasks.json 파일)에서 정의된 작업이 먼저 로드된 작업 파일 (예: CN 서버의 tasks.json 파일)에서도 동일한 이름의 작업이 정의된 경우 다음과 같습니다:

가상 작업

가상 작업은 또한 숫자 기호(# 유형 작업)로 불립니다.

이름에 #이 포함된 작업은 가상 작업입니다. # 다음에는 next, back, self, sub, on_error_next, exceeded_next, reduce_other_times가 따라옵니다.

가상 작업 유형의미간단한 예시
self부모 작업 이름"A": {"next": "#self"}에서 "#self""A"로 해석됩니다.<br>"B": {"next": "A@B@C#self"}에서 "A@B@C#self""B"로 해석됩니다.<sup>1 </sup>
back# 앞 작업 이름"A@B#back""A@B"로 해석됩니다.<br>직접 나타날 경우 "#back"은 무시됩니다.
next, sub 등이전 작업 이름에 대응하는 필드next를 예로 들면:<br>"A#next"Task.get("A")->next로 해석됩니다.<br>직접 나타날 경우 "#next"은 무시됩니다.

참고 <sup>1 </sup>: "XXX#self""#self"와 같은 의미를 갖습니다.

간단한 예시

{
    "A": { "next": [ "N1", "N2" ] },
    "C": { "next": [ "B@A#next" ] },

    "Loading": {
        "next": [ "#self", "#next", "#back" ]
    },
    "B": {
        "next": [ "Other", "B@Loading" ]
    }
}

다음 형식도 가능합니다.

Task.get("C")->next = { "B@N1", "B@N2" };

Task.get("B@Loading")->next = { "B@Loading", "Other", "B" };
Task.get("Loading")->next = { "Loading" };
Task.get_raw("B@Loading")->next = { "B#self", "B#next", "B#back" };

몇 가지 사용 예시

기타 관련 정보

{
    "A": { "next": ["N0"] },
    "B": { "next": ["A#next"] },
    "C@A": { "next": ["N1"] }
}

위의 예시에서, "C@B" -> next (즉, C@A#next)는 ["N1"]이 아닌 ["C@N0"]입니다.

런타임에서 작업 수정

사용 예시

다음과 같은 작업 구성 파일이 있다고 가정합니다.

{
  "A": {
    "baseTask": "A_default"
  },
  "A_default": {
    "next": ["xxx"]
  },
  "A_mode1": {
    "next": ["yyy"]
  },
  "A_mode2": {
    "next": ["zzz"]
  }
}

다음 코드는 mode 값에 따라 작업 "A"를 변경하며, "A"에 의존하는 다른 작업인 "B@A" 등도 변경됩니다:

switch (mode) {
case 1:
    Task.set_task_base("A", "A_mode1");  // 이것은 사실상 A를 A_mode1의 내용으로 대체하는 것과 같습니다. 아래와 같이 진행됩니다.
    break;
case 2:
    Task.set_task_base("A", "A_mode2");
    break;
default:
    Task.set_task_base("A", "A_default");
    break;
}

표현식 계산

기호의미예시
@템플릿 작업Fight@ReturnTo
# (unary/단항)가상 작업#self
# (binary/이항)가상 작업StartUpThemes#next
*작업 반복(ClickCornerAfterPRTS+ClickCorner)*5
+작업 목록 병합A+B
^작업 목록 차집합 (앞쪽에는 있지만 뒤쪽에는 없는 작업으로, 순서는 유지됨)(A+A+B+C)^(A+B+D) (= C)

@, #, *, +, ^ 연산자의 우선순위는 다음과 같습니다: # (단항) > @ = # (이항) > * > + = ^.

스키마 확인

이 프로젝트는 tasks.json에 대한 JSON 스키마 확인을 설정하며, 스키마 파일은 docs/maa_tasks_schema.json입니다.

Visual Studio

MaaCore.vcxproj에 구성되어 있으며 즉시 사용할 수 있습니다. 힌트 효과는 상대적으로 불명확하며 일부 정보가 누락됩니다.

Visual Studio Code

.vscode/settings.json에 구성되어 있으며, 해당 프로젝트 폴더를 vscode로 열고 사용할 수 있습니다. 힌트가 더 잘 작동합니다.

번역 경고
MAA의 문서는 주로 중국어 간체로 되어 있습니다. 다른 언어로 된 문서는 번역이 이상하거나, 번역이 되어있지 않을 수 있습니다.