GM Map

GM Map

An Obsidian plugin for tabletop RPG game masters. Display a map to your players on a second screen with full DM control — including fog of war, DM-only markers, and creature tokens linked to your bestiary.

Desktop only — this plugin requires the Obsidian desktop app.

---

Table of Contents

• Features
• Screenshots
• Quick Start
• Code Block Reference
  • Basic Options
  • Grid Options
  • Tokens
  • Markers
• DM View
  • Toolbar
  • Fog of War
  • Working with Tokens
  • Working with Markers
  • Player Pan Control
  • Grid Alignment
  • Saving State to the Note
• Player View
• Statblock Integration
• Plugin Settings
• State Persistence
• Tips & Tricks
• Troubleshooting
• Installation
• Obsidian Developer Policy Disclosures
• License
• Contributing

---

Features

• Dual-view layout — a DM view (with full visibility) and a Player view (showing only what you reveal)
• Fog of war — paint and erase fog to reveal the map progressively; two independent modes: grid cells and freeform brush
• DM-only markers — place waypoints and notes visible only to the DM, each with an optional longer note and a linked vault note
• Creature tokens — drag tokens onto the map and optionally link them to entries in your bestiary
• Statblock integration — works with the Fantasy Statblocks plugin to display creature statblocks directly from a token
• Grid overlay — optional square grid that can be toggled for both DM and Player views simultaneously
• Player pan control — the DM can pan the player's view remotely without moving their own viewport
• Persistent state — token positions, fog, and markers are auto-saved in a sidecar file; tokens and markers can also be written back into the code block

---

Screenshots

Rendered code block in a note — quick access to DM and Player views, with a live token/marker count.

DM view — full map visibility with toolbar, fog layer, tokens, and DM-only markers.

DM view — marker note panel — click any marker to read its note in the side panel without leaving the map.

DM view — statblock panel — click a token linked to a bestiary creature to see its full statblock inline.

Player view — only the areas you have revealed are visible; fog covers the rest.

Plugin settings — configure default grid size, fog opacity, brush size, colors, label size, and player screen DPI.

---

Quick Start

1. Add a map image to your vault (e.g. Maps/dungeon.png).

2. Open or create a note and add the following code block:

   ```gm-map
   id: my-dungeon
   image: "Maps/dungeon.png"
   grid: 70
   ```
   

3. Click the Open DM view button that appears in the rendered block, or use the command palette → GM Map: Open DM view.

4. Open a second Obsidian window (or split the workspace) and run GM Map: Open Player view.

5. Move the Player view window to your second monitor and go full-screen.

6. In the DM view, use the fog tools to reveal areas as the session progresses.

---

Code Block Reference

All gm-map code blocks are written in YAML. Every property is optional except image.

Basic Options

Minimal example:

```gm-map
image: "Maps/tavern.png"
```

Full basic example:

```gm-map
id: session-5-dungeon
image: "Maps/dungeon-level-1.png"
width: 2048
height: 1536
fogOpacity: 0.5
```

---

Grid Options

The grid is used both as a visual overlay and to drive the grid-cell fog tool. Each cell in the grid represents one map square (typically 5 ft. in D&D).

Example — aligning a grid to existing map art:

```gm-map
id: keep-ground-floor
image: "Maps/keep.jpg"
grid: 64
gridOffsetX: 12
gridOffsetY: 8
gridOverlay: true
```

Tip: Use the Grid Alignment panel in the DM toolbar to adjust gridOffsetX/gridOffsetY interactively. The values are shown live and can be pasted back into the code block.

---

Tokens

Tokens are circular markers that represent creatures or NPCs on the map. They are visible to both the DM and the players.

Tokens can be authored directly in the code block or placed interactively in the DM view. The Save to note button writes the current working set back into the code block.

Each token in the tokens array supports these fields:

Example — a combat encounter:

```gm-map
id: goblin-ambush
image: "Maps/forest-road.png"
grid: 70
tokens:
  - id: goblin-1
    x: 320
    y: 480
    label: "Goblin"
    color: "#27ae60"
    creature: "Goblin"
  - id: goblin-2
    x: 420
    y: 500
    label: "Goblin"
    color: "#27ae60"
    creature: "Goblin"
  - id: bugbear-boss
    x: 600
    y: 350
    radius: 50
    label: "Krug"
    color: "#8e44ad"
    creature: "Bugbear"
  - id: fighter-pc
    x: 200
    y: 480
    label: "Aldric"
    color: "#2980b9"
```

---

Markers

Markers are DM-only diamond-shaped pins. They are never shown in the Player view. Use them for hidden room descriptions, trap locations, notes to yourself, or links to detailed vault notes.

Example — dungeon key:

```gm-map
id: dungeon-level-2
image: "Maps/dungeon-l2.png"
grid: 70
markers:
  - id: room-1
    x: 150
    y: 200
    label: "Room 1"
    color: "#f39c12"
    note: "Empty guardroom. Overturned table, dried blood on the floor."
  - id: secret-door
    x: 340
    y: 410
    label: "Secret door"
    color: "#e74c3c"
    note: "DC 15 Perception to notice. Opens into Room 7."
  - id: boss-lair
    x: 720
    y: 580
    label: "Lair"
    color: "#8e44ad"
    linkedNote: "Encounters/Lich Lair.md"
```

Note: linkedNote opens the referenced note in the DM side panel. The player view is never affected.

---

DM View

Open the DM view via the Open DM view button in the rendered code block, or through the command palette (GM Map: Open DM view). The DM view shows the full map with all tokens, all markers, and a semi-transparent fog layer so you can work underneath the fog.

Toolbar

Additional toolbar controls:

• Eye / Eye-off toggle — switches between "reveal" mode (paint away fog) and "hide" mode (re-add fog). Applies to both fog tools.
• Brush size slider — adjusts the diameter of the freeform brush in image pixels.
• Snap to grid toggle (magnet icon) — when active, tokens snap to the nearest grid cell center when placed or dragged. Large creatures whose diameter covers an even number of cells (2×2, 4×4 …) snap to grid corners instead, which is the correct position for creatures that straddle four cells. Can be toggled on/off per session; the default is controlled by the Snap tokens to grid plugin setting.
• Grid overlay toggle (layout-grid icon) — shows or hides the square grid on both the DM and Player views simultaneously.
• Save to note button — writes the current token and marker positions back into the gm-map code block in your note.

---

Fog of War

The fog system uses two independent layers that are composited together:

1. Grid layer — a boolean per-cell grid. Toggle individual cells on and off with the fog-grid tool. Efficient for revealing rooms one square at a time.
2. Brush layer — a freeform PNG mask painted with the fog-brush tool. Useful for organic shapes like cave systems or outdoor areas.

Both layers are always active at the same time. A cell is revealed if either the grid cell is revealed or the brush has painted over it.

Workflow example — revealing a dungeon room:

1. Select the Fog: grid cells tool.
2. Make sure the toggle shows Eye (reveal mode).
3. Click and drag across the cells that make up the room to reveal them.
4. Switch to Fog: freeform brush to touch up edges or reveal corridors smoothly.
5. To re-fog an area (e.g., the players retreat), flip the toggle to Eye-off (hide mode) and paint over it.

The fog state is saved automatically to a sidecar file (.obsidian/plugins/gm-player-map/maps/<id>.json). It does not live in the code block — fog data is too large and binary to embed in Markdown.

---

Working with Tokens

Adding a token interactively:

1. Select the Add token (user) tool.
2. Click the location on the map where you want to place the token.
3. Fill in the token dialog: label, color, radius, and optionally a creature name from your bestiary.
4. Click Save.

Moving a token:

1. Switch to the Pan / select tool.
2. Click the token to select it (a white ring appears).
3. Drag it to the new position. If Snap to grid is enabled, the token snaps to the nearest cell center (or grid corner for large creatures) as you drag.

Editing or deleting a token:

1. Select the token with the Pan / select tool.
2. The token details appear in the side panel.
3. Click Edit to change the label, color, size, or linked creature.
4. Click Delete to remove the token.

Snap to grid:

The Snap to grid toggle (magnet icon in the toolbar) automatically places or snaps dragged tokens to clean grid positions:

• Medium and smaller creatures (radius ≤ half a cell, or covering 1×1 / 3×3 cells): center snaps to the middle of the nearest cell.
• Large creatures (diameter covering 2×2 or 4×4 cells): center snaps to the nearest grid corner, correctly positioning the creature over four cells.

The snap tile size is derived from the token's radius relative to the map's grid value, so resizing a token and saving re-snaps it automatically on the next placement.

Linking a token to a bestiary creature:

When editing a token, type a creature name in the Creature field. If Fantasy Statblocks is installed, a dropdown will suggest matching creatures from your bestiary. Once linked, clicking the token shows the full statblock in the side panel.

---

Working with Markers

Adding a marker interactively:

1. Select the Add marker (map-pin) tool.
2. Click the location on the map.
3. Fill in the marker dialog: label, color, optional note text, and optionally a linked vault note path.
4. Click Save.

Viewing and editing a marker:

1. Switch to the Pan / select tool.
2. Click the marker diamond to select it.
3. The note (if any) appears in the side panel. If a linkedNote is set, the note's content is rendered there.
4. Click Edit to change the marker's fields or Delete to remove it.

Markers are completely invisible to players. They are never sent to the Player view.

---

Player Pan Control

The Player pan tool (navigation icon) lets you scroll what the players see without moving your own DM viewport.

1. Select the Player pan tool.
2. Click and drag on the map — the Player view pans to match.
3. Switch back to Pan / select to resume normal DM navigation.

This is useful when you want to draw the players' attention to a specific area of the map without revealing your own view.

---

Grid Alignment

If your map image has a grid baked into the artwork, use the Grid Alignment panel to align the plugin's overlay grid to the art:

1. Click the Grid alignment button (ruler icon) in the toolbar.
2. Drag the X offset and Y offset sliders until the overlay lines up with the art.
3. Note the values and paste them into gridOffsetX / gridOffsetY in your code block so the alignment is preserved across sessions.

The grid cell size (grid) must also match the pixel size of one map square in the image.

---

Saving State to the Note

Click Save to note in the DM toolbar to write the current token and marker positions back into the gm-map code block in your note. This is useful to:

• Version-control a snapshot of the encounter in your session notes.
• Pre-populate a map with tokens that should appear at the start of the next session.
• Share the note with someone else with all positions intact.

Important: Fog state is not saved into the note — it lives in a separate sidecar file. Only token and marker data is embedded in the code block.

---

Player View

Open the Player view via the command palette (GM Map: Open Player view). Move the view to your second monitor and make it full-screen.

The Player view:

• Shows only revealed areas (fully opaque fog everywhere else).
• Shows creature tokens.
• Never shows DM markers or the DM toolbar.
• Reflects all DM changes in real time: fog reveals, token movements, and grid overlay toggles.
• Can be panned remotely by the DM using the Player pan tool.

Recommended setup:

1. In Obsidian, open a new window: View → New window (or drag a tab out).
2. Open the Player view in that window.
3. Move the new window to your second monitor and press F11 (or your OS full-screen shortcut).
4. The players only see the second monitor. You retain full control on the primary monitor.

---

Statblock Integration

GM Map integrates with the Fantasy Statblocks community plugin (obsidian-5e-statblocks). When that plugin is installed and enabled:

• The token edit dialog shows a searchable dropdown of all creatures in your bestiary.
• Clicking a token that has a creature field set renders the full statblock in the DM side panel.
• All creature data stays local — no network requests are made.

Setup:

1. Install and enable Fantasy Statblocks.
2. Import your bestiary (e.g., the SRD monsters or a custom YAML file) via the Statblocks settings.
3. In GM Map, edit any token and start typing in the Creature field — matching names will appear in the dropdown.

Example code block using creature links:

```gm-map
id: throne-room-encounter
image: "Maps/throne-room.png"
grid: 70
tokens:
  - id: vampire
    x: 800
    y: 400
    radius: 45
    label: "Count Strahd"
    color: "#7f0000"
    creature: "Vampire"
  - id: zombie-1
    x: 600
    y: 350
    label: "Zombie"
    color: "#556b2f"
    creature: "Zombie"
  - id: zombie-2
    x: 620
    y: 450
    label: "Zombie"
    color: "#556b2f"
    creature: "Zombie"
```

---

Plugin Settings

Open Settings → GM Map to configure global defaults. Per-map overrides in the code block always take precedence.

---

State Persistence

GM Map separates two kinds of state:

How seeding works:

When you open a map, GM Map computes a signature of the tokens and markers in the code block. If the signature has changed since the last save (because you edited the note), the code block data re-seeds the working state. If the signature is unchanged, the last saved dynamic state is used — so live edits such as token movements persist across sessions.

This means you can safely edit your code block to add new tokens without losing any fog work. Only the tokens/markers are re-seeded; fog state is always loaded from the sidecar file.

---

Tips & Tricks

Use unique, stable IDs. Always set an explicit id in your code block. If you omit it, the plugin auto-generates one from the image path — which will break if you rename the image or the note.

```gm-map
id: session-07-crypt      # ← always set this
image: "Maps/crypt.png"
```

Pre-place tokens before the session. Author all expected encounter tokens in the code block the night before. When you open the map, they will appear ready to go.

Use a TV as a player screen. Set Player screen DPI in settings to match your TV's pixel density. The plugin will scale the map so each grid square is exactly 1 inch — perfect for placing physical minis on the screen.

Reveal the whole map instantly. With the fog-grid tool in reveal mode, hold and drag across the entire map to reveal everything in one sweep.

Re-fog explored areas. Switch the fog toggle to Eye-off (hide mode) and paint over areas the players have left. Useful for dungeon crawls where backtracking should restore the unknown feeling.

Combine grid and brush fog. Use grid cells for rooms (clean edges) and the brush tool for organic areas like caves or forests. Both layers composite together seamlessly.

Link markers to notes. For complex locations, set linkedNote on a marker to point to a detailed encounter note. Clicking the marker in the DM view opens the full note in the side panel — no need to switch tabs.

markers:
  - id: dungeon-master-notes
    x: 400
    y: 300
    label: "Room 12"
    linkedNote: "Sessions/Session 7/Room 12 - Oubliette.md"

---

Troubleshooting

The map image does not appear. Make sure the image path is relative to the vault root and uses forward slashes. The image must be inside your vault.

# Correct
image: "Maps/dungeon.png"
image: "Assets/Maps/city.jpg"

# Wrong — absolute path
image: "/Users/me/pictures/map.png"

Fog / tokens reset after reopening the note. Check that your code block has a stable id. If the id changes (e.g., because you omitted it and renamed the image), the plugin cannot find the saved state. Add an explicit id and the issue will not recur.

The grid does not align with the map art. Use the Grid Alignment panel (ruler icon in the toolbar) to find the correct gridOffsetX/gridOffsetY values. Also verify that the grid value matches the pixel size of one square in your map image.

The Player view is blank or not updating. Ensure both DM and Player views refer to the same map (same id). Both views must be open at the same time; the Player view receives live updates from the DM view only while both are loaded.

Fantasy Statblocks creatures do not appear in the dropdown. Make sure the Statblocks plugin is enabled and your bestiary has been imported. Try reloading Obsidian (Ctrl/Cmd + R). The creature dropdown only appears if at least one creature is in the bestiary.

Saving state is slow or fails silently. The plugin writes to .obsidian/plugins/gm-player-map/maps/. Ensure your vault is on a writable filesystem and that Obsidian has the necessary permissions.

Map is not moving for players Close GM and player view and open it again.

---

Installation

From the Obsidian Community Plugin directory

1. Open Settings → Community plugins → Browse
2. Search for GM Map
3. Click Install, then Enable

Manual installation

1. Download main.js, styles.css, and manifest.json from the latest release
2. Copy the files into your vault at .obsidian/plugins/gm-map/
3. Reload Obsidian and enable the plugin under Settings → Community plugins

---

Obsidian Developer Policy Disclosures

In compliance with the Obsidian developer policies, the following disclosures are made:

---

License

This project is licensed under the MIT License — see the LICENSE file for details.

Third-party licenses

This plugin is built on top of the Obsidian Plugin API. Obsidian is a trademark of Dynalist Inc. This plugin is an independent community project and is not affiliated with or endorsed by Obsidian.

---

Contributing

Bug reports and pull requests are welcome. Please open an issue before submitting large changes.