🏃 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

---

✨ 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:

   git clone [https://git.zb-server.de/ZB-Server/it232Abschied.git](https://git.zb-server.de/ZB-Server/it232Abschied.git)
   cd it232Abschied
   

2. Run:

   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:

   docker run -d -p 6379:6379 redis:alpine
   

2. Start the Server:

   go run .
   

---

🎶 Credits

This project was made possible by:

• Development & Code: Sebastian Unterschütz
• Music Design: Max E.
• Sound Effects: Generated via bfxr.net
• Graphics: Gemini AI / 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! 🏃💨