Skip to content

Latest commit

 

History

History
183 lines (129 loc) · 7.66 KB

1.1-快速开始.md

File metadata and controls

183 lines (129 loc) · 7.66 KB
Raw

快速开始

开发思路

在开始之前，我们先简单介绍一下整体的集成思路。
MaaFramework 支持通过 Json 低代码编程（Pipeline Json）；同时也提供了 C++, Python, Rust, C#, HTTP 接口以供开发者更灵活的操作。
我们推荐的集成方式有以下几种：

  1. 完全依赖 Json 低代码编程

    简单快捷，推荐初次接触 MaaFramework 及编程小白使用。缺点是对于复杂逻辑的处理不够灵活。🎞️视频教程
    我们为此方式提供了⭐项目模板，可更方便的进行开发！
    以下是一个例子：

    // 此处为伪代码，仅供参考思路，无法直接运行
{
    "识别结算画面": {
        "next": [
            "战斗完成",
            "战斗失败"
        ]
    },
    "战斗完成": {
        "next": [
            "点击确认"
        ]
    },
    "战斗失败": {
        "next": [
            "点击重试"
        ]
    },
    "点击确认": {
        "action": "Click"
    },
    "点击重试": {
        "action": "Click"
    }
}

  2. 自行编写代码控制流程，将自己的代码与 Json 低代码无缝结合

    该方式由集成方自行处理流程，可调用 MaaFramework 进行截图、点击等操作，也可独立执行 Pipeline Json 中任务的识别或动作部分。

    # 此处为伪代码，仅供参考思路，无法直接运行
# "识别结算画面", "点击确认" 等均为 Json 中的逻辑
def my_task():
    detail = await maafw.run_recognition("识别结算画面")

    if detail.text == "战斗失败":
        await maafw.click(100, 100)

    else detail.text == "战斗完成":
        image = await maafw.screencap()
        save_to_file(image)
        await maafw.run_task("点击确认")

  3. 依赖 Pipeline Json 掌控流程，但注册自定义任务处理复杂逻辑

    该方式是在 1 的基础上进一步升级。非常反直觉，但根据我们在 MAA 中总结的经验，这才是最佳实践。
    由于黑盒测试的特性，需要处理大量 unhappy path，集成方自行编写的控制逻辑，在任务分支越来越多、逻辑越来越复杂后，会变得极不可维护。需要一套统一、鲁棒的流程控制逻辑，而 Pipeline 正是我们整理出的这样一套流程体系。

    # 此处为伪代码，仅供参考思路，无法直接运行
class MyAction:
    def run():
        image = await maafw.screencap()
        save_to_file(image)
        await maafw.run_action("点击确认")

def main():
    maafw.register_action("我的点击确认", MyAction)

准备资源文件

⭐若您使用项目模板，直接在 文件夹 中修改即可。

您需要准备一些资源文件，典型的文件结构 如下：

my_resource
├── image
│   ├── my_image_1.png
│   └── my_image_2.png
├── model
│   └── ocr
│       ├── det.onnx
│       ├── keys.txt
│       └── rec.onnx
└── pipeline
    ├── my_pipeline_1.json
    └── my_pipeline_2.json

其中以 my_ 开头的文件/文件夹均可自行修改名称，其他的则为固定文件名，不可修改，下面依次介绍：

Pipeline JSON 文件

my_resource/pipeline 中的文件，包含主要的脚本执行逻辑，会递归读取目录中所有的 json 格式文件。

可参考 任务流水线协议 进行编写，一个简单的 demo

小工具：

图片文件

my_resource/image 中的文件，主要为 pipeline 所用到的模板匹配图片、特征检测图片等，会按照 pipeline 中设定的 template 等字段读取对应的文件。

请注意所使用的图片需要是无损原图的裁剪。若使用安卓模拟器，请使用模拟器自带的截图功能！（不可以直接对模拟器窗口进行截图）

小工具：

文字识别模型文件

⭐若您使用项目模板，直接按照其文档，运行 configure.py 即可自动部署模型文件。

my_resource/model/ocr 中的文件，为 PaddleOCR 转 ONNX 后的模型文件。

可使用我们的预转换文件：MaaCommonAssets，选择需要的语种，按照 上述 目录结构存放即可。

若有需要也可以自行对 PaddleOCR 的官方预训练模型进行 fine-tuning （请自行参考 PaddleOCR 官方文档），并转换成 ONNX 文件使用，转换命令可参考 这里

调试

  • 推荐使用 MaaDebugger。

  • 若使用 MaaPiCli，会在同目录下生成 config/maa_option.json 文件，其中：

    • logging: 保存日志，会生成 debug/maa.log。默认 true。
    • recording: 保存录像功能，会保存运行期间所有的截图及操作数据，可使用 DbgController 进行复现调试。默认 false。
    • save_draw: 保存图像识别可视化结果，会保存运行期间所有图像识别可视化结果绘制图。默认 false。
    • show_hit_draw: 显示任务命中弹窗，每次识别成功会弹窗显示识别结果。默认 false。
    • stdout_level: 控制台显示日志等级。默认 2（Error），可设为 0 关闭全部控制台日志，或设为 7 打开全部控制台日志。

  • 若自行集成，可通过 Toolkit.init_option / MaaToolkitInitOptionConfig 接口开启调试选项。生成的 json 文件同上。

运行

使用 MaaPiCli（通用 CLI）或者 自行编写集成代码

使用 MaaPiCli

⭐若您使用项目模板，直接按照其文档，运行 install.py 后即可自动打包相关文件

使用 Release 包 bin 文件夹中的 MaaPiCli，并编写 interface.json 置于同目录下，即可使用

该 Cli 已完成基本功能开发，更多功能不断完善中！详细文档待进一步完善，当前可参考 Sample 编写

实践:

自行编写集成代码

请参考 集成文档

实践:

  • MAABH3 基于 C++ & cmake 的集成实践
  • MBA 基于 C# .NET 的集成实践

其它工具

MaaSupportWeb

基于 MaaHttp 的前端界面工具。

  • 连接控制器、加载资源、执行任务，查看任务执行情况
    • 支持 Adb 和 Win32
  • 文件管理，上传、下载资源文件
  • 基于 UI 的 Task 编辑
  • 截图以及获取 ROI
    • 支持使用已连接的控制器直接获取截图
    • 支持自行上传截图