Game Reference Interactive Management Orchestrator for Immersive Roleplay Experiences
GRIMOIRE is an advanced web application designed to be the ultimate Game Master (GM) assistant for Dungeons & Dragons (D&D) campaigns. It leverages AI (Google Gemini API), powerful offline capabilities, and a robust Virtual Tabletop (VTT) to streamline campaign management, automate content extraction, and enhance storytelling.
-
AI-Powered Game Master (Gemini API Integration):
- Dynamic story, NPC dialogue, and quest generation
- Rule enforcement and clarification
- Immersive descriptions and character interaction simulation
- Real-time campaign updates and suggestions
- Secure, user-provided API key
-
Content Extraction from PDFs/EPUBs:
- Client-side and optional server-side parsing
- Structured extraction of characters, lore, locations, monsters, spells, items, quests
- Semantic understanding and categorization
-
Data Management & Persistence (PWA & Offline First):
- Full PWA with offline mode
- Flexible storage: IndexedDB (default), Google Drive, AWS S3
- In-browser SQLite (via WebAssembly/IndexedDB)
- Asset storage and campaign version control
-
Virtual Tabletop (VTT) Functionality:
- Interactive, multi-layered map display (tactical, role-playing, global views)
- Dynamic fog of war, vision types, environmental effects
- 3D dice rolling with physics and customization
- Token management, turn order, and real-time collaboration
- Integrated voice/video chat and modular plugin system
-
User Interface & Experience:
- Campaign dashboard and content browsing
- AI interaction panel and document management
- Powerful search/filtering, responsive design, and theming
- Custom content creation and sharing
- Frontend: Next.js v15 (App Router), React, TypeScript
- UI: shadcn/ui (Radix UI + Tailwind CSS), next-themes
- Styling: Tailwind CSS
- Database: SQLite (WebAssembly, IndexedDB)
- Cloud Storage: Google Drive API, AWS SDK v3
- AI Integration: Google Gemini API (via secure proxy)
- Document Parsing: PDF.js, epub.js
- 3D Graphics: Three.js
- Physics Engine: Cannon.js (or Rapier.js)
- State Management: React Context API or Zustand
- Data Fetching: React Query (TanStack Query)
- PWA: Workbox or custom service worker
-
Clone the repository:
git clone https://github.com/your-username/grimoire-dnd-vtt.git cd grimoire-dnd-vtt -
Install dependencies:
bun install
-
Configure environment variables:
- Copy
.env.exampleto.envand fill in required values (e.g., Gemini API key proxy settings).
- Copy
-
Run the development server:
bun run dev
-
Open the app:
- Visit http://localhost:3000 in your browser.
- First Launch:
- The app will prompt for your Gemini API key (kept secure and never exposed to the client).
- Upload Documents:
- Use the document management interface to upload D&D PDFs/EPUBs for extraction.
- Explore & Manage Content:
- Browse extracted characters, monsters, spells, and more.
- Use the campaign dashboard to manage multiple campaigns.
- Virtual Tabletop:
- Access the VTT for map display, token management, dice rolling, and fog of war.
- AI Interaction:
- Chat with the Gemini-powered GM for story ideas, rules, and immersive content.
- Offline & Cloud Sync:
- Works offline by default; configure cloud sync in settings for Google Drive or AWS S3.
Contributions are welcome! Please see CONTRIBUTING.md for guidelines on setting up your environment, coding standards, commit conventions, and submitting pull requests.
This project is licensed under the MIT License. See LICENSE for details.
See CHANGELOG.md for a history of major changes and releases.
For questions, suggestions, or support, please open an issue or contact the maintainers.