0.1-DevelopmentApproach.md

Development Approach

MaaFramework supports complete low-code programming through JSON (Pipeline JSON) and also provides APIs for developers to integrate on their own.
It is also possible to combine both approaches, using low-code as a form of "wrapper" for invocation.
Below are several common integration methods:

Complete Dependence on JSON Low-Code Programming (Using MaaPiCli.exe)

This method is simple and quick, but not very flexible. It is recommended for beginners and those new to programming with MaaFramework.
We provide a 🎞️ video tutorial and ⭐ project template for this method. Here is an example:

// JSON does not support comments; this is pseudo-code for reference only and cannot be executed directly
{
    "Recognize and Click Start Button": {
        "recognition": "OCR",           // Optical Character Recognition
        "expected": "Start",           // Text to recognize
        "action": "Click",             // Action: Click
        "next": [
            "Recognize and Click Confirm Icon"
        ]
    },
    "Recognize and Click Confirm Icon": {
        "recognition": "TemplateMatch", // Image template matching
        "template": "Confirm.png",       // Image file name
        "action": "Click"
    }
}

Use JSON Low-Code Programming with Custom Logic for Complex Tasks

Launch the CLI through the API while registering some custom tasks. This method allows a seamless switch from method 1. Here is an example:

{
    "Recognize and Click Confirm Icon": {
        "next": [
            "My Custom Task"
        ]
    },
    "My Custom Task": {
        "recognition": "Custom",
        "custom_recognition": "MyReco",
        "action": "Custom",
        "custom_action": "MyAct"
    }
}

# This is pseudo-code for reference only and cannot be executed directly
def main():
    # Register custom recognition
    maafw.Toolkit.register_custom_recognition("MyReco", MyRecognition())

    # Register custom action
    maafw.Toolkit.register_custom_action("MyAct", MyAction())

    # Start MaaPiCli
    maafw.Toolkit.run_pi_cli("C:/MaaXXX/resource", "C:/MaaXXX/cache")

class MyRecognition(CustomRecognition):
    def analyze(context, ...):
        # Obtain the image and perform custom image processing
        image = context.tasker.controller.cached_image
        # Return image analysis result
        return AnalyzeResult(box=(10, 10, 100, 100))

class MyAction(CustomAction):
    def run(context, ...):
        # Perform click action
        context.controller.post_click(100, 10).wait()
        # Override the next tasks to execute
        context.override_next(task_name, ["TaskA", "TaskB"])

Write Your Own Code

You can use low-code as a "wrapper" for invocation or register custom callbacks.

# This is pseudo code, for reference only, and cannot be run directly
# "Recognize and click the start button", "Recognize and click the confirmation icon" and so on are all logic in Json
def main():
    detail = tasker.post_pipeline("Recognize and click the start button").wait().get()

    if detail.completed:
        tasker.controller.post_click(100, 100).wait()

    else:
        image = tasker.controller.cached_image
        save_to_file(image)

        my_act = MyAction()
        tasker.resource.register_custom_action("MyAction", MyAction())
        tasker.post_pipeline("Recognize and click the confirmation icon").wait()

    image: np.ndarray = tasker.controller.post_screencap().wait().get()