"""
Action: my_custom_action — TEMPLATE for creating new actions.
Copy this file to actions/my_custom_action.py and customize.

Requirements:
    - Class must be named 'Action'
    - Must have a unique 'name' attribute
    - Must have a 'run(self, ctx, params)' method
"""
import time


class Action:
    name = "my_custom_action"

    def run(self, ctx, params):
        """
        ctx provides:
            ctx["adb"]        — AdbClient (tap, swipe, keyevent, text, etc.)
            ctx["vision"]     — Vision (find_template, pixel_color, etc.)
            ctx["engine"]      — Engine (stop(), config)
            ctx["screenshot"]  — current screenshot (numpy BGR array)
            ctx["log"]         — logger (.info, .warning, .error)
            ctx["_templates_dir"] — path to templates/ directory

        params contains whatever the playbook passes, e.g.:
            params.get("x")
            params.get("y")
            params.get("message")
            params.get("my_param", "default_value")
        """

        # Example: read params and do something
        x = params.get("x", 100)
        y = params.get("y", 100)
        msg = params.get("message", "Custom action ran")

        # Log it
        ctx["log"].info("[%s] %s (x=%d, y=%d)", self.name, msg, x, y)

        # Do something with ADB
        ctx["adb"].tap(x, y)

        # Wait
        time.sleep(params.get("delay", 1.0))

        # You can also do template matching
        # from pathlib import Path
        # import os
        # tmpl = os.path.join(ctx["_templates_dir"], "my_template.png")
        # pos = ctx["vision"].find_template(tmpl, confidence=0.8)
        # if pos:
        #     ctx["adb"].tap(pos[0], pos[1])

        # Return value is ignored; set ctx keys for other actions to read
        ctx["_last_result"] = f"Done: {msg}"