AI Dungeon Master — Real-Time Fantasy Text RPG with AI Storytelling (React + Flask + Groq LLaMA)
A fully playable AI-powered dungeon crawler where an LLM acts as a live Dungeon Master, generating branching narratives, enemies, loot, and quests in real time.
Technology Used
React | JavaScript | Vite | Tailwind CSS | Flask | Python | Groq API | LLaMA 4 Scout | Flask-CORS | Requests
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.
Frequently Asked Questions
Extra Add-Ons Available – Elevate Your Project
Add any of these professional upgrades to save time and impress your evaluators.
Live 1-on-1 Mentorship
Personal session with an expert developer
Project Setup
We'll install and configure the project on your PC via remote session (Google Meet, Zoom, or AnyDesk).
Source Code Explanation
1-hour live session to explain logic, flow, database design, and key features.
Want to know exactly how the setup works? Review our detailed step-by-step process before scheduling your session.
₹999
Custom Documents (College-Tailored)
- Custom Project Report: ₹1,500
- Custom Research Paper: ₹1,000
- Custom PPT: ₹800
Fully customized to match your college format, guidelines, and submission standards.
Project Modification
Need feature changes, UI updates, or new features added?
Charges vary based on complexity.
We'll review your request and provide a clear quote before starting work.
Project Files
ReviewsWhat Our Students Say
He explained the project clearly and thoroughly. He was very supportive throughout the process and was always available to help when needed. His guidance and assistance made it easier to understand the project and complete tasks effectively.
I had a very good experience with CodeAj Marketplace. The team is professional and supportive, especially Ajay Pandit sir who guides clearly throughout the project. The work was completed neatly and according to requirements. A great place for learning and project development. Highly recommended for students and developers.
Excellent explanation! Concepts are explained in a very simple and understandable way. It really helped me a lot in improving my knowledge. Great work!
Codeaj was really helpful with my project, especially during the customization part. He didn't just do the work but also took the time to explain everything, from the project structure and database to the code itself. It was a huge help, especially for students trying to understand how everything fits together. I really appreciated his support and the way he made things easier to follow.
Working with CodeAj Marketplace has been such a positive experience. The projects delivered are original, carefully crafted from scratch, and tailored to meet expectations with impressive attention to detail. What really makes him stand out is his willingness to go the extra mile — not just in creating outstanding work, but also in helping others understand how everything functions. He explains things clearly, addresses questions patiently, and ensures the whole process feels like a learning journey instead of just a handover. On top of the technical expertise, his calm and approachable personality makes communication effortless. No unnecessary stress, just smooth collaboration and genuine support. I truly value the dedication he brings to his work and would highly recommend him to anyone in search of high-quality, authentic projects.
I purchased a project from him recently and I have to say it's one of the best decisions I've made. The project was absolutely beautiful, built completely from scratch with no shortcuts, and perfectly matched what I wanted. What makes him stand out is not just his ability to create anything we ask for, no matter how complex, but also the way he helps us understand every part of it. He patiently explains the process, clears doubts, and makes sure we actually learn from the project instead of just using it. On top of his skills, his personality is amazing — he's calm, chill, and very friendly to talk to. There's no stress when working with him, only smooth communication and genuine support. I truly appreciate the effort he puts in and would highly recommend him to anyone looking for original, high-quality projects.
I received my project from CodeAJ Marketplace on time, and the work was very neat and well-presented. The team maintained good communication and delivered everything as promised. I appreciate their timely completion and professional approach.
I sincerely thank Mr. Ajay Pandit for his constant support and valuable guidance throughout the project. His timely advice, encouragement, and expertise greatly contributed to the successful completion of the work. I'm truly grateful for his mentorship.
I had an outstanding experience with CodeAj while developing my mobile app. Their team was incredibly cooperative, ensuring every customization I requested was implemented flawlessly. The service was top-notch, and the final product exceeded my expectations. Highly recommend CodeAj for anyone seeking professional and reliable app development services! 11/10
I would like to sincerely thank Ajay Pandit for providing me with the project. His guidance and explanation of the system's architecture, modules, and AI integration were extremely helpful in understanding the project thoroughly. Ajay's support played a key role in helping me implement the hotel booking and payment module effectively. His willingness to clarify concepts and walk me through complex logic made the learning process smooth and insightful. I truly appreciate his mentorship and the time he dedicated to ensuring I was well-prepared for both the development and presentation of this project.
I had a great experience with the project I purchased. It was well-structured and met all my expectations. The team was responsive and supportive throughout, addressing all my queries promptly. Highly recommended for anyone looking for quality projects and good service.
I'm really thankful to Codeaj for helping me with my project explanation and guiding me throughout. Your support made everything much easier and clearer.
The project he made was wonderful, and the way he patiently listened, understood all my ideas and presented them so well in the project, was amazing. I would highly recommend him to everyone.
I would like to sincerely thank Ajay Pandit for providing me with the project. His guidance and explanation of the system's architecture, modules, and AI integration were extremely helpful in understanding the project thoroughly.
Too good experience, I love their projects and they are available for you to help, they are incredible good. Must avail their services. I am happy customer.
The team was very supportive and their explanation was very good, they are clarifying each and every doubts with lots of patience. Highly recommended for quality projects.
I really like their work and they made good project in less amount.
Thank you, CodeAj Bro, for supporting the Doctor Appointment System project. Your guidance during the project setup, installation, and report creation was very helpful and greatly appreciated.
One of the best Software Developer provide the best setup environment for project, good explain skills, and good technical skills, step by step explain project through google meet and budgetly price project Available.
Thank you so much for your excellent work on our project! Your kindness and clear explanations made the entire process smooth and enjoyable. Highly recommend!
Really very supportive, helpful and kind, loving nature. Available for any time for any query, highly recommend to get projects from him.
Awesome projects. They support on setting up the project after purchasing. Completely legal one. Affordable projects too.
Code AJ guide team are very formal, friendly to setup project step by step and explain each question 🙂
Thank you codeAj, Best site to get your project done quickly, with fast responses and instant clarification of any project-related doubts.
I really liked the work, and they solved my issues very well too.
They provide very good service and code also running condition and they fulfill all the queries it's very helpful.
Really helpful, makes things easy to understand and very kind nature, you can look forward to get help from here.
Thank you so much for building the Project for my requirement.
Looking forward to many many collaborations and always tend to buy the projects.
I am so satisfied with codeAJ because of his help.
Thank you so much sir for your support and help.
Ajay bro has excellent knowledge and his response is nice.
This is a great app I love it with good functionality.
Thank you so much for your help and support.
Highly recommended for the projects.
Loved the project work.
It is super for students.
I recently purchased this project online and I am very satisfied with it. The project was well-designed, properly organized, and included all the necessary files and documentation. The source code was clean, easy to understand, and worked as expected. A special appreciation for the project explanation and setup session. The session was detailed and easy to understand, covering both the project implementation and the complete setup process. All my questions were answered clearly, which helped me understand the project much better. Thanks for giving your time.