ONESHOTGEMS

For game developers

Map atlas cells to source and destination rectangles

A sprite atlas packs many frames into one image, but the browser only draws the rectangle you ask it to draw. A wrong frame width can slice into a neighbor; a mismatched pivot can make an animation appear to wobble even when each image is valid. Define frame geometry in one data map and keep source pixels separate from the destination size used by the game. That turns atlas debugging into checking explicit rectangles instead of adjusting each draw call by eye.

Describe frame geometry and animation order

For a regular grid, store cell width, cell height, columns, and the frame index for each animation. Derive source x as (index modulo columns) times cell width and source y as the floored row index times cell height. For irregular atlases, store explicit source rectangles. Keep animation order separate from file order; an eight-frame walk might use indices [0, 1, 2, 1, 0, 3, 4, 3] when the art is arranged by pose rather than sequence.

If sprites are trimmed to remove transparent margins, also store the original canvas size and trim offset. Draw around a stable pivot, such as the character's feet, so frame bounds do not move the collision body or visual ground contact as the artwork changes.

Use the source rectangle deliberately

Canvas drawImage has an overload that selects a source rectangle and scales it into a destination rectangle. MDN documents the source x, y, width and height separately from destination x, y, width and height. Use that separation to keep the atlas crop exact while changing rendered size. Test the first, last, and row-boundary frames; a mistaken column count often appears as a one-pixel sliver from the adjacent sprite at those boundaries.

Check seams and loading before diagnosing geometry

Give atlas cells a transparent gutter if adjacent art bleeds during scaled drawing, and check whether your chosen filtering mode suits the art style. Draw a debug rectangle around each destination frame and temporarily label its index. Wait until the image is loaded and decoded before drawing, then test at the actual canvas scale and backing resolution. Compare an unscaled frame with a scaled one; if only the scaled version shows a seam, investigate sampling and atlas padding before changing the source coordinates.

Questions about sprite atlas rendering

Why does part of the neighboring sprite appear?

The source rectangle may include neighboring pixels, or scaled sampling may show edge pixels from a tightly packed atlas. Check the crop and add suitable gutters before changing frame order.

Should collision boxes use the trimmed sprite bounds?

Usually keep collision dimensions tied to the game character, not incidental transparent pixels. A stable pivot and explicit hit shape prevent animation frames from changing gameplay geometry.

Sources and further reading

Report a correction · How these guides are made

Follow your curiosity