{"id":44752179,"url":"https://github.com/fraction12/dndbuddy","last_synced_at":"2026-02-15T23:15:33.952Z","repository":{"id":326566454,"uuid":"1106142066","full_name":"fraction12/dndbuddy","owner":"fraction12","description":null,"archived":false,"fork":false,"pushed_at":"2025-11-28T18:55:02.000Z","size":129,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-30T22:53:12.512Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://dndbuddy.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fraction12.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-28T17:42:01.000Z","updated_at":"2025-11-28T18:55:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fraction12/dndbuddy","commit_stats":null,"previous_names":["fraction12/dndbuddy"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/fraction12/dndbuddy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraction12%2Fdndbuddy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraction12%2Fdndbuddy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraction12%2Fdndbuddy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraction12%2Fdndbuddy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fraction12","download_url":"https://codeload.github.com/fraction12/dndbuddy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraction12%2Fdndbuddy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29492013,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T19:29:10.908Z","status":"ssl_error","status_checked_at":"2026-02-15T19:29:10.419Z","response_time":118,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-15T23:15:33.291Z","updated_at":"2026-02-15T23:15:33.945Z","avatar_url":"https://github.com/fraction12.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎲 DnD Buddy\n\nAn immersive D\u0026D companion app where ChatGPT acts as your Dungeon Master, bringing epic campaigns to life for 4 players with real-time stat tracking, dice rolling, and AI-powered storytelling.\n\n[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new)\n\n---\n\n## ✨ Features\n\n- 🤖 **AI Dungeon Master** - ChatGPT narrates your adventure with dramatic, immersive storytelling\n- 🎭 **4-Player Co-op** - Real-time multiplayer synchronization\n- 📊 **Strict Stat Tracking** - HP, Mana, Armor, XP, Inventory, and more\n- 🎲 **Dice Roller** - Server-side dice rolls with beautiful animations\n- ⚔️ **Combat System** - Initiative tracking, turn-based combat, status effects\n- 🔊 **Text-to-Speech** - AI narration comes alive with voice\n- 🎨 **AI Image Generation** - Character portraits, scene images, enemy visuals (DALL-E 3 + Stable Diffusion)\n- 💾 **Session Management** - Save/load campaigns, session history\n- 📱 **Mobile Responsive** - Play on any device\n\n---\n\n## 🎯 Based on Your ChatGPT Session\n\nThis app is specifically designed around your epic campaign featuring:\n\n### Characters\n- **Lira the Fairy** (Player A) - 11-inch magical support with Fairy Bliss\n- **Rorek the Rune Knight** (Player B) - Dwarven tank with rune magic and Ropey the rope familiar\n- **Elliathel the Elf Ranger** (Player P) - Agile archer with True Shot and moon-blessed dagger\n- **Veyrath the Dark High Mage** (Player D) - Powerful spellcaster with shadow magic\n\n### Campaign\n- **5-hour epic quest** divided into 1-hour sessions\n- Enemies: Goblins, Werewolves, Trolls, Mimics, Manticore, and 2 Dragons\n- **Heroic tone** with moments of chaotic humor\n- **STRICT mode** - Real D\u0026D stat tracking\n\n---\n\n## 📚 Documentation\n\n| Document | Description |\n|----------|-------------|\n| **[PLAN.md](./PLAN.md)** | Complete project plan, architecture, features, and development phases |\n| **[TECH_STACK_COMPARISON.md](./TECH_STACK_COMPARISON.md)** | Technology choices, cost analysis, and recommendations |\n| **[CHARACTER_DATA_EXAMPLES.md](./CHARACTER_DATA_EXAMPLES.md)** | Real data structures from your ChatGPT session |\n| **[IMAGE_GENERATION_PLAN.md](./IMAGE_GENERATION_PLAN.md)** | 🎨 AI image generation guide (characters, scenes, enemies) |\n| **[QUICK_START.md](./QUICK_START.md)** | Step-by-step guide to start building |\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n- Node.js 18+\n- npm or yarn\n- OpenAI API key\n- Database (Supabase or Vercel Postgres)\n\n### Installation\n\n```bash\n# 1. Clone repository\ngit clone https://github.com/your-username/dndbuddy.git\ncd dndbuddy\n\n# 2. Install dependencies\nnpm install\n\n# 3. Set up environment variables\ncp .env.example .env.local\n# Edit .env.local with your API keys\n\n# 4. Set up database\nnpx prisma migrate dev --name init\nnpx prisma generate\n\n# 5. Seed with sample data (optional)\nnpm run seed\n\n# 6. Start development server\nnpm run dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000)\n\n---\n\n## 🏗️ Tech Stack\n\n### Recommended (Production Ready)\n- **Frontend**: Next.js 14 (App Router), TypeScript, Tailwind CSS, shadcn/ui\n- **Backend**: Next.js API Routes, Vercel Postgres, Prisma ORM\n- **AI**: OpenAI GPT-4 Turbo, OpenAI TTS\n- **Real-time**: Pusher or Supabase Realtime\n- **State**: Zustand\n- **Deployment**: Vercel\n\n### Budget-Friendly Alternative\n- **Database**: Supabase (free tier)\n- **AI**: GPT-3.5 Turbo (cheaper)\n- **TTS**: Web Speech API (free)\n- **Real-time**: Supabase Realtime (included)\n\n**Cost**: ~$5-10/month vs ~$40-70/month\n\nSee [TECH_STACK_COMPARISON.md](./TECH_STACK_COMPARISON.md) for detailed analysis.\n\n---\n\n## 📂 Project Structure\n\n```\ndndbuddy/\n├── app/                    # Next.js App Router\n│   ├── (auth)/            # Authentication pages\n│   ├── (game)/            # Main game interface\n│   └── api/               # API routes\n├── components/            # React components\n│   ├── character/         # Character sheets, stats\n│   ├── combat/            # Initiative, combat log\n│   ├── dice/              # Dice roller\n│   ├── dm/                # DM narration panel\n│   └── ui/                # shadcn/ui components\n├── lib/\n│   ├── db/                # Database client \u0026 queries\n│   ├── ai/                # ChatGPT integration\n│   ├── game/              # Game logic (combat, dice)\n│   └── utils/             # Utilities\n├── hooks/                 # Custom React hooks\n├── types/                 # TypeScript types\n└── prisma/                # Database schema\n```\n\n---\n\n## 🎮 How It Works\n\n### 1. Campaign Setup\n- Create campaign with 4 player slots\n- Each player creates their character\n- ChatGPT generates opening narration\n\n### 2. Gameplay Loop\n```\nPlayer Action → API Request → ChatGPT Processes\n                                     ↓\n                            Game State Updates\n                                     ↓\n                         Real-time Sync to All Players\n                                     ↓\n                            DM Narrates Outcome\n                                     ↓\n                        Next Player's Turn → Repeat\n```\n\n### 3. Combat Flow\n```\nEncounter Triggers → Initiative Rolls → Turn Order\n                                             ↓\nPlayer Turn → Choose Action → Roll Dice → Apply Effects\n                                             ↓\n                           DM Narrates Result\n                                             ↓\n                         Enemy Turn (AI controlled)\n                                             ↓\n                             Repeat Until Victory\n```\n\n---\n\n## 🎯 Development Roadmap\n\n### Phase 1: MVP (Week 1-6) ✅ PLANNING COMPLETE\n- [x] Complete planning documentation\n- [ ] Project setup\n- [ ] Character creation \u0026 display\n- [ ] Dice rolling system\n- [ ] ChatGPT DM integration\n- [ ] Basic combat system\n- [ ] Multi-player sync\n- [ ] Deploy to Vercel\n\n### Phase 2: Polish (Week 7-8)\n- [ ] Animations \u0026 effects\n- [ ] Mobile responsive\n- [ ] Session save/load\n- [ ] Inventory management\n- [ ] Quest log\n\n### Phase 3: Advanced Features (Week 9-12)\n- [ ] Battle map visualization\n- [ ] Enhanced TTS (ElevenLabs)\n- [ ] Character portraits\n- [ ] Session recording\n- [ ] Statistics dashboard\n\n---\n\n## 💰 Cost Breakdown\n\n### Per Session (1 hour, 4 players)\n| Service | Cost |\n|---------|------|\n| OpenAI GPT-4 Turbo | ~$2.80 |\n| OpenAI TTS | ~$0.15 |\n| Real-time (Pusher) | $0 (free tier) |\n| **Total** | **~$3.00** |\n\n### Monthly (100 sessions)\n| Service | Tier | Cost |\n|---------|------|------|\n| Vercel Pro | Required | $20 |\n| Vercel Postgres | Starter | $20 |\n| OpenAI API | Pay-as-you-go | ~$280 |\n| Pusher | Free tier | $0 |\n| **Total** | | **~$320** |\n\n**Budget Option**: Use Supabase + GPT-3.5 for ~$5-10/month during development.\n\n---\n\n## 🧪 Example Character Data\n\nAll character data from your ChatGPT session is documented in [CHARACTER_DATA_EXAMPLES.md](./CHARACTER_DATA_EXAMPLES.md).\n\nExample:\n```typescript\nconst liraCharacter = {\n  characterName: \"Lira\",\n  characterType: \"Fairy\",\n  stats: {\n    hp: { current: 18, max: 18 },\n    mana: { current: 24, max: 24 },\n    armor: 10,\n    speed: \"Fast\",\n    size: \"11 inches\"\n  },\n  skills: [\n    {\n      name: \"Fairy Bliss\",\n      type: \"once_per_session\",\n      description: \"Calm hostile creatures in 20ft radius\",\n      saveDC: 14\n    }\n  ]\n};\n```\n\n---\n\n## 🔧 Configuration\n\n### Environment Variables\n\n```bash\n# OpenAI API\nOPENAI_API_KEY=sk-...\nOPENAI_MODEL=gpt-4-turbo-preview\n\n# Database\nDATABASE_URL=postgresql://...\n\n# Real-time (Pusher)\nNEXT_PUBLIC_PUSHER_APP_KEY=...\nPUSHER_APP_ID=...\nPUSHER_SECRET=...\n\n# Authentication\nNEXTAUTH_SECRET=...\nNEXTAUTH_URL=http://localhost:3000\n\n# Text-to-Speech (Optional)\nELEVENLABS_API_KEY=...\n```\n\n---\n\n## 📖 API Examples\n\n### Roll Dice\n```typescript\nPOST /api/dice/roll\n{\n  \"dieType\": \"d20\",\n  \"modifier\": 5,\n  \"advantage\": false\n}\n\nResponse:\n{\n  \"rolls\": [17],\n  \"modifier\": 5,\n  \"total\": 22,\n  \"isCritical\": false\n}\n```\n\n### Get DM Narration\n```typescript\nPOST /api/dm/narrate\n{\n  \"campaignId\": \"...\",\n  \"playerAction\": \"I attack the werewolf with my dagger\",\n  \"gameContext\": { ... }\n}\n\nResponse (streamed):\n{\n  \"narration\": \"Elliathel raises her dagger...\",\n  \"requiresRoll\": {\n    \"player\": \"P\",\n    \"type\": \"d20\",\n    \"modifier\": 3,\n    \"dc\": 15\n  }\n}\n```\n\n### Update Character HP\n```typescript\nPATCH /api/characters/:id/hp\n{\n  \"currentHP\": 15\n}\n```\n\n---\n\n## 🐛 Troubleshooting\n\n### ChatGPT responses are slow\n- Use streaming responses\n- Show loading states\n- Consider GPT-3.5 for faster (but lower quality) responses\n\n### Real-time sync not working\n- Check Pusher/Supabase configuration\n- Verify environment variables\n- Test with multiple browser tabs\n\n### Database queries failing\n- Run `npx prisma generate`\n- Check DATABASE_URL\n- Verify migrations: `npx prisma migrate dev`\n\n---\n\n## 🤝 Contributing\n\nThis is a personal project, but suggestions are welcome!\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Submit a pull request\n\n---\n\n## 📝 License\n\nMIT License - feel free to use this for your own campaigns!\n\n---\n\n## 🎉 Credits\n\n- **ChatGPT** - Your amazing DM\n- **OpenAI** - GPT-4 and TTS\n- **Vercel** - Hosting platform\n- **Shadcn** - UI components\n- **You** - The adventurers!\n\n---\n\n## 🔗 Links\n\n- [Live Demo](#) - Coming soon\n- [Documentation](./PLAN.md)\n- [Tech Stack Guide](./TECH_STACK_COMPARISON.md)\n- [Quick Start](./QUICK_START.md)\n\n---\n\n## 📬 Contact\n\nHave questions? Found a bug? Want to collaborate?\n\n- **GitHub Issues**: [Create an issue](https://github.com/your-username/dndbuddy/issues)\n- **Email**: your-email@example.com\n\n---\n\n## 🎲 May Your Rolls Be Ever in Your Favor!\n\nBuilt with ❤️ for epic adventures.\n\n**Status**: 📋 Planning Complete → 🏗️ Ready to Build\n\n---\n\n## Quick Commands\n\n```bash\n# Development\nnpm run dev          # Start dev server\nnpm run build        # Build for production\nnpm run start        # Start production server\n\n# Database\nnpx prisma studio    # Open database GUI\nnpx prisma migrate dev  # Run migrations\nnpx prisma generate  # Generate client\n\n# Deployment\nvercel               # Deploy to Vercel\nvercel --prod        # Deploy to production\n```\n\n---\n\n**Last Updated**: November 28, 2025\n\n**Next Steps**: Read [QUICK_START.md](./QUICK_START.md) to begin building! 🚀\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffraction12%2Fdndbuddy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffraction12%2Fdndbuddy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffraction12%2Fdndbuddy/lists"}