CrystalMazeProton/README.md

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:

• 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: Configure DLL Overrides in Heroic

1. In Heroic, go to Game Settings ➔ Advanced tab.
2. Under Environment Variables, add:
   • Key: WINEDLLOVERRIDES
   • Value: ddraw,d3dimm=n,b

Step 4: Run Prefix Setup (Once)

Open a terminal in the game folder and run:

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).

Step 5: 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.