motioninput-tui 0.1.0__py3-none-any.whl

motioninput_tui/__init__.py

@@ -0,0 +1,9 @@
+"""Python App motioninput-tui."""
+
+from .constants import PROGRAM_NAME, PROGRAM_REPO_URL, PROGRAM_VERSION
+
+__all__ = [
+    "PROGRAM_NAME",
+    "PROGRAM_REPO_URL",
+    "PROGRAM_VERSION",
+]

motioninput_tui/__main__.py

@@ -0,0 +1,179 @@
+"""Main entrypoint."""
+
+import argparse
+import sys
+from pathlib import Path
+
+from rich import traceback
+
+from .config import Config, config_path
+from .constants import PROGRAM_NAME, PROGRAM_NAME_WITH_FULL_VERSION, PROGRAM_NAME_WITH_VERSION
+from .controls.layouts import DEFAULT_LAYOUT, available_layouts
+from .engine.recognizer import BufferPolicy
+from .games.loader import GameDataMissingError, available_games, load_game
+from .games.rulesets import GAME_SPECS
+from .terminal import detect, query_support
+from .utils.logger import get_logger, setup_logger_cli
+
+traceback.install(extra_lines=2)
+logger = get_logger(__name__)
+
+
+def _get_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(prog=PROGRAM_NAME, description="Fighting game motion input trainer.")
+    parser.add_argument("--game", choices=sorted(GAME_SPECS), help="Skip the game picker.")
+    parser.add_argument("--character", help="Skip the character picker. Needs --game.")
+    parser.add_argument(
+        "--layout",
+        choices=sorted(layout.key for layout in available_layouts()),
+        default=None,
+        help=f"Control layout (default: last used, or {DEFAULT_LAYOUT}).",
+    )
+    parser.add_argument(
+        "--no-key-release",
+        action="store_true",
+        help="Do not ask the terminal for key release reporting; infer holds from auto-repeat instead.",
+    )
+    parser.add_argument(
+        "--loose-buffer",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Do not spend inputs when a move comes out, so one motion can feed several moves. "
+        "Not how the games behave; it is also in the trainer's settings, ctrl+b. Default: last used.",
+    )
+    parser.add_argument(
+        "--config",
+        type=Path,
+        default=None,
+        help=f"Config file holding the last used selection (default: {config_path()}).",
+    )
+    parser.add_argument("--list", action="store_true", help="List games and characters, then exit.")
+    parser.add_argument("--check-terminal", action="store_true", help="Report terminal suitability, then exit.")
+    parser.add_argument("--version", action="version", version=PROGRAM_NAME_WITH_FULL_VERSION)
+    parser.add_argument("-v", action="count", default=0, help="Increase verbosity (can be used multiple times).")
+    return parser.parse_args()
+
+
+def _print_terminal() -> int:
+    info = detect()
+    logger.info("Terminal: %s (%s, %s)", info.name, info.speed, info.detail)
+    if info.warning():
+        logger.warning("%s", info.warning())
+    else:
+        logger.info("Should be fast enough for accurate input timing.")
+
+    releases = query_support()
+    if releases is None:
+        logger.info("Key releases: could not ask, no terminal attached.")
+    elif releases:
+        logger.info("Key releases: supported. Holds will be tracked exactly.")
+    else:
+        logger.warning(
+            "Key releases: not supported. Holds will be inferred from auto-repeat, "
+            "so charge moves depend on your keyboard repeat delay. "
+            "Terminals that do support this: Ghostty, Alacritty, WezTerm, kitty, foot, Contour, Rio."
+        )
+    return 0
+
+
+def _print_roster() -> int:
+    for game in available_games():
+        logger.info("%s - %s", game.key, game.name)
+        for character in game.characters:
+            # The input display's "characters" are button sets, with no moves
+            # to count, so they say what they are instead.
+            if character.moves:
+                logger.info("    %-22s %d trainable moves", character.key, len(character.trainable_moves))
+            else:
+                logger.info("    %-22s %s", character.key, character.name)
+    return 0
+
+
+def main() -> int:
+    """Main entrypoint."""
+    args = _get_args()
+    setup_logger_cli(args.v)
+    logger.debug("%s", PROGRAM_NAME_WITH_VERSION)
+
+    if args.check_terminal:
+        return _print_terminal()
+    if args.list:
+        return _print_roster()
+
+    if args.character and not args.game:
+        logger.error("--character needs --game as well")
+        return 2
+
+    config = Config.load(args.config)
+    _apply_overrides(config, args)
+
+    if not _resolve_selection(config, from_cli=bool(args.character)):
+        return 1
+
+    info = detect()
+    if info.should_warn:
+        logger.warning("%s", info.warning())
+
+    # Ask before the interface takes over the terminal, so holds are tracked
+    # exactly from the very first keystroke rather than from the first release.
+    key_release = False if args.no_key_release else bool(query_support())
+    if key_release:
+        logger.debug("Terminal reports key releases; holds will be tracked exactly")
+    else:
+        logger.info("Terminal does not report key releases; holds will be inferred from auto-repeat")
+
+    from .tui import MotionInputApp  # ruff: ignore[import-outside-top-level] - importing textual is slow, only do it when running the app
+
+    MotionInputApp(
+        config,
+        key_release=key_release,
+        skip_setup=bool(args.game and args.character),
+    ).run()
+    return 0
+
+
+def _resolve_selection(config: Config, *, from_cli: bool) -> bool:
+    """Check the selection against the rosters. False means do not start.
+
+    A remembered character can simply be gone: rosters are regenerated, and a
+    name override in ``motioninput_tui_datagen/names.py`` renames the key with the character.
+    That is no reason to refuse to start, so the selection is dropped and the
+    picker opens on it instead. A character named on the command line is
+    different, and still gets an error.
+    """
+    if not config.game:
+        return True
+    try:
+        game = load_game(config.game)
+    except GameDataMissingError as exc:
+        logger.error("%s", exc)  # ruff: ignore[error-instead-of-exception] - a traceback helps nobody here
+        return False
+    if not config.character:
+        return True
+    try:
+        config.character = game.character(config.character).key
+    except KeyError as exc:
+        if from_cli:
+            logger.error("%s", exc)  # ruff: ignore[error-instead-of-exception] - a traceback helps nobody here
+            return False
+        logger.info("Forgetting the saved character, it is not in the roster any more: %s", exc)
+        config.character = None
+    return True
+
+
+def _apply_overrides(config: Config, args: argparse.Namespace) -> None:
+    """Let command line arguments win over what was remembered."""
+    if args.game:
+        config.game = args.game
+        # Not the character from whatever game was being played last: whoever
+        # was last trained on this one. --character always wins, and cannot be
+        # given without --game.
+        config.character = args.character or config.characters.get(args.game)
+    if args.layout:
+        config.layout = args.layout
+    if args.loose_buffer is not None:
+        config.buffer_policy = BufferPolicy.LOOSE if args.loose_buffer else BufferPolicy.CONSUME
+
+
+if __name__ == "__main__":
+    sys.exit(main())  # pragma: no cover

motioninput_tui/config.py

@@ -0,0 +1,246 @@
+"""Remembering the last used selection between runs.
+
+Stored as JSON under the XDG config directory, which is
+``~/.config/motioninput-tui/config.json`` unless ``XDG_CONFIG_HOME`` says
+otherwise. Nothing here is essential: a missing, unreadable or corrupt file
+just means the defaults are used, and a config that cannot be written is
+logged and ignored rather than interrupting a training session.
+"""
+
+import json
+import os
+import re
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .controls.layouts import DEFAULT_LAYOUT, KEYBOARD_DEFAULT_BINDINGS, LAYOUTS
+from .engine.recognizer import BufferPolicy
+from .notation_styles import STYLES
+from .utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+APP_DIR_NAME = "motioninput-tui"
+CONFIG_FILENAME = "config.json"
+
+
+def config_dir() -> Path:
+    """The directory holding the config file."""
+    override = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(override).expanduser() if override else Path.home() / ".config"
+    return base / APP_DIR_NAME
+
+
+def config_path() -> Path:
+    """The config file itself."""
+    return config_dir() / CONFIG_FILENAME
+
+
+@dataclass(slots=True)
+class Config:
+    """What the trainer remembers between runs.
+
+    ``key_release`` is deliberately not stored. It is probed per terminal on
+    every launch, so remembering it would disable exact tracking after moving
+    to a different terminal.
+    """
+
+    game: str | None = None
+    character: str | None = None
+    characters: dict[str, str] = field(default_factory=dict)
+    """Who was last trained on each game, ``{game key: character key}``.
+    :meth:`save` folds the current selection in, so coming back to a game comes
+    back to the character as well."""
+    layout: str = DEFAULT_LAYOUT
+    buffer_policy: BufferPolicy = BufferPolicy.CONSUME
+    lenient_half_circles: bool = True
+    """Whether a half circle may skip straight down. See
+    :mod:`motioninput_tui.settings`."""
+    neo_geo_slant: bool = False
+    """Whether the Neo Geo's four buttons are arranged as the arcade slants
+    them. See :mod:`motioninput_tui.controls.buttons`."""
+    notation: dict[str, str] = field(default_factory=dict)
+    """How each family of motions is written, ``{family: style}``. Empty means
+    the plain default. See :mod:`motioninput_tui.notation_styles`."""
+    gamepad_bindings: dict[str, str] = field(default_factory=dict)
+    """The player's gamepad attack rebinds, ``{button name: pad code}``. Empty
+    means the built-in default. :func:`~.controls.layouts.gamepad_layout` has
+    the final say on which entries are usable."""
+    keyboard_bindings: dict[str, str] = field(default_factory=dict)
+    """The custom keyboard layout's rebinds, ``{slot: key name}`` over the four
+    movement axes and the six attacks. Empty means the built-in default;
+    :func:`~.controls.layouts.keyboard_layout` has the final say."""
+    path: Path | None = None
+    """Where this was loaded from, and where :meth:`save` writes back to."""
+
+    @property
+    def loose_buffer(self) -> bool:
+        """The buffer policy as a plain on/off, which is how it is presented.
+
+        The settings pane treats every setting as a boolean attribute, and
+        ``buffer_policy`` is the one that is really an enum, so it is bridged
+        here rather than special cased there.
+        """
+        return self.buffer_policy is BufferPolicy.LOOSE
+
+    @loose_buffer.setter
+    def loose_buffer(self, on: bool) -> None:
+        self.buffer_policy = BufferPolicy.LOOSE if on else BufferPolicy.CONSUME
+
+    @classmethod
+    def load(cls, path: Path | None = None) -> Config:
+        """Read the saved config, falling back to defaults on any problem."""
+        target = path or config_path()
+        try:
+            with target.open(encoding="utf-8") as handle:
+                raw = json.load(handle)
+        except FileNotFoundError:
+            return cls(path=target)
+        except (OSError, json.JSONDecodeError) as exc:
+            logger.warning("Ignoring unreadable config at %s: %s", target, exc)
+            return cls(path=target)
+
+        if not isinstance(raw, dict):
+            logger.warning("Ignoring config at %s: expected an object", target)
+            return cls(path=target)
+        return cls(
+            game=_optional_str(raw.get("game")),
+            character=_optional_str(raw.get("character")),
+            characters=_valid_characters(raw.get("characters")),
+            layout=_valid_layout(raw.get("layout")),
+            buffer_policy=_valid_policy(raw.get("buffer_policy")),
+            lenient_half_circles=_valid_flag(raw.get("lenient_half_circles"), default=True),
+            neo_geo_slant=_valid_flag(raw.get("neo_geo_slant"), default=False),
+            notation=_valid_notation(raw.get("notation")),
+            gamepad_bindings=_valid_gamepad_bindings(raw.get("gamepad_bindings")),
+            keyboard_bindings=_valid_keyboard_bindings(raw.get("keyboard_bindings")),
+            path=target,
+        )
+
+    def save(self, path: Path | None = None) -> bool:
+        """Write the config. Returns False if it could not be saved."""
+        target = path or self.path or config_path()
+        if self.game and self.character:
+            self.characters[self.game] = self.character
+        payload = {
+            "game": self.game,
+            "character": self.character,
+            "characters": self.characters,
+            "layout": self.layout,
+            "buffer_policy": str(self.buffer_policy),
+            "lenient_half_circles": self.lenient_half_circles,
+            "neo_geo_slant": self.neo_geo_slant,
+            "notation": self.notation,
+            "gamepad_bindings": self.gamepad_bindings,
+            "keyboard_bindings": self.keyboard_bindings,
+        }
+        try:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            _write_atomic(target, json.dumps(payload, indent=2) + "\n")
+        except OSError as exc:
+            logger.warning("Could not save config to %s: %s", target, exc)
+            return False
+        logger.debug("Saved config to %s", target)
+        return True
+
+
+def _write_atomic(target: Path, text: str) -> None:
+    """Write via a temporary file so an interrupted run cannot truncate it."""
+    handle = tempfile.NamedTemporaryFile(  # ruff: ignore[open-file-with-context-handler] - closed before the rename
+        "w",
+        encoding="utf-8",
+        dir=target.parent,
+        prefix=f".{target.name}.",
+        delete=False,
+    )
+    temporary = Path(handle.name)
+    try:
+        with handle:
+            handle.write(text)
+        temporary.replace(target)
+    except OSError:
+        temporary.unlink(missing_ok=True)
+        raise
+
+
+def _optional_str(value: object) -> str | None:
+    return value if isinstance(value, str) and value else None
+
+
+_LAYOUT_ALIASES = {"hitbox": "keyboard-left", "southpaw": "keyboard-right"}
+"""The keyboard layouts that were replaced, mapped to their nearest successor so
+a config from before the change still opens somewhere sensible."""
+
+
+def _valid_layout(value: object) -> str:
+    # An unavailable layout (gamepad without the extra installed) falls back,
+    # so a stale config cannot drop the trainer into a dead input mode.
+    if isinstance(value, str):
+        value = _LAYOUT_ALIASES.get(value, value)
+    if isinstance(value, str) and value in LAYOUTS and LAYOUTS[value].available:
+        return value
+    return DEFAULT_LAYOUT
+
+
+def _valid_keyboard_bindings(value: object) -> dict[str, str]:
+    # Best-effort like the rest of the loader; keyboard_layout is authoritative.
+    if not isinstance(value, dict):
+        return {}
+    return {
+        slot: key
+        for slot, key in value.items()
+        if isinstance(slot, str) and slot in KEYBOARD_DEFAULT_BINDINGS and isinstance(key, str) and key
+    }
+
+
+def _valid_characters(value: object) -> dict[str, str]:
+    # Best-effort like the rest of the loader; a character who has since left
+    # the roster is dealt with by the picker falling back to the first one.
+    if not isinstance(value, dict):
+        return {}
+    return {
+        game: character
+        for game, character in value.items()
+        if isinstance(game, str) and game and isinstance(character, str) and character
+    }
+
+
+def _valid_flag(value: object, *, default: bool) -> bool:
+    """A saved on/off, ignoring anything that is not one."""
+    return value if isinstance(value, bool) else default
+
+
+def _valid_policy(value: object) -> BufferPolicy:
+    try:
+        return BufferPolicy(value)
+    except ValueError:
+        return BufferPolicy.CONSUME
+
+
+def _valid_notation(value: object) -> dict[str, str]:
+    # Styles come and go as the notation menu grows, so an entry naming one
+    # that is not there any more is dropped rather than left to draw nothing.
+    if not isinstance(value, dict):
+        return {}
+    known = {family.value: {style.key for style in styles} for family, styles in STYLES.items()}
+    return {
+        family: style
+        for family, style in value.items()
+        if isinstance(family, str) and isinstance(style, str) and style in known.get(family, ())
+    }
+
+
+_PAD_CODE = re.compile(r"^pad:\d+$")
+
+
+def _valid_gamepad_bindings(value: object) -> dict[str, str]:
+    # Best-effort, like the rest of the loader: keep the entries that look sane
+    # and drop the rest. gamepad_layout does the authoritative check.
+    if not isinstance(value, dict):
+        return {}
+    return {
+        key: code
+        for key, code in value.items()
+        if isinstance(key, str) and isinstance(code, str) and _PAD_CODE.match(code)
+    }

motioninput_tui/constants.py

@@ -0,0 +1,41 @@
+"""Version tracking within the package."""
+
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+PROGRAM_NAME = Path(__file__).parent.name.replace("_", "-").lower()  # Calculate this
+PROGRAM_REPO_URL = "https://github.com/kism/motioninput-tui"
+try:
+    PROGRAM_VERSION = version(PROGRAM_NAME)
+except PackageNotFoundError:  # pragma: no cover
+    PROGRAM_VERSION = "<unknown, please run uv sync>"
+
+
+def _get_version_str() -> str:
+    """Get a string representation of the version, including branch and commit hash."""
+    repo_root = Path(__file__).parent.parent
+    git_head_log = repo_root / ".git" / "logs" / "HEAD"
+    git_head = repo_root / ".git" / "HEAD"
+    last_commit = ""
+    current_branch = ""
+
+    if git_head_log.is_file():
+        with git_head_log.open("r") as f:
+            lines = f.readlines()
+            if lines:
+                last_commit = lines[-1].strip().split(" ")[1][:7]  # Get the new commit hash, first 7 characters
+
+    if git_head.is_file():
+        with git_head.open("r") as f:
+            current_branch = f.read().strip().split("/")[-1]
+
+    return (
+        f"{PROGRAM_NAME} "
+        f"v{PROGRAM_VERSION}"
+        f"{('-' + current_branch) if current_branch and (last_commit not in current_branch) else ''}"
+        f"{('/' + last_commit + '') if last_commit else ''}"
+    )
+
+
+PROGRAM_NAME_WITH_VERSION = f"{PROGRAM_NAME} v{PROGRAM_VERSION}"
+PROGRAM_NAME_WITH_FULL_VERSION = _get_version_str()

motioninput_tui/controls/__init__.py

@@ -0,0 +1 @@
+"""Physical control layouts and the input sources that read them."""

motioninput_tui/controls/buttons.py

@@ -0,0 +1,131 @@
+"""Button sets: how many attack buttons a game has, and what they are called.
+
+A layout says where your fingers go; a set says what those positions mean. They
+are kept apart so that adding a game with a different panel is a table entry
+rather than a new layout for every keyboard arrangement.
+
+A set is rows of buttons, laid onto the layout's rows of attack keys in order.
+On the southpaw layout, whose attack keys are ``asdf`` over ``zxcv``, that gives:
+
+    Street Fighter   asd zxc     LP MP HP over LK MK HK
+    Mortal Kombat    asd zx      HP HK BL over LP LK, the modern pad mapping
+    Neo Geo          asdf zxcv   A B C D, the same four on both rows
+    Neo Geo slant    zx as       A B on the bottom row, C D above them
+    Tekken           as zx       □ △ over ✕ ○
+    Eight button     asdf zxcv   1-8
+
+The Neo Geo has two arrangements in circulation, so which one is used is the
+player's choice: :func:`arrangement` applies it.
+"""
+
+from dataclasses import dataclass
+
+from motioninput_tui.engine.notation import Button
+
+_B = Button
+
+
+@dataclass(frozen=True, slots=True)
+class ButtonSet:
+    """The attack buttons of one game's panel, in rows.
+
+    Attributes:
+        key: What is saved in the config, and the pseudo-character key the
+            input display is picked with.
+        name: What the pickers call it.
+        rows: Buttons in panel order, top row first. A row is laid onto the
+            matching row of the layout's attack keys, so a row longer than the
+            layout has keys for simply runs out. The same button may appear
+            twice, which is how the Neo Geo gets its second row.
+        note: One line on where the arrangement comes from.
+    """
+
+    key: str
+    name: str
+    rows: tuple[tuple[Button, ...], ...]
+    note: str = ""
+
+    @property
+    def buttons(self) -> tuple[Button, ...]:
+        """Every button once, in panel order."""
+        seen: dict[Button, None] = {}
+        for row in self.rows:
+            for button in row:
+                seen.setdefault(button, None)
+        return tuple(seen)
+
+
+STREET_FIGHTER = ButtonSet(
+    key="street-fighter",
+    name="Street Fighter, 6 button",
+    rows=((_B.LP, _B.MP, _B.HP), (_B.LK, _B.MK, _B.HK)),
+    note="Three punches over three kicks.",
+)
+
+MORTAL_KOMBAT = ButtonSet(
+    key="mortal-kombat",
+    name="Mortal Kombat, 5 button",
+    # Not the arcade panel: this is how modern Mortal Kombat maps onto a six
+    # button controller, the two heavy attacks and block on top with the light
+    # pair beneath, which is why the bottom row is the short one.
+    rows=((_B.HP, _B.HK, _B.BL), (_B.LP, _B.LK)),
+    note="Heavy punch, heavy kick, block, with the light pair beneath.",
+)
+
+NEO_GEO = ButtonSet(
+    key="neo-geo",
+    name="Neo Geo, 4 button",
+    rows=((_B.A, _B.B, _B.C, _B.D), (_B.A, _B.B, _B.C, _B.D)),
+    note="A B C D straight across, and again on the row below.",
+)
+
+NEO_GEO_SLANT = ButtonSet(
+    key="neo-geo-slant",
+    name="Neo Geo, arcade slant",
+    rows=((_B.C, _B.D), (_B.A, _B.B)),
+    note="A B on the bottom row with C D above, as the arcade panel slants them.",
+)
+
+TEKKEN = ButtonSet(
+    key="tekken",
+    name="Tekken, 4 button",
+    rows=((_B.SQUARE, _B.TRIANGLE), (_B.CROSS, _B.CIRCLE)),
+    note="Left and right punch over left and right kick.",
+)
+
+EIGHT_BUTTON = ButtonSet(
+    key="eight",
+    name="Eight button",
+    rows=((_B.B1, _B.B2, _B.B3, _B.B4), (_B.B5, _B.B6, _B.B7, _B.B8)),
+    note="Every attack key a layout has, numbered.",
+)
+
+BUTTON_SETS: tuple[ButtonSet, ...] = (
+    STREET_FIGHTER,
+    MORTAL_KOMBAT,
+    NEO_GEO,
+    TEKKEN,
+    EIGHT_BUTTON,
+)
+"""The sets offered in the pickers. The Neo Geo slant is not among them: it is
+the same set differently arranged, and :func:`arrangement` chooses it."""
+
+DEFAULT_SET = STREET_FIGHTER
+
+
+def get_set(key: str) -> ButtonSet:
+    """Look up a button set by key, falling back to the Street Fighter six."""
+    for button_set in (*BUTTON_SETS, NEO_GEO_SLANT):
+        if button_set.key == key:
+            return button_set
+    return DEFAULT_SET
+
+
+def arrangement(button_set: ButtonSet, *, slanted_neo_geo: bool) -> ButtonSet:
+    """The set as the player wants it arranged.
+
+    Only the Neo Geo has a second arrangement, so this is a no-op for the rest.
+    """
+    if slanted_neo_geo and button_set is NEO_GEO:
+        return NEO_GEO_SLANT
+    return button_set