SpaceCadetPinball/README.md

# SpaceCadetPinball
**Summary:** Reverse engineering of `3D Pinball for Windows – Space Cadet`, a game bundled with Windows.

**How to play:** Place compiled executable into a folder containing original game resources (not included).\
Supports data files from Windows and Full Tilt versions of the game.

**Known source ports:**
| Platform | Author | URL |
| --- | --- | --- |
| PS Vita | Axiom | <https://github.com/suicvne/SpaceCadetPinball_Vita> |
| Emscripten | alula | <https://github.com/alula/SpaceCadetPinball> <br> Play online: https://alula.github.io/SpaceCadetPinball |
| Nintendo Switch | averne | https://github.com/averne/SpaceCadetPinball-NX |
| webOS TV | mariotaku | https://github.com/webosbrew/SpaceCadetPinball |

Platforms covered by this project: desktop Windows, Linux and macOS.
\
\
\
\
\
\
**Source:**
 * `pinball.exe` from `Windows XP` (SHA-1 `2A5B525E0F631BB6107639E2A69DF15986FB0D05`) and its public PDB
 * `CADET.EXE` 32bit version from `Full Tilt! Pinball` (SHA-1 `3F7B5699074B83FD713657CD94671F2156DBEDC4`)

**Tools used:** `Ghidra`, `Ida`, `Visual Studio`

**What was done:**
 * All structures were populated, globals and locals named.
 * All subs were decompiled, C pseudo code was converted to compilable C++. Loose (namespace?) subs were assigned to classes.

**Compiling:**

Project uses `C++11` and depends on `SDL2` libs.\
On Windows:\
Download and unpack devel packages for `SDL2` and `SDL2_mixer`.\
Set paths to them in CMakeLists.txt, see suggested placement in /Libs.\
Compile with Visual Studio; tested with 2019. 

On Linux:\
Install devel packages for `SDL2` and `SDL2_mixer`.\
Compile with CMake; tested with GCC 10, Clang 11.\
To cross-compile for Windows, install a 64-bit version of mingw and its `SDL2` and `SDL2_mixer` distributions, then use the `mingwcc.cmake` toolchain. 

On macOS:\
**Homebrew**: Install the `SDL2`, `SDL2_mixer` homebrew packages.\
**MacPorts**: Install the `libSDL2`, `libSDL2_mixer` macports packages.\
Compile with CMake. Ensure that `CMAKE_OSX_ARCHITECTURES` variable is set for either `x86_64` Apple Intel or `arm64` for Apple Silicon.\
Tested with: macOS Big Sur (Intel) with Xcode 13 & macOS Montery Beta (Apple Silicon) with Xcode 13.

**Plans:**
 * ~~Decompile original game~~
 * ~~Resizable window, scaled graphics~~
 * ~~Loader for high-res sprites from CADET.DAT~~
 * Misc features of Full Tilt: 3 music tracks, multiball, centered textboxes, etc.
 * Cross-platform port
   * Using SDL2, SDL2_mixer, ImGui
   * Maybe: Android port
 * Maybe x2: support for other two tables 
   * Table specific BL (control interactions and missions) is hardcoded, othere parts might be also patched

**On 64-bit bug that killed the game:**\
I did not find it, decompiled game worked in x64 mode on the first try.\
It was either lost in decompilation or introduced in x64 port/not present in x86 build.\
Based on public description of the bug (no ball collision), I guess that the bug was in `TEdgeManager::TestGridBox`
-												Added Readme.md
											
										
										
											2021-01-29 17:34:45 +01:00
+								# SpaceCadetPinball
 								**Summary:** Reverse engineering of `3D Pinball for Windows – Space Cadet`, a game bundled with Windows.
-												Made it compile with GCC on Linux.
Fixed GCC warnings and Windows specifics.
Restored C++11, switch to 14 was not supposed to happen.
Not 100% sure about my Find* module section.

											
										
										
											2021-09-09 10:40:54 +02:00
+								**How to play:** Place compiled executable into a folder containing original game resources (not included).\
-												Updated readme.

											
										
										
											2021-02-20 13:58:16 +01:00
+								Supports data files from Windows and Full Tilt versions of the game.
-												Added linear filter option for vScreen texture.
Rollback blit to backing storage – its persistence is not guaranteed.
Added project URL to About dialog.
Added source ports table to readme.

											
										
										
											2021-09-23 11:16:58 +02:00
 								**Known source ports:**
 								| Platform | Author | URL |
 								| --- | --- | --- |
 								| PS Vita | Axiom | <https://github.com/suicvne/SpaceCadetPinball_Vita> |
-												Added links to Emscripten source port.

Ref #12
											
										
										
											2021-10-02 07:04:54 +02:00
+								| Emscripten | alula | <https://github.com/alula/SpaceCadetPinball> <br> Play online: https://alula.github.io/SpaceCadetPinball |
-												Added link to Switch source port.

Mentioned macOS as supported.
											
										
										
											2021-10-15 13:07:25 +02:00
+								| Nintendo Switch | averne | https://github.com/averne/SpaceCadetPinball-NX |
-												Added webOS source port entry (#43)


											
										
										
											2021-10-16 13:26:15 +02:00
+								| webOS TV | mariotaku | https://github.com/webosbrew/SpaceCadetPinball |
-												Fixed md error in readme.

What is GFM? We just don't know.
											
										
										
											2021-09-23 11:21:18 +02:00
-												Added link to Switch source port.

Mentioned macOS as supported.
											
										
										
											2021-10-15 13:07:25 +02:00
+								Platforms covered by this project: desktop Windows, Linux and macOS.
-												Added Readme.md
											
										
										
											2021-01-29 17:34:45 +01:00
+								\
 								\
 								\
 								\
 								\
 								\
-												Updated readme.

											
										
										
											2021-02-20 13:58:16 +01:00
+								**Source:**
 								 * `pinball.exe` from `Windows XP` (SHA-1 `2A5B525E0F631BB6107639E2A69DF15986FB0D05`) and its public PDB
 								 * `CADET.EXE` 32bit version from `Full Tilt! Pinball` (SHA-1 `3F7B5699074B83FD713657CD94671F2156DBEDC4`)
-												Added Readme.md
											
										
										
											2021-01-29 17:34:45 +01:00
 								**Tools used:** `Ghidra`, `Ida`, `Visual Studio`
 								**What was done:**
 								 * All structures were populated, globals and locals named.
-												Updated readme.

											
										
										
											2021-02-20 13:58:16 +01:00
+								 * All subs were decompiled, C pseudo code was converted to compilable C++. Loose (namespace?) subs were assigned to classes.
-												Added Readme.md
											
										
										
											2021-01-29 17:34:45 +01:00
-												Update README.md to include macOS build instructions 

Include instructions for successful build of Space Cadet Pinball on both Intel macOS and Apple Silicon macOS. Small formatting fix.
											
										
										
											2021-09-29 03:42:22 +02:00
+								**Compiling:**
-												Made it compile with GCC on Linux.
Fixed GCC warnings and Windows specifics.
Restored C++11, switch to 14 was not supposed to happen.
Not 100% sure about my Find* module section.

											
										
										
											2021-09-09 10:40:54 +02:00
+								Project uses `C++11` and depends on `SDL2` libs.\
 								On Windows:\
 								Download and unpack devel packages for `SDL2` and `SDL2_mixer`.\
 								Set paths to them in CMakeLists.txt, see suggested placement in /Libs.\
 								Compile with Visual Studio; tested with 2019.
 								On Linux:\
 								Install devel packages for `SDL2` and `SDL2_mixer`.\
-												Mingw cross compilation (#24)

* Fixed icon filename capitalization

* Created mingw cmake toolchain

* Adjusted CMakeLists.txt for compatibility

* Small mingwcc.cmake cleanup

* Added cross-compilation instructions to readme

* Update README.md

Fixed typo

Co-authored-by: Nicola Orlando <nicolaorlando24@gmail.com>
Co-authored-by: Muzychenko Andrey <33288308+k4zmu2a@users.noreply.github.com>
											
										
										
											2021-10-07 11:53:56 +02:00
+								Compile with CMake; tested with GCC 10, Clang 11.\
 								To cross-compile for Windows, install a 64-bit version of mingw and its `SDL2` and `SDL2_mixer` distributions, then use the `mingwcc.cmake` toolchain.
-												Added Readme.md
											
										
										
											2021-01-29 17:34:45 +01:00
-												Update README.md to include macOS build instructions 

Include instructions for successful build of Space Cadet Pinball on both Intel macOS and Apple Silicon macOS. Small formatting fix.
											
										
										
											2021-09-29 03:42:22 +02:00
+								On macOS:\
 								**Homebrew**: Install the `SDL2`, `SDL2_mixer` homebrew packages.\
 								**MacPorts**: Install the `libSDL2`, `libSDL2_mixer` macports packages.\
 								Compile with CMake. Ensure that `CMAKE_OSX_ARCHITECTURES` variable is set for either `x86_64` Apple Intel or `arm64` for Apple Silicon.\
 								Tested with: macOS Big Sur (Intel) with Xcode 13 & macOS Montery Beta (Apple Silicon) with Xcode 13.
-												Added Readme.md
											
										
										
											2021-01-29 17:34:45 +01:00
+								**Plans:**
 								 * ~~Decompile original game~~
-												Updated readme.

											
										
										
											2021-02-20 13:58:16 +01:00
+								 * ~~Resizable window, scaled graphics~~
 								 * ~~Loader for high-res sprites from CADET.DAT~~
-												Fix a typo (#32)


											
										
										
											2021-10-15 06:26:16 +02:00
+								 * Misc features of Full Tilt: 3 music tracks, multiball, centered textboxes, etc.
-												SDL port v1, Windows only for now.
Working: graphics, sound, music (3dpb only).
Not working: GUI, user settings.

											
										
										
											2021-08-27 12:29:41 +02:00
+								 * Cross-platform port
 								   * Using SDL2, SDL2_mixer, ImGui
 								   * Maybe: Android port
-												Added Readme.md
											
										
										
											2021-01-29 17:34:45 +01:00
+								 * Maybe x2: support for other two tables
 								   * Table specific BL (control interactions and missions) is hardcoded, othere parts might be also patched
 								**On 64-bit bug that killed the game:**\
 								I did not find it, decompiled game worked in x64 mode on the first try.\
 								It was either lost in decompilation or introduced in x64 port/not present in x86 build.\
 								Based on public description of the bug (no ball collision), I guess that the bug was in `TEdgeManager::TestGridBox`