Installation Guide

Installation Guide — AI Dungeon Master

Prerequisites

• Node.js 18 or higher — download from nodejs.org
• Python 3.10 or higher — download from python.org
• A free Groq API key — sign up at console.groq.com
• Git installed on your system

Step 1 — Download the Project

After purchasing, extract the ZIP file you received. Open a terminal and navigate into the project folder.

cd ai-dungeon-master

You will see two folders inside — backend and frontend.

Step 2 — Set Up the Backend

Navigate into the backend folder.

cd backend

Install all required Python packages.

pip install -r requirements.txt

The requirements file includes Flask, Flask-CORS, and the Requests library.

Step 3 — Add Your Groq API Key

Open the file backend/ai_engine.py in any text editor. Find the line that says:

GROQ_API_KEY = "your-api-key-here"

Replace the placeholder value with your actual Groq API key. Save the file. You can get a free key by visiting console.groq.com and creating an account.

Step 4 — Start the Flask Server

Make sure you are still inside the backend folder, then run:

python app.py

You should see output like this in your terminal:

Running on http://127.0.0.1:5001

Keep this terminal window open. The backend must stay running while you play the game.

Step 5 — Set Up the Frontend

Open a second terminal window. Navigate to the frontend folder from the project root.

cd frontend

Install all Node.js dependencies.

npm install

This will install React, Vite, Tailwind CSS, and all other frontend packages. It may take a minute.

Step 6 — Start the Frontend Dev Server

npm run dev

The terminal will show:

Local: http://localhost:3000

Open that URL in your browser. The game should load immediately.

Step 7 — Play the Game

1. Enter your character name in the text field.
2. Select a class — Warrior, Mage, Rogue, or Healer.
3. Select a race — Human, Elf, Dwarf, Orc, Halfling, Tiefling, or Dragonborn.
4. Click the Start Game button.
5. The AI Dungeon Master will generate your opening scene with four choices.
6. Click any choice or type a custom action in the input field and press Act.
7. During combat encounters, use the combat panel — Attack, Defend, Magic, Potion, or Flee.

Configuration Reference

Setting	File	Default Value
Backend port	backend/app.py	5001
Frontend port	frontend/vite.config.js	3000
API proxy target	frontend/vite.config.js	http://localhost:5001
Groq model	backend/ai_engine.py	meta-llama/llama-4-scout-17b-16e-instruct
AI temperature	backend/ai_engine.py	0.85
Max tokens per response	backend/ai_engine.py	1024
Conversation history window	backend/game_state.py	20 messages

Project Folder Structure

ai-dungeon-master/
  backend/
    app.py
    ai_engine.py
    game_state.py
    system_prompt.py
    requirements.txt
  frontend/
    index.html
    vite.config.js
    tailwind.config.js
    src/
      App.jsx
      index.css
      hooks/
        useGameState.js
      utils/
        combatLogic.js
      components/
        CharacterCreation.jsx
        GameLayout.jsx
        StoryPanel.jsx
        CharacterPanel.jsx
        InventoryGrid.jsx
        CombatMode.jsx
        InfoPanel.jsx
        LevelUpModal.jsx
        EmberParticles.jsx

Common Issues

Backend not starting

Make sure Python 3.10 or higher is installed. Run python --version to check. If you have both Python 2 and Python 3 installed, use python3 app.py instead.

Frontend shows API error

This usually means the Flask server is not running. Check that the backend terminal is still active and showing the running message. If you closed it, go back to the backend folder and run python app.py again.

Groq API returning errors

Double-check that your API key is correctly pasted in backend/ai_engine.py with no extra spaces. Also make sure your Groq account is active and has available free-tier credits.

npm install fails

Make sure Node.js 18 or higher is installed. Run node --version to check. If the version is lower, download the latest LTS release from nodejs.org and reinstall.

Port already in use

If port 5001 or 3000 is already occupied by another process, change the port in backend/app.py and update the proxy target in frontend/vite.config.js to match.