KINGDOM QUEST

⚠️ Note: GitLab Pages enforces HTTPS automatically. If the game fails to connect, manually change https:// to http:// in your address bar.

---

📌 Overview

KINGDOM QUEST is a real-time multiplayer tactical board game built as a full-stack web application. Players create a custom avatar, join or host sessions on a grid-based map, and compete in turn-based combat using dice mechanics.

The game supports two modes:

• Classic — eliminate opponents and control the map
• Capture the Flag (CTF) — seize the enemy flag before they seize yours

Up to 6 players can compete simultaneously, with AI-controlled virtual players available to fill open slots.

---

📖 Table of Contents

• Overview
• Screenshots
• Features
• Project Structure
• How to Use
• Technologies
• License

---

📸 Screenshots

Home	Avatar Selection
Map Editor	Waiting Room
Game View	End-Game Statistics

---

🎮 Features

• Avatar creation — choose from 12 unique avatars and customize your character's stat distribution
• Map editor — create, save, and share custom maps with tiles, doors, water, and sanctuaries
• Real-time multiplayer — WebSocket-powered sessions with up to 6 players
• Turn-based combat — dice-based attack and defence system with combat logs
• Two game modes — Classic elimination and Capture the Flag
• AI virtual players — intelligent bots with offensive and defensive behaviours
• In-game chat — communicate with other players during a session
• Game journal — live event log tracking all actions during a game
• End-game statistics — performance breakdown at the end of each session
• Admin panel — manage active game maps

---

📂 Project Structure

LOG2995/
├── client/                     # Angular 21 frontend
│   └── src/
│       ├── app/
│       │   ├── components/     # Reusable UI components (chat, combat panel, player list…)
│       │   ├── constants/      # App-wide constants
│       │   ├── enums/          # TypeScript enums
│       │   ├── interfaces/     # TypeScript interfaces
│       │   ├── pages/          # Routed pages (home, editor, game view, waiting room…)
│       │   ├── services/       # Angular services (game, audio, avatar, round handler…)
│       │   ├── types/          # Utility type definitions
│       │   └── utils/          # Pure helper functions
│       └── assets/
│           ├── avatar-page/    # Avatar selection images
│           ├── editor-page/    # Tile and object images for the map editor
│           ├── game-view/      # In-game background and UI assets
│           ├── initial-page/   # Logo and landing background
│           ├── shared/
│           │   └── sounds/     # Background music and sound effects
│           └── waiting-room/   # Full-body avatar images + crown icon
│
├── server/                     # NestJS 11 backend
│   └── app/
│       ├── constants/          # Server-side constants and messages
│       ├── controllers/        # REST controllers (game, player, session)
│       ├── gateways/           # WebSocket gateways (chat, waiting room, game)
│       ├── model/              # Mongoose schemas and DTOs
│       └── services/
│           ├── game/           # Game CRUD and validation rules
│           ├── game-runtime/   # Core game engine, combat, AI, turn management
│           ├── player/         # Player and virtual player services
│           ├── session/        # Session management
│           └── waiting-room/   # Waiting room lifecycle and chat
│
└── common/                     # Shared TypeScript types (client + server)
    └── runtime/                # Combat types, runtime constants and types

---

🚀 How to Use

Prerequisites

• Node.js ≥ 20
• npm ≥ 10
• A MongoDB instance (local or MongoDB Atlas)

Installation

# 1. Clone the repository
git clone https://github.com/<your-org>/<repo-name>.git
cd <repo-name>

# 2. Install client dependencies
cd client && npm install && cd ..

# 3. Install server dependencies
cd server && npm install && cd ..

# 4. Configure environment variables
cp server/.env.example server/.env
# Edit server/.env with your MongoDB connection string

Running locally

# Terminal 1 — Backend (http://localhost:3000)
cd server
npm start

# Terminal 2 — Frontend (http://localhost:4200)
cd client
npm start

The app will open automatically at http://localhost:4200.

Running tests

# Client unit tests
cd client && npm run coverage

# Server unit tests
cd server && npm run coverage

Environment variables

Copy server/.env.example to server/.env and fill in the values:

Variable	Description	Example
DATABASE_CONNECTION_STRING	MongoDB connection URI	mongodb://localhost:27017/game-db
PORT	HTTP server port	3000

---

🔧 Technologies

Layer	Stack
Frontend	Angular 21, Angular Material, Socket.io-client
Backend	NestJS 11, Socket.io, Mongoose
Database	MongoDB
Testing	Karma / Jasmine (client), Jest (server)
Code quality	ESLint, Prettier

---

📜 License

This project was developed as part of the LOG2995 course at Polytechnique Montréal during the Winter 2026 semester.