Codex.Quest is a comprehensive web-based character creation and management system for Basic Fantasy Role-Playing Game (BFRPG). Built with modern React architecture and a beautiful, accessible interface, it provides players and Game Masters with powerful tools to create, manage, and track characters throughout their adventures.
- Step-by-step character creation wizard with guided experience
- Complete BFRPG race and class support (Core + Supplemental + custom race and class creation)
- Persistent character storage with Firebase integration
- Character sheet display and live editing capabilities
- Comprehensive dice rolling system
- Game session creation and management
- Encounter management with initiative tracking
- Encount and Treasure generation tools
- Real-time data synchronization across devices
- React 19 with functional components and hooks
- TypeScript 5.9 for type-safe development
- Vite 7.1 for fast development and optimized builds
- TailwindCSS 4.1 with modern design tokens
- Wouter 3.7 for lightweight client-side routing
- TanStack Query 5.x for server state management and caching
- Zustand 5.x for client-side state management with persistence
- Firebase 12.2 for authentication and Firestore database
- Real-time synchronization for multiplayer features
- Automated data migration for schema evolution
- Secure user authentication with email/password and Google OAuth
- Node.js 18+
- npm
Perfect for contributors and trying out the app:
# Clone the repository
git clone https://github.com/gvorbeck/codex-quest.git
cd codex-quest
# Install dependencies
npm install
# Start development server (auto-detects mock mode)
npm run dev🎉 That's it! The app automatically detects missing Firebase credentials and runs in mock mode with sample data.
For production deployment with Firebase:
# Follow the steps above, then create .env with your Firebase config:
# VITE_FIREBASE_API_KEY=your_api_key
# VITE_FIREBASE_AUTH_DOMAIN=your_auth_domain
# VITE_FIREBASE_PROJECT_ID=your_project_id
# VITE_FIREBASE_STORAGE_BUCKET=your_storage_bucket
# VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
# VITE_FIREBASE_APP_ID=your_app_id
# VITE_FIREBASE_MEASUREMENT_ID=your_measurement_id
# Build for production
npm run build| Command | Description |
|---|---|
npm run dev |
Start development server in mock mode |
npm run dev:firebase |
Start development server with Firebase |
npm run build |
Build for production (TypeScript + Vite) |
npm run preview |
Preview production build locally |
npm run lint |
Run ESLint on TypeScript/React files |
npm run test |
Run unit tests in watch mode |
npm run test:ui |
Run unit tests with visual interface |
npm run test:run |
Run unit tests once (for CI/commits) |
npm run test:coverage |
Run unit tests with coverage report |
npm run test:e2e |
Run end-to-end tests (headless) |
npm run test:e2e:ui |
Run E2E tests with visual debugging |
npm run test:e2e:headed |
Run E2E tests with browser visible |
npm run test:all |
Run all tests (unit + E2E) |
npm run test:ci |
Full CI pipeline (lint + build + tests) |
Codex.Quest features an intelligent mock mode that automatically activates when Firebase credentials aren't available. This provides a zero-setup experience for contributors and demos.
When in mock mode, additional debugging tools are available:
- Reset Sample Data button appears in the header (orange button next to "Codex.Mock")
- Instantly resets all data back to original sample characters and games
- Reloads the page automatically to show fresh data
// Available in browser console as window.devUtils
devUtils.resetAllData(); // Reset to sample data
devUtils.clearAllData(); // Clear all data
devUtils.signInAsUser(userData); // Test different users
devUtils.exportCharacterData(); // Export for debugging
devUtils.exportGameData(); // Export game dataForce mock mode even with Firebase credentials:
VITE_MOCK_FIREBASE=true npm run devWe use a comprehensive two-layer testing approach for quality assurance:
Complete Testing Guide → TEST_PLAN.md
- Unit Tests (Vitest): Fast feedback for individual functions and components
- E2E Tests (Playwright): Complete user workflow validation across browsers
- Visual Interfaces: Beautiful web dashboards for both testing layers
- Coverage Reports: Track which code needs more testing**
- WCAG 2.1 AA compliance target
- Screen reader support with proper ARIA labels
- Keyboard navigation throughout the application
- Skip links and semantic HTML structure
- High contrast support and readable typography
- Responsive design for all device types
Read our comprehensive Style Guide for detailed development patterns, TypeScript best practices, performance optimization, and component architecture.
This project is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License.
- Basic Fantasy RPG community for the excellent open-source game system
Light up your adventures with codex.quest! 🔥