MaaFW interface.json (PI V2) Development

interface.json is the standardized external declaration of a project: it is used by general-purpose GUIs, packaging and distribution, and toolchains to understand the project. All field semantics must be routed to the 3.3-ProjectInterfaceV2 protocol of MaaLLMWiki and the official schema (interface.schema.json), and should not be filled in from memory (when the

maallmwiki

skill is installed, it handles the complete routing process).

This document only covers three aspects that cannot be obtained via routing: selection decisions (when to use what), silent failure scenarios (field interactions that do not report errors but simply do not take effect), and processes and verification methods. Field dictionaries (enumerations, default values, field lists) are not duplicated here; all version annotations in this document are historical facts indicating "which version this mechanism was introduced in", not snapshots of the current version.

Dual-track versioning to avoid confusion:

interface_version

is fixed at the number

(the major version of the JSON structure, which is not modified for compatibility-related additions); the PI protocol has its own semantic version v2.x.y (evolved independently of MaaFW releases) — the latter is used to determine "whether a target Client supports a certain field". The current version of the protocol is subject to the original change log, and is not hard-coded.

Hard Guardrails

External Contract: Field changes = user-visible behavior changes; software updates follow the release convention specified in the
```
github
```
field (general-purpose UIs only update resource releases), and custom update channels should not be created.
resource / Bundle Layering (definitions are from the official glossary 1.2-Term Explanation; the "resource package" mentioned in the 3.3-ProjectInterfaceV2 protocol refers to resource entries, not Bundles):
- Bundle: A folder stored according to the standard structure of pipeline / model / image; each entry in
```
path[]
```
  points to a Bundle root directory (not a
```
pipeline/
```
  subdirectory), loaded in order, with later entries overriding earlier ones.
- resource Entry: A declaration unit (name / label / option), which is what users select in the Client.
- controller / resource declarations cannot be merged via import — the resource root is always declared by the main interface.
No Fabricated Fields: If you are unsure about enumerations, default values, or version support, route to the schema and original protocol text. It is better to write less and use defaults.
i18n Completeness: Keys starting with
```
$
```
must have corresponding keys in the translation file pointed to by
```
languages
```
; if
```
languages
```
is not configured, the default is only Chinese.
Secret Hygiene: interface.json is distributed with resources, so plaintext secrets must not be written into it;
```
password
```
input fields must not have
```
default
```
values (hard-rejected by the schema) and must not be included in presets (protocol recommendation, not validated by schema — relies on discipline).

Workflow

When writing from scratch, follow the order 1→7; when adding or modifying in an existing project, first refer to "Existing Project Modifications" below.

Skeleton:
```
interface_version: 2
```
+
```
name
```
/
```
version
```
; if adb screenshot/input methods are not configured, the framework will automatically detect and select the optimal one. Two decisions for controller (enumerations and default values are routed to the schema):
- Target form factor (Android device / desktop window / Mac app / gamepad...) determines the type.
- Screenshot scaling baseline (the resolution space where recognition and coordinates are located: short edge lock / long edge / Expand / original resolution) — this is the scaling of the framework's screenshots, not the game's own UI scaling; if nothing is configured, the default is 720px short edge (the baseline resolution of
```
maafw-pipeline
```
  is taken from here).
How to organize resource differences — choose one of four options:
- Let users choose → multiple resource entries (declaration layer).
- Overlay within the same resource → base Bundle + difference Bundle in
```
path[]
```
  , where the difference Bundle only contains override files.
- Bind differences to controller →
```
controller.attach_resource_path
```
  (v2.2.0+) is appended after all Bundles of this resource are loaded.
- The entire package only serves a specific controller → the
```
controller
```
  list of the resource entry (by name) — the Client only displays applicable resources for selection.
- Configure
```
hash
```
  verification for release (v2.6.0+). Note: the value is calculated only after loading Bundles in
  path
  — if the packaging script includes attached Bundles in the calculation, it will trigger false warnings; mismatch only gives a warning and does not block execution, can be skipped in debug/pre-release versions, and no verification is performed if not set.
Tasks: One task for each user-visible feature:
- ```
entry
```
  is the pipeline node name — this is a cross-file reference between interface and pipeline, not a file name.
- Use
```
group
```
  (v2.4.0+) for grouping when there are many features.
- Task-level
```
resource
```
  /
```
controller
```
  filtering is referenced by name (not type).
Options and Presets: Adjustable parameters are defined in the top-level
```
option
```
and then referenced level by level; for the override priority between task-level
```
pipeline_override
```
(hard-coded in this task, not user-selectable) and options, see options.md;
```
preset
```
(v2.3.0+) is a snapshot of task selections + option values. For control selection, declaration hierarchy, override order, and silent pitfalls, see references/options.md.
Child Processes — let the Client start programs for you, choose between two fields based on timing:
- Resident during task execution, handling Custom recognition/action logic →
```
agent
```
  (the Client starts a child process such as
```
python ./agent/main.py
```
  and communicates with it; for whether to use Custom, see
```
maafw-custom
```
  ).
- Run one-time preparation before connecting to the device (such as launching an emulator, environment self-check) →
```
pretask
```
  (v2.7.0+, the Controller is connected only after it finishes running, non-zero exit aborts startup); controller / resource filtering can be declared (v2.8.1+) — the protocol only stipulates that the Client may hide/gray out inapplicable items, but does not guarantee skipping execution. "Only run on a specific controller" must be judged within the program itself.
- The CWD of both is the directory where interface.json is located.
- ```
pretask.option
```
  only serializes option values as the last parameter passed to the program, and does not participate in pipeline_override merging.
- The agent child process reads Client-side context via
```
PI_*
```
  environment variables (v2.5.0+). Variables may be missing, so the child process needs fault tolerance.
Long-tail Fields:
```
setting
```
(settings partition),
```
telemetry
```
(telemetry), etc. — just know they exist, route to the original text when needed.
Splitting and Validation:
- Use
```
import[]
```
  for splitting when the task volume is large (see options.md for silent pitfalls).
- Run scripts for static validation: for projects with dev-tools (generated by create-maa-project), run
```
pnpm check
```
  — this validates interface.json, import fragments under
```
tasks/
```
  , and pipeline files of each Bundle against the official schema, catching typos in fields, illegal types and enumeration values (import fragments placed outside
```
tasks/
```
  are not in the validation scope); for projects without this infrastructure, fall back to editor schema association.
- Verify override targets for each option branch one by one (override is targeted by node name, renaming a node = silent disconnection).
- Runtime validation (Client can load, tasks can run through, override actually takes effect) is beyond the scope of this skill — hand over to
```
maafw-debug
```
  .

Existing Project Modifications

For renaming operations, first search the entire repository for references before proceeding — the consequences of missed modifications vary: missed option key name changes cause interface loading failure in the reference implementation (which can be caught), while most others result in silent disconnection:

Rename pipeline node:
```
task.entry
```
, task-level and option
```
pipeline_override
```
are all targeted by node name, so all must be synchronized (for other reference lists on the pipeline side, see the modification track of
```
maafw-pipeline
```
).
Rename option key / case name: missed key name change → reference implementation loading failure; missed case name change → preset values silently fail to apply. Reference scope: four levels of task / controller / resource / global_option,
```
setting[].option
```
,
```
pretask[].option
```
, and
```
option[]
```
in nested cases.
Add new import file: first check whether there are option keys with the same name in the main file and existing split files — if names are the same, the later imported file takes precedence, and the main file is overridden.

Review Checklist

```
interface_version
```
is 2; each
```
task.entry
```
is resolvable in the merged pipeline.
Option reference keys exist and match character by character — task-level dangling references directly cause loading failure (not silent) in the reference implementation, and invalid references in saved configurations are discarded after a warning.
Option applies to the current controller / resource — when not applicable, the entire option (including nested sub-items) silently fails (v2.3.1; the top cause of "option not taking effect" (empirical value), see applicability filtering in options.md for the mechanism).
For multi-level references to the same option, deduce the final value according to the override order (task > controller > resource > global, later overrides earlier); checkbox multiple cases are merged in definition order.
Each entry in
```
path[]
```
is a Bundle root directory (not a
```
pipeline/
```
subdirectory); no option keys with the same name in imports (same name takes precedence from later import).
```
languages
```
file exists and all
```
$
```
keys are fully covered; password has no default, is not included in presets, and there are no plaintext secrets in the entire file.
The version prerequisites of the fields used are compatible with the PI support version of the target Client. Verify item by item via routing — protocol inclusion ≠ schema / reference implementation / target Client already supports it. Test before release.

maafw-interface

NPX Install

Tags

SKILL.md Content (Chinese)

MaaFW interface.json (PI V2) Development

Hard Guardrails

Workflow

Existing Project Modifications

Review Checklist

Further Reading (As Needed)