Map

A battle map — the playing surface and everything placed on it.

A Map is a background image or video, a grid describing how that background maps to game distances, and layers of objects on top: tokens for creatures, tiles for scenery, walls for the vision and movement mesh, lights, areaEffects, markers, drawings and measurements.

Two systems make maps more than pictures. Fog of war (fogOfWar) hides the map from the players until revealed, and line of sight (lineOfSight) computes what each token can actually see from the wall mesh and the light sources — which is why walls carry types distinguishing what blocks vision from what blocks movement.

The map the game master edits and the map the players see are the same object rendered differently: dmDarkness and dmMarkerStyle control only the GM’s view.

JSON Example

A map with a background image, fog of war and line of sight enabled, one wall segment and one token. Object collections that are empty are shown here for completeness; the elements of each follow their own model’s schema.

{
  "id" : "8C2F1A9E-5B3D-4E6F-9A1C-2D7E4F8B0C13",
  "name" : "Cragmaw Hideout",
  "slug" : "cragmaw-hideout",
  "descr" : "A goblin lair in a cave beside a stream.",
  "gridSize" : 50,
  "gridOffsetX" : 0,
  "gridOffsetY" : 0,
  "gridColor" : "#cccccc",
  "gridVisible" : true,
  "gridScale" : 5,
  "gridUnits" : "ft",
  "gridType" : "square",
  "gridStyle" : "solid",
  "gridOpacity" : 1,
  "scale" : 1,
  "x" : 1024,
  "y" : 1024,
  "zoom" : 1,
  "width" : 2048,
  "height" : 2048,
  "image" : "cragmaw-hideout_a1b2c3.jpg",
  "snapshot" : "cragmaw-hideout-snapshot_d4e5f6.jpg",
  "fogOfWar" : true,
  "fogExploration" : true,
  "fog" : "cragmaw-hideout-fog_a1b2c3.png",
  "lineOfSight" : true,
  "losDaylight" : 0,
  "losVisionLimit" : -1,
  "weatherType" : "rain",
  "weatherIntensity" : 0.5,
  "dmDarkness" : 0.6,
  "parentId" : "",
  "rank" : 0,
  "version" : 1,
  "walls" : [
    {
      "id" : "1F0A6B4C-7D8E-4A2B-9C3D-5E6F7A8B9C0D",
      "data" : [ 100, 100, 100, 400 ],
      "type" : "door",
      "door" : "closed"
    }
  ],
  "tokens" : [
    {
      "id" : "3B7E2D1F-9A4C-4E8B-8D6A-1C2F3E4D5B6A",
      "name" : "Goblin",
      "x" : 300,
      "y" : 250,
      "width" : 50,
      "height" : 50
    }
  ],
  "markers" : [],
  "tiles" : [],
  "areaEffects" : [],
  "lights" : [],
  "measurements" : [],
  "drawings" : []
}

• SeeAlso: Token, Tile, Wall, Light, Marker, AreaEffect

View JSON Schema

Property	Type	Required	Description
id	string	Yes	The unique identifier for this map. A UUID string automatically generated when the map is created. This serves as the primary key in the Realm database and names the map’s resource directory on disk.
name	string	Yes	The display name of the map. Examples: "Cragmaw Hideout"
slug	string	Yes	A URL-friendly identifier for the map. Used to link to the map from page content, as /map/cragmaw-hideout. Examples: "cragmaw-hideout"
descr	string	Yes	The description of the map. Read-aloud text or the game master’s notes on the location.
gridSize	integer	Yes	The length of one grid cell in image pixels. The core calibration value: it ties the background artwork to game distances, so a 50-pixel cell at a gridScale of 5 means 50 pixels is five feet.
gridOffsetX	integer	Yes	The horizontal offset of the grid origin, in pixels. Shifts the grid to line up with artwork that was not drawn flush to the image edge.
gridOffsetY	integer	Yes	The vertical offset of the grid origin, in pixels.
gridColor	string	Yes	The color of the grid lines, as an RGB string. Examples: "#cccccc"
gridVisible	boolean	Yes	Whether the grid is drawn at all.
gridScale	number	Yes	The in-game distance one grid cell represents, in gridUnits. Examples: 5 — five feet per square, the D&D convention; 1.5 — with gridUnits of "m"
gridUnits	string	Yes	The unit gridScale is expressed in. Shown alongside measured distances. Examples: "ft", "m", "sq"
gridType	string	Yes	The grid geometry, as the raw value of a GridType. Use gridTypeValue for the typed form. Examples: "square", "hexFlat", "hexPointy"
gridStyle	string	Yes	How grid lines are drawn, as the raw value of a GridStyle. Use gridStyleValue for the typed form. Examples: "solid", "corners"
gridOpacity	number	Yes	The opacity of the grid lines, from 0 to 1.
image	string	No	The file name of the background image. Note: Resolved against the map’s dataURL. Examples: "map.jpg"
video	string	No	The file name of the background video, for animated maps. Takes the place of image when present. Examples: "map.mp4"
scale	number	Yes	A uniform scale applied to the background. Lets a map be enlarged or reduced without re-exporting the artwork; scaledSize is the result.
x	integer	Yes	The horizontal center of the saved viewport, in map coordinates. Restores where the game master was looking when the map is reopened. SeeAlso: center
y	integer	Yes	The vertical center of the saved viewport, in map coordinates.
zoom	number	Yes	The saved zoom level of the viewport.
width	integer	Yes	The map width in pixels. Usually derived from the background rather than set directly — see size.
height	integer	Yes	The map height in pixels.
canvas	string	No	The file name of the freehand drawing layer raster. Note: Distinct from drawings, which holds vector shapes.
snapshot	string	No	The file name of the generated thumbnail. A rendered preview of the map with its objects, shown in map lists.
floor	string	No	The file name of an image drawn beneath the background. Shows through wherever the background is transparent.
fogOfWar	boolean	Yes	Whether the map is covered by fog of war. While enabled the players see only what the game master has revealed. SeeAlso: fog, fogExploration
fogExploration	boolean	Yes	Whether moving tokens reveal fog as they go. Turns fog of war from something the game master paints manually into something the party uncovers by exploring.
fog	string	No	The file name of the fog-of-war mask. A raster recording which parts of the map have been revealed.
lineOfSight	boolean	Yes	Whether dynamic line of sight is computed. When enabled, each token’s visible area is derived from the walls mesh and the available light, and the player display is masked to it. SeeAlso: Wall, Vision, Light
losDaylight	number	Yes	How much ambient light the map has, from 0 (pitch dark) to 1 (full daylight). At 0 tokens see only what their own vision and placed lights illuminate.
losVisionLimit	integer	Yes	The maximum sight distance in grid units, or -1 for unlimited. Caps vision regardless of light — for fog, mist, or simply to bound the computation on very large maps.
weatherType	string	No	The weather overlay, as the raw value of a WeatherType. Use weatherTypeValue for the typed form. nil means no weather. Examples: "rain", "snow", "fog"
weatherIntensity	number	Yes	How heavy the weather effect is, from 0 to 1.
dmDarkness	number	Yes	How much the map is dimmed in the game master’s view, from 0 to 1. Darkens areas outside token vision for the GM without hiding them, so unlit regions stay legible while still reading as dark.
dmMarkerStyle	string	No	How markers appear in the game master’s view, as the raw value of a MarkerStyle. Use dmMarkerStyleValue for the typed form. Examples: "normal", "shape", "hidden"
parentId	string	Yes	The identifier of the group containing this map in the library tree.
rank	integer	Yes	The manual sort position of the map. Lower values sort first.
version	integer	Yes	The map format version, used when importing and migrating map data.
walls	Array<Object>	No	The vision and movement mesh, stored as JSON. Walls are kept as an encoded array rather than Realm objects because a detailed map can carry thousands of segments and they are always loaded and rendered as a whole. Note: Access through wallsValue.; SeeAlso: Wall
drawings	Array<Object>	No	The vector drawing layer, stored as JSON. Kept encoded for the same reason as walls. Note: Access through drawingsValue.; SeeAlso: Drawing
markers	Array<Marker>	Yes	Points of interest placed on the map. SeeAlso: Marker
tiles	Array<Tile>	Yes	Scenery and props placed on the map. SeeAlso: Tile
tokens	Array<Token>	Yes	The creatures on the map. SeeAlso: Token
areaEffects	Array<AreaEffect>	Yes	Spell templates and other marked-out areas. SeeAlso: AreaEffect
lights	Array<Light>	Yes	Standalone light sources, independent of any token or tile. SeeAlso: Light
measurements	Array<Measurement>	Yes	Persistent distance measurements drawn on the map. SeeAlso: Measurement
data	Object	No	Flexible JSON storage for system-specific or arbitrary structured data. Note: Access through dataValue or dataJSON.

BattleMapLayer

View JSON Schema

Type: string — one of:

• token
• object
• map
• dm
• wall
• floor
• light

Drawing

A vector shape drawn on a Map.

Drawings are the annotation layer — outlines, highlights and sketched-in features the game master adds over the artwork. Unlike Map/canvas, which is a raster, these stay editable and can be moved between map layers.

Like Wall, a drawing is a plain Codable value stored encoded in Map/drawings, and its derived geometry is cached — call invalidate() after editing data directly.

• SeeAlso: Map/drawings, Wall

View JSON Schema

Property	Type	Required	Description
id	string	Yes	The unique identifier for this drawing. A UUID string generated when the drawing is created.
data	Array<number>	Yes	The drawing’s vertices, as a flat list of alternating x and y coordinates. Note: Edit through update(_:), which also invalidates the cached geometry.; SeeAlso: points
shape	Shape	No	The drawing’s geometry; nil behaves as Shape/polygon.
layer	BattleMapLayer	No	Which map layer the drawing sits on. Determines whether it is drawn under or over the tokens.
strokeWidth	number	No	The outline width, in map coordinates.
strokeColor	string	No	The outline color, as an RGB string. Examples: "#ff0000"
fillColor	string	No	The fill color, as an RGB string; nil leaves the shape unfilled.
opacity	number	No	The drawing’s opacity, from 0 to 1.

Drawing.Shape

The geometry of a Drawing.

Type: string — one of:

• polygon
• ellipse
• rectangle

GridStyle

How a Map’s grid lines are drawn.

View JSON Schema

Type: string — one of:

• solid
• corners

GridType

The tiling geometry of a Map’s grid.

View JSON Schema

Type: string — one of:

• square
• hexFlat
• hexPointy

Wall

One segment chain of a Map’s vision and movement mesh.

Walls are what make line of sight work: each is a polyline whose type says whether it stops vision, movement, or both. Doors additionally carry a door state that can change during play, so opening one changes what the party can see.

Unlike the other map objects a wall is a plain Codable value, not a Realm object — the whole mesh is stored encoded in Map/walls because a detailed map carries thousands of segments and they are always loaded together. The derived geometry (points, path, hitPath, wall segments) is cached and must be discarded with invalidate() after editing data.

• SeeAlso: Map/walls, Map/lineOfSight, WallType

View JSON Schema

Property	Type	Required	Description
id	string	Yes	The unique identifier for this wall. A UUID string generated when the wall is created.
data	Array<number>	Yes	The wall’s vertices, as a flat list of alternating x and y coordinates. Stored flat rather than as points to keep the encoded mesh compact. Examples: [100, 200, 340, 200] — a single segment from (100, 200) to (340, 200) Note: Edit through update(_:), which also invalidates the cached geometry.; SeeAlso: points
color	string	No	An override for the color the wall is drawn in while editing. Defaults to the color of its type when absent.
type	WallType	No	What this wall blocks. nil behaves as WallType/normal. SeeAlso: WallType
side	Side	No	Which side of the wall blocks; nil behaves as Side/both.
door	DoorState	No	The door’s state, for walls of type WallType/door or WallType/secretDoor. SeeAlso: DoorState
generated	boolean	No	Whether this wall was produced by automatic wall detection rather than drawn by hand. Lets generated walls be cleared in bulk without disturbing the user’s own.

Wall.Side

Which side of a wall blocks.

A one-sided wall lets a creature see out but not in — useful for balconies, cliff edges and one-way windows.

Type: string — one of:

• both
• left
• right

Wall.DoorState

The state of a door wall.

Type: string — one of:

• closed
• open
• locked

WallType

What a Wall segment blocks.

Vision and movement are blocked independently, which is what lets a window stop a creature but not its line of sight, and a curtain do the reverse.

View JSON Schema

Type: string — one of:

• normal
• invisible
• ethereal
• terrain
• door
• secretDoor