QUICKUPSCALE

PRACTICAL GUIDE

Tilesets, animation and atlas handoff

Use an extruded tileset without treating gutters as artwork

Start here

For the actual 20×16 padding-tool result, use Tiled tile size 6×4, margin 2 and spacing 4. The 10×8 allocated cell includes gutters; it is not a 10×8 content tile.

Expected result:

A Tiled tileset and 4×3 map using all four content tiles. The actual extrusion-1 PNG was saved into native resources, reopened and rasterized at 1× with matching decoded content.

What you need

Use the original CC0 21×16 sheet from the source pack. The pack's transparent/extrusion-1/extrusion-2 PNGs and native projects are generated software references. The actual browser download below and new native consumer check are separate from that retained reference project.

Tested with: Actual production U04 padding2/extrusion1 → Tiled 1.12.2 / Qt 6.10.2 native save/reopen and 1× tmxrasterizer on macOS; independent Pillow 12.3.0. Browser producer: desktop Chrome 154 local Cloudflare/workerd.

1. Export the actual extruded image

Choose assets/inputs/tiles-margins.png in the padding tool. Declare cells 6×4; margins left 2/top 1/right 4/bottom 3; horizontal/vertical gaps 3/4; padding 2 and extrusion 1. Select Create padded PNG and keep its PNG, manifest and ZIP.

The recorded actual extrusion-1 PNG is 20×16. Its actual geometry manifest is generic metadata, not a Tiled TSX file. Extrusion 1 copies the inner ring; no new native extrusion-2 consumer run is claimed here.

2. Use content size and matching separation

When creating an image-based tileset in Tiled, choose the actual PNG and enter tile width 6, tile height 4, margin 2 and spacing 4. Keep two columns and four tiles. Save the tileset and map, then reopen them to verify the saved settings.

content origins: (2,2), (12,2), (2,10), (12,10)
content size:    6×4
allocated cell:  10×8
margin:         2
spacing:        2+2 = 4

The actual native verification used Tiled's public CLI readers/writers, not editor-dialog automation. It wrote previously absent TSX/TMX files, reopened both, checked all four rectangles and all twelve authored map IDs, then rasterized a fresh 24×12 image.

3. Compare the actual native result

Actual Tiled native raster of a four by three map using all four tiles from the browser extrusion-one output
Actual 24×12 Tiled raster exported at native 1× and enlarged here to fit the page. It uses the actual extrusion-1 PNG, not a reconstructed Node atlas.

All 288 native output pixels matched the actual PNG's four content crops and a fresh native plain-sheet baseline. The extrusion-0 control produced the same native map bytes, because both select the same content rectangles. This checks correct cropping, not bilinear or GPU sampling.

Keep raw-source→Canvas and artifact→Qt boundaries separate. Alpha and opaque samples passed; hidden RGB and some partial-alpha RGB can change during decode/composition. Exact integer raster output does not imply original PNG-byte fidelity.

4. Distinguish wrong spacing from rendering seams

The source project includes a deliberately wrong spacing:2 variant. Its second content rectangle starts at (10,2), instead of (12,2), selecting gutter or adjacent content. The retained reference-native control failed visibly, then matching spacing recovered the intended map. That older reference control is not a fresh actual-U04 wrong-spacing run.

Restore spacing 4 before diagnosing a renderer. Mipmaps, fractional camera positions, UV conventions, sRGB and GPU filtering need separate runtime tests; padding does not guarantee a seam-free game.

5. Reproduce the standalone reference project

Extract the ZIP into a fresh directory. With Node 24, run:

node --test --test-concurrency=1 --test-timeout=30000 fixture.test.mjs
node generate.mjs
node generate.mjs --check

The 18 original cases check the finite 29-member project, source pins, geometry and readonly/CLI behavior. Tiled and optional Pillow are separate installed tools; no runtime is bundled or installed by these commands.

Follow the ZIP's README for its optional native reference recipe and absolute project/report/render paths. Require a fresh matching report and actual output files as well as exit status: Tiled can exit 0 after a script error. The retained source recipe reads and rereads; the new actual extrusion-1 run separately verified native write→reopen.

Sources and next steps