# Playcard Cosmic — native cross-platform port

A modern C++20 / SDL3 reimplementation of **Cosmic** (Cube / Playcard, 2000),
a Windows 95 DirectX shoot-'em-up released as *Pocket Playcard Game #11*. The
game logic was reverse-engineered from the original `COSMIC.EXE` and rebuilt on
portable subsystems. It runs natively on **Windows, Linux and macOS**, reads its
data straight from the untouched original executable, and adds a full settings
menu, gamepad support, resolution scaling and a frame-rate–independent
simulation.

> [!IMPORTANT]
> **This repository does not include any original game files.** No code, graphics,
> sounds or video from the 2000 release are distributed here. To play, you need
> `COSMIC.EXE` (and optionally `INTRO.AVI`) from the original disc, which is
> preserved on the Internet Archive:
> **[Pocket Playcard Game – The Complete Collection](https://archive.org/details/pocket_playcard_games)**
> (file `ISO Files/Pocket Playcard Game #11 - Cosmic.iso`).
> See [Getting the game data](#1-getting-the-game-data).

> [!NOTE]
> **Made with AI tools.** The reverse engineering (static analysis, Ghidra
> decompilation review), the C++ source code and this documentation were
> produced with the help of AI tools (Anthropic's Claude) and then tested
> against the original game. Expect the occasional inaccuracy; issues and
> corrections are welcome.

* [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md): static analysis of the
  binary, recovered data structures and rules, original bugs, porting strategy,
  and a function-by-function map from the original addresses to the port.
* [`docs/RESOURCES.md`](docs/RESOURCES.md): what every embedded bitmap and
  sound is used for.

---

## 1. Getting the game data

The game data is **only needed to run** the port; building does not need it.

1. Download **`Pocket Playcard Game #11 - Cosmic.iso`** (≈25 MB) from the
   *ISO Files* folder of
   [archive.org/details/pocket_playcard_games](https://archive.org/details/pocket_playcard_games).
2. Open the ISO and copy two files out of it:
   * **Windows**: double-click the `.iso` to mount it as a drive.
   * **macOS**: double-click it, or run `hdiutil attach "Pocket Playcard Game #11 - Cosmic.iso"`.
   * **Linux**: `7z x "Pocket Playcard Game #11 - Cosmic.iso"`, or mount it with
     `sudo mount -o loop,ro <file>.iso /mnt`.

The disc contains only three files:

```
autorun.inf
cosmic.exe   (24 MB — code *and* every sprite and sound, as Win32 resources)
intro.avi    (Cinepak intro movie)
```

Copy `cosmic.exe` and `intro.avi` into a folder called `data` next to the
port's executable. The port searches, in order:

1. `[data] dir = …` in `cosmic.ini`, or `--data <folder>` on the command line
2. the `COSMIC_DATA` environment variable
3. `./data`, then the current directory
4. `<executable dir>/data`, then the executable's directory
5. `<user dir>/data` (see *Files* below)

File names are matched case-insensitively, so `COSMIC.EXE` from a CD works on
Linux and macOS too.

### Extracting the assets (optional)

Nothing has to be unpacked to play: the port decodes resources on demand
directly from `cosmic.exe`. To look at or edit the assets, use the bundled
extractor:

```bash
cosmic-extract path/to/cosmic.exe extracted --intro path/to/intro.avi --keyed --raw
```

| Output | Contents |
|---|---|
| `extracted/bitmaps/<id>.png` | all 423 bitmaps as RGBA PNG (`--keyed`: colour key turned into alpha) |
| `extracted/bitmaps/<id>.bmp` | the original DIB, byte for byte (`--raw`) |
| `extracted/sounds/<id>.wav` | the 21 original WAVE resources, byte for byte |
| `extracted/intro/NNN.png` | decoded intro frames |
| `extracted/manifest.txt` | id, type, dimensions / audio format |

### Mods and high-resolution texture packs

Create a `mods` folder next to the executable (or in the current or user
directory):

```
mods/bitmaps/<id>.png   (or .bmp)   replaces bitmap <id>
mods/sounds/<id>.wav                replaces sound <id> (8/16-bit PCM)
```

Replacement images may be any resolution. They are drawn at the original
sprite's size, so a 2× or 4× pack lines up automatically. Set **Display →
Internal resolution** to 1280×960 or higher to see the extra detail. PNGs with
alpha are used as-is; images without alpha get the original's colour key
(the top-left pixel's colour is transparent).

---

## 2. Building

Requirements: **CMake ≥ 3.24**, a **C++20** compiler (MSVC 2022, GCC 11+,
Clang 14+, Apple Clang 14+) and Git. SDL3 (`release-3.4.16`) is downloaded and
built automatically, and linked statically by default. To use an installed SDL3
instead, pass `-DCOSMIC_VENDOR_SDL=OFF` (or use the `system-sdl` preset).

Presets live in [`CMakePresets.json`](CMakePresets.json):

| Preset | Host → target |
|---|---|
| `windows-msvc` | Windows, newest installed Visual Studio (2022 or later), x64 |
| `windows-mingw` | Windows, MinGW-w64 / LLVM-MinGW |
| `linux` | Linux native |
| `macos` | macOS universal (arm64 + x86_64), 11.0+ |
| `cross-windows-x64` | Linux/macOS → Windows x64 (MinGW-w64 toolchain file) |
| `cross-linux-arm64` | Linux x64 → Linux arm64 (`aarch64-linux-gnu` toolchain file) |
| `system-sdl` | native, against an installed SDL3 |

Binaries are written to `build/<preset>/`.

### Windows

Visual Studio 2022 or later with the *Desktop development with C++* workload
(CMake picks the newest installed version):

```bash
cmake --preset windows-msvc
```

```bash
cmake --build --preset windows-msvc
```

The result is `build\windows-msvc\Release\cosmic.exe`. MinGW-w64 or
[LLVM-MinGW](https://github.com/mstorsjo/llvm-mingw) also work; with
`make`/`clang` on `PATH`, use the `windows-mingw` preset. MinGW builds link the
C++ runtime statically, so the `.exe` has no DLL dependencies.

### Linux

Install a compiler and SDL3's build dependencies. On Debian/Ubuntu:

```bash
sudo apt install build-essential cmake git libasound2-dev libpulse-dev libpipewire-0.3-dev libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxi-dev libxss-dev libxtst-dev libwayland-dev libxkbcommon-dev wayland-protocols libegl1-mesa-dev libgl1-mesa-dev libdbus-1-dev libudev-dev
```

```bash
cmake --preset linux && cmake --build --preset linux -j
```

On Fedora, install the matching `-devel` packages
(`alsa-lib-devel pulseaudio-libs-devel pipewire-devel libX11-devel libXext-devel libXrandr-devel libXcursor-devel libXi-devel libXScrnSaver-devel libXtst-devel wayland-devel libxkbcommon-devel mesa-libEGL-devel mesa-libGL-devel dbus-devel systemd-devel`).

### macOS

Install the Xcode command-line tools (`xcode-select --install`) and CMake
(`brew install cmake`):

```bash
cmake --preset macos && cmake --build --preset macos -j
```

This produces a universal `cosmic.app`. Put the `data` folder in
`~/Library/Application Support/CosmicPort/Cosmic/data` or inside the bundle at
`cosmic.app/Contents/Resources/data`, or launch with `--data <folder>`.

### Cross-compiling

Linux or macOS → Windows (MinGW-w64 from your package manager, or LLVM-MinGW
on `PATH`):

```bash
cmake --preset cross-windows-x64 && cmake --build --preset cross-windows-x64 -j
```

Linux x64 → Linux arm64 (install `g++-aarch64-linux-gnu` and an arm64 sysroot
containing SDL3's dependencies):

```bash
cmake --preset cross-linux-arm64 -DCOSMIC_SYSROOT=/path/to/arm64-sysroot && cmake --build --preset cross-linux-arm64 -j
```

### Build options

| Option | Default | Meaning |
|---|---|---|
| `COSMIC_VENDOR_SDL` | `ON` | fetch and build SDL3; `OFF` uses `find_package(SDL3)` |
| `COSMIC_STATIC_SDL` | `ON` | link the fetched SDL3 statically |
| `COSMIC_BUILD_TOOLS` | `ON` | build `cosmic-extract` |

CI ([`.github/workflows/build.yml`](.github/workflows/build.yml)) builds the
Windows, Linux and macOS presets on every push.

---

## 3. Playing

| | Keyboard (default) | Gamepad |
|---|---|---|
| Move | Arrow keys / WASD | D-pad / left stick |
| Fire (one volley per press) | Ctrl / Space | A (South) / RB / RT |
| Confirm | Enter | A / Start |
| Pause & settings | Esc, F1 or Tab | B (East) / Back |
| Fullscreen | F11 or Alt+Enter | — |
| Screenshot | F12 (saved to the user dir) | — |

Every binding can be changed under **Settings → Controls**.

**How to play.** Pick a planet on the star chart and press Enter. Shoot aliens
until the station opens. Destroy its two turrets, then its core, and pick up
the prize. The first four planets of each sector hold wormhole keys, the
others upgrade your weapon (twin cannon → orbiting mine → rear gun → side
guns). Four keys reveal the wormhole. Three sectors later you reach Earth's
final defender.

### Settings menu (new)

The original game had no options at all. The port adds:

* **Display**: windowed, borderless fullscreen or exclusive fullscreen (with a
  resolution picker); window size presets plus free resizing; *Fit* (4:3
  letterbox), *Integer* (pixel-perfect) or *Stretch* scaling; sharp or smooth
  filtering; internal resolution 1×–4× for HD texture packs; VSync.
* **Performance**: uncapped frame rate or a 30–360 fps cap (used when VSync is
  off), precise frame pacing (sleep and spin), physics sub-step size, FPS
  counter.
* **Audio**: Master, Music and Effects volume; mute while in the background.
* **Controls**: rebind every action for keyboard and gamepad (Enter to rebind,
  Delete to clear), stick dead zone, optional auto-fire (off by default; the
  original fires once per key press), reset to defaults.
* **Gameplay**: *Fix original bugs* (on by default; see ARCHITECTURE.md §2) and
  *Skip intro*.

Settings are saved to `cosmic.ini` when the menu closes.

### Files

| Platform | User directory |
|---|---|
| Windows | `%APPDATA%\CosmicPort\Cosmic\` |
| Linux | `~/.local/share/CosmicPort/Cosmic/` |
| macOS | `~/Library/Application Support/CosmicPort/Cosmic/` |

It contains `cosmic.ini` (settings), `hiscore.txt`, `cosmic.log` and
`screenshots/`. On Windows, an existing high score from the original game
(`HKLM\SOFTWARE\Cube\Cosmic\HiScore`) is imported on first launch.

### Command line

```
cosmic [--data <dir>] [--config <cosmic.ini>] [--windowed | --fullscreen] [--skip-intro]
       [--warp boss|ending|level2] [--autoplay <script>]
```

`--warp` jumps straight to a late game state, and `--autoplay` replays a timed
input script and can save screenshots, for testing and attract-mode demos. The
script format is documented in `src/core/Engine.cpp` (`LoadAutoplay`).

---

## 4. Code layout

```
CMakeLists.txt, CMakePresets.json, cmake/toolchains/   build system
src/core/     Engine Core: main loop, timing and frame pacing, config, paths, logging
src/assets/   PE resource reader, DIB/WAV/AVI/Cinepak decoders, AssetManager with mod overrides
src/render/   Rendering subsystem: 640×480 logical canvas, scaling, display modes
src/audio/    Audio mixer: 70 DirectSound-style slots, Music/SFX/Master buses
src/input/    Input manager: actions, keyboard, gamepads, repeat, rebinding
src/ui/       Pause / settings overlay
src/game/     Game state machine and gameplay (Game, Map, Combat, Boss, World, HiScore)
tools/        cosmic-extract
docs/         reverse-engineering notes and resource map
```

Start with `core/Engine.cpp` for the frame loop, then `game/Game.h` for the
state machine and the list of original functions each method replaces.
Gameplay code keeps the original's entity indices, timers and constants, and
each function names the address it was reconstructed from, so behaviour can be
checked against the binary.

### Timing model

The original measured time with `timeGetTime()` (1 ms resolution) and ran one
logic step per rendered frame with no limiter. On today's hardware that means
frame deltas of 0–1 ms and juddering motion. The port:

* measures frame time in nanoseconds and advances a game clock that stops
  while the game is paused, minimised or unfocused;
* splits each frame into sub-steps of at most *Physics sub-step* ms, so
  movement, collisions and missile steering behave the same at 30 fps or
  500 fps;
* replaces every blocking `Sleep()` with a timed state, so the window stays
  responsive;
* renders as fast as allowed: VSync, a frame cap with precise pacing, or
  uncapped.

---

## 5. License and disclaimer

The source code in this repository is licensed under the
**GNU General Public License v3.0** — see [`LICENSE`](LICENSE).

This is an unofficial, non-commercial fan project. It is not affiliated with or
endorsed by Cube, Playcard or any rights holder of the original game. It
contains **no code or data from the original game**: it reads the original
files you supply at run time. *Cosmic* and all of its original assets are ©
their respective authors (Cube / Playcard, 2000).

This project was created with the assistance of AI tools.