# DM-Pal

An offline-first desktop toolkit for Dungeon Masters, powered by a local LLM.
Built with **Tauri v2** + **Rust** on the back end and **React 19** + **TypeScript**
on the front. Every generator is grounded in your own world bible via a local
RAG index — no data leaves your machine unless you point it at a remote API.

![DM-Pal](public/favicon.svg)

## What's in the box

DM-Pal packs every tool a DM reaches for at and between the table, grouped
into **Session** (live) and **World** (prep) tools:

- **Initiative Tracker** — combatants, HP, conditions, death saves, turn timer
- **Dice Roller** — notation parsing, advantage/disadvantage, roll templates
- **Encounter Builder** — AI-generated encounters with a 5e XP budget
- **NPC Generator** — portraits, personality, goals, stat blocks
- **Quest Designer** — multi-step quests with twists and reward breakdown
- **Item Forge** — magic items with art and structured mechanics
- **Image Generator** — portraits, maps, scene art (macOS, via Ollama)
- **Session Logger** — Markdown notes, multiple sessions, streaming AI summary
- **Soundboard** — synthesized ambience/SFX with one-click scenes
- **World Builder** — generated regions, landmarks, a draggable-pin map
- **Lore (RAG)** — index your world bible, ground every generation in it
- **Calendar** — custom fantasy calendars, weather, moon phases, events
- **Random Tables** — built-in and custom tables, weighted rolls

A **⌘K command palette**, **History view** (re-open any past generation), and
persistent state round it out — reload loses nothing.

## Quick start

### Prerequisites

- **Rust** + **Cargo** — https://rustup.rs
- **Node.js** 20+ — https://nodejs.org
- **[Ollama](https://ollama.com)** running locally (default `http://localhost:11434`)

### Install & run

```bash
npm install
npm run tauri dev
```

On first launch open **Settings (⌘,)** and confirm the API URL, then pull a
text model (e.g. `llama3.2`) and an embedding model (e.g. `nomic-embed-text`):

```bash
ollama pull llama3.2
ollama pull nomic-embed-text
```

Optionally, for image generation (macOS / Apple Silicon only):

```bash
ollama pull x/flux2-klein:4b
```

## Where your data lives

All campaign data stays on disk under your OS app-data dir (default
`$APPDATA/dm-toolkit/`, configurable in Settings):

| File | Contents |
|------|----------|
| `lore.db` | RAG chunks + embeddings (SQLite) |
| `generations.db` | History of every generated NPC/encounter/item/quest/… |
| `images/` | Cached generated PNGs, keyed by prompt hash |
| `dm-pal-state.json` | UI state (initiative, dice history, calendar events, …) |

Settings → **Data location** lets you relocate everything to an external drive
and migrates existing data for you.

## Architecture

```
React 19 + TypeScript  ──invoke()/Channel──▶  Rust (Tauri v2)
  Zustand · framer-motion                          LLM (Ollama / OpenAI-compatible)
  react-konva (world map)                         SQLite (rusqlite, bundled)
  Tailwind v4 + glassmorphism                     RAG (brute-force cosine → sqlite-vec path)
```

Each tool is a self-contained component mounted behind a single `renderView`
switch; the dashboard is a launcher of at-a-glance tiles. The design system is
dark-only (navy + Cinzel + gold), self-hosts its fonts for true offline use,
and meets WCAG AA contrast.

## Scripts

```bash
npm run dev          # Vite dev server (frontend only)
npm run tauri dev    # Full app, hot-reload
npm run build        # tsc -b && vite build
npm run lint         # oxlint
node scripts/check-worldmap.ts        # world-map layout self-check
node scripts/check-encounter-budget.ts # XP-budget self-check
node scripts/check-dice.ts             # dice-notation parser self-check
```

## Project layout

```
src/                 React front end
  components/         one file per tool
  lib/                pure logic + persistence hooks
src-tauri/src/       Rust back end
  commands/           Tauri IPC commands (llm, image, rag, data, generation)
  llm/                Ollama/OpenAI client + config
  rag/                embedding + cosine search
  generations/        history store
docs/                plan + UI/UX review
```

## Roadmap

See [`docs/plan.md`](docs/plan.md) for the full plan and `docs/ui-ux-improvements.md`
for the living UI/UX review with a prioritized checklist.

Planned / in progress: first-run model wizard, quest branching graph, world
hierarchy tree, real ambience packs, GitHub Actions CI, code signing, and an
auto-updater.

## License

TBD. Built-in rule references use only 5e SRD / OGL / CC-BY content. Model files
ship under their own licenses (e.g. Meta's Llama license) — accept them in
Ollama before pulling.