How to Import a JPG or PDF Map Into Foundry VTT for Live Play
To use a map during a live game, prepare it as an image, add it as a Foundry scene background, then align the scene grid before placing tokens or building walls. JPG files can be uploaded directly; a PDF map page must first be exported as an image. The key setup choice is whether the map already has a visible grid: that determines whether you align Foundry’s grid to the art or use a gridless scene.
1. Check the map before importing
Open the JPG or PDF and identify the actual play area. For a PDF, check whether the map is one page or split across several pages, and whether margins, a title block, or other page furniture surround it. A multi-page PDF usually needs one image export per map page; importing the whole document as a single scene background is not a way to switch between its pages during play.
Decide whether you need grid-based movement and measurement. If so, count the map’s grid spaces horizontally and vertically if a grid is printed on it. If there is no printed grid, decide on a scale appropriate to your group’s rules before configuring the scene. Foundry measures grid size in pixels per space; its grid settings also affect token placement and distance measurement. Foundry’s Scenes guide
2. Convert a PDF page to an image
Export only the page containing the map when the PDF includes other material. In Acrobat’s web workflow, choose Convert > Export a PDF, select the file, choose an image format such as JPG, set image quality, then convert and download. Acrobat may put exported page images into a ZIP file, so extract the image before uploading it. The menu labels can differ between Acrobat versions. Adobe’s PDF export instructions
Inspect the exported image at a useful zoom level. Check that the map edges are intact, labels remain legible, and no important part was cropped. JPG uses lossy compression; repeated compression can soften fine lines and text. Foundry’s media guidance notes that JPEG can reduce file size but compression can create visible artifacts. For a map where tiny labels or delicate linework matter, use a higher image quality setting or an image format that preserves sharper detail when your VTT accepts it. Foundry’s media guide
3. Create a scene and upload the map
In Foundry, open the Scenes Directory and create a scene. Configure it and use the Background Image file picker to select or upload the JPG you prepared. The selected background determines the scene dimensions by default; Foundry lets you adjust those dimensions in the scene’s grid settings. Keep an untouched copy of the source image so you can retry with a different export or scale without losing the original. Foundry’s Scenes guide
Name the scene so you can find it during play, then save and view it before adding details. If the map does not appear, confirm the background image path points to the uploaded file. A renamed or moved background can leave the scene showing only its background color. Foundry’s scene-loading troubleshooting guide
4. Match the grid to the map
For a printed square grid, measure the number of complete spaces across the image and divide the image width in pixels by that count. For example, if the image is 2,800 pixels wide and contains 20 spaces across, the implied space size is 140 pixels. Check the height calculation too: it should produce roughly the same value. This is a practical estimate based on Foundry’s documented method of dividing image dimensions by the number of spaces. Foundry’s Scenes guide
Enter the corresponding grid type and size in the scene’s grid settings. If the printed lines and overlay do not align, use Foundry’s Grid Alignment Tool to adjust the overlay against the map. Avoid placing tokens, walls, or lights until alignment is satisfactory, because changing the grid later can shift how scene objects line up. Foundry has a 50-pixel minimum grid size; if your calculated scale is below that, increase the displayed background dimensions and grid size together while preserving their proportions. Foundry’s Scenes guide
If the map has no printed grid, choose a grid size that suits your desired movement scale, or select Gridless if free placement and point-to-point measuring better fit the session. A visible overlay is optional, but the grid configuration still governs how Foundry places tokens and measures distance when using a grid. Select square or hexagonal grid type to match the map and game. Foundry’s Scenes guide
5. Check image size and legibility
A very large image can be hard for players’ devices to render. Foundry says the practical maximum varies by hardware and gives approximate limits of 8,000 pixels per dimension on older computers and 16,000 on newer ones; these are guidance, not a guarantee for every device. If the image loads slowly or renders as a black screen, try a smaller export while retaining enough pixels per grid space for tokens and labels to remain clear. Foundry’s scene-loading troubleshooting guide
For example, reducing a map from 10,000 pixels wide to 5,000 pixels wide also halves the pixel count per printed square. That can make labels less readable at close zoom, so inspect the resized file before replacing the larger version. Foundry does not use an image’s DPI/PPI metadata for scene quality; pixel resolution and pixels per grid space are the relevant considerations. Foundry’s content creation guide
6. Run a live-play check before adding detail
View the scene as a player would and confirm the whole map fits the visible canvas, the overlay follows the printed lines, and tokens snap or move as expected. Try measuring a known number of spaces. If the grid appears doubled, the JPG likely already has printed lines while the VTT overlay is enabled; reduce overlay opacity, hide it, or use a gridless setup if you do not need the software grid.
Once the background and grid are stable, add tokens and any optional walls, lighting, or notes. Test the scene with a connected player if possible, especially when the map is large. If the background goes missing later, verify its file path and that the image has not been moved. This order keeps import, scale, and live-play checks separate, making a misalignment easier to diagnose.