CTmine-client/README.md

# ⛏ CTmine-client · ContainerMine Client

Eine Docker-WebApp, die einen **echten Minecraft Java-Client** im Container
laufen lässt und ihn per **noVNC direkt im Browser** anzeigt. Ideal, um einen
Account AFK an eine Farm zu stellen — ohne lokalen Minecraft-Client oder
Java-Installation.

Das Dashboard ist eine **Vite + Vue 3**-Anwendung, die im selben Container
mit ausgeliefert wird.

---

## Architektur

```
Browser  ──HTTP/WS──▶  nginx (:8080)
                        ├── /            → Vue-Dashboard (statisch)
                        ├── /api/*       → Node-Status-API (127.0.0.1:3000)
                        └── /websockify  → websockify (127.0.0.1:6080)
                                              │
                       supervisord verwaltet ▼
                        Xvfb :0  →  x11vnc  →  websockify  →  Browser
                          ▲
                     Prism Launcher + echter Minecraft-Client
                     (rendert per Software-OpenGL/llvmpipe auf Xvfb)
```

**Warum Prism Launcher statt offiziellem Mojang-Launcher?** Der Mojang-Launcher
nutzt für den Microsoft-Login ein eingebettetes Webview, das in einem headlessen
Container regelmäßig Probleme macht. Prism startet denselben Vanilla-Client,
ist aber container-freundlich und nutzt den **Device-Code-Flow** für den Login:
Code notieren → `microsoft.com/link` auf irgendeinem Gerät öffnen → fertig.

---

## Voraussetzungen

- **Docker** (mit BuildKit) und **Docker Compose v2**
- ~2 GB freier Speicher für das Image
- Einen **gültigen Microsoft-Account** mit Minecraft-Lizenz
- Chromium/Firefox (für WebGL & WebSocket in noVNC)

> Lokales Bauen ohne Docker ist nicht vorgesehen. Wenn du nur das Dashboard
> entwickeln willst, siehe [Entwicklung](#dashboard-entwickeln).

---

## Schnellstart

```bash
# 1. Env-Datei erzeugen und anpassen
cp .env.example .env
#    PUID/PGID mit `id -u` / `id -g` setzen, damit ./config dir gehört.

# 2. Image bauen und starten
docker compose up -d --build

# 3. Dashboard öffnen
#    http://localhost:8080
```

---

## Erster Login (einmalig)

1. **Dashboard öffnen** → http://localhost:8080
2. Auf **„Instanz starten“** klicken. Prism Launcher öffnet sich im VNC-Fenster.
3. In Prism oben rechts: **Konto → Konto hinzufügen → Microsoft**.
4. Prism zeigt einen **Code** an. Auf *irgendeinem* Gerät
   `https://microsoft.com/link` öffnen, Code eingeben, mit Microsoft einloggen.
5. Zurück in Prism: im Hauptfenster die gewünschte **Instanz** wählen und auf
   **„Spielen“** klicken. Prism lädt die passende Minecraft-Version + Java
   automatisch herunter.
6. Im Minecraft-Hauptmenü: **Mehrspieler → Server hinzufügen** → Adresse der
   Farm eingeben → **Verbinden**.

Ab jetzt ist der Account auf der Farm. Der Login liegt persistent in
`./config/prism` und bleibt auch nach `docker compose down` erhalten.

> **Tipp:** Bevor du den Container Neustartest, kannst du in Minecraft über
> *Optionen → Steuerelemente* auch schon die korrekte Farm-Anbindung
> (z. B. eine Trade/Anti-AFK-Makro-Mod) konfigurieren — sie bleibt erhalten.

---

## AFK-Farm-Setup

Die konkrete Einrichtung hängt von deiner Farm ab. Typische Schritte:

- **Anti-AFK**: periodisch springen/bewegen, damit der Server dich nicht kickt.
  Du kannst die Vanilla-Funktion (z. B. Wasserstrom, der dich ständig leicht
  bewegt) nutzen oder eine Client-Mod wie *Mouse Tweaks* / *Inventory Profiles*
  installieren. Mods legst du über Prism in die jeweilige Instanz.
- **Auto-Reconnect**: manche Server trennen nach Stunden. Nutze ggf. eine
  *Reconnect*-Mod.
- **Fenster offen lassen**: Solange das Dashboard geöffnet ist, siehst du den
  Client live. Du kannst den Tab schließen — Minecraft läuft im Container
  weiter. Nur der Container muss laufen.

---

## Konfiguration (`.env`)

| Variable            | Standard      | Bedeutung                                          |
| ------------------- | ------------- | ------------------------------------------------- |
| `PUID` / `PGID`     | `1000`        | UID/GID des Container-Benutzers. Mit `id -u`/`id -g` deines Host-Users setzen, damit `./config` dir gehört. |
| `TZ`                | `Europe/Berlin` | Zeitzone des Containers.                        |
| `DISPLAY_WIDTH`     | `1280`        | Breite des virtuellen Displays (MC-Auflösung).   |
| `DISPLAY_HEIGHT`    | `720`         | Höhe des virtuellen Displays.                    |
| `DISPLAY_DEPTH`     | `24`          | Farbtiefe (24 = 8-bit RGB).                      |
| `DISPLAY_REFRESH`   | `60`          | Bildwiederholrate des virtuellen Displays.       |
| `WEB_PORT`          | `8080`        | Browser-Port.                                     |
| `VNC_PASSWORD`      | *(leer)*      | Optional. Leer = ohne Auth (nur lokales Netz!).   |
| `X11VNC_EXTRA`      | siehe `.env`  | Low-Latency-/Eingabe-Flags für x11vnc.            |

---

## Steuerung über VNC

Die Steuerung ist auf **Minecraft-Menü, Chat, Inventar und AFK-Farmen**
optimiert. Sie ist **nicht** für aktives PVP/Mouselook gedacht — das ist eine
grundsätzliche Grenze von VNC (siehe unten).

**Bedienung im Browser:**
- **Klick ins Bild** → setzt den Tastaturfokus ins Spielfenster (Tasten gehen
  ans Spiel, nicht an den Browser).
- **Maus freigeben** → `Strg + Alt + Umschalt` (noVNC-Standard).
- **Vollbild** → Button in der Toolbar; für Minecraft flächendeckend.
- **Zwischenablage** → automatisch verknüpft (Login-Codes / Server-IPs kopieren
  geht direkt zwischen Browser und Container).

**Was automatisch eingestellt ist:**
- `resize=remote`: die Xvfb-Auflösung folgt der Fenstergröße (1:1-Maus-Mapung,
  keine Skalierungs-Unschärfe).
- `reconnect=1`: bei Abbruch verbindet noVNC selbstständig neu.
- x11vnc mit `-threads -pointer_mode 4 -norepeat`:
  - `-threads` → parallele I/O-Threads, weniger Eingabe-Lag.
  - `-pointer_mode 4` → flüssigere Mausübertragung als der Default (1).
  - `-norepeat` → verhindert doppelte Tastaturwiederholungen im Spiel.
- `-nodpms -nofbpm -nowf -nowcr` → Energiesparen und Rate-Limiting aus, damit
  nichts nach Leerlauf ruckelt.

**Für langsames Netz** (z. B. Remote über Internet statt LAN) in der `.env`
Kompression aktivieren:
```
X11VNC_EXTRA=-threads -pointer_mode 4 -norepeat -tight -compresslevel 6 -quality 7
```

### Warum Mouselook nicht richtig geht

VNC überträgt **absolute** Mauskoordinaten („Cursor an Position X/Y"). Minecraft
wie jedes FPS-artige Spiel braucht aber **relative** Mausbewegung und setzt den
Cursor dafür jeden Frame auf die Bildmitte zurück ([noVNC Issue #1493][novnc1493]).
Darum lässt sich die Kamera per VNC nicht sinnfrei drehen.

Für Menü, Buttons, Chat, Inventar und reines AFK auf einer Farm ist das ohne
Bedeutung. Wer wirklich remote *spielen* will, braucht ein anderes Protokoll
(Sunshine/Moonlight statt VNC) — das ist mit dieser Architektur nicht abgedeckt.

[novnc1493]: https://github.com/novnc/noVNC/issues/1493

---

## API

| Methode | Pfad             | Beschreibung                              |
| ------- | ---------------- | ---------------------------------------- |
| `GET`   | `/api/status`    | Status von Display, VNC und Minecraft.   |
| `POST`  | `/api/mc/start`  | Startet Prism Launcher.                  |
| `POST`  | `/api/mc/stop`   | Beendet Prism + Minecraft.               |

Beispiel:
```bash
curl -X POST http://localhost:8080/api/mc/start
```

---

## Dashboard entwickeln

Für die Vue-Entwicklung ohne jedes Mal neu zu bauen:

```bash
cd web
npm install
npm run dev    # → http://localhost:5173 (proxyt /api + /websockify nach :8080)
```

Damit das Dev-Dashboard funktioniert, muss der Container laufen
(`docker compose up -d`), damit der VNC-Stream und die API erreichbar sind.

---

## Performance-Hinweise

- Minecraft rendert im Container per **llvmpipe (CPU-Software-OpenGL)**.
  Für AFK-Farmen absolut ausreichend (~1–2 CPU-Kerne), aber kein flüssiges PVP.
- `shm_size: 1gb` ist gesetzt, damit OpenGL genug Shared Memory hat.
- Bei verfübarer GPU kannst du `/dev/dri` durchreichen (in `docker-compose.yml`
  auskommentiert). MC nutzt dann Hardware-Rendering.

---

## Projektstruktur

```
CTmine-client/
├── Dockerfile                # Multi-Stage: Vue-Build + Runtime
├── docker-compose.yml
├── .env.example
├── docker/
│   ├── entrypoint.sh         # PUID/PGID, /config, Xvfb/x11vnc-Conf generieren
│   ├── supervisor.conf       # Prozess-Manager für alle Dienste
│   ├── nginx.conf            # Dashboard + /api + /websockify Proxy
│   └── mc-api/               # Node-Status-API (ohne externe Dependencies)
│       ├── server.js
│       └── package.json
└── web/                      # Vite + Vue 3 + TypeScript Dashboard
    ├── package.json · vite.config.ts · tsconfig.json
    └── src/
        ├── App.vue · main.ts · api.ts · types.ts
        ├── styles/main.css
        └── components/
            ├── VncViewer.vue     # noVNC-Integration
            ├── ControlPanel.vue  # MC Start/Stop, Schnellstart-Anleitung
            └── StatusBar.vue     # Status-Indikatoren
```

---

## Bekannte Einschränkungen

- **Sound** ist im MVP nicht konfiguriert (für AFK-Farmen irrelevant).
- **Erster Login interaktiv**: der Microsoft-Login muss einmalig im VNC-Fenster
  per Device-Code durchgeführt werden. Danach persistent.
- **EULA/Nutzungsbedingungen**: Dieses Projekt stellt nur die Infrastruktur
  bereit. Du bist selbst für die Einhaltung der Mojang/Minecraft-Nutzungs-
  bedingungen und der Regeln deines Zielservers verantwortlich.

---

## Lizenz

MIT — siehe `LICENSE` falls beigefügt. Minecraft ist Eigentum von Mojang/Microsoft;
dieses Projekt steht nicht in offizieller Verbindung.