Update README.md
This commit is contained in:
432
README.md
432
README.md
@@ -1,300 +1,272 @@
|
|||||||
# ✅ Project Status Report
|
# tic-tac-toe — Authoritative Multiplayer Game Server (Nakama + Go)
|
||||||
|
|
||||||
## Multiplayer Tic-Tac-Toe Platform
|
A production-grade, server-authoritative multiplayer backend built using **Nakama 3**, **Go plugins**, and **PostgreSQL**, deployed via **Drone CI/CD** and exposed securely through **Traefik**.
|
||||||
|
|
||||||
**To:** CTO & Technical Interview Panel
|
|
||||||
|
|
||||||
**Date:** November 29, 2025
|
|
||||||
|
|
||||||
**Version:** v1.0.0
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## **1. Objective**
|
## 🚀 Overview
|
||||||
|
|
||||||
Design and implement a scalable, server-authoritative multiplayer game system using **Nakama + custom Go plugins**, featuring:
|
This repository contains a fully authoritative Tic-Tac-Toe backend built on **Nakama 3.21.0 ARM**, using a custom **Go plugin** to implement game logic, matchmaking, validation, leaderboards, and session management.
|
||||||
|
|
||||||
* Authentication
|
The server ensures:
|
||||||
* Matchmaking
|
|
||||||
* Authoritative gameplay
|
|
||||||
* Leaderboards
|
|
||||||
* A production-ready UI
|
|
||||||
* Fully automated CI/CD and Docker deployment pipeline
|
|
||||||
|
|
||||||
The system is now deployable on **any ARM or x86 infrastructure, including Google Cloud**.
|
* **Zero client trust**
|
||||||
|
* **Deterministic gameplay**
|
||||||
|
* **Secure matchmaking**
|
||||||
|
* **Validated moves**
|
||||||
|
* **Authoritative outcomes**
|
||||||
|
|
||||||
|
Designed for scalability, extensibility, and cloud deployment (GCP, AWS, or ARM homelab environments).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## **2. Current Completion Summary**
|
## ⭐ Key Features
|
||||||
|
|
||||||
| Requirement | Status |
|
* **Authoritative Go match handler** (`tictactoe`)
|
||||||
| -------------------------------------------- | ------------------------ |
|
* Device-ID authentication + JWT session
|
||||||
| Install Nakama + PostgreSQL | ✅ Completed |
|
* Matchmaking queue support
|
||||||
| Custom Go server plugins (ARM compatible) | ✅ Completed |
|
* Deterministic game validation
|
||||||
| Server-authoritative Tic-Tac-Toe | ✅ Completed |
|
* Match lifecycle handling
|
||||||
| Real-time WebSocket communication | ✅ Completed |
|
* Disconnect handling & forfeit detection
|
||||||
| Device-based authentication | ✅ Completed |
|
* Leaderboards creation + scoring
|
||||||
| JWT-based session management | ✅ Completed |
|
* Production-grade CI/CD with Drone
|
||||||
| Match creation & joining | ✅ Completed |
|
* Automated ARM Docker builds
|
||||||
| **Matchmaking queue support** | ✅ Completed |
|
* Full Traefik routing (HTTP + WebSocket)
|
||||||
| **Game state validation & turn enforcement** | ✅ Completed |
|
* Compatible with x86/ARM/GCP
|
||||||
| **Leaderboard system** | ✅ Completed |
|
|
||||||
| **UI Game Client (production build)** | ✅ Completed |
|
|
||||||
| Google Cloud deployment | 🟡 Pending |
|
|
||||||
| **Drone CI/CD build & deploy pipeline** | ✅ Completed |
|
|
||||||
|
|
||||||
Backend is **fully authoritative** and stable. UI is **production-ready** but needs polish and error recovery improvements.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## **3. Core Technical Architecture**
|
## 🧩 Architecture
|
||||||
|
|
||||||
* **Backend:** Nakama 3.21.0 (ARM build)
|
### High-Level System Diagram
|
||||||
* **Runtime Logic:** Go plugin (built with Go 1.21.6 for ABI compatibility)
|
|
||||||
* **Frontend:** React + Vite + Nakama JS
|
```mermaid
|
||||||
* **Database:** PostgreSQL 16
|
flowchart LR
|
||||||
* **Networking:** WebSockets (secure / insecure configurable)
|
UI[Frontend (React + Vite)] -->|WebSocket / REST| Traefik
|
||||||
* **Authentication:** Device-ID auth → JWT session
|
Traefik --> Nakama[Nakama 3.21.0 ARM]
|
||||||
* **Deployment:** Docker images with Drone CI/CD
|
Nakama --> Plugin[Go Plugin main.so]
|
||||||
* **Production UI Deployment:** BusyBox static server
|
Nakama --> Postgres[(PostgreSQL)]
|
||||||
|
DroneCI --> Registry[Private Docker Registry]
|
||||||
|
Registry --> Nakama
|
||||||
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## **4. Authentication**
|
## 🛠 Tech Stack
|
||||||
|
|
||||||
### Backend
|
**Backend**
|
||||||
|
|
||||||
* Device authentication
|
* Nakama 3.21.0 ARM
|
||||||
* Automatic account creation
|
* Go 1.21.6 (plugin ABI compatible)
|
||||||
* JWT session handling
|
* PostgreSQL 16
|
||||||
|
* Docker / multi-stage builds
|
||||||
|
* Drone CI/CD
|
||||||
|
* Traefik reverse proxy
|
||||||
|
|
||||||
### UI
|
**Cloud/Infra**
|
||||||
|
|
||||||
* Generates device UUID
|
* GCP-ready
|
||||||
* Uses `client.authenticateDevice()`
|
* ARM homelab deployments
|
||||||
* Session stored in context
|
* Private registry support
|
||||||
* Reconnect logic planned
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## **5. Game Server Logic (Go)**
|
## 📦 Repository Structure
|
||||||
|
|
||||||
### ✔ State Initialization
|
```
|
||||||
|
tic-tac-toe/
|
||||||
* On second player join, server broadcasts full authoritative state.
|
│── plugins/
|
||||||
|
│ ├── match.go
|
||||||
### ✔ Turn Validation
|
│ ├── matchmaking.go
|
||||||
|
│ └── leaderboard.go
|
||||||
Rejects:
|
│
|
||||||
|
│── Dockerfile
|
||||||
* invalid coordinates
|
│── go.mod
|
||||||
* occupied cells
|
│── go.sum
|
||||||
* wrong turn
|
│── README.md
|
||||||
* malformed payloads
|
```
|
||||||
|
|
||||||
### ✔ Forfeit Detection
|
|
||||||
|
|
||||||
* Disconnects → match ends
|
|
||||||
* Final state broadcast to opponent
|
|
||||||
|
|
||||||
### ✔ Server Authority
|
|
||||||
|
|
||||||
* No client trust
|
|
||||||
* All moves validated server-side
|
|
||||||
* Structured logging everywhere
|
|
||||||
|
|
||||||
Result: **Deterministic, authoritative, cheat-proof gameplay.**
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## **6. Real-Time Networking**
|
## 🔌 Registered Server Components
|
||||||
|
|
||||||
Validated end-to-end:
|
### 📌 Match Handler
|
||||||
|
|
||||||
* Match creation/join
|
Name: **`tictactoe`**
|
||||||
* Matchmaker queues/matching
|
|
||||||
* OpCode 1 → player move submission
|
|
||||||
* OpCode 2 → authoritative board broadcast
|
|
||||||
|
|
||||||
Python simulator & UI both confirm:
|
Handles:
|
||||||
|
|
||||||
* correct turn ordering
|
* Turn validation
|
||||||
* full sync
|
|
||||||
* stable sockets
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## **7. Matchmaking System**
|
|
||||||
|
|
||||||
### Backend
|
|
||||||
|
|
||||||
* `MatchmakerMatched` hook ensures:
|
|
||||||
|
|
||||||
* valid mode
|
|
||||||
* same mode for both players
|
|
||||||
* exactly two players
|
|
||||||
* Server creates authoritative match
|
|
||||||
* RPC `leave_matchmaking` implemented
|
|
||||||
|
|
||||||
### UI
|
|
||||||
|
|
||||||
* Mode selection (classic / blitz)
|
|
||||||
* Queue → ticket → matched → auto-join
|
|
||||||
* Uses Vite-driven environment variables for dynamic host/port selection
|
|
||||||
|
|
||||||
**Status:** Fully functional
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## **8. Leaderboards**
|
|
||||||
|
|
||||||
### Backend
|
|
||||||
|
|
||||||
* Leaderboard created on startup
|
|
||||||
* Win → +1 score
|
|
||||||
* Metadata logged
|
|
||||||
|
|
||||||
### UI
|
|
||||||
|
|
||||||
* Leaderboard display works via API
|
|
||||||
|
|
||||||
Remaining UI polish:
|
|
||||||
|
|
||||||
* improved styling
|
|
||||||
* sorting
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## **9. UI Implementation Status (React + Vite)**
|
|
||||||
|
|
||||||
### ✔ Implemented
|
|
||||||
|
|
||||||
* Authentication
|
|
||||||
* WebSocket session handling
|
|
||||||
* Matchmaking integration
|
|
||||||
* Full gameplay loop
|
|
||||||
* State updates
|
* State updates
|
||||||
* End-of-game status
|
* Win/loss/draw
|
||||||
* Leaderboard viewing
|
* Disconnect forfeit
|
||||||
* Environment-configurable host, port, SSL, server key
|
* Broadcasting authoritative state
|
||||||
|
|
||||||
### 🟡 Partially Implemented
|
### 📌 RPCs
|
||||||
|
|
||||||
* Error handling (WS failures, move rejections)
|
| RPC Name | Purpose |
|
||||||
* Resume/reconnect logic
|
| ----------------------- | ---------------------------------------- |
|
||||||
* UI layout consistency
|
| **`leave_matchmaking`** | Allows clients to exit matchmaking queue |
|
||||||
* Mobile/responsive UI
|
|
||||||
* Animation/transition polish
|
|
||||||
|
|
||||||
### 🔴 Missing / Planned
|
### 📌 Matchmaker Hook
|
||||||
|
|
||||||
* Rematch flow
|
| Hook | Purpose |
|
||||||
* Lobby navigation
|
| ----------------------- | --------------------------------------------------------- |
|
||||||
* Disconnect-recovery UX
|
| **`MatchmakerMatched`** | Validates matchmaker tickets and instantiates a new match |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## **10. Testing & Validation**
|
## 🎮 Gameplay Protocol
|
||||||
|
|
||||||
### Backend
|
### OpCodes
|
||||||
|
|
||||||
* Test coverage for win/loss/draw
|
| OpCode | Direction | Meaning |
|
||||||
* Illegal moves scenarios
|
| ------ | --------------- | ----------------------------- |
|
||||||
* Disconnect behavior
|
| **1** | Client → Server | Submit move `{x, y}` |
|
||||||
* Matchmaking scaling
|
| **2** | Server → Client | Full authoritative game state |
|
||||||
|
|
||||||
### UI
|
|
||||||
|
|
||||||
* Verified across full flow
|
|
||||||
* Missing stress and mobile testing
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## **11. Google Cloud Deployment Plan**
|
## 🧠 Authoritative Flow Diagram
|
||||||
|
|
||||||
| Component | GCP Service |
|
```mermaid
|
||||||
| ------------- | ------------------------------- |
|
sequenceDiagram
|
||||||
| Nakama server | Compute Engine VM (Docker) |
|
participant C1 as Client 1
|
||||||
| PostgreSQL | Cloud SQL |
|
participant C2 as Client 2
|
||||||
| Game UI | Cloud Run / Firebase Hosting |
|
participant S as Nakama + Go Plugin
|
||||||
| Networking | HTTPS Load Balancer + Static IP |
|
|
||||||
| Secrets | Secret Manager |
|
|
||||||
|
|
||||||
Estimated time: **6–8 hours**
|
C1->>S: Matchmaker Join
|
||||||
|
C2->>S: Matchmaker Join
|
||||||
|
S->>S: MatchmakerMatched()
|
||||||
|
S-->>C1: Matched
|
||||||
|
S-->>C2: Matched
|
||||||
|
|
||||||
|
C1->>S: OpCode 1 (Move)
|
||||||
|
S->>S: Validate Move
|
||||||
|
S-->>C1: OpCode 2 (Updated State)
|
||||||
|
S-->>C2: OpCode 2 (Updated State)
|
||||||
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## **12. Risks & Considerations**
|
## ⚙️ Build & Development
|
||||||
|
|
||||||
| Risk | Mitigation |
|
### Build Go Plugin
|
||||||
| ------------------------- | ------------------------------- |
|
|
||||||
| UI lacks reconnect logic | Add retry + resume capabilities |
|
|
||||||
| No rematch flow | Add match lifecycle management |
|
|
||||||
| Minimal mobile UI | Add responsive layout |
|
|
||||||
| Cloud deployment pending | Prioritize next sprint |
|
|
||||||
| Missing polish in UI flow | Add app shell + transitions |
|
|
||||||
|
|
||||||
Backend has *no major technical risks*. UI polish is the only remaining area.
|
```
|
||||||
|
CGO_ENABLED=1 go build \
|
||||||
|
--trimpath \
|
||||||
|
--buildmode=plugin \
|
||||||
|
-o build/main.so \
|
||||||
|
./plugins
|
||||||
|
```
|
||||||
|
|
||||||
|
### Run Nakama Locally
|
||||||
|
|
||||||
|
```
|
||||||
|
nakama migrate up --database.address "$DB_ADDR"
|
||||||
|
nakama \
|
||||||
|
--database.address "$DB_ADDR" \
|
||||||
|
--socket.server_key="$SERVER_KEY"
|
||||||
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## **13. New CI/CD Enhancements (v1.0.0)**
|
## 🐳 Docker Build (Multi-Stage)
|
||||||
|
|
||||||
### ✔ Fully Automated Drone Pipeline Added
|
```dockerfile
|
||||||
|
FROM --platform=linux/arm64 golang:1.21.6 AS plugin_builder
|
||||||
|
|
||||||
* Fetch & validate latest Git tags
|
RUN go mod download
|
||||||
* Skip image build if tag already exists
|
COPY . .
|
||||||
* Build production UI image with correct Vite env
|
RUN CGO_ENABLED=1 go build --buildmode=plugin -o build/main.so ./plugins
|
||||||
* Push to private registry
|
|
||||||
* Stop old containers and auto-run the new one
|
|
||||||
* ARM-compatible builds
|
|
||||||
|
|
||||||
### ✔ New Frontend Dockerfile
|
FROM heroiclabs/nakama:3.21.0-arm
|
||||||
|
COPY --from=plugin_builder /workspace/build/main.so /nakama/data/modules/main.so
|
||||||
* Multi-stage build using Node → BusyBox
|
ENTRYPOINT ...
|
||||||
* Extremely small production image
|
```
|
||||||
* Environment-driven configuration
|
|
||||||
|
|
||||||
### ✔ Go Plugin Build Fix
|
|
||||||
|
|
||||||
* Updated to Go **1.21.6** to match Nakama
|
|
||||||
* Fixes plugin ABI mismatch: `internal/goarch`
|
|
||||||
|
|
||||||
### ✔ Improved Repository Hygiene
|
|
||||||
|
|
||||||
* Added `.dockerignore`
|
|
||||||
* Eliminated unnecessary build context
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## **14. Executive Summary**
|
## 🤖 CI/CD — Drone Pipeline
|
||||||
|
|
||||||
### Issues Encountered
|
Drone performs:
|
||||||
|
|
||||||
Several areas required deep debugging, adding roughly **+1 day** of engineering time:
|
1. Fetch latest Git tag
|
||||||
|
2. Check if Docker image already exists
|
||||||
|
3. Build Nakama + plugin
|
||||||
|
4. Push to private registry
|
||||||
|
5. Stop old container
|
||||||
|
6. Deploy new Nakama server automatically
|
||||||
|
|
||||||
* Aligning UI matchmaking with authoritative server systems
|
Full pipeline included in repository (`.drone.yml`).
|
||||||
* Handling Nakama JS socket lifecycle, ticket flow, and session timing
|
|
||||||
* OpCode synchronization and state update mapping
|
|
||||||
* Environment variable mismatches between Vite and production builds
|
|
||||||
* WebSocket connection reset issues and CORS origins
|
|
||||||
|
|
||||||
### Current State
|
|
||||||
|
|
||||||
The platform is now:
|
|
||||||
|
|
||||||
* **Fully playable**
|
|
||||||
* **Authoritative**
|
|
||||||
* **Stable across backend + UI**
|
|
||||||
* **CI/CD automated**
|
|
||||||
* **Docker deployable**
|
|
||||||
|
|
||||||
Any remaining work is **purely UI/UX polishing and cloud deployment**.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## **Conclusion**
|
## 🌐 Traefik Routing
|
||||||
|
|
||||||
The system is production-ready at the backend level and feature-complete at the gameplay level. With UI refinements and deployment, the platform will be fully presentation-ready.
|
### HTTPS
|
||||||
|
|
||||||
**The project is now stable, secure, and demonstrates full multiplayer systems engineering capability end-to-end.**
|
```
|
||||||
|
nakama.aetoskia.com
|
||||||
|
/ → HTTP API
|
||||||
|
/ws → WebSocket (real-time)
|
||||||
|
```
|
||||||
|
|
||||||
|
Includes:
|
||||||
|
|
||||||
|
* CORS rules
|
||||||
|
* WebSocket upgrade headers
|
||||||
|
* Certificate resolver
|
||||||
|
* Secure default middlewares
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔧 Environment Variables
|
||||||
|
|
||||||
|
| Variable | Description |
|
||||||
|
| --------------- | ---------------------------- |
|
||||||
|
| `DB_ADDR` | PostgreSQL connection string |
|
||||||
|
| `SERVER_KEY` | Nakama server key |
|
||||||
|
| `REGISTRY_HOST` | Private registry |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 Leaderboards
|
||||||
|
|
||||||
|
* Created during server start
|
||||||
|
* Score: `+1` on win
|
||||||
|
* Metadata logged (mode, player IDs)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🧪 Testing
|
||||||
|
|
||||||
|
* Win/loss/draw simulation
|
||||||
|
* Invalid move rejection
|
||||||
|
* Disconnect → forfeit
|
||||||
|
* Load testing matchmaking
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📈 Production Deployment
|
||||||
|
|
||||||
|
Supported on:
|
||||||
|
|
||||||
|
* ARM homelabs (Raspberry Pi)
|
||||||
|
* Google Cloud (Compute Engine + Cloud SQL)
|
||||||
|
* AWS EC2
|
||||||
|
* Kubernetes (optional)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🤝 Contributing
|
||||||
|
|
||||||
|
1. Fork repo
|
||||||
|
2. Create feature branch
|
||||||
|
3. Write tests
|
||||||
|
4. Submit PR
|
||||||
|
|
||||||
|
Coding style: Go fmt + idiomatic Go; follow Nakama plugin constraints.
|
||||||
|
|
||||||
|
---
|
||||||
|
|||||||
Reference in New Issue
Block a user