RP411/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.

> ✅ **Verified build (2026-07-01):** all 4 projects build clean (`Release|Win32`)
> with **Visual C++ 2008 Express SP1** + **Windows SDK v6.0A** (VS-bundled) +
> **DirectX SDK (June 2010)**. Outputs: `Release\rpl4opt.exe` (the game),
> `Release\RPL4TOOL.exe`, `lib\Munga_L4.lib`, `lib\DivLoader.lib`.
> Only compiler *warnings* remain (deprecated CRT calls, int→Scalar narrowing,
> benign `LNK4006`/`LNK4221` duplicate-symbol notes). See §7 for the CLI recipe.

---

## 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) — **Express is fine** | 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`. The code uses **no MFC** and (as of the ATL-removal change) **no ATL**, so the free **Visual C++ Express** editions build it — see §6. |
| **DirectX SDK** | June 2010 (installed) — March 2009 also works | Provides `d3d9.lib`, `d3dx9.lib`, `dinput8.lib`, `dxguid.lib`, `dxerr.lib` and headers. ✅ Confirmed installed at `C:\Program Files (x86)\Microsoft DirectX SDK (June 2010)` with `DXSDK_DIR` set machine-wide. |
| **Windows SDK / Platform SDK** | Matching your VS (e.g. Windows SDK 7.1) | Provides `WS2_32.lib`, `dbghelp.lib`, etc. With an Express edition, install the standalone Windows SDK 7.1 to guarantee these. Note: `dbghelp.lib` is listed as a link input but **no source references it** — drop it from the linker line if it isn't found. |
| **`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.

---

## 6. Building with Visual C++ Express (2008)

The Express editions are free but ship **without MFC and without ATL**. This
codebase uses no MFC, and its only ATL dependency has been removed, so Express
now builds it:

- `MUNGA_L4/L4APP.cpp` previously included `<atlbase.h>` / `<atlconv.h>` and used
  the `USES_CONVERSION` / `W2A` macros to convert wide command-line arguments to
  ANSI. These were replaced with a small self-contained `L4WideToAnsi` helper
  (a thin `WideCharToMultiByte` wrapper) that reproduces ATL's `W2A` behaviour.
- `UseOfATL` was set to `0` in `Munga_L4.vcproj`, `RP_L4.vcproj` and their
  `VS2008` variants.

Checklist for a clean Express build:

1. Install **Visual C++ 2008 Express SP1**.
2. Install the **DirectX SDK (June 2010)** and confirm `DXSDK_DIR` is set.
3. Open `WinTesla.sln`, pick `Release|Win32`, build.

> The Windows SDK **v6.0A** that ships with VS2008 already provides `WS2_32.lib`
> and `dbghelp.lib`, so a separate Windows SDK 7.1 install was **not** needed in
> the verified build. `dinput8.lib`/`dxguid.lib` come from the DirectX SDK.

---

## 7. Verified command-line build recipe

This is exactly what produced the verified build. The key gotcha: a shell opened
*before* the DirectX SDK set the machine-level `DXSDK_DIR` will not see it, so the
recipe sets it explicitly.

```bat
@echo off
call "C:\Program Files (x86)\Microsoft Visual Studio 9.0\Common7\Tools\vsvars32.bat"
set "DXSDK_DIR=C:\Program Files (x86)\Microsoft DirectX SDK (June 2010)\"
cd /d C:\VWE\RP411
vcbuild /nologo /rebuild WinTesla.sln "Release|Win32"
```

Expected result: `4 Projects succeeded, 0 Projects failed`.

### DirectX SDK paths per project (all via `$(DXSDK_DIR)`)

For the build to find DirectX headers/libs, each project that touches DirectX
must reference the SDK through `$(DXSDK_DIR)`. This is now wired up as:

| Project | Include `$(DXSDK_DIR)Include` | Lib `$(DXSDK_DIR)Lib\x86` |
|---------|:---:|:---:|
| Munga_L4 | ✅ | ✅ |
| RP_L4 | ✅ | ✅ |
| RPL4TOOL | (not needed) | ✅ |
| DivLoader | ✅ | (static lib, no link) |