CTR Native

Crash Team Racing decompiled — recompiled as a native 64-bit PC executable. No emulator. No ROM. No PS1 SDK.

---

What is this?

CTR Native is a ground-up port of Crash Team Racing (PS1, 1999) that takes the decompiled game source from CTR-ModSDK and recompiles it directly to x86-64 machine code — no MIPS cross-compiler, no emulator, no PS1 BIOS.

How it differs from the original project

	CTR-ModSDK (original)	CTR Native
Target	PS1 (MIPS, 32-bit)	PC (x86-64, 64-bit)
Build system	CMake (PS1 toolchain)	SCons (native GCC/MinGW)
Architecture	32-bit pointers, MIPS ABI	64-bit pointers, SSE SIMD
GPU	Real PS1 hardware	OpenGL via software GPU emulation
Audio	Real SPU hardware	SDL3 audio backend
Overlays	PS1 CD-streamed binary blobs	Native .dll / .so shared libraries
Input	PS1 controller ports	SDL3 gamepad + keyboard
Build type	Cross-compiled ROM	Native executable (.exe / ELF)

⚠️ 64-bit caveat: Native pointers are 8 bytes vs the PS1's 4. A LEV_PTR bridge translates 32-bit file offsets to host pointers at load time, and GPU primitive link fields (24-bit on PS1) use a token table. Most of the game works, but some pointer-arithmetic edge cases can still crash — especially in less-tested overlays.

---

Architecture at a glance

┌──────────────────────────────────────────────────┐
│                Host OS (Win / Linux)              │
│  ┌───────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │  SDL3     │ │  OpenGL  │ │  Filesystem      │ │
│  │ (input,   │ │ (GPU     │ │ (assets, saves,  │ │
│  │  audio,   │ │  output) │ │  overlays)       │ │
│  │  window)  │ │          │ │                  │ │
│  └─────┬─────┘ └────┬─────┘ └────────┬─────────┘ │
│        │            │                │           │
│  ┌─────┴────────────┴────────────────┴─────────┐ │
│  │         platform/  (native PSX facade)      │ │
│  │  GPU · GTE · SPU · CD · Controller · BIOS   │ │
│  │  ~30 files, 1900+ LoC renderer, SSE GTE     │ │
│  └─────────────────────┬───────────────────────┘ │
│                        │                         │
│  ┌─────────────────────┴───────────────────────┐ │
│  │  game/  (same decompiled CTR source, ~266   │ │
│  │  files — physics, AI, menus, audio, HUD)    │ │
│  └─────────────────────────────────────────────┘ │
│                        │                         │
│  ┌─────────────────────┴───────────────────────┐ │
│  │  Overlays: .dll / .so loaded at runtime     │ │
│  │  libovr221_225 · 226_229 · 230 · 231 ·      │ │
│  │  232 · 233 + test_menu (hot-reloadable)     │ │
│  └─────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘

Overlay system (DLL/SO)

The PS1 original streamed 13 code overlays from CD into 3 fixed memory regions. CTR Native compiles each logical overlay group into a native shared library loaded at runtime via dlopen() (Linux) or LoadLibraryA() (Windows):

Region	PS1 original	CTR Native	File
221–225	5 end-of-race screens	1 shared lib	libovr221_225.so / .dll
226–229	4 LOD renderers	1 shared lib	libovr226_229.so / .dll
230	Main menu	1 shared lib	libovr230.so / .dll
231	Race gameplay	1 shared lib	libovr231.so / .dll
232	Adventure hub	1 shared lib	libovr232.so / .dll
233	Cutscenes + podium	1 shared lib	libovr233.so / .dll
—	—	Test menu (hot-reload)	libtestmenu.so / .dll

Each overlay exposes ovl_init(), ovl_update(), ovl_destroy() via dlsym/GetProcAddress. The test menu can be rebuilt and reloaded without restarting the game (F12).

---

Major changes from CTR-ModSDK

🔧 Build & toolchain

• SCons replaces CMake — single SConstruct for both Windows and Linux
• 64-bit target (-m64) with SSE enabled (-msse)
• Unity build — all game .c files are #included into main.c as a single translation unit
• SDL3 vendored at externals/SDL and compiled inline
• Automatic git hash + build number embedding

🧱 Platform abstraction layer (entirely new)

• platform/ (~30 files) replaces every PS1 hardware dependency
• GPU → OpenGL — software GPU emulation translates PS1 primitive packets to GL draw calls
• GTE → SSE — Geometry Transformation Engine emulated with SSE intrinsics
• SPU → SDL audio — full SPU register and DMA emulation
• CD-ROM → filesystem — cdrom:\ paths redirected to assets/ directory
• Controller → SDL — gamepad + keyboard with hotplug support
• BIOS functions → native — LoadImage, DrawSync, VSync, etc.

🧠 Memory model

• PS1 2MB RAM → host arena (8MB default, 2MB retail-pressure mode)
• LEV_PTR bridge converts 32-bit level data offsets to 64-bit host pointers
• GPU link bridge — 24-bit OT link fields mapped to 64-bit pointers via token table
• Scratchpad (1KB) translated from fixed PS1 address to host buffer

🎮 New features (not in ModSDK)

• Save states — F5 save / F8 load, full state capture (GPU, audio, input, mempack)
• Deterministic replay system — record/pad input for bug reproduction
• Debug overlay — FPS, VRAM, MEMPACK stats, wireframe mode
• Performance profiler — per-frame timing with CSV export, 35+ buckets
• Widescreen (16:9) — corrected projection matrix
• 60 FPS toggle
• Hot-reloadable test menu (F12 to rebuild + reload)
• Case-insensitive asset path resolution
• Build metadata — version, git hash, compiler info in title bar

🧹 Code quality

• stdint types replace PsyQ aliases (u32 → uint32_t, etc.)
• Enums made portable with fixed underlying types
• CTR_STATIC_ASSERT across all modules
• -Werror-safe with format diagnostics and strict prototypes
• .clang-tidy static analysis configuration
• Pointer hygiene scans via analyze_bits.py / verify_64bit.py

---

Quick start

Prerequisites

Platform	Requirements
Windows	MSYS2 + MinGW-w64 (mingw-w64-x86_64-gcc)
Linux	GCC, libx11-dev, libgl1-mesa-dev, libasound2-dev, libudev-dev

Build

# Linux
scons

# Windows (MSYS2 or MSVC environment)
scons

Output: build/linux/ctr_native or build/win/ctr_native.exe

Run

1. Extract BIGFILE.BIG, KART.HWL/*.XA, TEST.STR from a CTR NTSC-U disc
2. Place them in assets/ with the correct structure (see docs/)
3. Launch:

./build/linux/ctr_native        # Linux
build\win\ctr_native.exe        # Windows

Debug controls

Key	Action
F1	Toggle wireframe
F5	Save state
F8	Load state
F9/F10	Record replay (start/stop)
F12	Reload test menu

---

Project structure

ctr-native/
├── main.c                 # Entry point + unity build manifest
├── SConstruct             # SCons build system (Win + Linux)
├── platform.h             # Platform abstraction API
├── platform/              # Native PSX facade (~30 files)
│   ├── native_renderer.c  # OpenGL renderer (1900+ LoC)
│   ├── native_gpu.c       # PS1 GPU emulation
│   ├── native_gte_core.c  # SSE GTE emulation
│   ├── native_audio.c     # SDL audio backend
│   ├── native_overlay.c   # dlopen/LoadLibrary overlay loader
│   ├── native_savestate.c # Save/restore game state
│   └── ...
├── game/                  # Original decompiled CTR source (~266 files)
│   ├── 230/ 231/ 232/ 233/# Overlay modules (menus, race, hub, cutscenes)
│   ├── HOWL/              # Audio engine
│   ├── MATH/              # Math library
│   └── ...
├── game/overlay_modules/  # Shared library entry points
├── include/               # Headers + PsyQ-compatible facades
│   ├── psx/               # PsyQ SDK headers (libgte.h, libgpu.h, ...)
│   ├── platform/          # Native platform API headers
│   └── ...
├── externals/SDL          # Vendored SDL3
├── docs/                  # Technical documentation
│   ├── MEMORY_MODEL.md
│   ├── OVERLAYS.md
│   └── REPLAYS.md
└── metadata/              # Retail disc layout reference

---

Roadmap

• Eliminate remaining (int)ptr assumptions in game code
• Improve GPU emulation accuracy (dithering, blending)
• Network multiplayer (original modem/adapter protocol)
• Rumble support
• Full audio effect parity

---

Credits

• CTR-ModSDK — decompilation foundation
• PsyCross — PsyQ compatibility layer reference (MIT)
• PSn00bSDK — PS1 type/constant headers (MPL-2.0)
• SDL3 — cross-platform multimedia (zlib)
• Crash Team Racing © Sony Computer Entertainment / Naughty Dog