README.md

Planet Blupi — Technical Documentation

This documentation describes the internal workings of Planet Blupi (Epsitec SA, 1997). It is aimed at developers working with this codebase or reverse-engineering related games (especially Speedy Blupi, which is authored by the same team and shares core design).

---

Table of Contents

Overview

• Game Overview — what is Planet Blupi, technical summary, gameplay pillars
• History & Relation to Speedy Blupi — origin, fork context, shared code

Architecture

• System Architecture — class diagram, subsystem relationships, tick lifecycle
• Source Files Reference — every .cpp/.h file explained

Engine Internals

• Data Structures — Cellule, Blupi, Move, Term, DescFile in full detail
• Game Phases (Screens) — WM_PHASE_* messages, screen lifecycle, flow diagram
• Rendering — image channels, coordinate system, draw order, CPixmap
• Pathfinding (A*) — CPileTriee, CheminCherche(), obstacle tables
• Fog of War — quadrant bit encoding, 15 fog patterns, API
• Minimap — generation, colour coding, click-to-scroll
• Demo Recording & Playback — DemoHeader, DemoEvent, replay mechanism
• Undo System — single-step undo in the level editor

World (Map)

• World File Format (.blp) — binary layout, DescFile header, versioning
• World Grid — 200×200 cells, coordinate system, viewport, scrolling
• Terrain & Auto-tiling — floor tiles, regions, arrange.cpp, tableSee
• Object Layer — object categories, channels, passability

Characters

• Character Overview (Blupi struct) — every field of the Blupi structure
• Player Character (Blupi) — energy, spawning, selection, idle animations
• Enemies — spider, virus, tracks, robot, bomb, electro — AI & behaviour
• Vehicles — boat, jeep, armour — boarding, movement, exits
• Animation Actions (ACTION_*) — all codes for all character types
• Task Interpreter (GOAL_*) — all opcodes, parameters, GoalNextOp(), WM_ACTION_* mapping

Gameplay

• Win Conditions (Term) — Term struct, IsTerminated()
• Toolbar Buttons (BUTTON_*) — all 35 actions, WM_ACTION_* mapping
• Movement Directions (DIRECT_*) — 8-direction system, GetVector()
• Skill Levels — easy / normal / hard
• Regions (World Themes) — 4 visual themes, sprite sheet swap
• Cheat Codes — invincible, super

Assets

• Image Assets — all .blp images, channels CHBACK–CHBIGNUM
• Sound Effects (SOUND_*) — all 85 SFX with descriptions
• Music Tracks — 10 MIDI tracks
• Data Files — data/ directory, mission numbering
• Movie Sequences — AVI files, fallback images

User Interface

• Windows Messages (WM_*) — complete WM_ACTION_, WM_BUTTON_, WM_PHASE_* tables
• Mouse Cursor Sprites (SPRITE_*) — 14 cursor sprites
• Statistics Panel — contents, update, rendering
• Error Codes (ERROR_*) — 8 error states

Platforms

• Build System — CMake, dependencies, target platforms
• Configuration File — data/config.def, all keys
• Localisation — language packs, string resources
• Web (Emscripten) — IndexedDB persistence, export/import

Speedy Blupi Reference

• Relation to Speedy Blupi — fork context, shared elements, key differences
• actions.h Reference — complete enum listings for decompilation use