Gacha Game - Realm of Eldoria

A browser-based gacha monster game built on a microservices architecture. Players collect monsters through an invocation system, manage their roster, and challenge other players in turn-based PvP battles.

---

Table of contents

• Concept
• Architecture
• Tech stack
• Getting started
• Services
• Known Issues
• Contributors

---

Concept

Gatcha is a gacha-style monster collecting game. Each player starts with an empty roster and spends resources to invoke creatures of varying rarity — from Common to Legendary. Monsters have stats (HP, attack, defense, speed) and a set of skills that grow as they level up.

Once a player has built their team, they can challenge other players to a PvP fight. The battle outcome is computed server-side using a turn-based engine: each round, the fastest monster acts first, dealing damage based on its attack against the opponent's defense. The frontend replays the fight turn by turn with animations, letting players watch the duel unfold.

Core gameplay loop:

1. Invoke — spend a summon to receive a random monster
2. Train — gain XP from fights, level up monsters, upgrade skills
3. Fight — select your champion and challenge another player's monster

---

Architecture

The backend is split into five independent Spring Boot microservices, each with its own MongoDB database. They communicate over HTTP and are orchestrated via Docker Compose. Prometheus and Grafana are included for monitoring.

graph TD
    Browser["Browser"] -->|HTTP| Vite["Vite dev proxy\nlocalhost:5173"]

    Vite -->|":8081 /api/auth"| Auth["api-authentication"]
    Vite -->|":8082 /api/players"| Player["api-player"]
    Vite -->|":8083 /api/monsters"| Monster["api-monsters"]
    Vite -->|":8084 /api/invocations"| Invocation["api-invocation"]
    Vite -->|":8085 /api/fights"| Fight["api-fight"]

    Invocation -->|"HTTP"| Monster
    Fight -->|"HTTP"| Monster

    Auth --- AuthDB[("auth_db")]
    Player --- PlayerDB[("player_db")]
    Monster --- MonsterDB[("monsters_db")]
    Invocation --- InvocationDB[("invocation_db")]
    Fight --- FightDB[("fight_db")]

    subgraph MongoDB [:27017]
        AuthDB
        PlayerDB
        MonsterDB
        InvocationDB
        FightDB
    end

    subgraph Monitoring
        Prometheus["Prometheus :9090"]
        Grafana["Grafana :3000"]
        Prometheus --> Grafana
    end

Loading

---

Tech stack

Backend

Technology	Version	Role
Java	21	Language
Spring Boot	4.x	Microservice framework
Spring Data MongoDB	—	ORM / data access
MongoDB	7.0	Document database (one DB per service)
Docker / Docker Compose	—	Containerisation and orchestration
Prometheus + Grafana	latest	Metrics and monitoring

Frontend

Technology	Version	Role
React	19	UI framework
Vite	8	Build tool and dev server
React Router	7	Client-side routing
Zustand	5	Global state management
Axios	1	HTTP client

---

Getting started

Prerequisites

• Docker and Docker Compose

Launching the game

The entire project (MongoDB, all five backend microservices, the frontend, the database seeder, Prometheus, and Grafana) is fully containerized and runs with a single command.

cd back
docker compose up -d

Once all containers are running, you can access the game at: http://localhost:5173

Note: On the very first run, a temporary seed-db container will automatically insert the initial monster templates into the database so that you can start playing immediately.

Monitoring

Service	URL
Prometheus	http://localhost:9090
Grafana	http://localhost:3000

---

Services

Service	Port	Responsibility
api-authentication	8081	JWT token issuance and credential validation
api-player	8082	Player accounts, XP, level, monster roster
api-monsters	8083	Monster CRUD, stats, skills, levelling
api-invocation	8084	Random monster generation from rarity-weighted templates
api-fight	8085	Turn-based combat engine, fight history

---

Known Issues

Seed fails with error parsing command line options on Windows

Symptom: the gatcha-seed container exits immediately with error parsing command line options. Monster invocation then returns No templates found for rarity: COMMON.

Cause: on Windows, Git converts the line endings of mongo-init.sh to CRLF. The stray \r is passed as part of the mongoimport arguments, which it does not recognize.

Fix: from the back/seed/ folder, fix the line endings with PowerShell:

(Get-Content mongo-init.sh -Raw) -replace "`r`n", "`n" | Set-Content mongo-init.sh -NoNewline

Then restart the seed (still from back/seed/, using the compose file in back/):

docker compose -f ../docker-compose.yml up seed-db

---

Contributors

Project realized by IMT Nord Europe students as part of the "Web API & data" course.