How to Align a Custom Map Grid With a Virtual Tabletop Scene

A map’s visible lines and the VTT’s functional grid are separate layers. The VTT grid controls token placement and measurement even when the map already has lines drawn into its image. Foundry’s scene documentation makes this distinction explicit: its grid governs token positions, measured distances, and templates, so a map that merely looks lined up may still behave incorrectly. Foundry Virtual Tabletop: Scenes

First decide whether the map uses square cells, flat-topped or pointy-topped hexes, or no regular grid. Set the scene to the matching type before tuning alignment. On a gridded map, keep the overlay visible during setup and choose a contrasting color or opacity so you can compare both sets of lines. If the printed grid is not needed for play, a gridless scene may be simpler; however, that also removes the VTT grid’s cell-based snapping and measurement behavior.

Look for grid dimensions in the map export settings, file name, or accompanying map notes. A known count of columns and rows is more reliable than judging a single cell by eye. Owlbear Rodeo, for example, lets you enter those values directly, and its documentation says maps made in Dungeondraft can use the creator’s width and height as columns and rows. Owlbear Rodeo: Aligning a Map

If you have the image’s pixel dimensions and can count whole grid spaces, divide width by columns and height by rows. For example, a 3,080 × 2,520-pixel image with 22 columns and 18 rows has 140 pixels per square in both directions. This is an illustrative calculation based on those inputs; it is also the example Foundry gives for estimating an unknown square-grid size. If the horizontal and vertical results differ substantially, the image may include borders, partial cells, or distortion, so do not force a single guessed size without checking the edges. Foundry Virtual Tabletop: Scenes

Import the map, select the correct grid type, and avoid placing walls, lights, tokens, or notes until alignment is settled. In Foundry, changing grid size can affect the alignment of those scene elements, so the documentation recommends choosing the grid before detailing the scene. Foundry Virtual Tabletop: Scenes

For a known square grid, use the pixel count per cell if the VTT asks for grid size. Make sure the image’s displayed width and height remain proportional; stretching one dimension to make a few cells fit can distort the art and still leave alignment wrong elsewhere. Foundry permits a background offset in X and Y to shift a pre-gridded image, and its grid alignment tool can help when the built-in grid does not line up with the image. The controls and names vary by platform, so use the scene’s own alignment workflow rather than assuming another VTT’s menu path applies. Foundry Virtual Tabletop: Scenes

Enter the number of columns and rows if the tool accepts cell counts. With Owlbear Rodeo, a 49-column by 28-row map can be set using those values; some exported map names include the dimensions for automatic recognition. Owlbear Rodeo: Aligning a Map

If the VTT instead asks for pixel scale, derive it from the image size and cell count, then set the grid and image dimensions consistently. Foundry’s media guidance recommends maps whose grid reaches the image edges with whole cells: for instance, 20 cells across at 100 pixels per cell means a 2,000-pixel-wide image. That convention gives the scene a clear top-left grid origin and avoids hidden margins throwing off every cell. Foundry Virtual Tabletop: Media Optimization Guide

Use the VTT’s visual alignment tool and choose a clear, undamaged grid intersection near a corner as your anchor. Match the tool’s sample grid to several adjacent cells, not just one. Roll20’s documented beta workflow uses three steps—anchor, scale a 3×3 sample, then fine-tune from another intersection or line—and supports square, hex, isometric, and dimetric grid types. Roll20: Explore the New Align to Grid Feature in Beta Owlbear Rodeo similarly recommends placing an alignment ruler at a visible cell corner, scaling it to the map, and using precision rails for refinement. Owlbear Rodeo: Aligning a Map

The practical reason to use multiple cells is accumulated error: a small size mismatch may appear correct at the anchor but drift farther from it across the image. After the initial fit, inspect a grid intersection near the opposite edge. If it misses, refine scale; if the spacing matches but every line is displaced by about the same amount, adjust position. If one axis aligns while the other drifts, refine that axis independently where the tool allows it.

Zoom in near the anchor and at the far edge. Confirm that the VTT overlay follows the printed cell boundaries across the whole playable area, including near borders and irregular map edges. For hex maps, check both directions: Owlbear Rodeo notes that pixel rounding can cause drift in one axis even after the other appears aligned, requiring another adjustment on the drifting axis. Owlbear Rodeo: Aligning a Map

Then test with a temporary token or marker. Move it across several cells and try the scene’s measuring tool; verify that snapping and distances match the grid you intend the group to use. If the overlay matches visually but measurements or token positions do not, recheck the scene’s grid type and scale, not only the image placement. Foundry identifies grid configuration as the basis for token placement and distance measurement. Foundry Virtual Tabletop: Scenes Once those checks pass, save the scene and add walls, lighting, notes, and other play aids.

If every line is shifted by roughly the same amount, move the image or adjust its offset without changing scale. If the first cells line up but the last ones drift, revisit scale using a longer span of cells. If only one direction drifts, check for a partial border or pixel rounding and tune that axis separately. If both directions fit locally but diverge elsewhere, confirm that the map has not been stretched non-proportionally or exported with uneven spacing.

An image with a visible grid baked in can be aligned, but it leaves two grids on screen and may reduce flexibility. Foundry’s map-creation guidance recommends omitting the visible grid from final art when possible so the VTT overlay can be customized or disabled. Foundry Virtual Tabletop: Media Optimization Guide If you control the export, use a whole-cell canvas and let the VTT draw the play grid; if you only have a finished gridded image, retain the printed lines and align carefully across the full map.

• Aligning a Map — Owlbear Rodeo Documentation
• Scenes — Foundry Virtual Tabletop
• Media Optimization Guide — Foundry Virtual Tabletop
• Explore the New Align to Grid Feature in Beta — Roll20 Blog