An AI-powered text-based RPG that brings classic tabletop gaming to life with dynamic storytelling, intelligent dungeon mastering, and immersive adventures.
- Choose from three distinct classes: Warrior, Mage, or Rogue
- Point-buy stat allocation system for customized builds
- Unique character portraits for each class
- Dynamic stat calculation (HP, MP, modifiers)
- Powered by OpenAI GPT-5 for intelligent, context-aware storytelling
- Dynamic world generation tailored to your character class
- Realistic NPC interactions and branching narratives
- Proactive world events that keep adventures engaging
- D20 skill checks with stat modifiers
- Attribute-based difficulty classes (DC)
- Eight core stats: STR, DEX, CON, INT, WIS, CHA, HP, MP
- Real-time stat tracking and adjustments
- Item collection with descriptions and reasons
- Gold system for trading and purchases
- AI-detected transactions (buying, selling, looting)
- Persistent inventory across sessions
- AI-generated scene backgrounds based on location
- Background caching and reuse system
- Adaptive scene descriptions
- Glossary building for lore and world-building
- Experience points (XP) and level-up mechanics
- Class-specific stat growth
- Character development tracking
- Level-based difficulty scaling
- Multiple adventure save slots
- Automatic progress saving
- Continue from where you left off
- Adventure dashboard with all your quests
- User accounts with Better Auth
- Protected adventure data
- Personal adventure library
- Secure session management
| Technology | Purpose |
|---|---|
| React 19 | Frontend UI framework |
| TypeScript | Type-safe development |
| Vite | Build tool and dev server |
| Convex | Real-time backend and database |
| OpenAI API | GPT-5 Mini for AI storytelling |
| Better Auth | Authentication system |
| Tailwind CSS | Utility-first styling |
| Lucide React | Icon library |
- Node.js 18+ and npm
- OpenAI API Key (Get one here)
- Convex Account (Sign up free)
-
Clone the repository
git clone https://github.com/yourusername/fable-forge.git cd fable-forge -
Install dependencies
npm install
-
Set up environment variables
Create a
.env.localfile in the root directory:# OpenAI API Configuration OPENAI_API_KEY=your_openai_api_key_here # Convex (configured via `npx convex dev`) VITE_CONVEX_URL=your_convex_deployment_url
-
Initialize Convex
npx convex dev
This will:
- Set up your Convex backend
- Open the Convex dashboard
- Generate your deployment URL
-
Run migrations (if you have existing data)
In the Convex dashboard, run these mutations:
// Add gold to existing adventures await mutation(api.adventures.migrateGoldField, {}) // Add leveling fields to existing adventures await mutation(api.adventures.migrateLevelingFields, {})
-
Start the development server
npm run dev
The app will open at
http://localhost:5173
Sign up with email to save your adventures and progress.
- Select a class: Warrior (tanky), Mage (magical), or Rogue (agile)
- Allocate 27 points across your six core stats
- View your calculated HP and MP
- Choose a character portrait
The AI Dungeon Master generates:
- A unique world setting
- Your starting location
- An engaging adventure title
- Visual scene backgrounds
Type natural language commands:
- "I search the room for treasure"
- "I try to persuade the guard"
- "I cast a fireball at the goblin"
- "I buy a health potion from the merchant"
The game automatically determines when skill checks are needed:
- D20 roll + stat modifier vs. DC
- Results affect the narrative outcome
- Visible roll breakdown in the log
- Track your HP and MP
- Monitor your gold for purchases
- View your inventory items
- Reference the glossary for lore
- Earn XP through challenges
- Level up to increase stats
- Unlock new abilities and power
- Adventures auto-save after each turn
- Return to the dashboard anytime
- Continue or start new adventures
- Delete old campaigns
| Stat | Abbreviation | Primary Use |
|---|---|---|
| Strength | STR | Melee attacks, lifting, breaking |
| Dexterity | DEX | Agility, stealth, ranged attacks |
| Constitution | CON | Health, stamina, resistance |
| Intelligence | INT | Magic power, knowledge, investigation |
| Wisdom | WIS | Perception, insight, willpower |
| Charisma | CHA | Persuasion, deception, leadership |
- HP = Base (class) + CON modifier × 2
- MP = Base (class) + INT modifier × 2
- Modifier = floor((stat - 10) / 2)
- D20 + stat modifier vs. DC
- DC ranges: 6-10 (easy), 10-15 (medium), 16-20 (hard), 21+ (very hard)
- Critical success on natural 20
- Automatic failure on natural 1
- Start with 100 gold
- Earn through quests and looting
- Spend on items, services, bribes
- AI detects purchase intent automatically
- Earn XP through successful actions and combat
- Level up unlocks stat increases
- Class-specific growth patterns
- Progressive difficulty scaling
fable-forge/
├── convex/ # Backend (Convex)
│ ├── schema.ts # Database schema
│ ├── adventures.ts # Adventure queries/mutations
│ ├── startAdventure.ts # AI turn processing
│ ├── dmSchema.ts # AI response schema
│ ├── levelingSystem.ts # XP and leveling logic
│ ├── backgrounds.ts # Scene background generation
│ └── auth.ts # Authentication config
├── src/
│ ├── components/ # React components
│ │ ├── CharacterCreation.tsx
│ │ ├── CharacterStats.tsx
│ │ ├── AdventureLog.tsx
│ │ ├── ActionInput.tsx
│ │ ├── InventoryPanel.tsx
│ │ └── GlossaryPanel.tsx
│ ├── hooks/ # Custom React hooks
│ ├── lib/ # Utilities and helpers
│ └── App.tsx # Main application
├── .env.local # Environment variables
└── package.json # Dependencies
| Model | Purpose | Reasoning Effort |
|---|---|---|
| gpt-5-mini | Main storytelling, adventure generation | Minimal |
| gpt-5-nano | Quick roll checks and decisions | Minimal |
adventures- Character and world stateadventureActions- Turn-by-turn game logadventureInventory- Items and quantitiesadventureGlossary- Lore and terminologysceneBackgrounds- Generated scene imagescharacterPortraits- Class portrait images
This is a personal showcase project, but contributions are welcome!
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is open source and available under the MIT License.
- OpenAI for powerful language models
- Convex for seamless real-time backend
- Better Auth for secure authentication
- D&D 5e for game mechanics inspiration
For questions or feedback, open an issue on GitHub.
Enjoy your adventure in Fable Forge! ⚔️✨