AI Dungeon Master — Real-Time Fantasy Text RPG with AI Storytelling (React + Flask + Groq LLaMA)

AI Dungeon Master — Final Year Project with Source Code

This is a full-stack AI text RPG where every story beat, enemy encounter, and quest update is generated live by a large language model. You pick a race and class, and from that point the game world builds itself around your decisions. No two playthroughs are the same.

The backend is a lightweight Flask API that handles session management, XP tracking, and all communication with Groq's inference engine running LLaMA 4 Scout. The frontend is a React app styled with Tailwind CSS — three columns, animated HP/MP/XP bars, a typewriter story panel, a 16-slot inventory grid, and a dedicated combat mode with its own enemy card and action buttons.

If you are looking for an AI final year project that goes beyond a standard prediction model, this one is worth considering. It covers full-stack development, LLM API integration, stateful session design, and real-time UI rendering — topics that are difficult to demonstrate in a single project.

What This Project Does

When a player starts a game, the Flask backend creates a session, sends the character details and a structured system prompt to Groq, and gets back a JSON object with a narrative, four choices, an optional enemy, loot, XP, and location data. The React frontend parses that JSON and renders each field into the right panel. Combat is handled client-side using damage formulas, then the result is sent back to the AI to continue the story.

The AI response is always structured JSON. This makes the game deterministic and parseable — the frontend does not have to guess what the AI meant. Every field in the response maps directly to a UI element.

Key Features

• Live AI Storytelling: LLaMA 4 Scout via Groq generates narrative, choices, enemies, and loot on every turn. The last 20 messages are sent with each request to keep the story consistent without hitting token limits.
• Turn-Based Combat System: Attack, Defend, Magic, Potion, and Flee actions each follow a damage formula. Magic ignores enemy defense. Potions heal 35% of max HP. The Defend action halves incoming damage for that turn.
• 4 Playable Classes: Warrior, Mage, Rogue, and Healer — each with different base stats and combat trade-offs. Rogues have a higher flee success rate. Mages deal more damage but die faster.
• 7 Playable Races: Human, Elf, Dwarf, Orc, Halfling, Tiefling, and Dragonborn — selected at character creation.
• Inventory System: 16-slot grid storing weapons, armor, potions, and scrolls. Items appear as loot rewards from the AI after combat or exploration turns.
• XP and Leveling: XP threshold scales with level (current level x 100). Each level-up adds HP, MP, ATK, and DEF with a particle burst modal.
• Typewriter Narrative: Story text renders character by character for an immersive reading experience.
• Dark Fantasy UI: Animated ember particle background, gold accent borders, blood-red combat indicators, and smooth animated stat bars built with Tailwind and custom CSS variables.
• Responsive Layout: Three-column desktop grid collapses cleanly to mobile. Character panel, story panel, and info panel each stack correctly.
• Event Log: Tracks the last several turns with XP gains, damage taken, and items found.

Project Structure Overview

The project is split into a backend/ folder (Flask) and a frontend/ folder (React + Vite). The backend has four files: the Flask app with three API endpoints, an AI engine that calls Groq and parses the JSON response, a session manager that handles in-memory game state and leveling logic, and the system prompt that instructs the AI to respond only in structured JSON. The frontend has eight components covering character creation, the three-column game layout, story rendering, combat mode, inventory, the info panel, and visual effects.

All API calls from the frontend are proxied through Vite's dev server, so you do not need to configure CORS manually during development. For deployment, the Flask server can be hosted separately and the proxy target updated.

API Endpoints

• POST /api/start-game: Accepts character name, class, and race. Returns a session ID, opening narrative, choices, and initial player stats.
• POST /api/action: Accepts a session ID and the player's chosen action (one of four AI-generated options or a custom typed input). Returns the next narrative turn.
• POST /api/combat-action: Accepts a session ID, action type, and current enemy state. Processes the combat round and returns an updated game state.

Tech Stack

Frontend is React 18 with Vite 5 and Tailwind CSS 3. Backend is Flask 3 with Flask-CORS and the Requests library for HTTP calls to Groq. The AI layer uses Groq's inference API with LLaMA 4 Scout 17B at a temperature of 0.85 and a max token limit of 1024 per response.

Who This Project Is For

This project fits students who want to show full-stack skills alongside AI/LLM integration. It is not just a form that calls an API — it has session management, structured AI response parsing, client-side game logic, and a polished multi-panel UI. If you are also exploring game development projects or want something that stands out from the usual prediction model submissions, this covers both.

For students who need help getting it running or want a custom version with different game mechanics, the project setup and explanation service walks through the full codebase with you over a screen share session.

What You Get

• Complete source code — frontend and backend
• Pre-built project report in college format
• Installation guide with step-by-step setup instructions
• Working Groq API integration with the LLaMA 4 Scout model

Add-On Services

• Idea Implementation: Want a different game genre, different AI model, or custom mechanics? We build it from scratch to your spec.
• Project Setup + Source Code Explanation: We set it up on your machine and walk through every file so you can explain it in your viva.
• Custom Project Report, Research Paper, and PPT: College-format documentation written for your specific submission requirements.