Repository navigation
DM Panel Guide
The DM panel is the central control surface. It runs at http://localhost:3000 (DM machine only) and is password-protected.
The panel uses a three-column layout:
| Column | Contents |
|---|---|
| Left sidebar | Maps & Audio asset browser (collapsible) |
| Center | Map Control (top 60%) + tabbed utility panels below (Reference / Monster / Scene) |
| Right sidebar | Initiative Tracker, Dice, connected players (collapsible) |
Sections are draggable — grab the ⠿ handle on any panel header to reorder them. Layout is saved per-browser in localStorage.
Scenes are organized as Area › Scene › Map. For example: Phandalin › Stonehill Inn › Ground Floor.
- Create and edit scenes; assign per-map ambience audio, fog toggle, and image fit mode.
- The file picker auto-fills the image URL from files in
public/assets/maps/. - Chain navigation — each map row has a dropdown to jump to any other map in the same scene.
Filter maps by area, scene, or map name; filter audio by category or track title.
A cycling button on each map row sets the display mode:
| Mode | Icon | Behavior |
|---|---|---|
| Fit | 📐 | Letterbox — full image visible with bars |
| Cover | 🔲 | Fills screen, may crop edges |
| Fill | ⬜ | Stretches to fill (no bars, no crop) |
The setting is saved per map.
When a map is loaded, the Map Control panel shows the active scene image with all overlays.
| Button | Effect |
|---|---|
| ⬛ BLACKOUT | Solid black overlay on the entire player screen (including popups); click again to reveal. Audio stops on blackout. |
| 🧹 CLEAR | Dismisses any open popup (initiative, text, image) without disturbing the scene image or audio. |
| 🌫 Fog | Runtime fog toggle — enables/disables fog of war on the active map regardless of Scene Builder settings. Fog state is broadcast instantly. Hidden while no map is loaded; green-tinted when fog is ON. |
- Freehand draw annotations directly on the active map.
- Choose pen color and stroke width.
- Drawn lines appear as an overlay layer over the map and tokens.
- Annotations clear when a new map is loaded or when 🗑 Clear is clicked.
- Useful for circling points of interest or drawing attention live during play.
- Categorized library (grouped by
Category - Title.extnaming convention frompublic/assets/audio/). - Preview tracks locally on the DM machine before broadcasting.
- Loop or Once buttons per track — sends the correct loop flag to players.
- Per-map ambience with a 🔁/
▶️ toggle saved on the scene. - Auto-stop — audio stops automatically when switching to a new map view.
- ⏹ Stop All Audio — immediately silences DM previews and all player screens.
- Add Mob — type a name and roll; token is added to the tracker.
- Add All Players — rolls for every rostered player and adds them to the round in one click.
- PC entries show a PC badge so players are visually distinct from mobs.
- Auto-add to initiative toggle — automatically adds a newly placed token to the current round.
| Button | Effect |
|---|---|
| ⚔️ Send | Broadcast current initiative order to player screens. |
| ⏭️ Next | Advance to the next turn and broadcast. Fires combat attack animations before advancing. |
| 🧹 Clear Mobs | Remove all mob/NPC entries; keep PC entries for the next encounter. |
| 🔄 Hard Reset | Clear the entire initiative list including players (prompts confirmation). |
Initiative round, turn position, and all entries survive a page refresh — saved in localStorage.
- Add conditions (buffs / debuffs) to any combatant.
- Set the number of rounds, or mark as permanent (∞).
- Conditions tick down per turn; permanent conditions stay until manually removed.
- Condition rings appear on the corresponding map token: 🟢 green for buffs, 🔴 red for debuffs.
- Drag-and-drop any condition row from the Reference panel onto an initiative entry or a token dot on the map to apply it.
- 💫 Rings: ON/OFF toggle — show or hide condition rings on player/projector screens.
A collapsible section lists every non-player token on the current active map as chip buttons:
- Click a chip → pre-fills the mob name field so you can enter a roll and add normally.
- Shift+click → adds the mob instantly with a random d20 roll.
- Chips for mobs already in the tracker appear dimmed; the section header shows a live count.
- Each initiative entry has a 🎯 Target button to assign a target manually.
- Players can also tap a mob token on their own screen to set it as their target.
- When Next Turn is clicked, attack animations fire automatically:
- Active player has a target → attack animation plays on their target on all screens.
- Active mob has players targeting it → attack animation plays on those player tokens.
- Animation type is class-aware: Sorcerer / Wizard / Druid / Cleric / Priest / Bard → ✨ spell flash; all others → ⚔️ sword swipe.
A running log below the initiative table records every auto-triggered attack: attacker name (gold), target(s) (red), spell/sword icon, and timestamp. A Clear button wipes the log.
A tabbed quick-reference hub for DMs. Tabs:
| Tab | Description |
|---|---|
| ⚔️ Conditions | Active conditions chart, condition dictionary, custom conditions, drag-and-drop |
| 📊 Rules | Static DC scale, attack rules, cover bonuses, concentration, common costs |
| ✨ Spells | Live lookup via Open5e API — filter by name and/or spell level |
| 💰 Items | Live lookup — weapons, armor, magic items via Open5e |
| 🎯 Feats | Live feat lookup (Open5e, falls back to D&D 5e SRD API) |
🔍 Global search bar — type a term, pick a category (Spells / Items / Feats / Conditions), press Go — automatically switches to the correct tab and fires the search.
Real-time stat block lookup powered by the Open5e API.
- Wildcard / partial-name search (
name__icontains) — typing"goblin"returns Goblin, Goblin Boss, Dust Goblin, etc. - When multiple matches are found, clickable result buttons appear — select one to load its full stat block.
- Displays: size/type/alignment, AC, HP, speed, ability scores + modifiers, saving throws, skills, traits, actions, reactions, legendary actions.
- Results are cached per session to avoid redundant API calls.
Push a labelled text block as a timed overlay to all player screens.
Push any image URL or local file upload as a timed overlay.
d4 through d100. Optional broadcast to players with a 3D animated die animation on their screen.
Live count of connected player browsers shown in the DM panel header. Hover to see a tooltip listing each client by name or guest ID.
A persistent list stored in seeds/players.json. Add or remove players once; they persist across server restarts and appear in the Player Login dropdown on the player screen.
seeds/scenes.json example:
[
{
"id": "phandalin-stonehill-inn-123",
"tab": "Phandalin",
"label": "Stonehill Inn",
"views": [
{
"id": "...-view-0",
"label": "Ground Floor",
"image": "/assets/maps/stonehill_ground.png",
"audio": "/assets/audio/Atmosphere - Tavern Night.mp3",
"audioLoop": false,
"fog": true,
"fit": "contain"
}
]
}
]