working through a review
This commit is contained in:
itsamejms
@@ -1,32 +1,129 @@
|
||||
# React + TypeScript + Vite
|
||||
# DM-Pal
|
||||
|
||||
This template provides a minimal setup to get React working in Vite with HMR and some Oxlint rules.
|
||||
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.
|
||||
|
||||
Currently, two official plugins are available:
|
||||
|
||||
|
||||
- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
|
||||
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
|
||||
## What's in the box
|
||||
|
||||
## React Compiler
|
||||
DM-Pal packs every tool a DM reaches for at and between the table, grouped
|
||||
into **Session** (live) and **World** (prep) tools:
|
||||
|
||||
The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
|
||||
- **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
|
||||
|
||||
## Expanding the Oxlint configuration
|
||||
A **⌘K command palette**, **History view** (re-open any past generation), and
|
||||
persistent state round it out — reload loses nothing.
|
||||
|
||||
If you are developing a production application, we recommend enabling type-aware lint rules by installing `oxlint-tsgolint` and editing `.oxlintrc.json`:
|
||||
## Quick start
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "./node_modules/oxlint/configuration_schema.json",
|
||||
"plugins": ["react", "typescript", "oxc"],
|
||||
"options": {
|
||||
"typeAware": true
|
||||
},
|
||||
"rules": {
|
||||
"react/rules-of-hooks": "error",
|
||||
"react/only-export-components": ["warn", { "allowConstantExport": true }]
|
||||
}
|
||||
}
|
||||
### 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
|
||||
```
|
||||
|
||||
See the [Oxlint rules documentation](https://oxc.rs/docs/guide/usage/linter/rules) for the full list of rules and categories.
|
||||
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.
|
||||
Reference in New Issue
Block a user