itsamejms
00fb901aee
- README: image gen is sd-server (cross-platform), not macOS/Ollama; Node 23.6+ note for self-checks; prefs store row in the data table. - plan.md: superseded banners on the Ollama image-gen sections. - gitea-release.sh: syncs Cargo.toml too; bumped to 0.1.3 to match. - public/icons.svg: unreferenced — favicon.svg is the icon.
131 lines
5.2 KiB
Markdown
131 lines
5.2 KiB
Markdown
# 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.
|
|
|
|
|
|
|
|
## 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 (cross-platform, via stable-diffusion.cpp)
|
|
- **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+ (23.6+ to run the `npm run check` self-checks) — 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
|
|
```
|
|
|
|
For image generation, DM-Pal talks to a [stable-diffusion.cpp](https://github.com/leejet/stable-diffusion.cpp) `sd-server` (cross-platform) via its AUTOMATIC1111-compatible API. Download a model (e.g. Z-Image-Turbo or FLUX.2-klein weights), start the server, then point DM-Pal at it under **Settings → Image Server** (default `http://localhost:1234`):
|
|
|
|
```bash
|
|
# build sd-server, then run with your chosen model
|
|
sd-server -m path/to/model.safetensors --vae path/to/vae.safetensors
|
|
```
|
|
|
|
## 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 |
|
|
|------|----------|
|
|
| `dm-pal-prefs.json` | App prefs — data-dir setting + LLM config incl. API key (stored locally, one level above `dm-toolkit/`) |
|
|
| `lore/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. |