Project Interface V2

Note: This document is about the creation and usage of ProjectInterface. In this document, PI refers to ProjectInterface and Client refers to the tool that can process PI.

Introduction

The so-called ProjectInterface is a standardized project structure declaration for MaaFramework. It currently consists of a single file, interface.json. By defining a PI, you can leverage various derivative tools of MaaFramework. Therefore, even if you intend to integrate solely using a general-purpose programming language, it is recommended to define a PI containing the basic information.

UI Support

• MFAAvalonia
• MaaPiCli
• MFW-CFA

interface.json

This file can be validated and receive hints via the schema file. When opening the project template folder with VSCode, the schema and file will be automatically associated.

Overall Structure

• interface_version number The interface version number, currently 2, fixed and required. Used to identify the ProjectInterface protocol version.

• languages object Multi-language support configuration. Keys are language codes, values are paths to corresponding translation files. If not specified, only Chinese is supported by default. File paths are relative to the directory containing interface.json.

  "languages": {
      "zh_cn": "interface_zh.json",
      "en_us": "interface_en.json"
  }

• name string The unique project identifier, used as the project ID.

• label string The project display name, shown in the user interface. Supports internationalized strings (starting with $). If not set, the value of the name field is displayed. Optional.

  {
    "name": "MyProject",
    "label": "$project_name"  // Internationalized project name
  }

• title string The window title. The Client will display this content directly without additional decoration. Optional, defaults to a combination of name and version. Supports internationalization (starting with $).

• icon string The application icon file path, relative to the project root directory. If not specified, the default icon is used. Supports internationalization (starting with $).

• mirrorchyan_rid string MirrorChyan resource package identifier, used for resource management and distribution.

• mirrorchyan_multiplatform boolean Whether multi-platform is supported, affecting resource package packaging and distribution strategies.

• github string The project's GitHub repository URL, used for version update checking and issue feedback. Software Update Convention:After painful lessons from version history, we expect general-purpose UIs to only provide update functionality for this GitHub release, not separate updates for the UI itself or MaaFW. Resource authors should package their specified UI/MaaFW when releasing, ensuring that a specific resource version on the user side corresponds to a unique UI and MaaFW version, avoiding various issues caused by version mixing.

• version string The project version number. The Client can display it to users and use it for version update checking.

• contact string Contact information, displayed on the "About" page. Supports file paths, URLs, or direct text. Content supports Markdown format. Supports internationalization (starting with $).

• license string Project license information, displayed on the "About" page. Supports file paths, URLs, or direct text. Content supports Markdown format. Supports internationalization (starting with $).

• welcome string Welcome message, displayed in a popup when the user first uses the application, can also be used as an announcement. Supports file paths, URLs, or direct text. Content supports Markdown format. The system records the displayed content and will show the popup again when the content is updated. Supports internationalization (starting with $).

• description string Project description information, displayed on the "About" page. Supports file paths, URLs, or direct text. Content supports Markdown format. Supports internationalization (starting with $).

• controller object[] Controller configuration, an array of objects containing preset controller information.

  • name string Unique name identifier, used as the controller ID.

  • label string Display name, shown in the user interface. Supports internationalized strings (starting with $). If not set, the value of the name field is displayed.

  • description string Detailed controller description. Supports file paths, URLs, or direct text. Content supports Markdown format. Optional. Supports internationalization (starting with $).

  • icon string Controller icon file path, relative to the project root directory. Optional. Supports internationalization (starting with $).

  • type 'Adb' | 'Win32' Controller type; valid values are Adb and Win32.

  • display_short_side number The short side length of the default scaled resolution, used for screen adaptation. Optional, defaults to 720. Mutually exclusive with display_long_side and display_raw.

  • display_long_side number The long side length of the default scaled resolution, used for screen adaptation. Optional. Mutually exclusive with display_short_side and display_raw.

  • display_raw boolean Whether to use the original resolution for screenshots without scaling. Optional, defaults to false. Mutually exclusive with scaled resolution settings.

  • adb object Specific configuration for the Adb controller.

    Note: In V2 protocol, the input/screencap methods for Adb controllers are automatically detected and selected by MaaFramework, no manual configuration required.

  • win32 object Specific configuration for the Win32 controller.

    • class_regex stringOptional. The regular expression used to search for window class names by the Win32 controller.

    • window_regex stringOptional. The regular expression used to search for window titles by the Win32 controller.

    • mouse stringOptional. The mouse control method for the Win32 controller. If not provided, the default is used. See Control Methods for details.

    • keyboard stringOptional. The keyboard control method for the Win32 controller. If not provided, the default is used. See Control Methods for details.

    • screencap stringOptional. The screenshot method for the Win32 controller. If not provided, the default is used. See Control Methods for details.

• resource object[] Resource configuration, an array of objects containing information about resource loading.

  • name string Unique name identifier, used as the resource package ID.

  • label string Display name, shown in the user interface. Supports internationalized strings (starting with $). If not set, the value of the name field is displayed. Optional.

  • description string Detailed resource description. Supports file paths, URLs, or direct text. Content supports Markdown format. Optional.

  • icon string Resource icon file path, relative to the project root directory. Optional. Supports internationalization (starting with $).

  • path string[] An array of paths to load. If multiple paths are provided, they will be loaded sequentially; resources loaded later will override those loaded earlier. File paths are relative to the directory containing interface.json. Note: Resources include not only pipeline but also image and model. Therefore, do not specify the pipeline directory directly.

  • controller string[]Optional. Specifies the list of controller types supported by this resource package. Array elements should correspond to the name field in the controller configuration. If not specified, all controller types are supported.

    When a user selects a controller, only resource packages that support that controller will be displayed in the user interface for selection. This allows providing specially optimized resource packages for different controller types.

    "resource": [
        {
            "name": "AndroidSpecificResource",
            "label": "$AndroidSpecificResource",
            "controller": ["Android"],
            "path": ["resource_android"]
        },
        {
            "name": "GeneralResource",
            "label": "$GeneralResource",
            "path": ["resource"]
        }
    ]

• agent object Agent configuration, an object containing information about the subprocess (AgentServer).

  • child_exec string The subprocess path, an executable file available in the system path. For example, if the Python path exists in the environment variables (system or user), you can simply write "python". CWD is the directory containing interface.json.

  • child_args string[]Optional. An array of arguments for the subprocess.

    "agent": {
        "child_exec": "python",
        "child_args": [
            "./agent/main.py",              // Note: CWD is the directory containing interface.json
            "--test-mode"                   // Fixed string, passed as-is
        ]
    }

  • identifier stringOptional. A connection identifier used to create a communication socket. If provided, it will be used; otherwise, one is created automatically.

• task object[] Task configuration, an array of objects containing information about executable tasks.

  • name string Unique task identifier, used as the task ID.

  • label string Task display name, shown in the user interface. Supports internationalized strings (starting with $). If not set, the value of the name field is displayed. Optional.

  • entry string The task entry, which is the name of the Task in the pipeline.

  • default_check boolean Whether this task is selected by default. Optional, defaults to false. The Client will use this value to determine whether to check this task by default during initialization.

  • description string Detailed task description to help users understand the task's functionality. Supports file paths, URLs, or direct text. Content supports Markdown format. Optional.

  • icon string Task icon file path, relative to the project root directory. Used for display in the user interface. Optional. Supports internationalization (starting with $).

  • resource string[]Optional. Specifies the list of resource packages supported by this task. Array elements should correspond to the name field in the resource configuration. If not specified, this task is available in all resource packages.

    When a user selects a resource package, only tasks that support that resource package will be displayed in the user interface for selection. This allows providing specialized task configurations for different resource packages, such as event tasks that are only available in specific resource packages.

    "task": [
        {
            "name": "EventTask",
            "label": "$EventTask",
            "entry": "ActivityTask",
            "resource": ["Official"],
            "description": "Event task only available in the Official resource package"
        },
        {
            "name": "CommonTask",
            "label": "$CommonTask",
            "entry": "CommonTask"
        }
    ]

  • pipeline_override pipelineOptional. Task parameters that override the loaded resources when executing the task. This structure is exactly the same as the JSON file in the pipeline and must include the task name part, for example:

    "pipeline_override": {
        "Quit": {
            "enabled": true
        }
    }

  • option string[]Optional. Task configuration options, an array containing keys from subsequent option objects. The Client will prompt the user to make selections based on these.

    The Client can display the options in the order provided in the option array.

• option record<string, object> Definition of configuration options, an object mapping containing information about each option.

  • key Unique name identifier; tasks will reference this name.

  • type string The option type. Optional, defaults to "select". Valid values:

    • "select": Dropdown selection box, user selects from predefined options
    • "input": User input field, allows manual input
    • "switch": Toggle switch, Yes or No

  • label string Option display label, shown in the user interface. Supports internationalized strings (starting with $). Optional.

  • description string Detailed option description to help users understand the option's purpose. Supports file paths, URLs, or direct text. Content supports Markdown format. Optional. Supports internationalization (starting with $).

  • icon string Option icon file path, relative to the project root directory. Optional. Supports internationalization (starting with $).

  • cases object[] Used only when type is "select" or "switch". Available options, an array of objects containing information about each option.

    Note: When type is "switch", only two cases are supported, and the following rules must be followed:

    • If case.name is one of "Yes", "yes", "Y", or "y", that case will be recognized as the Yes option
    • Other case.name values will be recognized as the No option
    • The Client will match the user's Y/N input based on the case's name

    It is recommended to use "Yes" and "No" as the names of the two cases to ensure consistency across different Clients.

    The Client can display the options in the order provided in the cases array.

    • name string Unique option identifier, used as the option ID.

    • label string Option display name, shown in the user interface. Supports internationalized strings (starting with $). If not set, the value of the name field is displayed. Optional.

    • description string Detailed option description. Supports file paths, URLs, or direct text. Content supports Markdown format. Optional. Supports internationalization (starting with $).

    • icon string Option icon file path, relative to the project root directory. Optional. Supports internationalization (starting with $).

    • option string[] Sub-option list. Optional. These sub-options are only displayed when the user selects the current option. These sub-options are also defined in the outer option and support unlimited nesting.

    • pipeline_override pipeline Same as the pipeline_override in the task. It takes effect when the option is activated.

  • inputs object[] Used only when type is "input". Input configuration, an array of objects defining user-inputtable fields.

    • name string Unique input field identifier, used as the input field ID.

    • label string Input field display name, shown in the user interface. Supports internationalized strings (starting with $). If not set, the value of the name field is displayed. Optional.

    • description string Detailed input field description to help users understand input requirements. Supports file paths, URLs, or direct text. Content supports Markdown format. Optional. Supports internationalization (starting with $).

    • default string Default value for the input field. Optional.

    • pipeline_type string The data type of the input field in pipeline_override. Valid values: "string", "int", "bool". When using variable substitution in pipeline_override, type conversion is performed according to this type.

    • verify string Regular expression used to validate whether user input is valid. Optional.

    • pattern_msg string Message displayed when regex validation of user input fails. Optional. Supports internationalization (starting with $).

  • pipeline_override pipeline Used when the option type is "input", as a substitution template for user input content. Supports using {name} format in strings to reference input field values. Optional.

  • default_case string Default option name, used only when type is "select". The Client can use this value as the initial selected value for the option. Optional.

Option Examples

Select Type Option Example

{
  "option": {
    "BattleStage": {
      "type": "select",
      "label": "$SelectBattleStage",
      "description": "Select the stage to farm",
      "default_case": "3-9 Dire",
      "cases": [
        {
          "name": "3-9 Dire (Lark)",
          "label": "$3-9Dire",
          "description": "Farm Lark",
          "icon": "lark.png",
          "option": [
            "UseSanityPotion",
            "AfterFarmingXXX"
          ],
          "pipeline_override": {
            "EnterTheShow": {
              "next": "MainChapter_3"
            }
          }
        }
      ]
    }
  }
}

Input Type Option Example

{
  "option": {
    "CustomStage": {
      "type": "input",
      "label": "Custom Stage",
      "description": "Choose which stage to play",
      "icon": "wrench.png",
      "inputs": [
        {
          "name": "ChapterNumber",
          "label": "$ChapterNumber",
          "description": "Stage chapter number, use Arabic numerals",
          "default": "4",
          "pipeline_type": "string",
          "verify": "^\\d+$"
        },
        {
          "name": "Timeout",
          "label": "$Timeout",
          "description": "Wait timeout duration",
          "default": "20000",
          "pipeline_type": "int",
          "verify": "^\\d+$"
        }
      ],
      "pipeline_override": {
        "EnterTheShow": {
          "next": "MainChapter_{ChapterNumber}",
          "timeout": "{Timeout}"
        }
      }
    }
  }
}

Internationalization Support

For all string fields that support internationalization, if the string starts with $, it indicates that the string is an internationalized string. The Client needs to read the actual value from the translation file before displaying it.

For example:

{
  "name": "MyDemo3",
  "label": "$MyDemo3",
  "controller": [
    {
      "name": "Android",
      "label": "$Android"
    }
  ]
}

Corresponding translation file (e.g., interface_en.json):

{
  "MyDemo3": "My Demo 3",
  "Android": "Android Device"
}

Resource Override

If a later-loaded resource contains a task with the same name as one already loaded, the tasks will be merged. Generally, the top-level keys of the new task will replace those of the old task. For example:

Old Task

{
    "task1": {
        "enabled": false,
        "recognition": "DirectHit",
        "next": [ "T1", "T2" ]
    }
}

New Task

{
    "task1": {
        "enabled": true,
        "action": "Click",
        "next": [ "T2", "T3" ]
    }
}

Merged Task

{
    "task1": {
        "enabled": true,
        "recognition": "DirectHit",
        "action": "Click",
        "next": [ "T2", "T3" ]       // Direct replacement; inner arrays/lists are not merged.
    }
}

Node Notification Handling

MaaFramework sends node notifications via callback functions during task execution. The Client needs to implement the corresponding handling logic to display task execution status to users.

Callback Function Signature

The Client needs to register a callback function to receive notifications. For the function signature, refer to MaaDef.h:

typedef void(MAA_CALL* MaaEventCallback)(
    void* handle,
    const char* message,
    const char* details_json,
    void* trans_arg
);

• message: Message type identifier (e.g., Node.Action.Starting, Node.Recognition.Succeeded, etc.)
• details_json: JSON string containing specific data

Message Template Mechanism

Resource authors can configure message templates in the Pipeline using the focus field. When the Client receives a callback, it should perform placeholder replacement based on the template and display the result to users.

Pipeline Configuration Example:

{
  "NodeA": {
    "focus": {
      "Node.Recognition.Succeeded": "{name} recognition hit, ready to start execution",
      "Node.Action.Starting": "{name} starts execution, task ID: {task_id}"
    }
  }
}

Callback Function Parameters Example:

// message parameter:
"Node.Action.Starting"

// details_json parameter (after parsing):
{
    "task_id": 12345,
    "action_id": 11111,
    "name": "NodeA",
    "focus": {
        "Node.Recognition.Succeeded": "{name} recognition hit, ready to start execution",
        "Node.Action.Starting": "{name} starts execution, task ID: {task_id}"
    }
}

Client Processing Flow

1. Parse the details_json parameter in the callback function
2. Check if the parsed object contains a focus field
3. If present, find the corresponding template string in focus based on the message parameter
4. Replace placeholders in the template (e.g., {name}, {task_id}) with data from details_json
5. Display the processed text to the user

Using the example above, the final display should be: NodeA starts execution, task ID: 12345

More Message Types

For a complete list of callback messages and detailed descriptions, please refer to Callback Protocol and MaaMsg.h.