# retoor <retoor@molodetz.nl>

from __future__ import annotations

from .spec import Action, Param


def arg(
    name: str, description: str, required: bool = False, kind: str = "string"
) -> Param:
    return Param(
        name=name,
        location="body",
        description=description,
        required=required,
        type=kind,
    )


DEVII = (
    "Controls devii, the on-screen avatar that is you rendered as a classic animated "
    "desktop character. Only effective in the web interface; in other interfaces it reports "
    "that no avatar is attached."
)

AVATAR_ACTIONS: tuple[Action, ...] = (
    Action(
        name="avatar_show",
        method="LOCAL",
        path="",
        summary="Show devii (yourself) on screen",
        description=DEVII,
        handler="avatar",
        requires_auth=False,
    ),
    Action(
        name="avatar_hide",
        method="LOCAL",
        path="",
        summary="Hide devii from the screen (plays a goodbye/hide animation)",
        description=(
            DEVII
            + " This already plays a goodbye animation, so do not queue a separate "
            "wave/goodbye animation immediately before calling it - hiding interrupts a still-"
            "queued animation."
        ),
        handler="avatar",
        requires_auth=False,
    ),
    Action(
        name="avatar_speak",
        method="LOCAL",
        path="",
        summary="Show a line of text in devii's speech balloon",
        description=DEVII,
        handler="avatar",
        requires_auth=False,
        params=(
            arg("text", "The text devii should say.", required=True),
            arg("hold", "Keep the balloon open until the next action.", kind="boolean"),
        ),
    ),
    Action(
        name="avatar_list_animations",
        method="LOCAL",
        path="",
        summary="List every animation the current character supports",
        description=DEVII,
        handler="avatar",
        requires_auth=False,
    ),
    Action(
        name="avatar_play_animation",
        method="LOCAL",
        path="",
        summary="Play a specific named animation (use avatar_list_animations first)",
        description=(
            DEVII
            + " A following avatar_hide or avatar_stop interrupts an animation that is "
            "still playing, so do not hide immediately after if you want it to finish."
        ),
        handler="avatar",
        requires_auth=False,
        params=(arg("name", "Exact animation name.", required=True),),
    ),
    Action(
        name="avatar_random_animation",
        method="LOCAL",
        path="",
        summary="Play a random non-idle animation to react expressively",
        description=DEVII,
        handler="avatar",
        requires_auth=False,
    ),
    Action(
        name="avatar_move_to",
        method="LOCAL",
        path="",
        summary="Walk devii to a pixel position on screen",
        description=DEVII,
        handler="avatar",
        requires_auth=False,
        params=(
            arg("x", "Target x in pixels.", required=True, kind="integer"),
            arg("y", "Target y in pixels.", required=True, kind="integer"),
            arg("duration", "Movement duration in milliseconds.", kind="integer"),
        ),
    ),
    Action(
        name="avatar_gesture_at",
        method="LOCAL",
        path="",
        summary="Make devii gesture toward a pixel position",
        description=DEVII,
        handler="avatar",
        requires_auth=False,
        params=(
            arg("x", "Target x in pixels.", required=True, kind="integer"),
            arg("y", "Target y in pixels.", required=True, kind="integer"),
        ),
    ),
    Action(
        name="avatar_get_viewport",
        method="LOCAL",
        path="",
        summary="Get the screen size and devii's current position",
        description=DEVII,
        handler="avatar",
        requires_auth=False,
    ),
    Action(
        name="avatar_stop",
        method="LOCAL",
        path="",
        summary="Stop all of devii's queued animations and speech immediately",
        description=DEVII,
        handler="avatar",
        requires_auth=False,
    ),
    Action(
        name="avatar_list_characters",
        method="LOCAL",
        path="",
        summary="List every character devii can appear as",
        description=DEVII,
        handler="avatar",
        requires_auth=False,
    ),
    Action(
        name="avatar_switch_character",
        method="LOCAL",
        path="",
        summary="Change which character devii is rendered as",
        description=DEVII,
        handler="avatar",
        requires_auth=False,
        params=(
            arg(
                "name",
                "Character name (e.g. Clippy, Merlin, Bonzi, Genie, Rover).",
                required=True,
            ),
        ),
    ),
)
