garmin-padel/docs/superpowers/specs/2026-07-02-padel-scoring-design.md

Padel Scoring App — Design Spec

Date: 2026-07-02 Target: Garmin Connect IQ watch-app (Monkey C), product venu445mm (Venu 4, 45mm, round AMOLED), minApiLevel 6.0.2. Status: Approved design, pre-implementation.

1. Purpose

A padel score tracker for the watch. It shows the live score (sets / games / points) and a top-down court diagram whose highlighted quadrant tells you who serves the next point. Points are recorded by swiping. No GPS, no recorded Garmin activity, no match history in v1.

2. Screen layout

Round screen. A top band (heart rate) and a bottom band (time) frame a central row split into three columns: left = sets + games, center = court, right = current-game points.

            ♥ 142  ▮▮▮▯▯               ← heart rate + zone (top band)

     S   G                    pts
     2   4     +------+------+  15      ← your team (upper number in each column)
     1   3     |      |      |  40      ← opponents (lower number)
               +------+------+ net
               |      |  ● ← yellow ball = next server
               +------+------+

                  14:32                 ← current time (bottom band)

• Left column — sets & games. Two mini-columns: S (sets) and G (games). A small label (S, G) sits above each pair of numbers; under it, two stacked numbers — your team on top, opponents below. Sets in bold accent color, games in accent color.
• Right column — points. A small pts label (same small font as S/G) above two stacked numbers for the current game — your team on top, opponents below — in white (0 / 15 / 30 / 40, and AD if advantage is enabled).
• Center — court. Simplified top-down padel court, your team the bottom half and opponents the top half. A small yellow ball is drawn in the quadrant of the next server (see §4); it moves as serve rotates. Nothing else is highlighted.
• Top band — heart rate. Current heart rate (bpm) with a zone indicator (the current HR zone 1–5, shown as a short colored bar / zone number). Requires a heart-rate sensor reading (see Permissions below).
• Bottom band — time. Current time (HH:MM), refreshed by a 1-second timer.

The small S / G / pts labels share one small font and a muted (dim grey) color so the numbers stay dominant.

Accent color. A single constant (proposed: a vivid padel green/teal) used for the sets and games numbers, so it can be changed in one place. The serve ball is yellow (its own constant).

Permissions. Reading live heart rate requires the Sensor permission; deriving the zone from the user's profile requires the UserProfile permission. Both are added via the Monkey C: Edit Permissions palette command (which regenerates manifest.xml).

3. Interaction model

During play (gestures):

• Swipe up → point to your team.
• Swipe down → point to the opponents.
• Swipe left → undo the last recorded point (steps back through game/set boundaries too).

Before the first point (tap):

• A tap toggles the starting server between bottom-right (your team serves first) and upper-left (opponents serve first) — the yellow ball jumps between those two quadrants. These are the only two options because the first point of any game is served from the deuce (right) court, and the opponents' right-hand court maps to the screen's upper-left. Tapping is only accepted while the match is at its very start (no points recorded yet).

At match end:

• The court shows a "won by your team / opponents" state and stops accepting points; undo still works. A tap starts a fresh match, returning to server-positioning.

4. Serving / court geometry

Your team = bottom half, opponents = top half. The yellow ball is drawn in the quadrant determined by (serving team) × (serve side):

Serving team	Serve side	Quadrant
Your team	deuce (right)	bottom-right
Your team	ad (left)	bottom-left
Opponents	deuce (their right)	upper-left
Opponents	ad (their left)	upper-right

Serve side by point parity. Even number of points played so far in the current game → deuce (right); odd → ad (left). Game start (0-0) is always deuce.

Serving team.

• Normal game: one team serves the entire game; the serving team alternates after each completed game.
• The first server of the match is chosen by tap (see §3).

Tiebreak serving (when tiebreak is enabled and reached, see §5):

• Serve side still follows point parity: even total tiebreak points → deuce, odd → ad.
• The first server serves 1 point, then service alternates every 2 points. (Server for the point with P points already played = the team given by floor((P+1)/2) mod 2 offset from the team due to serve at 6-6.)

5. Scoring rules

Rules are held in a RulesConfig object that the engine reads as parameters, so the future settings screen can drive them without an engine rewrite. v1 defaults (all overridable later):

• Points in a game: 0 / 15 / 30 / 40.
• 40-40 resolution: golden point (default). Next point at 40-40 wins the game. When RulesConfig is set to advantage instead, 40-40 = deuce, then advantage (AD), then game; must win by two points.
• Set: first to 6 games, win by 2.
• 6-6: 7-point tiebreak (win by 2). When tiebreak is disabled in RulesConfig, the set continues until a team leads by 2 games.
• Match: best of 3 sets (first to 2 sets).

6. Architecture (Monkey C)

Keeps the scaffold's file-per-role split; adds two logic-only files. The scoring engine imports no WatchUi/Graphics, so it is unit-testable in isolation.

• source/PadelMatch.mc — the scoring engine. Holds points/games/sets for both teams, the serving team, tiebreak state, and match-over/winner. Public surface:
  • pointTo(team) — record a point, advancing game/set/match as needed.
  • undo() — revert the last recorded point.
  • servingQuadrant() — returns which of the four quadrants holds the serve ball.
  • setStartingServer(team) / toggle — only valid at match start.
  • accessors for the display: points (per team, formatted), games, sets, isMatchOver(), winner().
  • Undo strategy: push a full state snapshot onto a stack before each pointTo; undo pops and restores. This makes swipe-left correct across point/game/set boundaries with no special-casing.
• source/RulesConfig.mc — the rules struct (golden-point flag, sets-to-win, games-per-set, tiebreak flag/target) plus the v1 defaults.
• source/CourtRenderer.mc — draws the top-down court and the yellow serve ball in a given quadrant, so the view stays focused on layout. Pure drawing against a Dc.
• source/HeartRateProvider.mc — wraps the heart-rate sensor and zone lookup. Enables Sensor.SENSOR_HEARTRATE, exposes the latest bpm, and maps it to a zone 1–5 using UserProfile.getHeartRateZones. Returns a "no reading" state when HR is unavailable (simulator / no strap) so the view can render a placeholder.
• source/garmin-padelView.mc — WatchUi.View. onUpdate draws the top HR band, the left sets/games column, the center court (via CourtRenderer), the right points column, and the bottom time band. A 1-second Timer calls requestUpdate to keep the clock (and HR) live.
• source/garmin-padelDelegate.mc — BehaviorDelegate. Maps onSwipe (up/down/left) and onTap (pre-match server toggle; new match after match end) to the engine, then requestUpdate.
• source/garmin-padelApp.mc — owns the PadelMatch, RulesConfig, and HeartRateProvider instances; wires the view + delegate; enables sensors on start and disables them on stop.

Resources (resources/): the whole screen is drawn programmatically in onUpdate rather than via a static layout, since positions depend on state. strings.xml holds team labels and the match-end text; the template menu can be removed or repurposed later. Sensor + UserProfile permissions are declared in manifest.xml via the Edit Permissions command.

7. Testing

• Engine unit tests (monkeyc --unit-test with a test runner) cover PadelMatch:
  • point → game → set → match progression (golden point and advantage modes),
  • tiebreak entry at 6-6, tiebreak win-by-2,
  • serving team alternation between games and serve-side parity within a game,
  • tiebreak serving rotation,
  • servingQuadrant() mapping for all four cases,
  • undo() across point/game/set boundaries and at match start (no-op).
• Rendering (CourtRenderer, view, HR band) is verified in the simulator (HR via the simulator's data-simulation, since there is no real strap).

8. Deferred (not in v1)

• Settings screen (drives RulesConfig; makes the top/bottom info slots configurable).
• Match history / saved matches.
• Resume-after-close persistence (engine state is in memory only for v1).
• Recorded Garmin activity, GPS. (Heart rate is in v1 as a read-only display, but the match is still not recorded as a Garmin activity.)