MaaGumballs

Pipeline 编写

编写规范

命名规范

为保证资源的美观一致,请尽量遵循以下现有规则。

资源命名

Node 命名

node 的定义为符合任务流水线(Pipeline)协议的一个完整的 JsonObject,大多数采用大驼峰命名法,特别地,部分情况下用 _ 连接前、后缀。

前缀一般为 Sub 或 当前活动缩写(如 SOD 黄昏的音序、EITM 山麓的回音)等。(其他情况建议不要前缀)

后缀一般为 数字状态 等,表示该 node 的具体阶段或状态。(建议新写的 node 不加后缀)

Node 编写

具体内容参见Pipeline 协议详细说明

[!NOTE]

[!WARNING]

Node 连接

Node 间主要通过 nextinterrupt 字段连接。

next完成 node 间的串联,interrupt实现执行以当前 interrupt node为 entry 的新任务链,并在该任务链完成后返回当前 node。

简单表示如下:

graph LR
    A(Task Entry<br>Node A) --> |next| B(Node B)
    A --> |interrupt| C(Node C)
    C --> |return| A

将 interrupt node 变复杂点:

graph LR
    A(Task Entry<br>Node A) --> |next| B(Node B)
    A --> |interrupt| C(Node C)
    C --> |next| D(Node D)
    C --> |interrupt| E(Node E)
    D --> |return| A
    E --> |return| C

为保证任务链有一个较好的结构,请按以下原则进行 node 连接:

  1. 标志完成阶段性任务的 node 应放在 next 中。
  2. 为达到匹配 next 中 node 而处理其他状况的 node 应放在 interrupt 中。

如 活动刷取任务、位于活动主界面、进入活动主界面 三者关系如下:

graph LR
   A(活动刷取任务) --> |next| B(位于活动主界面)
   A --> |interrupt| C(进入活动主界面)
   C --> |return| A

这里“进入活动主界面”就不会放在 next ,而是放入 interrupt

Next & Interrupt Node 排序

总体上,interrupt 第一个 node 比 next 最后一个 node 低一优先级。

nextinterrupt 内部,统一先按照优先级由高到低顺序排列,不能出现优先级倒挂的情况。举例:

现有判断一个小弹窗的 node B,和判断跳出弹窗前界面的 node A。
如果弹窗出现时依旧能匹配到A,则B的优先级应该高于A,否则会出现无法处理B而卡死于A的情况。

同一优先级内的 node,可按照匹配频率由高到低顺序排列,以便提高 node 命中率,降低资源消耗。

注释规范

pipeline.json 文件中,注释共两种属性字段:

  1. .*_doc$|^doc$: 以 _doc 结尾的字符串或者正好是 doc 的字符串。
  2. .*_code$|^code$:以 _code 结尾的字符串或者正好是 code 的字符串。

前者为对当前 node(或某字段)的说明,后者为对必填字段的占位。举例:

{
    "EnterTheActivityMain": {
        "doc": "进入当期活动主界面",
        "template_code": "在interface.json中修改template",
        "recognition": "TemplateMatch",
        "roi": [
            885,
            123,
            340,
            183
        ],
        "action": "Click",
        "post_wait_freezes": {
            "time": 500,
            "target": [
                0,
                179,
                190,
                541
            ]
        }
    }
}

doc 为当前 node 说明。

template_code 为必填字段占位, 原因是 recognitionTemplateMatch 时, “template” 字段必填,但我们想在 interface.json 中修改,而不是该 json 文件中。故用 template_code 占位。