Documentation: https://chronicle-of-whispers.github.io/cow-webpage/docs/projects/shadow-atlas/
Run tabletop RPG battle maps from your Obsidian vault and share them live with your players.
A .samap file becomes a fully interactive battle map inside Obsidian: paint fog
of war, drop pins, images and videos, overlay a grid, and link map objects to
other notes in your vault. A built-in local web server lets players on the same
network open a read-only view of whatever you're currently sharing — maps,
images, videos or note excerpts — with fog, cursors and object movement updating
in real time.
Features
- Battle map view for
.samap files, powered by the bundled MapViewer engine.
- Fog of war with circle, rectangle, square and polygon reveal tools.
- Pins, images, videos and a grid layer you can place and move on the map.
- Live player view served on your LAN — players just open a URL in any browser.
- Live View toggle to broadcast every map change instantly, or share on demand.
- Live Pan & Zoom toggle so players' view follows the GM's camera.
- Share Dock — a sidebar view for sharing and re-sharing maps, images, videos
and note excerpts, each with its own history.
- Overlay sharing from the file menu, an editor selection, the active tab, or
reading-mode images/videos, with an optional inline share button.
- Object links that connect map objects to notes and headings in your vault.
- Localization (English / German), following your Obsidian display language.
Requirements
- Obsidian 1.8.7 or newer.
- Desktop Obsidian only (the plugin runs a local Node HTTP/WebSocket server).
Usage
- Right-click a folder → New shadow atlas map to create a
.samap file, then open it.
- Drag an image or video onto the map to set the base map.
- Use the header actions to Share with players, toggle Live Pan & Zoom,
or toggle Live View.
- Players open the address shown in the bottom-left pill (e.g.
http://192.168.0.10:8000).
- Open the Share Dock (right sidebar) to share images, videos or note
excerpts alongside the map, and to re-share or revisit recent shares.
Commands
- Open map — opens (or focuses) the Shadow Atlas map view.
- Open share dock — opens the Share Dock in the right sidebar.
- Share current map with players — shares the map shown in the active view.
- Share active tab with players — shares the current markdown or map tab as an overlay.
Settings
- Language —
Auto (follows Obsidian), English or German.
- Map viewer style — derive colors/font from the active Obsidian theme, or
use MapViewer's fixed dark look.
- Server — a fixed port or a scanned port range (default
8000–8099), and
whether to allow LAN access or restrict to this machine only.
- Map defaults — default Live View state for new maps.
- Layer templates — object layers created automatically on new maps, and
where the always-present Fog layer sits among them.
- Pin shapes — the set of pin icons available in the object property
panel's pin picker; add, remove or reorder them.
- History limits — how many recent map and overlay shares are kept in the
Share Dock.
- Inline reading-mode share button — show a small share button when hovering
reading-mode content.
Building
The plugin bundles the MapViewer engine from
cow-shadow-atlas-viewer,
which npm install pulls in as a git dependency — no extra setup needed:
git clone https://github.com/Chronicle-of-Whispers/cow-shadow-atlas.git
cd cow-shadow-atlas
npm install
npm run build
This type-checks with tsc -noEmit and produces main.js (the plugin) and
www/mapviewer.bundle.js (the standalone player page). scripts/build.ps1 /
scripts/build.sh do the same. For quick local iteration, node esbuild.config.mjs production skips the type check.
To hack on the engine, clone it as a sibling folder — it then takes precedence
over the installed copy. See BUILDING.md for details.
Published releases are built when a version tag such as 1.1.1 is pushed. The
GitHub Actions release workflow installs the committed lockfile with npm ci,
builds on the Node.js version in .node-version, attests the runtime artifacts,
and uploads those exact files to the GitHub release.
License
GPL-3.0-or-later