Skip to content

GPU tile layers for isometric, staggered and hexagonal maps - #1899

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

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

Conversation

@obiot

@obiot obiot commented Nov 19, 2026

Copy link
Copy Markdown
Member

Description

Isometric, staggered and hexagonal tile layers are drawn by the GPU ("shader" render mode) on WebGL 2 and WebGPU, as orthogonal ones have been since 19.4: one quad for the layer, its tiles found by the fragment shader, in place of a quad per tile in view found and placed in JavaScript every frame.

How it is built

  • What differs with a map's orientation lives in one module for both backends (video/gpu/tmxlayer_orientation.js): the part of a layer a view shows, the tilesets a layer draws with, and the bounds of the shader's loops, which the layer's eligibility checks read too. Each backend has one renderer class and the shader text.
  • The fragment shader is a shared chunk plus one chunk per orientation (GLSL and WGSL). Staggered and hexagonal maps share a chunk: they are one geometry.
  • Texels are composited front to back until the fragment is opaque, so the soft edge of a tile shows the tile behind it. The orthogonal shader gets the same.
  • A layer the GPU cannot draw right is left to the CPU renderer, and the console says why: tiles of more than one tileset in an isometric, staggered or hexagonal layer, tiles past the size the shader walks, an isometric grid of odd size, a blend mode other than the normal one on those maps, a non-square tile flipped diagonally, more columns or rows than the largest texture, and on orthogonal maps large tiles from two tilesets or a render order other than "right-down".

Main-thread time per frame (tests/tmxlayer_bench.spec.js, 100 × 100 map, CPU-side only: the run is under a software rasterizer, so GPU time is not in these)

map tiles in view tile by tile GPU path
isometric 1200 0.68 ms 0.07 ms
isometric 4000 2.0 ms 0.04 ms
orthogonal 1000 0.62 ms 0.09 ms
orthogonal 3600 1.9 ms 0.06 ms

Bugs found on the way, fixed here

  • A tile layer ignored its offset in Tiled and its own pos; getTile() follows too. The pathfinding plugin's grid follows a moved layer (1.1.1, unreleased).
  • Tiles larger than a cell were cut off or left out: along the edges of the view, above and right of the map, on a map centred in the screen, in a level loaded into a container, and once the map itself had left the view.
  • Staggered and hexagonal maps were not drawn where Tiled draws them: tiles larger than a cell hung from the top of the cell, the tileset's tileoffset was ignored, and odd sizes drifted off whole pixels. They now follow Tiled 1.10's numbers.
  • On the orthogonal GPU path: soft edges of large tiles, large tiles cut at the map's top and right, and a tileset with a margin and no trailing margin.
  • A layer removed and added again threw; a tile missing from its tileset's image threw every frame.

Visible changes for existing games, all in the changelog: a map whose tile layers have an offset in Tiled now draws them moved; staggered and hexagonal maps with tiles larger than a cell sit where Tiled puts them; a half-transparent isometric, staggered or hexagonal layer fades as one picture on WebGL and WebGPU.

How it was tested

Every case is drawn through the CPU renderer and the GPU one and compared pixel by pixel with a reference painted with a plain 2D canvas and no engine. About 180 scenarios per GPU backend, plus Canvas suites for the CPU renderer, placement, layer offsets and getTile. The four real example maps (Isometric Dungeon, isometric and staggered grass and water, hexagonal mini) match between the two paths within one colour level.

The WebGPU pixel scenarios skip where the browser has no WebGPU adapter, which is the case in CI. They were run locally on a software WebGPU device and pass there; the WebGPU renderer's bookkeeping is covered in CI by the mock tests.

Not in this PR: oblique maps (still tile by tile), and hexagonal tiles rotated by 60° or 120°, which the engine has never drawn.

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 (pnpm lint passes)
  • I have tested my changes locally (pnpm test passes)
  • I have added tests that cover my changes (if applicable)
  • The build succeeds (pnpm build)

Related issues

Closes #1897


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
Copilot AI balanced review requested due to automatic review settings November 19, 2026 05:31

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 2072221 into master Nov 19, 2026
6 checks passed
@obiot
obiot deleted the claude/hopeful-hypatia-jl2ouu branch November 19, 2026 05:39
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.

GPU tile layers for isometric maps (the "shader" render mode)

3 participants