tony-remake/README.md

# Tony & Friends in Kellogg's Land — Remake

Ein plattformunabhängiges Remake (Python / pygame) des DOS-Jump'n'Runs
**„Kellogg's Tony and Friends in Kellogg's Land"** (1994). Ziel ist eine
lauffähige Neuimplementierung auf modernem x64, ohne DOS/DOSBox/QEMU — das
Original crasht in unserer FreeDOS-VM (RTM.EXE-Engine vs. QEMU-VGA-Emulation).

Das Remake liest die Grafiken, Sprites, Level und Musik **direkt aus den
Original-Spieldateien** (`game/original/PCKELL.DAT`) und dekodiert sie zur Laufzeit — es
werden keine vorab entpackten Assets benötigt.

## Status

- ✅ **Alle Asset-Formate geknackt & verifiziert:** PCC (Bilder), BOB (Sprites),
  ICO (Tilesets), MAP (Level), TFMX (Musik).
- ✅ **Boot-/Intro-Sequenz** spielbar (Rauser → Factor5 → Kellogg's-Logo →
  Titelbild, mit Fades, Vorhang-Wipe und Musik).
- ⏳ **Nächster Meilenstein:** echter Gameplay-Loop — Tony auf Level `W1L0`
  bewegen (Physik, Kollision, Level-Scrolling). Existiert noch nicht.

Die vollständige, chronologische Reverse-Engineering-Historie mit allen
Format-Details steht in [NOTES.md](NOTES.md).

## Rechtliches

„Kellogg's Tony and Friends in Kellogg's Land" war ein kostenloses Werbespiel
und ist innerhalb Deutschlands frei kopierbar. Die im Repo enthaltenen
gerenderten Musik-WAVs (`audio/`) wurden lediglich aus den Original-Daten
extrahiert. Die eigentlichen Original-Spieldateien (`game/original/`) sind
**nicht** im Repo (siehe `.gitignore`) — sie werden lokal benötigt, um das
Remake zu starten.

Der TFMX-Musik-Renderer unter [game/tfmx_player/](game/tfmx_player/) ist
Fremdcode (MIT-Lizenz, © Peter Fors) und liegt mit seiner LICENSE bei. Die
Format-Kenntnisse zu PCC/BOB/MAP/ICO stammen als Referenz aus
[movAX13h/tony-and-friends-in-kelloggs-land](https://github.com/movAX13h/tony-and-friends-in-kelloggs-land);
der Python-Code hier ist eine eigenständige Neuimplementierung.

## Voraussetzungen

- Python 3, `pygame`
- `Pillow` (PCX-Dekodierung), `numpy` (optional, für den Scanline-Effekt im Intro)
- `gcc` (einmalig, um den TFMX-Renderer zu bauen — passiert automatisch beim
  ersten Start)
- Die Original-Datei `PCKELL.DAT` unter `game/original/` (nicht im Repo)

```
sudo apt install python3-pygame python3-pil python3-numpy gcc
```

## Starten

```
python3 -m game            # Intro; bleibt am Titelbild stehen (Musik loopt)
python3 -m game --once      # Titelbild nur kurz halten (für Tests/headless)
```

Ablauf: Rauser → Factor5 → Kellogg's → Titelbild-Animation; danach bleibt das
fertige Titelbild stehen und die Titelmusik läuft in Schleife, bis eine Taste
das Programm beendet.

Steuerung:
- **Leertaste** — überspringt den aktuellen Intro-Screen (auf dem Titelbild
  beendet sie das Programm)
- **ESC** — beendet das Programm
- **Alt+Enter** — zwischen Fenster- und Vollbildmodus umschalten; der Zustand
  wird in `kelloggs.ini` gemerkt und beim nächsten Start wiederhergestellt
  (Standard ohne `kelloggs.ini`: Fenstermodus)

Ohne Soundkarte (z.B. headless) läuft das Spiel stumm weiter statt abzustürzen.

Liegt `PCKELL.DAT` woanders, kann der Pfad per Umgebungsvariable gesetzt werden:

```
KELLOGG_DAT=/pfad/zu/PCKELL.DAT python3 -m game
```

## Projektstruktur

```
game/                 Das eigentliche Spiel (startbar per `python -m game`)
  formats.py          Parser/Decoder für alle Asset-Formate aus PCKELL.DAT
  audio.py            Wrapper um den TFMX-Musik-Renderer (rendert & cached WAVs)
  intro.py            Boot-/Intro-Sequenz
  tfmx_player/        MIT-lizenzierter C-Renderer für TFMX-Musik
  original/           Original-DOS-Spieldateien (PCKELL.DAT etc.) — NICHT im Repo
tools/                Reine Dev-Werkzeuge (Assets auspacken / als PNG ansehen)
  dat_extract.py      PCKELL.DAT → alle 178 Einzeldateien (nach extracted_dat/)
  pcc_to_png.py       Eine PCC-Bilddatei → PNG
  render_assets.py    Batch-Render aller BOB/ICO/MAP → preview/render_out/
preview/              Vorab gerenderte Assets zum Ansehen/Anhören (Archiv, KEINE
                      Laufzeit-Abhängigkeit — das Spiel rendert alles selbst on the fly)
  png_out/            Vorab gerenderte PCC-Bilder
  render_out/         Vorab gerenderte BOB (Sprites) / ICO (Tiles) / MAP (Level)
  audio/              Aus PCKELL.DAT gerenderte Musik-WAVs
dosbox/               DOSBox-Konfiguration zum Laufenlassen des Originals (Referenz)
NOTES.md              Vollständiges Reverse-Engineering-Log
```

`game/formats.py` ist das gemeinsame Fundament: sowohl das Spiel als auch die
Dev-Werkzeuge in `tools/` importieren daraus. Zur Laufzeit braucht das Spiel
**nur** `raw/PCKELL.DAT` — alles unter `preview/` sind Verifikations-/Archiv-
Artefakte, keine Laufzeit-Abhängigkeit. Auch die Musik unter `preview/audio/`
wird vom Spiel nicht gelesen: `game/tfmx_player/` rendert sie zur Laufzeit
frisch aus `PCKELL.DAT` (nach `audio_cache/`).

## Original als Referenz laufen lassen (DOSBox)

Unter [dosbox/](dosbox/) liegt eine funktionierende Konfiguration, um das
Original zum visuellen Abgleich zu starten. Wichtig: In `KELLOGG.INI` **IRQ=5**
statt 7 setzen (sonst hängt sich das Spiel nach dem Factor-5-Logo auf) und die
`[sblaster]`-IRQ in der `dosbox.conf` passend dazu — Details in
[NOTES.md](NOTES.md).