タスク フロー プロトコル
2668字程度約9分
resource/tasks の使用方法と各フィールドの説明
ヒント
It is recommended to use Visual Studio Code and install Maa Pipeline Support extension for efficient editing. For more details, please visit the extension's homepage and the docs.
注意
JSONファイルはコメントをサポートしていません。テキスト内のコメントはプレゼンテーション用にのみ使用されます。直接コピーして使用しないでください。
完全なフィールドの一覧
{
"TaskName": { // タスク名。@ を含む場合は特殊なタスクである可能性があり、フィールドのデフォルト値が異なります。詳細は下方の特殊なタスクタイプを参照してください
"baseTask": "xxx", // xxx タスクをテンプレートとしてタスクを生成します。詳細は以下の特殊なタスクタイプにおける派生タスクを参照してください
"algorithm": "MatchTemplate", // オプション、認識アルゴリズムのタイプを示します
// 指定されていない場合はデフォルトで MatchTemplate になります
// - JustReturn: 認識なしでアクションを実行します
// - MatchTemplate: 画像をマッチングします
// - OcrDetect: テキスト認識
// - FeatureMatch: 特徴マッチング
"action": "ClickSelf", // オプション、認識後のアクションを示します
// 指定されていない場合はDoNothingになります
// - ClickSelf: 認識した位置をクリックします（認識された対象範囲内のランダムなポイント）
// - ClickRect: 指定した領域をクリックします、specificRectフィールドに対応し、このオプションは使用をお勧めしません
// - DoNothing: 何もしません
// - Stop: 現在のタスクを停止します
// - Swipe: スライドします、 specificRect および rectMove フィールドに対応します
// - Input: テキストを入力します。 algorithm が JustReturn である必要があり、 inputText フィールドに対応します
"sub": ["SubTaskName1", "SubTaskName2"],
// オプション、サブタスク。現在のタスクが実行された後、各サブタスクが順番に実行されます
// サブタスクにサブタスクの再セットを許可する。ただし、デッドループにならないよう注意してください
"subErrorIgnored": true, // オプション、サブタスクのエラーを無視するかどうか。
// 指定されていない場合はデフォルトで false になります
// false の場合、サブタスクにエラーがあると、後続のタスクは実行されません（このタスクがエラーを持つのと同等）
// true の場合、サブタスクにエラーがあるかどうかに影響を与えません
"next": ["OtherTaskName1", "OtherTaskName2"],
// オプション、現在のタスクとサブタスクが実行された後に実行される次のタスクを示します
// 前から後ろに識別され、最初に一致したものが実行されます
// デフォルトでは、現在のタスクが実行された後に停止します
// 同じタスクの場合、最初の認識後に2回目は認識されません。
// "next": [ "A", "B", "A", "A" ] -> "next": [ "A", "B" ]
// 最後のアイテム以外にJustReturnタイプのタスクが配置されないようにします
// リストに未定義のタスク名が存在する場合、認識開始前に UnknownTask エラーが送信され、タスクチェーン全体が停止されます
"maxTimes": 10, // オプション、タスクを実行できる最大回数を示します
// 指定されていない場合は無限になります
// 最大回数に達した場合、 exceededNext フィールドが存在する場合、タスクは exceededNext として実行されます；それ以外の場合、タスクは停止します
"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], // オプション、認識後のターゲット移動、このオプションは推奨されません。 1280 * 720 を基準とした自動スケーリング
// 例えばAが認識されたが、実際にクリックする場所はAの10ピクセル下の 5 * 2 エリアのどこかにある場合。
// その場合、[ 0, 10, 5, 2 ]を記入してください。直接クリックすべき位置を認識しようとしても、このオプションは推奨されません。
// 追加的に、 action が Swipe の場合、スライドの終了を示します。
"reduceOtherTimes": ["OtherTaskName1", "OtherTaskName2"],
// オプション、他のタスクの実行回数を減らすために実行します。
// 例えば、理性ポーションを取ると、青色の開始アクションボタンに最後にクリックが効かなくなります。したがって、青い開始アクションは -1 になります。
"specificRect": [100, 100, 50, 50],
// action が ClickRect の場合、指定されたクリック位置（範囲内のランダムなポイント）を示し、
// Swipe の場合、開始点を示します。
// 1280 * 720 を基準とした自動スケーリング
"specialParams": [int, ... ], // 一部の特殊な認識器に必要なパラメーター
// 追加、 action が Swipe の場合はオプション、 [0] が duration 、 [1] が追加スライドの方向（0 は無効、1/2/3/4 はそれぞれ上/下/左/右）、
// [2] と [3] はそれぞれスライド軌跡の緩入・緩出の傾斜を示し、10 倍して入力する必要があり、デフォルトはどちらも 10
// 通常の緩入・緩出にしたい場合、[2] と [3] はそれぞれ 37 と 1 を推奨
"highResolutionSwipeFix": false, // オプション項目。高解像度スワイプ修正を有効にするかどうか。
// 現在のところ、ステージナビゲーションのみが Unity のスワイプ方式を使用していないため、有効化が必要。
// デフォルトは false
/* 以下のフィールドは、 algorithm が MatchTemplate である場合にのみ有効です */
"template": "xxx.png", // オプション、マッチングされる画像ファイル名。文字列または文字列リストで指定できます
// デフォルト値は "TaskName.png"
// テンプレート画像ファイルは template フォルダおよびそのサブフォルダに配置でき、読み込み時に再帰的に検索されます
"templThreshold": 0.8, // オプション、イメージテンプレートのマッチングスコアの閾値。これを超えると、画像は認識されたと見なされます。
// デフォルトは 0.8、ログに従って実際のスコアを確認できます。
"maskRange": [1, 255], // オプション、グレースケールマスク範囲。
// 例えば、認識する必要のない画像の部分は黒く（グレースケール値が0）塗りつぶされます。
// その場合、 "maskRange" を [ 1, 255 ] に設定して、マッチング時に黒く塗りつぶされた部分を瞬時に無視できます。
"colorScales": [ // method が HSVCount または RGBCount の場合に有効で必須、色マスク範囲。
[ // list<array<array<int, 3>, 2>> / list<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 にすることをお勧めします
"pureColor": false, // オプション、method が HSVCount または RGBCount の場合に有効、デフォルトは false
// trueの場合、テンプレートマッチングのスコアを無視し、色マッチング結果のみに依存
// 色の特徴が明確だがテンプレートマッチングの効果が良くないシナリオに適用
// このオプションを使用する場合、templThresholdを上げることを推奨
"nmsDistance": 0, // オプション、テンプレートマッチング複数結果の重複排除半径、単位はピクセル、デフォルトは 0
// 2 つの命中位置の横縦座標差がいずれもこの値未満の場合、スコアが最も高いもののみ残す
// 未記入または 0 の場合はテンプレート短辺の半分を使用
"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：[ "start" ] の場合、実際の認識は "start action" でも成功と見なされます。
// true の場合、 "start" を認識する必要があり、1つ以上の単語ではない
"replaceFull": false, // オプション、ocrReplace が一致時に認識テキスト全体を置換するかどうか。デフォルトは false
// false の場合は一致した部分文字列のみ置換、true の場合はテキスト全体がいずれかの置換ルールに一致した場合、テキスト全体がそのルールの置換値で置き換えられます
"isAscii": false, // オプション、認識されるテキストコンテンツが ASCII 文字であるかどうか
// 指定されていない場合、デフォルトはfalse
"orderBy": "None", // オプション、複数マッチ時の結果の並び順（省略時は baseTask を継承、base がなければ並べ替えなし・認識順）
// - None: 並べ替えなし（認識順）。base で設定された並び順を上書きするには明示的に指定
// - Horizontal: 行優先（行内で左から右）
// - Vertical: 列優先（列内で上から下）
// - Score: スコアの高い順
"withoutDet": false, // オプション、検出モデルを使用しない場合
// 指定されていない場合、デフォルトは false
/* 以下のフィールドは、algorithm が OcrDetect かつ withoutDet が true の場合にのみ有効です */
"useRaw": true, // オプション、原画像でマッチングを行うかどうか
// 指定されていない場合、デフォルトは true、false の場合はグレースケールでマッチング
"binThreshold": [140, 255], // オプション項目。グレースケールの二値化上限（デフォルトは[140, 255]）
// この値より高い画素は背景とみなされ、文字領域から除外されます
// [lower, upper] 範囲内の画素のみが文字の前景として残ります
/* 以下のフィールドは、algorithm が JustReturn かつ action が Input の場合にのみ有効です */
"inputText": "A string text.", // 必須項目。入力する文字列の内容。文字列形式
/* 以下のフィールドは、アルゴリズムが FeatureMatch の場合のみ有効です */
"template": "xxx.png", // オプション。マッチングする画像ファイル名。文字列または文字列リストを指定できます。
// デフォルトは "taskname.png"
"count": 4, // マッチングする特徴点の数（閾値）。デフォルト値は 4
"ratio": 0.6, // KNN マッチングアルゴリズムの距離比。[0 - 1.0]。比率が大きいほどマッチングが緩くなり、接続されやすくなります。デフォルトは 0.6
"detector": "SIFT", // 特徴点検出の種類。オプションの値は SIFT、ORB、BRISK、KAZE、AKAZE、SURF。デフォルト値は SIFT
// SIFT: 計算量が多い、スケール不変性、回転不変性。最も効果的。
// ORB: 計算速度が非常に速い、回転不変性。ただし、スケール不変性は保証されません。
// BRISK: 非常に高速な計算速度、スケール不変性、回転不変性を備えています。
// KAZE: 2Dおよび3D画像に適用可能、スケール不変性、回転不変性を備えています。
// AKAZE: 高速な計算速度、スケール不変性、回転不変性を備えています。
}
}式の計算
タスクリスト型フィールド（sub, next, onErrorNext, exceededNext, reduceOtherTimes）は式の計算をサポートしています。
| 記号 | 意味 | 例 |
|---|---|---|
@ | @ 型タスク | Fight@ReturnTo |
#（単項） | 仮想タスク | #self |
#（二項） | 仮想タスク | StartUpThemes#next |
* | タスクの繰り返し | (ClickCornerAfterPRTS+ClickCorner)*10 |
+ | タスクリストの結合（next 系フィールドでは同名タスクのうち最も前方のもののみが残ります） | A+B |
^ | タスクリストの差分（前者にあり後者にないもの、順序は変わらない） | (A+A+B+C)^(A+B+D)（結果は C） |
演算子 @、#、*、+、^ には優先順位があります： #（単項）> @ = #（二項）> * > + = ^。
特殊なタスクタイプ
テンプレートタスク
テンプレートタスクには派生タスクと @ 型タスクが含まれます。テンプレートタスクの中核は、ベースタスクに基づいてフィールドのデフォルト値を変更することであると理解できます。
派生タスク
baseTask フィールドを持つタスクが派生タスクであり、baseTask フィールドに対応するタスクは、この派生タスクのベースタスクと呼ばれます。派生タスクの各フィールドのデフォルト値は次のとおりです。
- テンプレートマッチングタスクの場合、フィールド
templateのデフォルト値は引き続き"タスク名.png"になります。 - フィールド
algorithmがベースタスクと異なる場合、派生クラスのパラメータは継承されません（TaskInfoで定義されたパラメータのみが継承されます）。 - その他のフィールドのデフォルト値は、すべてベースタスクの対応するフィールドの値になります。
暗黙的な @ 型タスク
タスク "A" が存在し、かついずれのタスクファイルにも "B@A" の形のタスクとして直接定義されていないタスクが暗黙的な @ 型タスクです。タスク "A" はタスク "B@A" のベースタスクと呼ばれます。暗黙的な @ 型タスクの各フィールドのデフォルト値は次のとおりです。
- タスクリスト型フィールド（
sub,next,onErrorNext,exceededNext,reduceOtherTimes）のデフォルト値は、ベースタスクの対応するフィールドにB@接頭辞を直接追加したものになります（タスク名が#で始まる場合はB接頭辞を追加します）。 - その他のフィールドのデフォルト値は、すべてベースタスクの対応するフィールドの値になります（フィールド
templateも含む）。
明示的な @ 型タスク
タスク "A" が存在し、かつ何らかのタスクファイルで "B@A" の形のタスクとして直接定義されているタスクが明示的な @ 型タスクです。タスク "A" はタスク "B@A" のベースタスクと呼ばれます。明示的な @ 型タスクの各フィールドのデフォルト値は次のとおりです。
- タスクリスト型フィールド（
sub,next,onErrorNext,exceededNext,reduceOtherTimes）のデフォルト値は、ベースタスクの対応するフィールドにB@接頭辞を直接追加したものになります（タスク名が#で始まる場合はB接頭辞を追加します）。 - テンプレートマッチングタスクの場合、フィールド
templateのデフォルト値は引き続き"タスク名.png"になります。 - フィールド
algorithmがベースタスクと異なる場合、派生クラスのパラメータは継承されません（TaskInfoで定義されたパラメータのみが継承されます）。 - その他のフィールドのデフォルト値は、すべてベースタスクの対応するフィールドの値になります。
仮想タスク（# 型タスク）
仮想タスクとは "#{sharp_type}" または "B#{sharp_type}" の形のタスクのことで、{sharp_type} には none, self, back, next, sub, on_error_next, exceeded_next, reduce_other_times を指定できます。
仮想タスクは、命令仮想タスク（#none / #self / #back）とフィールド仮想タスク（#next など）に分類できます。
| 仮想タスクタイプ | 意味 | 簡単な例 |
|---|---|---|
| none | 空のタスク | 直接スキップされます1"A": {"next": ["#none", "T1"]} は "A": {"next": ["T1"]} と解釈されます"A#none + T1" は "T1" と解釈されます |
| self | 現在のタスク名 | "A": {"next": ["#self"]} の "#self" は "A" と解釈されます"B": {"next": ["A@B@C#self"]} の "A@B@C#self" は "B" と解釈されます2 |
| back | # の前のタスク名 | "A@B#back" は "A@B" と解釈されます"#back" が直接現れた場合はスキップされます3 |
| next、sub など | 前のタスク名に対応するフィールド | next を例に取ります。"A#next" は Task.get("A")->next と解釈されます"#next" が直接現れた場合はスキップされます |
注1："#none" は一般に、テンプレートタスクの接頭辞追加の特性と組み合わせて使用するか、不要なフィールドを複数ファイル間で継承しないようにするためにフィールド baseTask で使用されます。
注2："XXX#self" と "#self" は同じ意味を持ちます。
注3：複数のタスクが "next": [ "#back" ] を持つ場合、"T1@T2@T3" は T3, T2, T1 の順に順次実行されることを表します。
マルチファイルタスク
後で読み込まれたタスクファイル（例：Yostarクライアントの tasks.json、以下ファイル2と呼ぶ）で定義されたタスクが、さらに早く読み込まれたタスクファイル（例：CNクライアントの tasks.json、以下ファイル1と呼ぶ）で同じ名前のタスクも定義されている場合、次のようになります。
- ファイル2のタスクに
baseTaskフィールドがない場合、ファイル1の同じ名前のタスクのフィールドを直接継承します。 - ファイル2のタスクに
baseTaskフィールドがある場合、ファイル1の同じ名前のタスクのフィールドを継承せずに上書きします。特に、テンプレートタスクがない場合は"baseTask": "#none"を使用して、不要なフィールドの継承を避けることができます。
使用例
派生タスクの例（フィールド
baseTask）次の 2 つのタスクが定義されているとします。
"Return": { "action": "ClickSelf", "next": [ "Stop" ] }, "Return2": { "baseTask": "Return" },この場合、
"Return2"タスクのパラメータは"Return"タスクから直接継承され、実際には以下のパラメータを含むことになります。"Return2": { "algorithm": "MatchTemplate", // 直接継承 "template": "Return2.png", // "タスク名.png" "action": "ClickSelf", // 直接継承 "next": [ "Stop" ] // 直接継承。`@` 型タスクとは異なり、ここには接頭辞が付きません }@型タスクの例以下のパラメータを含むタスク
"A"が定義されているとします。"A": { "template": "A.png", ..., "next": [ "N1", "#back" ] },タスク
"B@A"が直接定義されていない場合、タスク"B@A"は実際には以下のパラメータを持ちます。"B@A": { "template": "A.png", ..., "next": [ "B@N1", "B#back" ] }タスク
"B@A"が"B@A": {}として定義されている場合、タスク"B@A"は実際には以下のパラメータを持ちます。"B@A": { "template": "B@A.png", ..., "next": [ "B@N1", "B#back" ] }仮想タスクの例
{ "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" };
注意事項
タスクリスト型フィールド（next など）で定義されたタスクが低優先度の演算を含む場合、実際の結果が期待と異なる可能性があるため、注意が必要です。
@と二項#の演算順序による特殊なケース{ "A": { "next": ["N0"] }, "B": { "next": ["A#next"] }, "C@A": { "next": ["N1"] } }上記の場合、
"C@B" -> next（すなわちC@A#next）は[ "N1" ]となり、[ "C@N0" ]にはなりません。@と+の演算順序による特殊なケース{ "A": { "next": ["#back + N0"] }, "B@A": {} }上記の場合、
Task.get("A")->next = { "N0" }; Task.get_raw("B@A")->next = { "B#back + N0" }; Task.get("B@A")->next = { "B", "N0" }; // [ "B", "B@N0" ] ではないことに注意実際、この特性を利用して不要な接頭辞の追加を避けることができます。次のように定義するだけです。
{ "A": { "next": ["#none + N0"] } }
実行中のタスク変更
Task.lazy_parse()は、実行時に json のタスク設定ファイルを読み込みます。lazy_parseのルールは マルチファイルタスク と同じです。Task.set_task_base()は、タスクのbaseTaskフィールドを変更します。
使用例
次のようなタスク設定ファイルがあるとします。
{
"A": {
"baseTask": "A_default"
},
"A_default": {
"next": [ "xxx" ]
},
"A_mode1": {
"next": [ "yyy" ]
},
"A_mode2": {
"next": [ "zzz" ]
}
}以下のコードは、mode の値に基づいてタスク "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;
}スキーマチェック
このプロジェクトでは、tasks.jsonのjsonスキーマチェックを設定しています。スキーマファイルは docs/maa_tasks_schema.json です。
Visual Studio
MaaCore.vcxproj で設定されており、すぐに使用できます。ヒント効果はより不明瞭で、いくつかの情報が欠落しています。
Visual Studio Code
.vscode/settings.json で設定されており、vscode でその プロジェクトフォルダ を開くと使用できます。ヒントはより良く機能します。