Chronicle of Whispers - Shadow Atlas

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

1. Right-click a folder → New shadow atlas map to create a .samap file, then open it.
2. Drag an image or video onto the map to set the base map.
3. Use the header actions to Share with players, toggle Live Pan & Zoom, or toggle Live View.
4. Players open the address shown in the bottom-left pill (e.g. http://192.168.0.10:8000).
5. 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