---

name: custom-actions description: "Guides MaaNTE Python CustomAction and CustomRecognition development, MaaFramework binding usage, registration, logging, maafocus, controllers, and registry checks." disable-model-invocation: true metadata: disco-role: operating license: AGPL 3.0

Custom Actions

Use This When

Use this sub-skill for work under agent/custom/action/, agent/utils/, or agent/main.py, especially when adding or debugging MaaFramework Python custom actions/recognitions.

Typical prompts:

• Add a new Python action for Pipeline logic that JSON cannot express.
• Diagnose an unknown custom_action or missing registration.
• Fix action parameter parsing, long-running loop stop behavior, key release, or screenshot handling.
• Decide whether code belongs in Pipeline JSON or Python.
• Use MaaFramework Context, direct recognition, controller APIs, logging, or maafocus messages.

Read First

1. references/custom-action-api.md for architecture, verified signatures, parameter parsing, controller calls, and registration rules.
2. references/logging-and-user-messages.md for utils.logger, maafocus.PrintT, and why print() is usually wrong in actions.
3. references/troubleshooting.md for platform imports, optional dependencies, stuck loops, and custom action mismatch symptoms.
4. Run scripts/check_custom_action_registry.py to scan decorators, Pipeline references, and __all__ exports.

Architecture Rule

Pipeline owns flow control. Python owns the hard parts: image algorithms, state machines, audio/MIDI processing, path navigation, network/route services, and cross-node data persistence. Do not move ordinary screen transitions into Python unless Pipeline cannot express the logic.

Registration Checklist

• Decorate with exactly the name used by Pipeline:

  @AgentServer.custom_action("my_action")
  class MyAction(CustomAction): ...
  

• For recognitions:

  @AgentServer.custom_recognition("my_recognition")
  class MyRecognition(CustomRecognition): ...
  

• Import the module in agent/custom/action/__init__.py and add public classes to __all__ when they are part of the registry surface.

• Ensure a Pipeline node calls the same custom_action or custom_recognition string.

Implementation Checklist

• Parse argv.custom_action_param as None, dict, or JSON string; reject invalid types gracefully.
• Use context.tasker.controller.post_screencap().wait() or .wait().get() consistently, then read the cached/current image shape before indexing.
• Check context.tasker.stopping in long loops and release held keys/buttons in finally.
• Return CustomAction.RunResult(success=True/False); do not leak uncaught tracebacks to users.
• Use context.run_recognition or run_recognition_direct when Python must reuse Pipeline recognizers.
• Keep coordinates and ROI assumptions at 1280×720.
• Avoid platform-specific imports at module import time when possible; wrap Windows/audio/backend imports or document the platform requirement.

High-Risk Existing Patterns

• auto_piano/maa_keyboard.py imports ctypes.windll.user32 at module import time; it is Windows-only.
• SoundTrigger/SoundListener.py imports soundcard, which may fail on headless Linux without an audio service.
• Navi coordinate capture depends on a Windows .pyd and capture backend; import/runtime errors need clear messages.
• PinkPaw Heist actions hold keys/buttons and use long timed route sequences; always preserve stop checks and release logic.
• Dataset recording uses ctypes.windll.user32.GetAsyncKeyState and writes image sequences; it is not a harmless import-only workflow on non-Windows.

Validation

Use safe checks first:

python sub-skills/custom-actions/scripts/check_custom_action_registry.py --repo-root .
python -m py_compile agent/custom/action/**/*.py

A successful import or compile does not prove a live game action works. For actual task verification, use the relevant gameplay/navigation/media sub-skill and a Windows MaaFramework runtime.