Skip to content

feat: grid3d helpers games shared, and a browser backend, for 0.5.0 - #79

Merged
dmccoystephenson merged 3 commits into
mainfrom
feat/grid3d-0.5
Nov 20, 2026
Merged

dmccoystephenson merged 3 commits into
mainfrom
feat/grid3d-0.5

Conversation

@dmccoystephenson

Copy link
Copy Markdown
Member

Summary

The helpers that Ophidian, Apex and Tic-Tak-Toe each hand-built for their 3D views are moved into preponderous.graphik.grid3d, and a browser backend is added so a grid3d game can draw 3D under pygbag later. The 0.4.0 API keeps working: a board built without the new options draws exactly as before, and the 216 existing tests pass unchanged.

Added to grid3d

  • Picking (pick.py): projectToScreen(camera, point, w, h), pickCell(camera, board, x, y, w, h), pickPoint, screenRay and cellScreenPosition, plus view.pickCell(x, y), view.camera() and view.projectToScreen(point) on the desktop and web views.
  • Text (text.py): measureText(text, pixelSize) for Strata's built-in 8 x 8 font, where each character is exactly one pixel size wide (checked against strata.h's StrataText and the overlay's glyph layout), plus wrapText and centredLabel alongside the existing fitText.
  • Screen buttons (ui.py): Button, which draws a panel with a centred label, uses drawButton's half-open hit test and gets drawButton's hover lift (hoverColor). It takes 0-255 colours as drawButton does and can be widened to fit its label. ScreenRecorder (with RecordedText, RecordedRect, RecordedButton) stands in for Graphik, so a game's 2D screens can run under a 3D view.
  • GridBoard options:
    • tiles gives a cell its own Tile(color, raised); a cell mapped to None gets no tile.
    • mergeTiles draws each row's neighbouring tiles that look the same as one box. A 64 x 64 board of one colour is 68 shapes instead of 4100, and a test checks those counts.
    • viewport=Viewport(...) / Viewport.around(column, row, reach) draws only a window of the board.
    • scene(highlight=cell) adds the hover slab, coloured by Theme.highlight.
    • bridgePairs and bridgeShape give public access to chain bridges. _bridges is kept for older code.
  • The PieceStyle.extras docs now say that extras return shapes placed relative to the piece. The browser backend depends on this.
  • Browser backend (web.py):
    • Grid3DWebView has the same calls as Grid3DView and draws through Strata's grid relay. It encodes wire format 1.0 (Strata's web/kit/grid-relay/WIRE.md) and sends messages through platform.window.StrataGridRelay.
    • drawScene works for games that build their own Scene each frame, and sends only what changed.
    • Grid3DView.open() returns a Grid3DWebView when sys.platform == "emscripten".
    • toPygameEvents turns relay events, and desktop Strata events, into pygame events, including FINGER*.
    • A pygbag page template ships as package data (templatePath()). It is pygbag 0.9.3's default template plus the relay canvas and scripts and a 3D button. The 3D view loads only when the button is pressed, the 2D canvas is hidden only once 3D is drawing, and 2D comes back if 3D fails to load. wants3D() and set3D() read and set the button from Python.
  • Build-time relay fetch (relay.py): python -m preponderous.graphik.grid3d.relay --strata 0.9.0 --dest <pygbag output> is for a game's browser.yml, because a browser can't fetch GitHub release assets cross-origin. It downloads Strata's strata-<version>-wasm32-emscripten.tar.gz, checks it against the release's SHA256SUMS and copies the prebuilt kit/grid-relay/dist/ next to the page. Files already there, such as pygbag's index.html, are left alone, and archive members that would land outside the folder are refused. It uses only the standard library. The README has the browser.yml steps.
  • Version 0.5.0. The README's 3D section covers the helpers and the browser.

Tests

  • 293 pass (216 before, all unchanged).
  • New test_grid3d_helpers.py covers picking round trips at three aspect ratios, text metrics, buttons, the recorder, own and merged tiles (with the 64 x 64 counts), the viewport, the highlight and bridge pairs.
  • New test_grid3d_web.py checks the encoding against WIRE.md: the 8-byte version header, record sizes and field offsets, label padding, the 64-byte VIEW body, rejection of an unknown major version, tolerance of a later minor version, and truncation. It also covers the web view against a recording relay, the emscripten branch of open(), the event adapter and the template.
  • New test_grid3d_relay.py covers the relay fetch against tarballs built in the test: verification, a checksum mismatch, a missing line in SHA256SUMS, a tarball with no relay, path traversal, keeping existing files, and the CLI.
  • A wheel build was checked to include grid3d/templates/pygbag.tmpl.

Follow-ups

  • Ophidian, Apex and Tic-Tak-Toe each have a branch ready that replaces their hand-built copies with these helpers and pins v0.5.0. They can be merged once this is tagged.
  • No game uses the browser backend yet. Fetching the relay needs Strata v0.9.0, the first release whose tarball includes it prebuilt. The relay fetch was tested only against synthetic tarballs, not the real v0.9.0 asset. Whether pygbag --template accepts a local template path should be confirmed on the first game that uses it.

drafted by Claude on behalf of Daniel Stephenson

🤖 Generated with Claude Code

dmccoystephenson and others added 3 commits November 19, 2026 22:23
The helpers three games had each hand-built for their 3D views are
moved into grid3d, and a browser backend is added so a grid3d game can
draw 3D under pygbag later. The 0.4.0 API is kept working.

- Picking (pick.py): projectToScreen, pickCell, pickPoint, screenRay
  and cellScreenPosition, plus view.pickCell(x, y) on both views.
- Text (text.py): measureText for Strata's 8x8 font (exactly one pixel
  size per character, checked against strata.h and the overlay's
  layout), wrapText and centredLabel beside fitText.
- Screen buttons and a Graphik stand-in (ui.py): Button (panel,
  centred label, drawButton's edges and hover lift), hoverColor and
  ScreenRecorder for running 2D screens under a 3D view.
- GridBoard options: per-cell tiles (Tile colour and raise),
  mergeTiles for big boards, a Viewport window, a hover highlight
  slab (scene(highlight=...)), and public bridgePairs/bridgeShape.
- PieceStyle.extras is documented as returning shapes relative to the
  piece.
- grid3d/web.py: Grid3DWebView drawn by Strata's grid relay (wire
  format 1.0 encoder and reader), Grid3DView.open() picking it under
  emscripten, toPygameEvents (FINGER* included) and a pygbag page
  template, shipped as package data, with a 3D toggle that loads the
  relay only on request and keeps the 2D canvas when it can't load.
- Version 0.5.0 and the README's 3D section.

drafted by Claude on behalf of Daniel Stephenson

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LYNeuoCqxFpUXrFhxnTg89
A cell that a GridBoard's `tiles` maps to None is now left without a
tile, so a board drawn from a map of only some cells (an off-grid edge
in a game's own close-up) leaves the rest empty. Missing cells still get
the theme's checker. An unused import is also dropped from the helper
tests.

drafted by Claude on behalf of Daniel Stephenson

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LYNeuoCqxFpUXrFhxnTg89
A browser can't fetch GitHub release assets cross-origin, so the grid
relay has to be served with the game. grid3d.relay
(`python -m preponderous.graphik.grid3d.relay --strata 0.9.0 --dest
build/web`) is added for a game's browser build: it downloads Strata's
strata-<version>-wasm32-emscripten.tar.gz, checks it against the
release's SHA256SUMS, and copies its prebuilt kit/grid-relay/dist/ next
to the pygbag page, leaving files already there (pygbag's index.html)
alone and refusing members that would land outside the folder. The
README gives the browser.yml steps; web.py and the page template point
at it. Standard library only; tested against tarballs made in the tests.

drafted by Claude on behalf of Daniel Stephenson

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LYNeuoCqxFpUXrFhxnTg89
@dmccoystephenson
dmccoystephenson merged commit 18b8f89 into main Nov 20, 2026
6 checks passed
@dmccoystephenson
dmccoystephenson deleted the feat/grid3d-0.5 branch November 20, 2026 05:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant