# 1.1 Quick Start

## Development Approach

MaaFramework provides three integration solutions to meet different development scenarios:

> [!TIP]
> Afraid of not being able to understand? It doesn't matter, there are many mature [projects](https://github.com/MaaXYZ/MaaFramework?tab=readme-ov-file#%E5%BA%94%E7%94%A8%E7%A8%8B%E5%BA%8F) in the community to refer to.

### Approach 1: Pure JSON Low-Code Programming

**Applicable Scenarios:** Quick start, simple logic implementation

**Features:**

- Zero coding prerequisite
- Automated processes configured through JSON
- Comes with a [🎞️ video tutorial](https://www.bilibili.com/video/BV1yr421E7MW) and a [⭐ project template](https://github.com/MaaXYZ/MaaPracticeBoilerplate) (The video tutorial uses an older version and some of the content may be outdated. Please refer to the documentation in this repository for details on the differences.)
- Combine drag-and-drop development with the [MaaPipelineEditor](https://mpe.codax.site/stable/) visual editor.

```jsonc
{
    "Click Start Button": {
        "recognition": "OCR",          // Text recognition engine
        "expected": "Start",           // Target text
        "action": "Click",             // Execute click action
        "next": ["Click Confirm Icon"] // Subsequent task chain
    },
    "Click Confirm Icon": {
        "recognition": "TemplateMatch",// Image template matching
        "template": "confirm.png",     // Matching asset path
        "action": "Click"
    }
}
```

### Approach 2: JSON + Custom Logic Extension (Recommended)

**Features**:

- Retains the low-code advantage of JSON; core flows remain visual and easy to edit
- Hosts custom recognition/actions in the Agent process, making it easier to encapsulate advanced logic
- Seamlessly integrates with the [⭐ boilerplate](https://github.com/MaaXYZ/MaaPracticeBoilerplate) to provide scaffolding and examples

```jsonc
{
    "Click Confirm Icon": {
        "next": ["Custom Processing Module"]
    },
    "Custom Processing Module": {
        "recognition": "Custom",
        "custom_recognition": "MyReco",  // Custom recognizer ID
        "action": "Custom",
        "custom_action": "MyAct"         // Custom action ID
    }
}

```

💡 The General UI automatically connects to your Agent process and invokes the registered recognition/action implementations when executing `MyReco`/`MyAct`.

```python
# Python pseudo-code example
from maa.agent.agent_server import AgentServer

# Register a custom recognizer
@AgentServer.custom_recognition("MyReco")
class CustomReco:
    def analyze(ctx):
        return (10, 10, 100, 100)  # Return your own processed recognition result

# Register a custom action
@AgentServer.custom_action("MyAct")
class CustomAction:
    def run(ctx):
        ctx.controller.post_click(100, 10).wait()  # Execute click
        ctx.override_next(["TaskA", "TaskB"])       # Dynamically adjust the task flow

# Start the Agent service
AgentServer.start_up(sock_id)
```

For a complete example, refer to the [template commit](https://github.com/MaaXYZ/MaaPracticeBoilerplate/commit/126a56cefc17bf6c8335c703387d8d3ee2dad4d1).

### Approach 3: Full-Code Development

> [!NOTE]
> MaaFramework offers full multi-language APIs, but code-only workflows lose ecosystem tools (visual editor, visual debugger, General UI). In most cases, the custom extensions in Approach 2 already cover advanced requirements without sacrificing those capabilities.

**Applicable Scenarios**:

- Deep customization requirements
- Implementation of complex business logic
- Need for flexible control over the execution flow

```python
# Python pseudo-code example
def main():
    # Execute the predefined JSON task
    result = tasker.post_task("Click Start Button").wait().get()
    
    if result.completed:
        # Execute code-level operations
        tasker.controller.post_click(100, 100)
    else:
        # Get the current screenshot
        image = tasker.controller.cached_image
        # Register a custom action
        tasker.resource.register_custom_action("MyAction", MyAction())
        # Execute a mixed task chain
        tasker.post_task("Click Confirm Icon").wait()
```

## Resource Preparation

After you confirm your development approach, prepare the corresponding resource files. The example below uses the project boilerplate as a baseline.

> [!TIP]
>
> - If you use the project boilerplate, follow the `TIP` marks below for a ready path.
> - If you choose full-code development, you still need resource files such as image assets and OCR models; otherwise related image-recognition features will be unavailable.

### File Structure Specification

> [!TIP]
>
> ⭐If you use the boilerplate, modify the [folder](https://github.com/MaaXYZ/MaaPracticeBoilerplate/tree/main/assets/resource) directly.

```tree
my_resource/
├── image/                # Image asset library
│   ├── my_button_ok.png
│   └── my_icon_close.png
├── model/
│   └── ocr/              # Text recognition models
│       ├── det.onnx
│       ├── keys.txt
│       └── rec.onnx
└── pipeline/             # Task pipelines
    ├── my_main.json
    └── my_subflow.json
```

You can modify the names of files and folders starting with "my_", but the others have fixed file names and should not be changed. Here's a breakdown:

### Task Pipeline

The files in `my_resource/pipeline` contain the main script execution logic and recursively read all JSON format files in the directory.

You can refer to the [Task Pipeline Protocol](3.1-PipelineProtocol.md) for writing these files. You can find a simple [demo](https://github.com/MaaXYZ/MaaFramework/blob/main/sample/resource/pipeline/sample.json) for reference.

Recommended tools:

- [JSON Schema](https://github.com/MaaXYZ/MaaFramework/blob/main/tools/pipeline.schema.json)
- [VSCode Extension](https://marketplace.visualstudio.com/items?itemName=nekosu.maa-support)
  - Config resources based on `interface.json`
  - Support going to task definition, finding task references, renaming task, completing task, click to launch task
  - Support launching as MaaPiCli
  - Support screencap and crop image after connected
- [MaaPipelineEditor](https://mpe.codax.site/stable/)
  - No-code visual editor; supports drag-and-drop nodes and JSON import/export

### Image Files

The files in `my_resource/image` are primarily used for template matching images, feature detection images, and other images required by the pipeline. They are read based on the `template` and other fields specified in the pipeline.

Use lossless source images scaled to 720p before cropping. Unless you're very familiar with MaaFramework's processing, use the capture tools below to obtain images.

- [Image Cropping and ROI Extraction Tool](https://github.com/MaaXYZ/MaaFramework/tree/main/tools/ImageCropper)
- [VSCode Extension](https://marketplace.visualstudio.com/items?itemName=nekosu.maa-support)
- [MFAToolsPlus](https://github.com/SweetSmellFox/MFAToolsPlus)

### Text Recognition Model Files

*⭐If you use the boilerplate, just follow the [steps](https://github.com/MaaXYZ/MaaPracticeBoilerplate?tab=readme-ov-file#%E5%A6%82%E4%BD%95%E5%BC%80%E5%8F%91) in their documentation.*

The files in `my_resource/model/ocr` are ONNX models obtained from [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR) after conversion.

You can use our pre-converted files: [MaaCommonAssets](https://github.com/MaaXYZ/MaaCommonAssets/tree/main/OCR). Choose the language you need and store them according to the [directory structure above](#file-structure-specification).

If needed, you can also fine-tune the official pre-trained models of PaddleOCR yourself (please refer to the official PaddleOCR documentation) and convert them to ONNX files for use. You can find conversion commands in [MaaCommonAssets/OCR](https://github.com/MaaXYZ/MaaCommonAssets/tree/main/OCR#command).

## Debug

After you finish preparing resources, you can start debugging.

> [!NOTE]
> If you choose full-code development, some tools in this section may not work; consider writing your own debug helpers instead.

[Development tools overview](https://github.com/MaaXYZ/MaaFramework/blob/main/README_en.md#development-tool)

Most tools will generate a `config/maa_option.json` file in the same directory, including:

- `logging`: Save the log and generate `debug/maafw.log`. Default true.
- `save_draw`: Save visualized image-recognition results during runtime. Default false.
- `stdout_level`: Console log level. Default 2 (Error); set 0 to silence logs, or 7 to show all logs.
- `save_on_error`: Save the current screenshot when a task fails. Default true.
- `draw_quality`: JPEG quality for visualized image-recognition results (0-100). Default 85.

If you integrate it yourself, you can enable debugging options through the `Toolkit.init_option` / `MaaToolkitConfigInitOption` interface. The generated json file is the same as above.

## Run

> [!NOTE]
> If you choose full-code development, the UI apps in this chapter may not work; consider writing your own interaction UI.

[General UI overview](https://github.com/MaaXYZ/MaaFramework/tree/main?tab=readme-ov-file#%E9%80%9A%E7%94%A8-ui)

We define a [ProjectInterface protocol](3.3-ProjectInterfaceV2.md) to describe the resource files and runtime configuration so General UI can correctly load and run your project.

*In short, write an `interface.json` to tell the General UI where your resources are and which tasks can be executed, so it can run for you.*

- [interface.json docs](3.3-ProjectInterfaceV2.md)
- [Example](https://github.com/MaaXYZ/MaaFramework/blob/main/sample/interface.json)

Best-practice references:

- [M9A](https://github.com/MaaXYZ/M9A/tree/main/assets/interface.json)

## Full-Code Development

Please refer to the [Integration Documentation](2.1-Integration.md) and the [Integrated Interface Overview](2.2-IntegratedInterfaceOverview.md).

## Project Packaging

If you need to package your project into an executable, refer to the following.

> [!TIP]
> If you use the [⭐ Project Template](https://github.com/MaaXYZ/MaaPracticeBoilerplate) for development, you can use the included CI workflow for packaging. See the relevant instructions in the template project for details.

For manual packaging, please refer to the documentation for each [General UI](/README_en.md#general-ui).

## Communication

Developers are welcome to join the official QQ group (595990173) for integration and development discussions. The group is reserved for engineering topics; product-usage support is not provided, and off-topic or spam accounts may be removed to keep the channel focused.
