# 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](https://github.com/Chronicle-of-Whispers/cow-shadow-atlas-viewer),
which `npm install` pulls in as a git dependency — no extra setup needed:

```sh
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](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](LICENSE)