EscapeFromTeacher/README.md

# 🏃 Escape From Teacher

Ein Endless-Runner-Spiel entwickelt als Schulprojekt. Renne vor dem Lehrer davon, sammle Münzen, nutze Power-Ups und klettere an Wänden!

![License](https://img.shields.io/badge/license-Proprietary-red)
![Go Version](https://img.shields.io/badge/go-1.25+-blue.svg)
![Platform](https://img.shields.io/badge/platform-Web-green)

## 📋 Inhaltsverzeichnis

- [Features](#-features)
- [Technologie-Stack](#-technologie-stack)
- [Installation](#-installation)
- [Spielmodi](#-spielmodi)
- [Entwicklung](#-entwicklung)
- [Architektur](#-architektur)
- [Tools](#-tools)
- [Lizenz](#-lizenz)

## ✨ Features

### Gameplay
- 🏃 **Endless Runner**: Unendliches Spiel mit prozedural generierten Levels
- 🧗 **Wall Climbing**: Klettere an Wänden hoch für neue Strategien
- 💰 **Coins & Power-Ups**: Sammle Münzen und nutze Power-Ups wie Double Jump und Godmode
- 🎯 **Hindernisse**: Weiche bewegenden Plattformen und Objekten aus
- ⚡ **Dynamische Schwierigkeit**: Das Spiel wird mit der Zeit schneller

### Modi
- 👤 **Solo-Modus**: Spiele alleine und sammle Highscores
- 👥 **Coop-Modus**: Spiele mit Freunden im Team
  - Team-Namen für Leaderboard
  - Multiplizierter Score basierend auf lebenden Spielern
  - Host-Controls für Lobby-Management

### Features
- 🏆 **Leaderboard**: Redis-basiertes globales Leaderboard mit Proof-Codes
- 🎮 **Cross-Platform**: Web (WASM) und Desktop (Native)
- 🎨 **Level Editor**: Erstelle eigene Levels mit dem integrierten Level Builder
- 🔊 **Audio**: Musik und Sound-Effekte mit Lautstärkeregelung
- 📱 **Mobile Support**: Touch-Controls für mobile Geräte

## 🛠 Technologie-Stack

### Backend
- **Go 1.25+**: Server und Game-Logik
- **NATS**: Message Broker für Echtzeit-Kommunikation (Legacy)
- **WebSocket**: Direkte WebSocket-Verbindungen für niedrige Latenz
- **Redis**: Persistentes Leaderboard mit Proof-Code-Validierung

### Frontend
- **Go + WASM + Ebiten**: Web-Client kompiliert zu WebAssembly
- **HTML/CSS/JavaScript**: Web-UI und Menüs

### Architektur
- **Client-Side Prediction**: Flüssiges Gameplay trotz Netzwerk-Latenz
- **Server-Authoritative**: Server validiert alle Spielaktionen
- **Deterministische Physik**: Gleiche Physik auf Client und Server

## 📦 Installation

### Voraussetzungen

```bash
# Go 1.25 oder höher
go version

# Redis für Leaderboard
redis-server --version
```

### Repository klonen

```bash
git clone https://git.zb-server.de/ZB-Server/EscapeFromTeacher.git
cd EscapeFromTeacher
```

### Assets generieren

Die Assets müssen aus den Raw-Dateien generiert werden:

```bash
# Asset-Builder starten (GUI)
go run ./cmd/builder

# Im GUI: Assets laden, anpassen und speichern
# Dies erstellt cmd/client/web/assets/assets.json und die PNG-Dateien
```

### Server starten

```bash
# Redis starten (Terminal 1)
redis-server

# Server starten (Terminal 2)
go run ./cmd/server
```

Server läuft auf `http://localhost:8080`

### Clients starten

#### Web-Client (WASM)

```bash
# WASM kompilieren
GOOS=js GOARCH=wasm go build -o cmd/client/web/main.wasm ./cmd/client

# Web-Server starten (z.B. mit Python)
cd cmd/client/web
python3 -m http.server 8000

# Browser öffnen: http://localhost:8000
```

#### Desktop-Client (Native)

```bash
go run ./cmd/client
```

## 🎮 Spielmodi

### Solo-Modus
- Starte direkt aus dem Hauptmenü
- Automatischer Room-Erstellen
- Score basiert auf zurückgelegter Distanz
- Eigener Highscore im Leaderboard

### Coop-Modus
1. **Raum erstellen** (Host):
   - "RAUM ERSTELLEN" klicken
   - Team-Namen festlegen (optional)
   - Raum-Code mit Freunden teilen

2. **Raum beitreten**:
   - Raum-Code eingeben
   - "RAUM BEITRETEN" klicken

3. **Gameplay**:
   - Host startet das Spiel wenn alle bereit sind
   - Team-Score = Distanz × Anzahl lebender Spieler
   - Beispiel: 100 Tiles mit 3 Spielern = 300 Punkte pro Spieler

### Steuerung

**Desktop:**
- `Leertaste` / `W` / `↑`: Springen
- `A` / `←`: Links bewegen
- `D` / `→`: Rechts bewegen
- `S` / `↓`: Schneller fallen

**Mobile:**
- Touch-Buttons auf dem Bildschirm

**Wall Climbing:**
- Laufe gegen eine Wand
- Halte Richtungstaste gedrückt zum Hochklettern
- Lasse los zum Herunterrutschen

## 🔧 Entwicklung

### Projekt-Struktur

```
EscapeFromTeacher/
├── cmd/
│   ├── server/          # Game Server
│   ├── client/          # Desktop & WASM Client
│   │   └── web/         # Web Assets & HTML
│   ├── builder/         # Asset Builder Tool
│   └── levelbuilder/    # Level Editor
├── pkg/
│   ├── game/            # Gemeinsame Game-Logik
│   ├── server/          # Server-spezifische Logik
│   └── config/          # Konfiguration
└── assets_raw/          # Rohe Asset-Dateien
```

### Neue Features entwickeln

1. **Server-Logik** in `pkg/server/`
2. **Game-Logik** (gemeinsam) in `pkg/game/`
3. **Client-Rendering** in `cmd/client/`
4. **Web-UI** in `cmd/client/web/`

### Build-Befehle

```bash
# Server
go build -o server ./cmd/server

# Desktop-Client
go build -o client ./cmd/client

# WASM-Client
GOOS=js GOARCH=wasm go build -o cmd/client/web/main.wasm ./cmd/client

# Level Builder
go build -o levelbuilder ./cmd/levelbuilder
```

## 🧰 Tools

### Level Builder

Erstelle eigene Levels mit dem visuellen Editor:

```bash
go run ./cmd/levelbuilder
```

**Features:**
- Drag & Drop von Assets
- Bewegende Plattformen konfigurieren
- Chunk-basiertes Level-Design
- JSON-Export in `cmd/client/web/assets/chunks/`

### Asset Builder

Konvertiere Raw-Assets zu optimierten Spiel-Assets:

```bash
go run ./cmd/builder
```

**Features:**
- PNG-Kompression und -Skalierung
- Hitbox-Editor
- Asset-Metadaten (Typ, Offsets, etc.)
- Generiert `assets.json`

## 📐 Architektur

### Client-Server Kommunikation

```
Client                    Server
  |                         |
  |------ WebSocket ------->|
  |   (Input Events)        |
  |                         |
  |<----- Broadcast --------|
  |   (Game State)          |
  |                         |
  |-- Score Submission ---->|
  |                         |
  |<--- Proof Code ---------|
```

### Game Loop

**Server (60 FPS):**
1. Verarbeite Inputs von allen Clients
2. Update Physik (Gravity, Kollision, etc.)
3. Update Map (Chunk spawning/despawning)
4. Broadcast Game State an alle Clients

**Client:**
1. Sende lokale Inputs an Server
2. Empfange Game State vom Server
3. Render Game State
4. (Optional) Client-Side Prediction für lokalen Spieler

### Score-System

**Solo:**
- Score = Zurückgelegte Distanz (in Tiles)
- Coins: +200 Punkte

**Coop:**
- Distanz-Score akkumuliert pro Tick
- Pro Tick: `Score += Anzahl lebender Spieler`
- Beispiel: 3 Spieler → +3 Punkte/Tick (180 Punkte/Sekunde)
- Coins werden geteilt: Alle Spieler bekommen +200

## 📄 Lizenz

Dies ist ein **Schulprojekt**. Kommerzielle Nutzung und Veränderung des Quellcodes sind ausdrücklich untersagt. Alle Rechte liegen bei den Urhebern.

**Projektleitung & Code:** Sebastian Unterschütz
**Musik & Sound Design:** Max Eisel

## 🙏 Credits

- **Ebiten**: Go 2D Game Engine
- **NATS**: Message Broker
- **Redis**: In-Memory Database
- **Go WASM**: WebAssembly Support

---

**Entwickelt als Abschieds-Projekt für IT232 (2025/2026)**