dartsnut-display-mapping

name	dartsnut-display-mapping
description	Dartsnut display and framebuffer mapping rules for panels, physical screens, layout, clipping, and fonts.
license	MIT

Dartsnut display mapping (dartsnut-display-mapping)

When to apply — mandatory: Read and follow this skill for any Dartsnut task that touches pixels, layout, resolution, framebuffer size, UI placement, fonts, or update_frame_buffer. That includes games, widgets, emulator previews, and refactors of drawing code.

Relationship to other skills: Use dartsnut-skill for pydartsnut APIs, loops, and I/O. Use conf-contract for root config. This file is the single reference for physical screens ↔ framebuffer mapping and related rendering rules.

---

Full-frame 128×160 layout (games and full-size widgets)

The framebuffer passed to update_frame_buffer is always 128 wide × 160 tall. It maps to two physical displays:

Surface	Image pixels (Pillow / pygame)	Physical size
Main	x ∈ [0, 127], y ∈ [0, 127]	128 × 128
Secondary	x ∈ [0, 63], y ∈ [128, 159]	64 × 32

The secondary panel is left-aligned in the lower band of the image. Its hardware firmware address origin is (129, 0) in the machine's own coordinate space — that does not map to image x/y directly. Always use the image pixel ranges in the table above when drawing.

Main vs secondary content

• Place gameplay and dart feedback on the main 128×128 area when using a full 128×160 buffer.
• Use the lower band mapped to the 64×32 hardware panel for scores, labels, icons, or status when it improves layout.

Partial-size widgets (128×128, 128×64, 64×32)

• Render a Pillow Image exactly at the configured [width, height] and pass it through pydartsnut as usual.
• Do not manually composite these into a 128×160 buffer — machine firmware performs framebuffer merges for these sizes.

Dart hit targets (critical)

• The bottom / secondary surface is not dart-sensitive.
• Do not place buttons, targets, or other interactive affordances that rely on dart hits only on the secondary panel.
• If the user insists on dart-interactive UI in that region, warn that hits may not register there and recommend relocating interaction to the main 128×128 area.

Clipping

• For every 128×160 framebuffer, always apply surface clipping in your reasoning and drawing:
  • Nothing may render outside x ∈ [0, 127], y ∈ [0, 159].
  • Respect the main vs secondary split so content does not straddle the logical boundary in a way that breaks on hardware.

Typography

• Choose font sizes and typefaces suited to the main vs secondary real estate (large playfield vs narrow ticker).
• Avoid oversized text that dominates the 64×32 strip or overflows the 128×128 play area.

Display layout convention (games)

• Resolution is typically [128, 160]. Treat the surface as a 128×128 primary area plus a secondary region mapped to the physical 64×32 panel.