Map settings
These are the settings of the map as a whole. Each entry comes from the schema that checks a map when it is saved, so the field names, types and values are exactly what a map accepts. Positions are fractions of the map: 0 to 1 across from the left and down from the top.

Right-click the map and pick Copy coordinates to copy where you clicked: the square's name (A15) on a square grid, else how far across and down the map it is.
Map settings
aspectRatio
The map's shape, width to height. Match the background picture's.
| Field | Type | Required | Default | What it is |
|---|---|---|---|---|
aspectRatio |
{ width, height } |
yes | ||
aspectRatio.width |
number |
yes | Its width part: 16 of 16:9. | |
aspectRatio.height |
number |
yes | Its height part: 9 of 16:9. |
To set it, use Aspect ratio in Map settings. Match the picture: a 4:3 picture on a 16:9 map puts pins in the wrong place. Changing it on a map that already has pins and areas moves where they are drawn.
{ "aspectRatio": { "width": 4, "height": 3 } }
scale
How wide the whole map is in the world, or null for no scale.
| Field | Type | Required | Default | What it is |
|---|---|---|---|---|
scale |
{ widthMeasurement, unit } | null |
|||
scale.widthMeasurement |
number |
yes | The map's real width, in the unit. | |
scale.unit |
string |
yes | The unit: ft, m, mi, km or another the world uses. |
To set it, use Scale in Map settings. Set it on every map. The GM uses it for distances, travel times, what sits inside what, and whether a map is ground for a scene or country to travel across. A scale of exactly 1 mile was the old default, so where the place is also outlined on its parent's map, the GM takes its size from that outline instead. If your files say how long a journey takes, the GM uses that instead of measuring.
{ "scale": { "widthMeasurement": 2000, "unit": "m" } }
background
The map's picture, or null for none.
| Field | Type | Required | Default | What it is |
|---|---|---|---|---|
background |
{ url, offset, scale } | null |
|||
background.url |
string |
yes | The picture's URL: an uploaded or generated image. | |
background.offset |
{ x, y } |
yes | Moves the picture inside the map's frame. | |
background.scale |
number |
yes | The picture's size inside the frame: 1 fits it. |
To set it, use Map image in Map settings: upload one, pick one from the Studio, Generate one, or make one From parent. The picture must be one Craft hosts, uploaded or generated: a link to an image anywhere else is refused. A map with no picture shows an empty canvas.
A generated picture is framed by the map's scale: up to about 300 m across it is a battle map (a floor plan with the roof off, or one spot's ground), up to about 10 km a town plan, and wider a regional map, always seen from directly above. Set the scale before generating. Don't ask for a grid in the picture: the map's own grid is laid over it.
When a map gets a new picture, Craft notes the features drawn in it (the bar, the stairs, the gate), each with where it is, and the GM places people by them. Reading the map shows the same list, so exits, walls and pins can go where the picture draws them.
{ "background": { "url": "https://…", "offset": { "x": 0, "y": 0 }, "scale": 1 } }
grid
A grid of squares or hexes to move on, or null for none.
| Field | Type | Required | Default | What it is |
|---|---|---|---|---|
grid |
object | null |
null |
||
grid.mode |
"none" | "square" | "hex" |
yes | No grid (none), squares (square) or hexes (hex). | |
grid.cellSize |
{ value, unit } |
yes | One cell's real size: 5 ft. | |
grid.origin |
{ x, y } |
{"x":0,"y":0} |
Where the grid starts, as a point on the map. | |
grid.color |
string |
"#d1d5db" |
The grid lines' color. | |
grid.opacity |
number |
0.3 |
How strongly the grid lines show, 0 to 1. | |
grid.measurement |
"euclidean" | "chebyshev" | "manhattan" | "alternating-diagonal" | "hex" |
How a distance is counted: euclidean a straight line, chebyshev a diagonal step as one (5e), alternating-diagonal diagonals as one then two (PF2e), manhattan only straight steps, hex the hex tiles. | ||
grid.snapTokens |
boolean |
true |
Tokens snap to the grid's cells when they are moved. | |
grid.orientation |
"pointy" | "flat" |
"pointy" |
Hex grids only: pointy-top or flat-top hexes. |
To set it, use Grid in Map settings, which has presets for common systems. Add a grid only where people move in squares or hexes: rooms, lairs, camps, decks. With a square grid and a scale, scenes on this place's own map are played in squares. Hex grids are drawn and measured but not played in squares.
Squares are named by column letter and row number from the top left, as on a battle map: A1 is the top-left square, and A15 is fifteen squares down the first column. The GM, the play screen and the map editor's coordinates all use these names. Where people can't stand on the grid is set with terrain and walls.
{ "grid": { "mode": "square", "cellSize": { "value": 5, "unit": "ft" }, "measurement": "chebyshev" } }
overlayImages
Pictures placed over the map: a label, a ship, a drawn-on detail.
| Field | Type | Required | Default | What it is |
|---|---|---|---|---|
overlayImages |
({ id, url, rect, opacity, locked? })[] |
yes | ||
overlayImages.id |
string |
yes | The picture's own id, unique on this map. | |
overlayImages.url |
string |
yes | The picture's URL: an uploaded or generated image. | |
overlayImages.rect |
{ x, y, width, height } |
yes | Where it sits and how big it is, as fractions of the map's width and height. | |
overlayImages.opacity |
number |
yes | How strongly it shows, 0 to 1. | |
overlayImages.locked |
boolean |
Locked in place, so it can't be dragged or removed by mistake. |
To add or change one, use pasting an image onto the map, then its Image tab.
useParentMap
When true, the place has no map of its own and is shown on the map it is drawn on.
| Field | Type | Required | Default | What it is |
|---|---|---|---|---|
useParentMap |
boolean |
To set it, use Use parent map under Behavior in Map settings, or in the pin's or area's panel. Turn it on for small places that don't need their own view, such as a waystone or a market stall. Leave it off for anywhere people fight, sneak or explore room by room.
{ "useParentMap": true }
clusteringEnabled
Fans out tokens that share a spot and merges pins that cover each other.
| Field | Type | Required | Default | What it is |
|---|---|---|---|---|
clusteringEnabled |
boolean |
true |
To set it, use Tidy overlapping markers under Display in Map settings.