constants.py 4.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101
  1. """Pet sprite geometry + animation-state taxonomy.
  2. Common petdex/Codex pet geometry. ``pet.json`` usually only carries
  3. ``id``/``displayName``/``description``/``spritesheetPath``; row taxonomy is
  4. inferred from the atlas shape so Hermes renders both legacy 8-row sheets and
  5. current 9-row Codex sheets.
  6. """
  7. from __future__ import annotations
  8. from enum import Enum
  9. # Frame geometry (pixels). Codex/petdex sheets are 8 cols x 9 rows (1536x1872);
  10. # older sheets 9 x 8 (1728x1664). Renderers derive taxonomy/columns from the sheet.
  11. FRAME_W = 192
  12. FRAME_H = 208
  13. # Frames stepped per state (petdex CSS ``steps(6)``); extra physical columns are ignored.
  14. FRAMES_PER_STATE = 6
  15. LOOP_MS = 1100 # full-loop duration for one state, ms (petdex default)
  16. # ``display.pet.scale`` is the single master scalar: the desktop canvas multiplies
  17. # native pixels by it and every terminal surface derives its column width from it
  18. # (:func:`cols_for_scale`). petdex clients render at 0.7; we default smaller so the
  19. # mascot stays a glanceable corner sprite (half-blocks clamp to ``UNICODE_MIN_COLS``).
  20. DEFAULT_SCALE = 0.33
  21. # User-settable bounds (``/pet scale``, desktop slider): floor keeps the pet
  22. # clickable/visible; ceiling stops a fat-fingered value from filling the screen.
  23. MIN_SCALE = 0.1
  24. MAX_SCALE = 3.0
  25. def clamp_scale(scale: float) -> float:
  26. """Clamp *scale* to ``[MIN_SCALE, MAX_SCALE]`` (the single validation point)."""
  27. return max(MIN_SCALE, min(MAX_SCALE, scale))
  28. # Cells one native frame spans at ``scale == 1.0`` (~8px cells → 24); mirrors the
  29. # kitty placement (``scaled_px // 8``) so at full scale every renderer agrees.
  30. BASE_UNICODE_COLS = FRAME_W // 8
  31. # Legibility floor for half-blocks: a cell samples 1 horizontal + 2 vertical taps,
  32. # so below this width the pet is an unreadable blob regardless of scale (kitty/GUI
  33. # draw true pixels, no floor). ``scale`` shrinks the unicode pet TO this floor, not past it.
  34. UNICODE_MIN_COLS = 16
  35. def cols_for_scale(scale: float) -> int:
  36. """Half-block width implied by *scale*, clamped to the legibility floor (tracks the kitty cell box above it)."""
  37. return max(UNICODE_MIN_COLS, round(BASE_UNICODE_COLS * (scale or DEFAULT_SCALE)))
  38. def resolve_cols(scale: float, unicode_cols: int = 0) -> int:
  39. """Resolve terminal width: explicit *unicode_cols* override, else from *scale*."""
  40. return int(unicode_cols) if unicode_cols and int(unicode_cols) > 0 else cols_for_scale(scale)
  41. class PetState(str, Enum):
  42. """Animation state a pet can be shown in (Hermes names; Codex rows say ``jumping``/``running`` for ``jump``/``run``)."""
  43. IDLE = "idle"
  44. WAVE = "wave"
  45. RUN = "run"
  46. FAILED = "failed"
  47. REVIEW = "review"
  48. JUMP = "jump"
  49. WAITING = "waiting"
  50. # Legacy Hermes/petdex row order (top -> bottom) for the older 8-row, 9-column atlas.
  51. LEGACY_STATE_ROWS: list[str] = ["idle", "wave", "run", "failed", "review", "jump", "extra1", "extra2"]
  52. # Current Petdex row order (top -> bottom) for 1536x1872 atlases (8 cols x 9 rows).
  53. CODEX_STATE_ROWS: list[str] = ["idle", "running-right", "running-left", "waving", "jumping", "failed", "waiting", "running", "review"]
  54. # Default for callers without a sheet: generated pets and the Codex contract use 9 rows.
  55. STATE_ROWS: list[str] = CODEX_STATE_ROWS
  56. # Canonical Hermes names -> accepted row-name aliases in descending preference.
  57. _CODEX_NAMES = {"wave": "waving", "jump": "jumping", "run": "running"}
  58. STATE_ALIASES: dict[str, tuple[str, ...]] = {
  59. s: (s, _CODEX_NAMES[s]) if s in _CODEX_NAMES else (s,) for s in ("idle", "wave", "jump", "run", "failed", "review", "waiting")
  60. }
  61. def state_aliases_for(state: PetState | str) -> tuple[str, ...]:
  62. """Return accepted row-name aliases for *state* (always non-empty)."""
  63. value = state.value if isinstance(state, PetState) else str(state)
  64. return STATE_ALIASES.get(value) or (value,)
  65. def state_rows_for_grid(row_count: int | None) -> list[str]:
  66. """Return the row taxonomy for a spritesheet with *row_count* rows."""
  67. try:
  68. rows = int(row_count or 0)
  69. except (TypeError, ValueError):
  70. rows = 0
  71. return CODEX_STATE_ROWS if rows >= len(CODEX_STATE_ROWS) else LEGACY_STATE_ROWS
  72. def state_row_index(state: PetState | str, row_count: int | None = None) -> int:
  73. """Return the spritesheet row index for *state* (clamped, never raises)."""
  74. rows = state_rows_for_grid(row_count)
  75. return next((rows.index(name) for name in state_aliases_for(state) if name in rows), 0) # 0 = idle row