# **🏃 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:** [Kenney.nl](https://kenney.nl) / 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! 🏃💨**