Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 37 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ This library assists developers with graphics programming.
graphik is released as git tags, not on PyPI. Install a release from its tag's
archive (no `git` needed):
```bash
pip install "graphik @ https://github.com/Stephenson-Software/graphik/archive/refs/tags/v0.4.0.zip"
pip install "graphik @ https://github.com/Stephenson-Software/graphik/archive/refs/tags/v0.5.0.zip"
```
In a `requirements.txt`, use the same line without the quotes. See
[RELEASING.md](RELEASING.md) for how releases are cut.
Expand Down Expand Up @@ -91,10 +91,11 @@ An alpha component in a fill color (`(r, g, b, a)`) does not make `drawRectangle
pieces standing on cells that slide smoothly between cells from one game tick
to the next. A game describes its board once and reports what is on each cell
every tick; the look lives in a `Theme`. It needs the optional Strata binding
and runs on Linux and Windows desktops:
and runs on Linux and Windows desktops, and in the browser under pygbag
(see [In the browser](#in-the-browser)):

```bash
pip install "graphik[strata] @ https://github.com/Stephenson-Software/graphik/archive/refs/tags/v0.4.0.zip"
pip install "graphik[strata] @ https://github.com/Stephenson-Software/graphik/archive/refs/tags/v0.5.0.zip"
```

```python
Expand All @@ -119,10 +120,42 @@ else:
- `Grid3DView.open(..., headless=True)` renders off-screen for tests and screenshots (`savePng`); `reducedMotion=True` makes pieces jump instead of slide.
- `Unavailable` says in plain words why 3D can't run (no binding, no library for the system, no window); the game should fall back to its 2D view.
- Everything except `Grid3DView.open` is plain Python, so scene code can be unit-tested without a GPU. Importing `grid3d` loads neither Strata nor pygame.
- `PieceStyle.extras(piece, x, z, baseY)` returns shapes placed relative to the piece: x and z measured from the given `(x, z)`, so moving the piece moves them all the same way. The browser backend sends them as offsets from the piece and relies on this.

### Helpers for a game's 3D view

So that games stop hand-building the same pieces:

- **Picking.** `view.pickCell(x, y)` (or `pickCell(camera, board, x, y, width, height)`) gives the `(column, row)` under a pointer, or `None`; the whole cell counts, gaps between tiles included. `projectToScreen(camera, point, width, height)` and `cellScreenPosition(camera, board, column, row, width, height, y)` go the other way, for aiming a tap at a piece or putting a note beside a tile. They use the same look-at and perspective the view asks Strata for.
- **Text.** Strata's built-in font is an 8 x 8 bitmap font in which every character is exactly `pixelSize` wide. `measureText(text, pixelSize)`, `fitText(text, width, pixelSize)` (cut with `...`), `wrapText(text, maxWidth, pixelSize)` (greedy word wrap) and `centredLabel(text, x, y, pixelSize, color, rise=0.5)` build on that.
- **Screen buttons.** `Button(x, y, width, height, text, color, textColor, pixelSize, function)` draws a panel and a centred label (`button.draw(pointer)`), hit-tests with `drawButton`'s edges (`contains`, `click`), and lifts under the pointer as `drawButton` does (`hoverColor`). Colours are 0-255, as for `drawButton`; `padding` widens a button whose label doesn't fit.
- **2D screens under a 3D view.** `ScreenRecorder` stands in for `Graphik`: a game's 2D screens draw into it as usual (`drawText`, `drawRectangle`, `drawButton`), the 3D view shows what they drew, and `recorder.click(pos)` runs the 2D button's own function.
- **Bigger boards.** `GridBoard(columns, rows, theme, tiles=..., mergeTiles=True, viewport=...)`: `tiles` maps a cell to its own `Tile(color, raised)`; `mergeTiles` draws each row's neighbouring tiles that look the same as one box (a 64 x 64 board of one colour is 64 boxes, not 4096); `viewport=Viewport.around(column, row, reach)` draws only a window of the board, framed and fitted as if it were the whole board, with pieces and picking still in whole-board cells.
- **Hover.** `board.scene(..., highlight=(column, row))` lays a thin slab in `Theme.highlight` on the tile under the pointer.
- **Chains.** `board.bridgePairs(pieces)` names the joined pieces and `board.bridgeShape(a, b, aAt, bAt)` draws one bridge.

### In the browser

Under [pygbag](https://pypi.org/project/pygbag/) (`sys.platform == "emscripten"`), `Grid3DView.open()` returns a `grid3d.web.Grid3DWebView`: the same calls, drawn by Strata's grid relay, a small Strata web-kit scene in the page (Strata's `web/kit/grid-relay`, whose `WIRE.md` specifies the messages). Python sends the board, each tick's pieces, the HUD and the camera as small versioned binary messages; the page slides the pieces between ticks itself, so nothing is sent per display frame. A game that builds whole `Scene`s can keep calling `drawScene()` every frame; only what changed is sent.

- `view.ready` turns true once the page has loaded the 3D view; `view.failure()` says why it couldn't. `open()` raises `Unavailable` on a page without the relay.
- `view.pollEvents()` returns Strata-style events (keys with desktop Strata's scancodes, mouse, wheel, resize, and `FINGER_*` for touch), and `grid3d.web.toPygameEvents(events, pygame)` turns them into pygame events, so a game's 2D input code runs unchanged. It converts desktop Strata events too.
- The page: build with `pygbag --template <grid3d.web.templatePath()> ...`, a copy of pygbag 0.9.3's default template with the relay's canvas and scripts and a **3D** button. The relay has to be served with the game (a browser can't fetch GitHub release assets cross-origin): `python -m preponderous.graphik.grid3d.relay --strata 0.9.0 --dest <pygbag output>` 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 page, leaving files already there (pygbag's `index.html`) alone. Nothing of the 3D view is downloaded until the player presses the button; the 2D canvas stays on screen while it loads and whenever it can't (too big, no WebGL 2), and the button then says so. `grid3d.web.wants3D()` tells the game the button is on, and `set3D(False, reason)` turns it off.

In a game's `browser.yml`, where graphik is installed into `src/` for pygbag:

```yaml
- name: Build with pygbag, on graphik's 3D page template
run: |
TEMPLATE="$(PYTHONPATH=src python -c 'from preponderous.graphik.grid3d.web import templatePath; print(templatePath())')"
python -m pygbag --build --template "$TEMPLATE" --title "My game" src
- name: Add Strata's grid relay next to the page
run: PYTHONPATH=src python -m preponderous.graphik.grid3d.relay --strata 0.9.0 --dest src/build/web
```

## Dependencies
- pygame
- optional: `strata-engine` 0.7.0 for the 3D grid view (the `strata` extra)
- optional: `strata-engine` 0.8.0 for the 3D grid view on the desktop (the `strata` extra)

Python 3.9 or newer is required (`requires-python` in [pyproject.toml](pyproject.toml)). The test suite is run against 3.9 through 3.13; see [`.github/workflows/test.yml`](.github/workflows/test.yml) for why 3.13 is the ceiling.

Expand Down
4 changes: 4 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,10 @@ package-dir = { "" = "src/main/python" }
[tool.setuptools.packages.find]
where = ["src/main/python"]

# grid3d's pygbag page template (grid3d.web.templatePath())
[tool.setuptools.package-data]
"preponderous.graphik.grid3d" = ["templates/*.tmpl"]

[tool.setuptools.dynamic]
version = { attr = "preponderous.graphik._version.__version__" }

Expand Down
2 changes: 1 addition & 1 deletion src/main/python/preponderous/graphik/_version.py
Original file line number Diff line number Diff line change
@@ -1 +1 @@
__version__ = "0.4.0"
__version__ = "0.5.0"
40 changes: 37 additions & 3 deletions src/main/python/preponderous/graphik/grid3d/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,31 @@
each cell every tick (Piece), and a Grid3DView draws it, sliding pieces
between cells. The scene description (scene.py, board.py, animate.py) is pure
Python and needs no GPU; only Grid3DView.open() loads Strata, through the
optional `graphik[strata]` extra. Desktop Linux and Windows only for now.
optional `graphik[strata]` extra, on desktop Linux and Windows. In a browser
(pygbag) Grid3DView.open() returns web.Grid3DWebView, drawn by Strata's grid
relay in the page.

Helpers shared by the 3D views of grid games: picking (pick.py: the cell
under a pointer, where a point lands on screen), text in Strata's font
(text.py: measure, fit, wrap, centre), screen buttons and a Graphik
stand-in for running 2D screens under a 3D view (ui.py).

Importing this package imports neither Strata nor pygame.
"""

from .animate import Animator, interpolatePosition
from .board import BED_TOP, GridBoard, Piece, PieceStyle, Theme, cellCenter, fitCamera
from .board import (
BED_TOP,
GridBoard,
Piece,
PieceStyle,
Theme,
Tile,
Viewport,
cellCenter,
fitCamera,
)
from .pick import cellScreenPosition, pickCell, pickPoint, projectToScreen, screenRay
from .scene import (
CAPSULE,
CLEAR_COLOR,
Expand All @@ -33,14 +51,30 @@
rgba,
shade,
)
from .text import centredLabel, measureText, wrapText
from .ui import (
Button,
RecordedButton,
RecordedDisplay,
RecordedRect,
RecordedText,
ScreenRecorder,
drawButtons,
hoverColor,
)
from .view import STRATA_VERSION, Grid3DView, Unavailable

__all__ = [
"Animator", "interpolatePosition",
"BED_TOP", "GridBoard", "Piece", "PieceStyle", "Theme", "cellCenter", "fitCamera",
"BED_TOP", "GridBoard", "Piece", "PieceStyle", "Theme", "Tile", "Viewport",
"cellCenter", "fitCamera",
"cellScreenPosition", "pickCell", "pickPoint", "projectToScreen", "screenRay",
"CAPSULE", "CLEAR_COLOR", "CUBE", "CYLINDER", "DIM_TEXT_COLOR",
"MAX_POINT_LIGHTS", "MAX_SHADOWED_POINT_LIGHTS", "SPHERE", "TEXT_COLOR",
"Camera", "Label", "Light", "Panel", "Scene", "SceneLimitError", "Shape",
"fitText", "rgb255", "rgba", "shade",
"centredLabel", "measureText", "wrapText",
"Button", "RecordedButton", "RecordedDisplay", "RecordedRect", "RecordedText",
"ScreenRecorder", "drawButtons", "hoverColor",
"STRATA_VERSION", "Grid3DView", "Unavailable",
]
Loading
Loading