Skip to content

Latest commit

 

History

History
446 lines (315 loc) · 9.15 KB

2.3-自定义任务.md

File metadata and controls

446 lines (315 loc) · 9.15 KB

自定义任务

除依照流水线协议编写 Json 实现低代码开发外,MaaFramework 也支持通过多种方式自行编写代码来实现自定义任务:

  • FFI(语言交互接口)

    MaaFramework 提供了 C 和 Python API,且理论上支持所有主流语言。
    但目前已适配的 Binding 较少,仅支持 C 和 Python,其他语言可能需要您自行编写(也欢迎在写完后向我们提交 PR!)。
    优点:执行效率相对较高,更符合标准编程范式。

  • 执行器代理

    简单来说,开发者可以编写一个自己的 exe,并通过 MaaToolkit 相关接口传入 exe 路径。MaaFramework 会在执行到对应任务时,调用该 exe,并通过启动参数传入当前画面的图片、识别结果、任务名等信息。
    开发者可在自己的 exe 中执行任意操作,并可以按照 协议 直接输出(print / std::cout / ...)部分命令。MaaFramework 会通过管道捕获这些输出命令,执行如点击滑动、截图识别等动作,再通过管道传出执行结果。开发者可以使用标准输入(input / std::cin / ...)来获取这些结果。
    这里的 exe 指代任何可执行文件,包括 exe, bat, shell, python 脚本等(也同样支持 Linux / macOS 下的可执行文件)。
    优点:简单。

FFI

开发者可实现自定义动作、自定义识别器,并通过注册接口传入。
其中的 SyncContext 用于在自定义任务中调用如点击滑动、截图识别等。

执行器代理

启动参数

自定义识别器(CustomRecognizer)

对于自定义识别器,启动参数为:

/path/to/my_recognizer.exe  custom_arg_1  custom_arg_2  ...  sync_context  image_path  task_name  custom_recognition_param
  • /path/to/my_recognizer.exe

    通过注册接口传入的可执行文件路径。若是 Python 等脚本,也可直接传入 Python.exe

  • custom_arg_1 custom_arg_2 ...

    通过注册接口传入的自定义参数(多个参数)。若是 Python 等脚本,其中第一个参数则为你的 .py 文件路径。

  • sync_context

    按照协议向 MaaFramework 输出命令时,所需要带上的实例信息。详见 输入输出协议

  • image_path

    当前画面截图的图片文件路径。

  • task_name

    当前正在执行的任务名。

  • custom_recognition_param

    在流水线 Json 中定义的 custom_recognition_param 值。

自定义动作(CustomAction)

对于自定义动作,启动参数为:

/path/to/my_action.exe  custom_arg_1  custom_arg_2  ...  sync_context  task_name  custom_action_param  cur_box  cur_rec_detail
  • /path/to/my_action.exe

    通过注册接口传入的可执行文件路径。若是 Python 等脚本,也可直接传入 Python.exe

  • custom_arg_1 custom_arg_2 ...

    通过注册接口传入的自定义参数(多个参数)。若是 Python 等脚本,其中第一个参数则为你的 .py 文件路径。

  • task_name

    当前正在执行的任务名。

  • sync_context

    按照协议向 MaaFramework 输出命令时,所需要带上的实例信息。详见 输入输出协议

  • custom_action_param

    在流水线 Json 中定义的 custom_action_param 值。

  • cur_box

    本任务识别器当前识别到的目标位置。格式为 Json 数组,[x, y, w, h]。

  • cur_rec_detail

    本任务识别器识别到的详细信息。格式为 Json,具体协议待补充~

输入输出协议

控制器代理执行的命令均为同步执行。且每输出一条命令后,都需要使用标准输入(input / std::cin / scanf / ...)取回执行结果,否则会影响后续命令的执行。

命令格式为 JSON,大致结构为

{
    "function": string,
    "sync_context": string,
    // ......
}
  • function: string
    执行的命令,必选。 可选的值:RunTask | RunRecognition | RunAction | Click | Swipe | PressKey | InputText | TouchDown | TouchMove | TouchUp | Screencap

  • sync_context: string
    实例信息,必选。启动自定义识别器/自定义动作时,由启动参数传入的字符串。

执行结果格式为 JSON,大致结果为

{
    "return": bool,
    // ......
}
  • return: bool
    执行成功与否。

RunTask

执行某个子任务。

该命令需要更多的参数,结构为

{
    "function": "RunTask",
    "sync_context": string,
    "task_name": string,
    "task_param": object
}
  • task_name: string
    任务名,必选。

  • task_param: string
    任务额外参数,可选。

执行结果为

{
    "return": bool
}

RunRecognition

执行某个任务的识别部分。

该命令需要更多的参数,结构为

{
    "function": "RunRecognition",
    "sync_context": string,
    "image": string,
    "task_name": string,
    "task_param": object
}
  • image: string
    待识别图片文件路径,必选。

  • task_name: string
    任务名,必选。

  • task_param: string
    任务额外参数,可选。

执行结果为

{
    "return": bool,
    "box": [int, int, int, int],
    "detail": any
}

RunAction

执行某个任务的动作部分。

该命令需要更多的参数,结构为

{
    "function": "RunAction",
    "sync_context": string,
    "task_name": string,
    "task_param": object,
    "cur_box": [int, int, int, int],
    "cur_rec_detail": any
}
  • task_name: string
    任务名,必选。

  • task_param: string
    任务额外参数,可选。

  • cur_box: array<int, 4>
    模拟识别到的范围,必选。

  • cur_rec_detail: any
    模拟识别到的详情,必选。

执行结果为

{
    "return": bool
}

Click

执行点击操作。

该命令需要更多的参数,结构为

{
    "function": "Click",
    "sync_context": string,
    "x": int,
    "y": int
}

执行结果为

{
    "return": bool
}

Swipe

执行滑动操作。

该命令需要更多的参数,结构为

{
    "function": "Swipe",
    "sync_context": string,
    "x1": int,
    "y1": int,
    "x2": int,
    "y2": int,
    "duration": int
}

执行结果为

{
    "return": bool
}

PressKey

执行按键操作。

该命令需要更多的参数,结构为

{
    "function": "PressKey",
    "sync_context": string,
    "keycode": int
}

执行结果为

{
    "return": bool
}

InputText

执行输入文本操作。

该命令需要更多的参数,结构为

{
    "function": "InputText",
    "sync_context": string,
    "input_text": string
}

执行结果为

{
    "return": bool
}

TouchDown

执行触摸按下操作。

该命令需要更多的参数,结构为

{
    "function": "TouchDown",
    "sync_context": string,
    "contact": int,
    "x": int,
    "y": int,
    "pressure": int
}

执行结果为

{
    "return": bool
}

TouchMove

执行触摸移动操作。

该命令需要更多的参数,结构为

{
    "function": "TouchMove",
    "sync_context": string,
    "contact": int,
    "x": int,
    "y": int,
    "pressure": int
}

执行结果为

{
    "return": bool
}

TouchUp

执行触摸抬起操作。

该命令需要更多的参数,结构为

{
    "function": "TouchUp",
    "sync_context": string,
    "contact": int
}

执行结果为

{
    "return": bool
}

Screencap

执行截图操作。

{
    "function": "Screencap",
    "sync_context": string
}

执行结果为

{
    "return": bool,
    "image": string
}

CachedImage

获取最近一次的截图。

{
    "function": "CachedImage",
    "sync_context": string
}

执行结果为

{
    "return": bool,
    "image": string
}