DungeonPlanner

A modern 3D dungeon editor for tabletop sessions

Website · Demo · Docs · Quick Start · Developer Setup · Contributing

---

Why DungeonPlanner

DungeonPlanner is built for fast encounter prep: paint rooms, place interactive props, switch camera modes, and present clean tabletop-ready layouts.

Highlights

• Grid painting and erase workflow
• Floor/wall content-pack assets
• Dynamic lighting with optional flicker
• Perspective, isometric, and top-down camera modes
• Undo/redo history for editing actions

Quick Start for Players

1. Open the demo at https://demo.dungeonplanner.com/.
2. Use the Room tool to paint your layout.
3. Use the Prop tool to place doors, torches, and objects.
4. Switch camera mode from the Move panel depending on prep or presentation.

Developer Setup

Prerequisites

• Node.js 24+
• pnpm 10+
• Python 3.11+ for tools/character-generator

Run locally

pnpm install
pnpm run dev

Editor runs at http://localhost:5173.

Workspace commands

pnpm run dev:full     # editor + server (both in watch mode)
pnpm run build        # editor build + docs build
pnpm run build:all    # build all workspace packages
pnpm run test         # unit tests
pnpm run lint         # lint editor + app
pnpm run verify       # lint + test + build + e2e

Usage

Tool	What it does
Move (hand icon)	Orbit, pan, zoom the camera. Activate camera presets and adjust the scene light rig.
Room (grid icon)	Left-drag to paint floor tiles, right-drag to erase.
Prop (torch icon)	Select a prop from the panel, click a floor tile to place it, right-click to remove.

Camera presets (Move tool → right panel):

• Perspective — free orbit, great for building
• Isometric — locked true-isometric angle, good for screenshots
• Top Down — overhead fisheye view, ideal for printing battle maps

Grid toggle — shows an amber grid overlay projected over painted floor tiles. In editing tools the grid reveals in a soft circle around the cursor.

Content Packs

Props and floor/wall tiles are defined as content packs — plain TypeScript objects that describe the asset path, connector type, and optional light configuration.

// Example: wall torch with a real flickering point light
export const propsWallTorchAsset: ContentPackAsset = {
  id: 'core/props/wall-torch',
  name: 'Wall Torch',
  metadata: {
    connectsTo: 'WALL',
    light: {
      color: '#ff9040',
      intensity: 6,
      distance: 8,
      offset: [0, 1.6, 0.25],
      flicker: true,
    },
  },
}

Project Structure

editor/
  src/components/canvas/    # R3F scene and 3D systems
  src/components/editor/    # UI panels and tools
  src/content-packs/        # asset definitions and metadata
  src/store/                # Zustand state and serialization
app/                    # authenticated workspace app
shared/                 # shared contracts and helpers
server/                 # multiplayer/backend package
tools/character-generator/ # Python batch portrait generator

Tech Stack

Layer	Technology
Frontend	React 19 + Vite 8
3D	React Three Fiber + Three.js
Rendering	WebGPU-first with WebGL fallback
State	Zustand
Language	TypeScript
Testing	Vitest + Playwright
Monorepo tooling	pnpm + Turborepo

Roadmap

• Floor grid overlay radial reveal (TSL shader debugging in progress)
• Character token placement with movement range indicator
• Export to PNG (Top-Down view)
• More content packs (doors, traps, furniture)
• Multiplayer / shared sessions

Contributing

Please read CONTRIBUTING and CODE OF CONDUCT before opening a pull request.

---

Made for TTRPG players who want their dungeon to look as good as it plays.

Made with ❤️ in Skåne. A Finger Gun project, making nothing into something.