Craft

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.

The Map image section with Image Fit, Replace, Studio, Generate and Remove background, and the Scale section set to 2000 meters wide

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.