RP412/BUILD.md

# Building Red Planet (v4.10, Win32)

This is the Win32 source for the pod-racing game **Red Planet**, built on the
in-house **MUNGA** engine and its **L4** (Win32 / DirectX 9) platform layer.
The code targets the Visual Studio 2005/2008 era and the legacy DirectX SDK.

---

## 1. Requirements

You must supply the toolchain — none of it is checked into this repo.

| Component | Required version | Notes |
|-----------|------------------|-------|
| **Visual Studio** | 2005 (v8) or 2008 (v9) | Project files are the legacy `.vcproj` format. Modern MSBuild **cannot** build `.vcproj` directly — it needs `VCBuild.exe`, which only ships with VS 2005/2008. A newer VS (2022) can build these but will first *upgrade* the projects to `.vcxproj`. |
| **DirectX SDK** | March 2009 (June 2010 also works) | Provides `d3d9.lib`, `d3dx9.lib`, `dinput8.lib`, `dxguid.lib`, `dxerr.lib` and headers. |
| **Windows SDK / Platform SDK** | Matching your VS | Provides `WS2_32.lib`, `dbghelp.lib`, etc. |
| **`DXSDK_DIR` environment variable** | — | The DirectX SDK installer sets this automatically (includes a trailing backslash). The projects reference the SDK **only** through this variable — see §4. |

### Bundled third-party libraries (already in the repo)

These are committed under [lib/](lib/) and do **not** need to be installed:

- `OpenAL32.lib` — OpenAL audio
- `libsndfile-1.lib` — sound-file loading

Their headers live in [MUNGA_L4/openal/](MUNGA_L4/openal/) and
[MUNGA_L4/sndfile.h](MUNGA_L4/sndfile.h). You will still need the matching
runtime DLLs (`OpenAL32.dll`, `libsndfile-1.dll`) next to the built `.exe` to run it.

---

## 2. Solution / project layout

The solution is [WinTesla.sln](WinTesla.sln). It builds four projects:

| Project | File | Type | Output | Depends on |
|---------|------|------|--------|------------|
| **Munga_L4** | [MUNGA_L4/Munga_L4.vcproj](MUNGA_L4/Munga_L4.vcproj) | Static lib | `lib\Munga_l4.lib` | — |
| **RP_L4** | [RP_L4/RP_L4.vcproj](RP_L4/RP_L4.vcproj) | Application (exe) | `rpl4opt.exe` | Munga_L4 |
| **RPL4TOOL** | [RP_L4/RPL4TOOL.vcproj](RP_L4/RPL4TOOL.vcproj) | Application (exe) | tool exe | Munga_L4 |
| **DivLoader** | [DivLoader/DivLoader.vcproj](DivLoader/DivLoader.vcproj) | Static lib | `lib\*.lib` | — |

**Build order:** `Munga_L4` → then `RP_L4` / `RPL4TOOL` (the dependency is
declared in the solution, so a solution-level build resolves it automatically).

`RP_L4` is the game itself. Its release output is **`rpl4opt.exe`**
(subsystem: Windows GUI).

### VS2008 project variants

Each of the three main projects also ships a `... VS2008.vcproj` variant
(format 9.00) alongside the original 8.00 files:

- `MUNGA_L4/Munga_L4 VS2008.vcproj`
- `RP_L4/RP_L4 VS2008.vcproj`
- `RP_L4/RPL4TOOL VS2008.vcproj`

The `.sln` references the **8.00** files. If you open in VS 2008, either let it
upgrade the 8.00 projects, or repoint the solution at the `VS2008` variants.

---

## 3. Build steps

1. Install VS 2005/2008 (with the C++ workload) and the DirectX SDK.
   Confirm the SDK set `DXSDK_DIR`:
   ```powershell
   echo $env:DXSDK_DIR
   ```
2. Open `WinTesla.sln` in Visual Studio.
   - If prompted to upgrade the projects (newer VS), accept — this rewrites the
     `.vcproj` files to `.vcxproj`. Keep those changes on a branch.
3. Select a configuration: **Debug | Win32** or **Release | Win32**.
   (`x64` is not configured — this is a 32-bit build.)
4. Build the solution (`Ctrl+Shift+B`). `Munga_l4.lib` is produced first into
   `lib\`, then the executables link against it.

### Command-line build (only with VS 2005/2008 installed)

```powershell
# From a "Visual Studio 2008 Command Prompt":
vcbuild WinTesla.sln "Release|Win32"
```
> Do **not** use `C:\Windows\Microsoft.NET\Framework\...\MSBuild.exe` on this
> solution — it fails with `MSB3428: Could not load the Visual C++ component
> "VCBuild.exe"` because the legacy C++ toolset is not present.

---

## 4. DirectX SDK path (no longer hardcoded)

Originally `Munga_L4.vcproj` and `RP_L4.vcproj` hardcoded the absolute path
`C:\Program Files (x86)\Microsoft DirectX SDK (March 2009)\...`. These have been
changed to use the standard installer-provided variable, matching what the
VS2008 variants already did:

- Include dir → `"$(DXSDK_DIR)Include"`
- Library dir → `"$(DXSDK_DIR)Lib\x86"`

So any DirectX SDK version installed to any location will work, as long as
`DXSDK_DIR` is set. If you build in an environment where it is not set, either
set it manually or pass it to the build, e.g.:

```powershell
$env:DXSDK_DIR = "C:\DXSDK\"   # note the trailing backslash
```

---

## 5. Known caveats

- **32-bit only.** No `x64` configuration exists.
- **`Remote Debug|Win32`** configuration is present but is a debugging target,
  not a normal build config.
- Requires the OpenAL and libsndfile **runtime DLLs** at run time (see §1).
- See [docs/BUILD-NOTES.md](docs/BUILD-NOTES.md) for the repository cleanup
  history, orphaned files, and the full findings behind this document.