# Crystal Maze (WildTangent) - Modern Proton & Linux Fix 🎮

A pre-configured, patched setup to run the classic 2000s WildTangent 3D casual game **Crystal Maze** (starring Lily) on modern Linux distributions and the Steam Deck using **Proton / Wine** (via Heroic Games Launcher, Lutris, or Steam).

---

## 📥 Download

Grab the complete pre-patched release package from the **[Releases Page](https://git.richardf.us/rebeccanod1/CrystalMazeProton/releases)**:
- **`Crystal-Maze-Proton-Ready.zip`**

---

## 🛠️ What Was Fixed?

Out of the box on modern systems and Wine, Crystal Maze suffered from multiple game-breaking incompatibilities:

1. **Infinite 100% CPU Lockup on Modern GPUs**:
   - `WebDriver/dx7drv.dll` originally performed signed 16-bit integer texture size checks. Modern GPUs with large VRAM caused this loop to overflow and hang indefinitely.
   - **Fix**: Patched `dx7drv.dll` at offsets `0x8dbc` and `0x8dc7` (`0f bf` ➔ `0f b7`, `movsx` ➔ `movzx`) and clamped maximum texture dimensions.
2. **Missing ActiveX / COM Registration (Silent Black Screen & No Audio)**:
   - `MAZE-WT.EXE` is an ATL host application that instantiates the 3D engine via ActiveX CLSID `{FA13A9FA-CA9B-11D2-9780-00104B242EA3}` (`WTDriver`). Because `webdriver.dll`'s `DllRegisterServer` was a dummy stub in the original installer, COM instantiation silently failed in Wine, causing the engine to skip level and audio loading.
   - **Fix**: `crystal_maze_setup.reg` properly registers `WTDriver`, `IWT`, and typelibs in `HKEY_CLASSES_ROOT` and `HKEY_LOCAL_MACHINE`.
3. **Runtime Attribute Crash on Startup**:
   - The game originally queried unpopulated registry runtime attributes, causing fatal exception dialogs.
   - **Fix**: Patched the exception handler in `MAZE-WT.EXE` to safely fallback.
4. **DirectDraw 7 / Direct3D Translation**:
   - Bundled **dgVoodoo 2.8.2** (`DDraw.dll` and `D3DImm.dll`) with custom configuration (`DeframerSize = 0`, watermarks disabled) translating DirectDraw 7 to Direct3D 11, which DXVK then maps to Vulkan at a locked 60 FPS.

---

## 🚀 Quick Setup Guide (Heroic Games Launcher)

### Step 1: Extract the Game
Download and extract `Crystal-Maze-Proton-Ready.zip` to your desired folder (e.g. `~/Games/Crystal Maze` or inside your Wine prefix).

### Step 2: Add Game to Heroic
1. Open **Heroic Games Launcher**.
2. Click **Add Game** ➔ **Sideload Game**.
3. Fill in the details:
   - **Game Title**: `Crystal Maze`
   - **Select Executable**: Browse to `MAZE-WT.EXE` inside your extracted folder.
   - **Working Directory**: The extracted `Crystal Maze` folder.
   - **Wine Version**: Select **GE-Proton9-27** (or any modern **GE-Proton 9.x / Proton 9+** installed via Heroic's Wine Manager).
   - **Wine Prefix**: Choose any folder (e.g. `~/Heroic Games/Prefixes/crystal maze`).

### Step 3: Run Prefix Setup (Once)
Open a terminal in the game folder and run:
```bash
bash setup_prefix.sh "/path/to/your/wineprefix"
```
*(Alternatively, in Heroic: go to **Wine Settings** ➔ click **"Run EXE on Prefix"** and select `setup_prefix.sh` or import `crystal_maze_setup.reg`).*

> **Note**: `setup_prefix.sh` automatically configures all required COM classes, SKU metadata, and DirectDraw DLL overrides directly into the prefix registry, so no manual environment variables or extra settings are needed!

### Step 4: Play!
Click **Play** in Heroic. Lily, the 3D maze, and original sound/music will launch immediately!

---

## 📂 Repository Contents

- `setup_prefix.sh`: One-click Bash script to copy driver configs and register COM components in a target Wine prefix.
- `crystal_maze_setup.reg`: Standalone Windows registry file containing all required COM CLSIDs, SKU info, and DLL overrides.
- `dgVoodoo.conf`: Pre-tuned dgVoodoo 2.8.2 configuration (no watermark, window aspect ratio fixes, DeframerSize disabled).
- `SKUInfo.ini`: WildTangent SKU configuration required to prevent CRT save aborts.
- `wt3d.ini`: Core 3D engine driver settings.

---

## 📜 Credits & Preservation

Crystal Maze originally developed by WildTangent (2003–2006). This repository is intended for digital preservation and compatibility on modern Linux/Proton systems.