Skip to content

Transitions: a sprite the game keeps for itself shapes every mask transition - #1901

Merged
obiot merged 15 commits into
masterfrom
claude/hopeful-hypatia-jl2ouu
Nov 19, 2026
Merged

obiot merged 15 commits into
masterfrom
claude/hopeful-hypatia-jl2ouu

Conversation

@obiot

@obiot obiot commented Nov 19, 2026

Copy link
Copy Markdown
Member

Description

state.transition("mask", …, sprite) let go of any sprite after one transition, because a level's player is destroyed by the state change. A sprite that is in no level, such as one made with atlas.createSpriteFromName() and kept by the game, is not destroyed, and was dropped all the same: the first change wore its shape, every later one was a plain iris on the middle of the screen, with nothing in the console.

const sprite = atlas.createSpriteFromName("logo");
state.transition("mask", "#000", 500, sprite);   // once, at startup

A sprite shape, and a renderable center, are now let go only when the change takes them away:

Where the sprite is After the change
in no level (the game's own) kept, shapes every transition
in the world and persistent, or under a persistent child of the world kept
in the level (the player) let go after that transition, as before

A kept sprite is read again at each change, so the transition shows the frame and facing it has by then.

Also in this PR: a test for using a sprite mask for a single change (set it, state.change(), set the usual transition back on the next line), which already worked and was not covered.

The state.transition TSDoc and the scenes-and-state skill describe both cases. No changelog entry: sprite-shaped transitions are new in the unreleased 20.17.0, so this belongs to that entry.

Type of change

  • Bug fix
  • New feature
  • Documentation update
  • Performance improvement
  • Refactoring (no functional changes)

Checklist

  • I have read the Contributing Guide
  • My code follows the existing code style (ESLint and Biome pass on the changed files, and the type check passes)
  • I have tested my changes locally (the mask, transition, state, trigger, container and world suites pass: 426 tests; the full suite is left to CI)
  • I have added tests that cover my changes (ten new cases in mask-transition-sprite.spec.js; five of the nine for this fix failed before it)
  • The build succeeds (pnpm build) (not run locally, left to CI)

Related issues

Follow-up to #1399.


Generated by Claude Code

On a machine with a WebGPU adapter, 14 tests of mask-effect-image.spec.js
failed: the pixel helper's WebGPU branch called a method the renderer does
not have, and the WebGPU application made in the same file took the place
of the Canvas one the later tests use.

- helpers/pixels.js: grabFrame() reads a whole frame on any backend (a
  texture-to-buffer copy on WebGPU), and drawOffscreen() has a WebGPU
  renderer draw into a texture of its own, which reads back the same on a
  headless software adapter, where a canvas texture cannot be presented
- the drawing checks move to helpers/mask-effect-checks.js, and take each
  frame once, as it is drawn: an application's loop draws over it while a
  test awaits
- the WebGPU checks get a spec file of their own, with a projection set

Verified with a software WebGPU adapter: the 12 WebGPU checks pass, and
skip as before where there is no adapter.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JnzwA4a7ZyjLBpbeEpFLu6
An isometric tile layer can take the "shader" render mode, on WebGL 2 and
on WebGPU: one quad for the view, the fragment shader finding each pixel's
tile. For a pixel it walks the cells whose tile image could cover it, front
to back (the reverse of the order TMXIsometricRenderer draws in), and keeps
the first texel that is not transparent, so tall tiles overlap the rows
behind them as on the CPU path.

- shaders: the part every orientation shares (index and animation lookups,
  flips, atlas sampling) is split from the orthogonal part, in GLSL and in
  WGSL; the isometric part adds only its cell maths
- renderers: a TMXLayerGPURenderer base per backend, with the orthogonal
  and isometric ones on top; the part of a layer a view shows is computed
  in one module both backends read (gpu/tmxlayer_region.js)
- TMXLayer: an isometric layer is eligible when its tiles come from one
  tileset (they overlap, and a pass draws one tileset), an image one, with
  tiles within the shader's bounds; a tileoffset is supported. A tile of
  another tileset set at run time moves the layer back to the CPU path
- tests: helpers/tile-layer-compare.js draws a layer through the CPU and
  the GPU path, with the whole engine in between, and compares the frames

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JnzwA4a7ZyjLBpbeEpFLu6
…rence (#1897)

The GPU path took the first texel that was not transparent, front to
back. With drawn art that is wrong wherever tiles overlap, which on an
isometric map is everywhere: the soft edge of a tile showed the
background in place of the tile behind it. Each texel now goes behind the
ones before it until the fragment is opaque, which is what drawing the
tiles one over the other comes to. The orthogonal shader shares it, for
tiles larger than the grid.

Found by a scenario suite that draws every case through the CPU renderer
and the GPU one, on WebGL and on WebGPU, and compares both with a
reference painted with no engine at all. It also found, and this fixes:

- the isometric CPU renderer left out tiles by the first tileset's size,
  and by no tileset's `tileoffset`
- the orthogonal CPU renderer widened the wrong side of the view for
  tiles taller than the grid
- the orthogonal GPU quad cut tiles larger than the grid above the first
  row and right of the last column
- a tile that is not square, flipped diagonally, is wrong on the GPU
  path: such a layer is left to the CPU renderer

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JnzwA4a7ZyjLBpbeEpFLu6
…1897)

From an independent review of the isometric GPU path:

- a grid of odd size, and a blend mode other than the normal one, are
  left to the CPU renderer: the first stands half the tiles half a pixel
  off, the second shows where tiles overlap
- a tileset image with no margin after its last tiles was counted a
  column short (the orthogonal path too)
- a layer asked for "shader" by hand after it was found unfit for it is
  drawn tile by tile, where an isometric one drew nothing
- the tile shader declares full precision itself, and finds a tile's
  place in the atlas in whole numbers

Faster per fragment: what sampling needs of a fragment is taken once
instead of for every cell tried, a cell whose tile cannot reach the
fragment is dropped before its index is fetched, and the isometric walk
skips the rows outside the map.

What differs with a map's orientation is in one module for both
backends (`gpu/tmxlayer_orientation.js`: the region, the tilesets, the
shader's limits, which the layer's checks read too), so each backend has
one renderer class and the shader text.

`tests/tmxlayer_bench.spec.js` measures the main thread's share of a
frame tile by tile and on the GPU path, orthogonal and isometric.

Changelog, API docs and the tilemaps skill.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JnzwA4a7ZyjLBpbeEpFLu6
…ir tiles reach

Two gaps the reference picture of the tile layer tests had to work
around (#1897), on every renderer and render mode.

A tile layer ignored its offset in Tiled (`offsetx`, `offsety`) and its
own `pos`: it was always drawn at the map's origin, where image layers
followed theirs. The offset now goes into `pos`, and the layer draws its
tiles, and `getTile()` finds them, where `pos` says.

A layer was skipped once its grid left the view, though tiles larger
than a cell, or moved by a `tileoffset`, still reached in: the tops of
tall tiles vanished above the map. The layer's bounds now cover how far
its tiles reach; its `width` and `height` stay the grid's.

Tests written first and seen to fail: both paths against the reference
on WebGL and WebGPU (offset layers, several layers, an infinite map, a
layer moved at run time, views that hold only the reach), and on the
Canvas renderer tile by tile and baked, with `getTile`, the bounds, and
staggered and hexagonal maps. The reference no longer leaves out a
layer whose grid is out of view.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JnzwA4a7ZyjLBpbeEpFLu6
Both are one geometry, on the base the isometric path shares: lines of
cells a row height apart, every other one shifted by a column width,
along the map's rows or its columns. One shader chunk (GLSL and WGSL)
and one region function draw both; a hexagonal map's cells are longer by
its side length, which is in the two lengths the shader is given (in
what was the padding of the WGSL uniform block). The layer's checks are
those of an isometric layer: one tileset, tiles up to 4 cells wide and 8
tall, a grid of even size.

The CPU renderer of these maps is fixed first, as the reference of the
tests showed it away from Tiled: its drawing loop hung a tile larger
than its cell from the top of the cell and ignored the tileset's
`tileoffset`, where its own `drawTile` (and Tiled) stand the tile on
the cell and move it by the offset; and it left out tiles of a large
tileset along the edges of the view.

Tests: the reference paints staggered and hexagonal maps; 24 scenes
(both orientations, either axis, either index, three kinds of tiles) on
the Canvas renderer tile by tile and baked, and 38 scenarios on WebGL
and WebGPU through both paths, with soft edges, flips, animation, layer
offsets, infinite maps, setTile and the fallbacks. The comparison of
the two paths moves to the shared test helper.

Changelog, API docs and the tilemaps skill.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JnzwA4a7ZyjLBpbeEpFLu6
A layer reads the camera's view in its own coordinates. It is handed the
view in the world's, and is drawn where its ancestors put it: a map
centred in the view by moving the world (`level.load`) lost the tiles
reaching above or left of its grid on the GPU and baked paths, and a
layer in a moved container lost tiles tile by tile.

A layer keeps track of whether the shader path can still draw it
whichever way it is drawn: a tile of a second tileset set while the
layer was switched to "perTile" by hand was left undrawn once it was
switched back.

A tile layer's bounds are its grid's again. What its tiles reach past
the grid is asked for separately (`getDrawBounds`, read by
`Camera2d#isVisible`): growing `getBounds()` moved what read it as the
map's area.

Pathfinding plugin: a grid from a tile layer stands where the layer was
moved to (its offset in Tiled, its `pos`), as the layer is now drawn.

One helper cuts the view to a layer's tiles for the isometric and the
staggered regions; stale comments and the docs corrected.

Tests: a layer in a centred map and in a moved container, on Canvas,
WebGL and WebGPU, in every render mode and orientation, against the
reference; render modes switched by hand with tiles set in between.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JnzwA4a7ZyjLBpbeEpFLu6
Probes written to break the tile layer code, each against the reference
picture, and what they found:

- An orthogonal layer whose tiles are larger than the grid lay them over
  each other in the wrong order on the GPU when they came from more than
  one tileset (a pass per tileset) or the map's render order was not
  "right-down": such a layer is drawn tile by tile.
- A layer with more columns or rows than the largest texture drew
  nothing on the GPU: drawn tile by tile.
- A hexagonal map whose side leaves an odd number of pixels of a cell is
  laid out on whole pixels, as Tiled's own numbers are; and so drawn by
  the GPU too. The baked canvas of a staggered or hexagonal map of odd
  tile size was a pixel short.
- The isometric CPU renderer left out tiles narrower than half a cell at
  the right edge of the view.
- A camera with an offset over a moved world: the layer asked a plain
  rectangle, in place of the camera, whether it was the default one.
- A container with a size of its own (a level loaded into one) is in
  view by its bounds before its layers are asked: it is told how far
  their tiles reach.
- A layer taken out of its container and added again threw; a tile its
  tileset's image does not hold threw every frame tile by tile, and is
  now left undrawn on both paths.

The probes are kept as tests (`tile-layer-edge-cases.js`, on WebGL and
WebGPU), with the reference taught the orthogonal render orders and
Tiled's whole numbers for hexagons.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JnzwA4a7ZyjLBpbeEpFLu6
Staggered and hexagonal maps are laid out with Tiled 1.10's own numbers:
what a side leaves of a tile is halved in whole numbers, and the cell a
tile stands on is made of those halves, a pixel smaller than a tile of
odd size. A map of odd sizes is on whole pixels, so the GPU path takes
it; the shader's pixels are measured from as much lower as the cell is
shorter. A painter written apart from the tests' reference, from Tiled's
source, agrees with both paths.

A container holds the tile layers that can draw outside its bounds, and
is in view as far as they do: their tiles' reach, a layer's offset, an
infinite map's first chunks. (A level loaded into a container gives it
the map's size, and the camera asks the container before its layers.)

A tile its tileset's image does not hold is left undrawn by `drawTile`
too: setting one on a baked layer threw.

Tests, from the gaps the audit listed: pictures for the grids of odd
sizes, where only the render mode was looked at; flips on hexagons; an
infinite map with chunks at odd coordinates; a layer offset and an
infinite map in a container; a sliver of 1, 2 and 5 pixels of each
orientation at each edge of the view, and a pixel out of sight;
`getTile` at the middle of every cell of every kind of map, the layer
moved; and two assertions that could not fail made to.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JnzwA4a7ZyjLBpbeEpFLu6
GPU rendering of isometric, staggered and hexagonal maps under Added;
its gain in percent under Performance, with the orthogonal figures for
reference; the opacity change under Fixed; the tile layer fixes merged
into six entries, those a game cannot see left out.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JnzwA4a7ZyjLBpbeEpFLu6
…maps

The Tiled feature line said orthogonal maps only, and that the others
fell back to the CPU renderer.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JnzwA4a7ZyjLBpbeEpFLu6
state.transition("mask", …, sprite), state.change(), then the usual
transition set back on the next line: that change hides and reveals with
the sprite's silhouette, and the next change is the usual fade.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JnzwA4a7ZyjLBpbeEpFLu6
…nsition

state.transition("mask", …, sprite) let go of any sprite after one
transition, because a level's player is destroyed by the change. A sprite
that is in no level (atlas.createSpriteFromName(), kept by the game) or a
persistent one is not, and was dropped all the same: the first change
wore it, every later one was a plain iris, with nothing said.

A sprite shape, and a renderable center, are now let go only when the
change takes them: in the world, and not under a persistent child of it.
Anything else is kept with the transition and read again at each change.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JnzwA4a7ZyjLBpbeEpFLu6
Copilot AI balanced review requested due to automatic review settings November 19, 2026 07:30

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@obiot
obiot merged commit 9ccf8cb into master Nov 19, 2026
6 checks passed
@obiot
obiot deleted the claude/hopeful-hypatia-jl2ouu branch November 19, 2026 07:40
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.

3 participants