better deploy
Some checks failed
Dynamic Branch Deploy / build-and-deploy (push) Has been cancelled
Some checks failed
Dynamic Branch Deploy / build-and-deploy (push) Has been cancelled
This commit is contained in:
Sebastian Unterschütz
146
README.me
Normal file
146
README.me
Normal file
@@ -0,0 +1,146 @@
|
||||
# **🏃 Escape the Teacher**
|
||||
|
||||
**A server-authoritative 2D endless runner built with Go, Redis, and JavaScript.**
|
||||
|
||||
## **📖 About the Project**
|
||||
|
||||
"Escape the Teacher" is a high-performance web game developed as a school project. You play as a student caught cheating, running away from an angry teacher. The game features increasing difficulty, power-ups, boss phases, and a competitive global leaderboard.
|
||||
Unlike typical browser games, this project implements **anti-cheat architecture** usually found in multiplayer RTS or FPS games. The browser does not decide if you survived; the server does.
|
||||
|
||||
## **✨ Features**
|
||||
|
||||
### **🎮 Gameplay**
|
||||
|
||||
* **Endless Progression:** The game speeds up over time.
|
||||
* **Controls:**
|
||||
* **Jump:** Space / Arrow Up / Tap / Left Click.
|
||||
* **Crouch:** Arrow Down / Swipe Down (Mobile).
|
||||
* **Power-Ups:**
|
||||
* 🛡️ **Godmode:** Survives 3 hits.
|
||||
* ⚾ **Baseball Bat:** Eliminates the next teacher obstacle.
|
||||
* 👟 **Jumpboots:** Grants higher jumping power for a limited time.
|
||||
* 💰 **Coins:** Bonus points (visual score only, does not affect game speed).
|
||||
* **Dynamic Backgrounds:** Environment changes as you progress.
|
||||
* **Boss Phases:** Every 1500 ticks, special boss enemies spawn.
|
||||
|
||||
### **📱 Mobile First**
|
||||
|
||||
* Fully responsive Canvas rendering (Letterboxing).
|
||||
* Touch gestures (Swipe to crouch).
|
||||
* "Rotate Device" enforcement for optimal gameplay.
|
||||
|
||||
### **🛡️ Security & Admin**
|
||||
|
||||
* **Admin Panel:** Password-protected (/admin) interface.
|
||||
* **Moderation:** Review and delete leaderboard entries.
|
||||
* **Badword Filter:** Automatic blocking of inappropriate names using Redis Sets.
|
||||
* **Proof System:** Players receive an 8-character "Claim Code" to prove their high score to the teacher.
|
||||
|
||||
## **🏗️ Technical Architecture**
|
||||
|
||||
The core philosophy is **"Server-Authoritative, Client-Predicted"**.
|
||||
|
||||
1. **Frontend (JS):** Captures inputs and renders the game state immediately (Client-Side Prediction) to ensure zero input lag. It sends input logs to the server in chunks.
|
||||
2. **Backend (Go):** Validates the inputs by re-simulating the game physics tick-by-tick.
|
||||
3. **Database (Redis):** Stores active sessions, RNG states, and leaderboards (Sorted Sets).
|
||||
|
||||
### **Tech Stack**
|
||||
|
||||
* **Backend:** Go (Golang) 1.21+
|
||||
* **Frontend:** Vanilla JavaScript (Canvas API), CSS3
|
||||
* **Database:** Redis
|
||||
* **Containerization:** Docker (Multi-Stage Build: Node Minifier \-\> Go Builder \-\> Alpine Runner)
|
||||
* **Orchestration:** Kubernetes (Deployment, Service, Ingress)
|
||||
|
||||
## **🔧 Development Challenges & Solutions**
|
||||
|
||||
Developing a cheat-proof game for the web came with significant technical hurdles. Here is how we solved them:
|
||||
|
||||
### **1\. The "Butterfly Effect" (RNG Desynchronization)**
|
||||
|
||||
* **Problem:** JavaScript's Math.random() and Go's rand implementations are different. Even if seeded with the same number, they produce different sequences. This caused "Ghost Objects" (Server spawns a teacher, Client spawns a coin).
|
||||
* **Solution:** We implemented a custom **Linear Congruential Generator (LCG)** in both languages.
|
||||
* **The Tricky Part:** JavaScript uses 64-bit Floating Point numbers for everything, while Go uses strict types. Math operations drifted apart after a few hundred iterations.
|
||||
* **Fix:** We forced JavaScript to use BigInt to simulate 32-bit integer overflows exactly like Go's uint32.
|
||||
|
||||
### **2\. Floating Point Drift & Spawning**
|
||||
|
||||
* **Problem:** We initially spawned objects based on pixel positions (if x \< 800). Due to floating point precision errors, the client sometimes calculated 799.99 (Spawn\!) while the server calculated 800.01 (Wait\!). This desynchronized the RNG state immediately.
|
||||
* **Solution:** **Tick-Based Spawning.** We decoupled spawning from spatial positions. The game now decides: *"The next object spawns at Tick 500"* rather than *"at Pixel 1200"*. Integers don't drift.
|
||||
|
||||
### **3\. Logic-Score Coupling**
|
||||
|
||||
* **Problem:** Initially, game speed and boss phases depended on the *Score*. When we added Coins (+2000 Points), the client's score jumped instantly, speeding up the game on the client side before the server acknowledged the coin pickup. This caused massive desyncs.
|
||||
* **Solution:** We decoupled logic from the visual score. Game difficulty now depends strictly on **"Ticks Alive" (Time)**, which cannot be manipulated by picking up items.
|
||||
|
||||
### **4\. Physics Tunneling (High Speed Collisions)**
|
||||
|
||||
* **Problem:** At high speeds, the player could move 20 pixels per frame. If an obstacle was only 15 pixels wide, the player effectively "teleported" through it without triggering a collision.
|
||||
* **Solution:** **Continuous Collision Detection (CCD).** We extend the hitbox of obstacles dynamically based on their current speed (width \+ speed).
|
||||
|
||||
### **5\. "Ghost Hits" (The CCD Side Effect)**
|
||||
|
||||
* **Problem:** The CCD fix caused a new issue where the extended hitbox would hit the player *after* they had already jumped over the obstacle (hitting them from behind).
|
||||
* **Solution:** A **"Passed Check"**. Before checking collisions, we verify if the obstacle's right edge is already physically behind the player's left edge. If so, collision is ignored.
|
||||
|
||||
## **🚀 Getting Started**
|
||||
|
||||
### **Using Docker (Recommended)**
|
||||
|
||||
This project includes a production-ready Dockerfile and docker-compose.yml.
|
||||
|
||||
1. **Clone the repository:**
|
||||
git clone \[https://git.zb-server.de/ZB-Server/it232Abschied.git\](https://git.zb-server.de/ZB-Server/it232Abschied.git)
|
||||
cd it232Abschied
|
||||
|
||||
2. Configure Environment (Optional):
|
||||
Edit docker-compose.yml to set your admin credentials:
|
||||
environment:
|
||||
\- ADMIN\_USER=teacher
|
||||
\- ADMIN\_PASS=secret123
|
||||
|
||||
3. **Run:**
|
||||
docker-compose up \--build \-d
|
||||
|
||||
4. **Play:** Open http://localhost:8080
|
||||
|
||||
### **Local Development (Go & Redis)**
|
||||
|
||||
1. Start Redis:
|
||||
docker run \-d \-p 6379:6379 redis:alpine
|
||||
|
||||
2. Start the Server:
|
||||
go run .
|
||||
|
||||
*(Note: Use go run . to include all files, not just main.go)*
|
||||
|
||||
## **📂 Project Structure**
|
||||
|
||||
.
|
||||
├── k8s/ \# Kubernetes manifests
|
||||
├── static/ \# Frontend files
|
||||
│ ├── assets/ \# Images & Sprites
|
||||
│ ├── fonts/ \# Local GDPR-compliant fonts
|
||||
│ ├── js/ \# Modular Game Engine
|
||||
│ │ ├── config.js \# Constants
|
||||
│ │ ├── logic.js \# Physics & Collision
|
||||
│ │ ├── network.js \# Server-Sync
|
||||
│ │ └── ...
|
||||
│ ├── index.html \# Entry Point
|
||||
│ └── style.css \# Retro Design
|
||||
├── secure/ \# Protected Admin Files
|
||||
├── main.go \# Go Server Entrypoint
|
||||
├── simulation.go \# Server-side Physics Engine
|
||||
├── rng.go \# Deterministic RNG
|
||||
├── types.go \# Data Structures
|
||||
├── Dockerfile \# Multi-Stage Build
|
||||
└── ...
|
||||
|
||||
## **📜 Legal**
|
||||
|
||||
This is a non-commercial educational project.
|
||||
|
||||
* **Privacy:** No tracking cookies are used. Highscores are stored in Redis; local scores in LocalStorage.
|
||||
* **Assets:** Font "Press Start 2P" is hosted locally.
|
||||
|
||||
**Good luck escaping\! 🏃💨**
|
||||
Reference in New Issue
Block a user