130 lines
6.1 KiB
Markdown
130 lines
6.1 KiB
Markdown
# **🏃 Escape the Teacher**
|
|
|
|
**A high-performance, server-authoritative 2D endless runner built with Go, Redis, and WebSockets.**
|
|
|
|
## **📖 About the Project**
|
|
|
|
"Escape the Teacher" is a web-based game developed as a final project (IT232). 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 **competitive multiplayer architecture** usually found in shooters or RTS games. The browser is treated as a "dumb" display terminal; the server simulates the entire world to prevent cheating.
|
|
|
|
**🔗 Repository:** [https://git.zb-server.de/ZB-Server/it232Abschied](https://git.zb-server.de/ZB-Server/it232Abschied)
|
|
|
|
---
|
|
|
|
## **✨ Features**
|
|
|
|
### **🎮 Gameplay**
|
|
* **Endless Progression:** The game speed increases 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.
|
|
* 💰 **Coins:** Bonus points for the highscore.
|
|
* **Level Editor:** Custom level segments ("Chunks") can be designed live in the Admin Panel and are streamed directly into active game sessions.
|
|
|
|
### **🛡️ Security & Technology**
|
|
* **Server-Authoritative:** Physics runs entirely on the server (Go). Speedhacks or Godmode cheats are impossible.
|
|
* **Admin Panel:** Password-protected interface to manage levels, badwords, and leaderboards.
|
|
* **Proof System:** Players receive an 8-character "Claim Code" to validate their high score offline.
|
|
|
|
---
|
|
|
|
## **🏗️ Technical Architecture**
|
|
|
|
The project utilizes a **Realtime Streaming Architecture** to handle latency and synchronization.
|
|
|
|
1. **Backend (Go):**
|
|
* Simulates physics at a fixed **20 TPS (Ticks Per Second)** to save CPU.
|
|
* Generates level chunks 5 seconds into the future.
|
|
* Streams object positions and game state via **WebSockets**.
|
|
2. **Frontend (JS):**
|
|
* **Client-Side Prediction:** Inputs are applied immediately for a "Zero-Lag" feel.
|
|
* **Buffering & Interpolation:** Although the server calculates at 20 FPS, the client renders at 60+ FPS by interpolating positions (`Lerp`) between server ticks.
|
|
* **Lag Compensation (RTT):** The client measures Round Trip Time and visually shifts server objects to match the client's timeline.
|
|
3. **Database (Redis):**
|
|
* Stores highscores, active session states, and level editor chunks.
|
|
|
|
---
|
|
|
|
## **🔧 Engineering Challenges & Solutions**
|
|
|
|
Building a lag-free, cheat-proof game on the web came with significant hurdles. Here is how we solved them:
|
|
|
|
### **1. The "Netflix" Approach (Streaming vs. RNG Sync)**
|
|
* **Problem:** Initially, we tried to sync the Random Number Generators (RNG) between Client and Server. However, a single floating-point deviation caused a "Butterfly Effect," desynchronizing the entire game world.
|
|
* **Solution:** **Streaming.** The client no longer generates obstacles. The server pre-calculates the future and streams objects into a buffer on the client. The client simply plays back the stream, similar to a video player.
|
|
|
|
### **2. Low Tick-Rate & Interpolation**
|
|
* **Problem:** To allow many concurrent players, the server physics runs at only **20 TPS**. Without smoothing, this looks choppy (like a slideshow) on a 144Hz monitor.
|
|
* **Solution:** **Linear Interpolation.** The rendering engine calculates the visual position between the current and the previous physics state (`alpha = accumulator / dt`). The result is buttery smooth motion despite the low server update rate.
|
|
|
|
### **3. Latency & "Ghost Kills"**
|
|
* **Problem:** If the internet lags (e.g., 100ms Ping), the server sees the player hitting an obstacle that appeared "safe" on the client screen.
|
|
* **Solution:** **RTT Compensation.** The client constantly measures the network delay. Incoming objects from the server are visually shifted towards the player (`Latency * Speed`), ensuring they appear exactly where the server expects them to be at the moment of interaction.
|
|
|
|
### **4. Vertical Synchronization (Platforms)**
|
|
* **Problem:** Jumping onto platforms is tricky. At high speeds, the server might calculate that the player fell *through* a platform between two ticks ("Tunneling").
|
|
* **Solution:** **Vertical Sweeping & Client Authority override.** The server checks the *path* of the player, not just the position. Additionally, if the client detects a safe landing, it forces a physics sync update to the server to prevent unfair deaths.
|
|
|
|
---
|
|
|
|
## **🚀 Getting Started**
|
|
|
|
### **Using Docker (Recommended)**
|
|
|
|
1. **Clone the repository:**
|
|
```bash
|
|
git clone [https://git.zb-server.de/ZB-Server/it232Abschied.git](https://git.zb-server.de/ZB-Server/it232Abschied.git)
|
|
cd it232Abschied
|
|
```
|
|
|
|
2. **Run:**
|
|
```bash
|
|
docker-compose up --build -d
|
|
```
|
|
|
|
3. **Play:** Open `http://localhost:8080`
|
|
4. **Admin:** Open `http://localhost:8080/admin` (User: `lehrer`, Pass: `geheim123`)
|
|
|
|
### **Local Development**
|
|
|
|
1. Start Redis:
|
|
```bash
|
|
docker run -d -p 6379:6379 redis:alpine
|
|
```
|
|
2. Start the Server:
|
|
```bash
|
|
go run .
|
|
```
|
|
|
|
---
|
|
|
|
## **🎶 Credits**
|
|
|
|
This project was made possible by:
|
|
|
|
* **Development & Code:** Sebastian Unterschütz
|
|
* **Music Design:** Max E.
|
|
* **Sound Effects:** Generated via [bfxr.net](https://www.bfxr.net/)
|
|
* **Graphics:** [Gemini AI](https://gemini.google.com/app) / Sebastian Unterschütz
|
|
* **Fonts:** "Press Start 2P" (Google Fonts / Local)
|
|
|
|
---
|
|
|
|
## **⚖️ License & Rights**
|
|
|
|
**© 2025 IT232 Final Project**
|
|
|
|
This project is released under a proprietary, restrictive license:
|
|
|
|
1. **No Commercial Use:** The source code, assets, and the game itself may not be used for commercial purposes or sold.
|
|
2. **No Modification:** You are not allowed to modify, fork, or redistribute this project in modified form without express written permission from the authors.
|
|
3. **Educational Use:** Viewing and running the code for educational purposes within the context of the school project is permitted.
|
|
|
|
---
|
|
|
|
**Run for your grade! 🏃💨** |