Zipping a release no longer costs you your own settings

The file-preserving repack landed with the restore before the zip and
skipped entirely under -Zip, to keep somebody's callsign and key
bindings out of a release. It worked, but at the price of -Zip quietly
wiping the settings out of dist\ - captured, then discarded.

Both properties are available at once by moving the restore after the
archive is taken: the zip is built from a folder with none of the
player's files in it, and they go back into dist\ immediately
afterwards. A fresh unzip still looks like a first run, and cutting a
release costs the person cutting it nothing.

Verified: edited all four files, packed with -Zip, and confirmed the
archive contains none of them - 1003 entries, nothing loose at the root -
while all four are still in dist\ with their edits intact.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.gitignore

@@ -45,6 +45,15 @@ rpl4.log
 # on somebody's desk.
 mfd_layout.cfg
 
+# The pilot's callsign, remembered between sessions. Whoever is sitting
+# at this machine, which is not the repo's business.
+pilot.cfg
+
+# Generated by stamp-version.ps1 as RP_L4's pre-build step. The patch
+# number in it IS this repository's commit count, so a committed copy
+# would be stale the moment it was committed.
+/RP_L4/rpl4build.h
+
 # Build-output static libs that land in lib/ (the two committed dependency
 # libs, OpenAL32.lib and libsndfile-1.lib, stay tracked).
 /lib/Munga_L4.lib

BUILD.md

@@ -50,10 +50,39 @@ The solution is [WinTesla.sln](WinTesla.sln) with four v143 projects:
 Build order is resolved by `ProjectReference` (RP_L4 and RPL4TOOL both reference
 Munga_L4).
 
+**Versioning:** the patch number *is* the repository's commit count, so a
+build always names the commit it came from and there is no question about
+which changes a given binary contains.
+[stamp-version.ps1](stamp-version.ps1) runs as RP_L4's pre-build step and
+writes the generated, uncommitted `RP_L4\rpl4build.h`:
+
+```
+#define RP412_VERSION       "4.12.96"
+#define RP412_VERSION_LONG  "4.12.96 (a1b2c3d)"
+```
+
+The game logs the long form on its first line. A trailing `+` on the hash
+means the tree had uncommitted changes to tracked files when it was built —
+useful when a test machine reports something a clean build cannot reproduce.
+Only the `4.12` product line is set by hand, at the top of the script.
+
+The header is deliberately not committed: the commit that recorded a
+hardcoded number would itself change the count, so the file would be stale
+the moment it landed. It is rewritten only when the stamp actually changes,
+so ordinary rebuilds do not recompile `RPL4.CPP` for nothing. Building
+outside a git checkout stamps `4.12.x (no repository)` rather than inventing
+a number that would sort against real ones.
+
 **Packaging:** [pack-dist.ps1](pack-dist.ps1) assembles a runnable game into
-`dist\` (exe + PDB, game data, OpenAL/libsndfile runtimes, desktop
-`environ.ini`, `start-windowed.bat`, README). Pass `-Zip` to also produce
-`dist\RedPlanet412-prototype.zip` for handing to someone else.
+`dist\` (exe + PDB, game data, OpenAL/libsndfile runtimes, launch scripts,
+HANDBOOK.html, README). It deliberately does **not** write `environ.ini` —
+the exe carries that template and writes it on first run
+([RP_L4/RPL4ENVIRON.cpp](RP_L4/RPL4ENVIRON.cpp)), so a tester can drop a new
+build over an old folder without losing their settings. Pass `-Zip` to also produce
+`RedPlanet-<version>.zip` for handing to someone else. It reads the version
+from `rpl4build.h` rather than asking git again, so the package and the
+binary inside it cannot disagree, and it warns if the build it is packing
+came from a modified tree.
 
 ## 3. VS2022 migration notes (what changed and why)
 

MUNGA/APP.cpp

@@ -649,8 +649,23 @@ Time endIntercom = Now();
 	//
 	if (GetApplicationState() == RunningMission)
 	{
-		secondsRemainingInGame =
-			currentMission->GetGameLength() - (Now() - gameStarted);
+		//
+		// Ask the console first: it owns the clock that actually ends the
+		// race, so this is the countdown the buzzer will agree with. Its
+		// own reckoning is the fallback for everything with no console of
+		// its own - see gMissionClockHook in APPMGR.h.
+		//
+		Scalar console_remaining;
+		if (gMissionClockHook != NULL &&
+			(*gMissionClockHook)(&console_remaining))
+		{
+			secondsRemainingInGame = console_remaining;
+		}
+		else
+		{
+			secondsRemainingInGame =
+				currentMission->GetGameLength() - (Now() - gameStarted);
+		}
 	}
 	routePacketFinished = False;
 
@@ -1125,6 +1140,12 @@ void
 	Check(this);
 	Check(egg_notation_file);
 
+	//
+	// Forget every peer's clock offset: the hosts in the next race are not
+	// the hosts in the last one, and a HostID gets reused.
+	//
+	NetClock_Reset();
+
 	//
 	//--------------------------------------------------------------------------
 	// Create mission from egg notation file

MUNGA/APPMGR.cpp

@@ -15,6 +15,9 @@ Logical gConsoleMarshalsLaunch = False;
 // losing the console mid-mission ends it (lobby-member races)
 Logical gConsoleLossEndsMission = False;
 
+// the console's countdown, when a console is marshalling (see APPMGR.h)
+Logical (*gMissionClockHook)(Scalar *seconds_remaining) = NULL;
+
 ApplicationManager* ApplicationManager::CurrentAppManager = NULL;
 
 ApplicationManager::ApplicationManager(HINSTANCE hInstance, HWND hWnd, Scalar frame_rate) : Node(ApplicationManagerClassID), runningApplications(this)

MUNGA/APPMGR.h

@@ -20,6 +20,28 @@ extern Logical gConsoleMarshalsLaunch;
 // console to return, exactly as always.
 extern Logical gConsoleLossEndsMission;
 
+//
+// The console's own countdown, when there is a console to ask.
+//
+// A mission ends when the console says so, but secondsRemainingInGame was
+// computed here from the engine clock and its own idea of when the race
+// started - a different clock, from a different epoch, than the one that
+// actually fires the buzzer. The two agree to within a frame or so, which
+// is why nobody noticed, but they are not the same number: the cockpit
+// clock could read 0:00 with the race still running, and the camera
+// directors' "last 30 seconds" behaviour switched on the engine's reading
+// rather than on the real remaining time.
+//
+// Set by the console when it is marshalling; NULL restores the engine's
+// own reckoning, which is what the arcade -net pods, lobby members and
+// mission review all use (none of them run a console locally, and their
+// clock is anchored by the console's RunMission arriving anyway).
+//
+// Returns False when it has no answer yet - the window between the
+// application reaching RunningMission and the console noticing.
+//
+extern Logical (*gMissionClockHook)(Scalar *seconds_remaining);
+
 class ApplicationManager : public Node
 {
 public:

MUNGA/ENTITY.cpp

@@ -377,8 +377,28 @@ void
 	//------------------------------------------------------------------------
 	// Step through each block until there are no more remaining, and send the
 	// update out the the simulation indicated by the subsystemID
+	//
+	// This is the only point on the receive path that knows WHOSE update
+	// this is - the records themselves carry a timestamp but not an owner -
+	// so the sender is published here for the net clock to align against.
+	// Every record in the message, and the damage zones nested inside them,
+	// came from the same machine in the same frame.
 	//------------------------------------------------------------------------
 	//
+	//
+	// Only for an entity somebody else owns. Our own clock needs no
+	// aligning, and an update we somehow handed ourselves would otherwise
+	// drag lastUpdate back by a frame for no reason.
+	//
+	Check(application);
+	Check(application->GetHostManager());
+	Logical remote_owner =
+		GetOwnerID() != application->GetHostManager()->GetLocalHostID();
+	if (remote_owner)
+	{
+		NetClock_BeginUpdate(GetOwnerID());
+	}
+
 	while (stream.GetBytesRemaining())
 	{
 		Simulation::UpdateRecord *update =
@@ -389,6 +409,11 @@ void
 		simulation->ReadUpdateRecord(update);
 		stream.AdvancePointer(update->recordLength);
 	}
+
+	if (remote_owner)
+	{
+		NetClock_EndUpdate();
+	}
 	Check_Fpu();
 }
 

MUNGA/SIMULATE.cpp

@@ -264,6 +264,109 @@ Simulation::SharedData
 // Model support
 //
 
+//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+//
+//##########################################################################
+// Net clock - see SIMULATE.h for why the sender's timestamp is estimated
+// rather than used as it stands.
+//##########################################################################
+
+namespace
+{
+	enum
+	{
+		netClockMaxPeers = 16,
+
+		// Samples per rolling minimum. A peer sends one record per
+		// simulation per frame, so at eight vehicles and 60 fps this is
+		// well under a second - fast enough to follow a route change,
+		// long enough that the minimum means something.
+		netClockWindow = 128,
+
+		// The furthest back we will believe a timestamp. Beyond this the
+		// packet is stale or the estimate is wrong, and extrapolating a
+		// vehicle half a second forward does more harm than the lag we
+		// are correcting.
+		netClockMaxLagTicks = 500
+	};
+
+	struct PeerClock
+	{
+		HostID	host;
+		Logical	inUse;
+		Logical	settled;
+		long	offsetTicks;		// our clock - their clock
+		long	windowMinTicks;
+		int		windowCount;
+	};
+
+	PeerClock	gPeerClocks[netClockMaxPeers];
+	HostID		gUpdateSender = 0;
+	Logical		gUpdateSenderValid = False;
+
+	Logical NetClockEnabled()
+	{
+		static int enabled = -1;
+		if (enabled < 0)
+		{
+			const char *setting = getenv("RP412NETCLOCK");
+			enabled = (setting != NULL && atoi(setting) == 0) ? 0 : 1;
+			if (!enabled)
+			{
+				DEBUG_STREAM << "NetClock: disabled by RP412NETCLOCK=0 - "
+					<< "replicants dead-reckon from arrival time\n" << std::flush;
+			}
+		}
+		return enabled ? True : False;
+	}
+
+	PeerClock *FindPeer(HostID host)
+	{
+		PeerClock *free_slot = NULL;
+		for (int i = 0; i < netClockMaxPeers; ++i)
+		{
+			if (gPeerClocks[i].inUse)
+			{
+				if (gPeerClocks[i].host == host)
+				{
+					return &gPeerClocks[i];
+				}
+			}
+			else if (free_slot == NULL)
+			{
+				free_slot = &gPeerClocks[i];
+			}
+		}
+		if (free_slot != NULL)
+		{
+			free_slot->inUse = True;
+			free_slot->host = host;
+			free_slot->settled = False;
+			free_slot->offsetTicks = 0;
+			free_slot->windowMinTicks = 0;
+			free_slot->windowCount = 0;
+		}
+		return free_slot;
+	}
+}
+
+void NetClock_BeginUpdate(HostID sender)
+{
+	gUpdateSender = sender;
+	gUpdateSenderValid = True;
+}
+
+void NetClock_EndUpdate()
+{
+	gUpdateSenderValid = False;
+}
+
+void NetClock_Reset()
+{
+	memset(gPeerClocks, 0, sizeof(gPeerClocks));
+	gUpdateSenderValid = False;
+}
+
 //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 //
 void
@@ -272,7 +375,84 @@ void
 	Check(this);
 	Check_Pointer(message);
 
-	lastUpdate = Now();     // HACK - should be based upon message->timeStamp
+	//
+	//------------------------------------------------------------------
+	// When this update arrived is not when it was taken. Put lastUpdate
+	// at the sender's sampling moment, expressed in our clock, so the
+	// dead reckoner extrapolates over the network latency instead of
+	// starting from scratch once it has already elapsed.
+	//------------------------------------------------------------------
+	//
+	long now_ticks = Now().ticks;
+	long local_ticks = now_ticks;
+
+	PeerClock *peer = gUpdateSenderValid && NetClockEnabled()
+		? FindPeer(gUpdateSender) : NULL;
+	if (peer != NULL)
+	{
+		//
+		// sample = trueOffset + oneWayLatency, so the running minimum
+		// converges on the offset from above.
+		//
+		long sample = now_ticks - message->timeStamp.ticks;
+
+		if (!peer->settled)
+		{
+			peer->settled = True;
+			peer->offsetTicks = sample;
+			peer->windowMinTicks = sample;
+			peer->windowCount = 0;
+			DEBUG_STREAM << "NetClock: host " << peer->host
+				<< " first sample, offset " << sample << " ms\n" << std::flush;
+		}
+		else
+		{
+			if (sample < peer->windowMinTicks)
+			{
+				peer->windowMinTicks = sample;
+			}
+			if (sample < peer->offsetTicks)
+			{
+				peer->offsetTicks = sample;		// a shorter path: believe it now
+			}
+			if (++peer->windowCount >= netClockWindow)
+			{
+				//
+				// Close the window: adopt its minimum even if it is
+				// LARGER than the running estimate, which is how the
+				// figure follows clock drift and a route that got
+				// slower rather than staying pinned to one old packet.
+				//
+				long moved = peer->windowMinTicks - peer->offsetTicks;
+				if (moved > 50 || moved < -50)
+				{
+					DEBUG_STREAM << "NetClock: host " << peer->host
+						<< " offset " << peer->offsetTicks << " -> "
+						<< peer->windowMinTicks << " ms\n" << std::flush;
+				}
+				peer->offsetTicks = peer->windowMinTicks;
+				peer->windowMinTicks = sample;
+				peer->windowCount = 0;
+			}
+		}
+
+		local_ticks = message->timeStamp.ticks + peer->offsetTicks;
+
+		//
+		// Never ahead of our own clock, and never further back than we
+		// are willing to extrapolate.
+		//
+		if (local_ticks > now_ticks)
+		{
+			local_ticks = now_ticks;
+		}
+		else if (now_ticks - local_ticks > netClockMaxLagTicks)
+		{
+			local_ticks = now_ticks - netClockMaxLagTicks;
+		}
+	}
+
+	lastUpdate.ticks = local_ticks;
 	SetSimulationState(message->simulationState);
 	Check_Fpu();
 }

MUNGA/SIMULATE.h

@@ -4,6 +4,41 @@
 #include "receiver.h"
 #include "time.h"
 #include "resource.h"
+#include "hostid.h"
+
+//##########################################################################
+//###########################    Net clock    ##############################
+//##########################################################################
+//
+// Aligning a peer's clock with ours, so a replicant is dead-reckoned from
+// when its update was SENT rather than when it happened to arrive.
+//
+// Every update record carries the sender's own timestamp. The receiver
+// used to throw it away and stamp lastUpdate with its own Now() - the
+// original code says so: "HACK - should be based upon message->timeStamp".
+// The dead reckoner then extrapolates over (lastPerformance - lastUpdate),
+// so starting that clock at ARRIVAL rather than at SEND leaves every
+// remote vehicle exactly one network latency behind where it should be.
+// On the 1 ms arcade LAN that was invisible. Over Steam Datagram Relay it
+// is a constant 50-150 ms of positional lag - a bias, not jitter.
+//
+// The timestamp cannot be used raw: two machines' clocks share no epoch,
+// both being QueryPerformanceCounter since their own boot. So we estimate
+// the offset per peer. Each arriving record gives
+//
+//     sample = ourNow - theirStamp = trueOffset + oneWayLatency
+//
+// and since latency is never negative, the SMALLEST sample seen is the
+// closest to the true offset. Taking a minimum over a short rolling
+// window tracks crystal drift and re-adapts when the route changes,
+// instead of being pinned forever by one lucky packet.
+//
+// RP412NETCLOCK=0 turns the whole thing off and restores the arrival-time
+// behaviour, so a test machine can A/B it without a rebuild.
+//
+void NetClock_BeginUpdate(HostID sender);	// around one message's records
+void NetClock_EndUpdate();
+void NetClock_Reset();						// forget every peer (new mission)
 
 class Simulation__SharedData;
 class Simulation__IndexData;

README.md

@@ -96,9 +96,13 @@ team/position columns and its own track list). Steam multiplayer: see
 [docs/STEAM-3-MACHINE-TEST.md](docs/STEAM-3-MACHINE-TEST.md) (until RP412
 has its own AppID it runs under Spacewar, 480).
 
-The two config files beside the exe are self-documenting: **environ.ini**
-(every engine option, commented) and **bindings.txt** (every key, pad
-button, and axis; written with the full default layout on first run).
+The config files beside the exe are self-documenting and none of them
+ship: the game writes each one the first time it needs it and then leaves
+it alone, so a new build dropped over an existing folder keeps every
+setting. **environ.ini** is every engine option, commented; **bindings.txt**
+every key, pad button and axis; **pilot.cfg** your callsign and loadout;
+**mfd_layout.cfg** where you dragged the windows. Delete any of them to
+start that part over with the current defaults.
 Default controls: numpad flies (8/2/4/6 stick, 7/9 pedals, 0 trigger),
 Shift/Ctrl throttle, Alt reverse, arrows look, Space fires, letter rows
 are the MFD button banks as printed on the panel. **Alt+Q** aborts a

RP_L4/RPL4.CPP

@@ -22,6 +22,7 @@
 
 #include "rpl4pb.h"
 #include "rpl4fe.h"
+#include "rpl4environ.h"
 #include "rpl4console.h"
 #include "rpl4lobby.h"
 #include "..\munga_l4\l4steamtransport.h"
@@ -29,6 +30,7 @@
 #include "..\munga_l4\l4mfdview.h"		// RPWindowLayout_*
 #include "..\munga_l4\l4joy.h"			// RPJoyConfigWizard
 #include "rpl4ver.h"
+#include "rpl4build.h"		// generated: RP412_VERSION / RP412_VERSION_LONG
 #include "..\munga\resver.h"
 #include "..\munga\resource.h"
 // added for game status drawing support
@@ -149,6 +151,15 @@ int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine
 
 	SetUnhandledExceptionFilter(RPL4CrashDumpFilter);
 
+   //
+   // Which build this is, before anything else can fail. The patch number
+   // is this repository's commit count and the hash beside it names the
+   // commit, so a log from a test machine says exactly where it came from.
+   // A trailing '+' means the tree had uncommitted changes when it was
+   // built. See stamp-version.ps1.
+   //
+   DEBUG_STREAM << "Red Planet " << RP412_VERSION_LONG << std::endl << std::flush;
+
    // load up our environment variables
    //controls
    if(getenv("L4CONTROLS") == NULL)
@@ -163,32 +174,14 @@ int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine
 	   putenv("TARGETFPS=60");
    if(getenv("MAXPARTICLES") == NULL)
 	   putenv("MAXPARTICLES=8192");
-   FILE *file;
-   char line[1024];
-   if (fopen_s(&file, "environ.ini", "r") == 0)
-   {
-      while (!feof(file))
-      {
-         if (fgets(line, sizeof(line), file))
-         {
-            for (int i = strlen(line); i >= 0; i--)
-               if (line[i] == '\n' || line[i] == '\r')
-                  line[i] = 0;
-            // the file is self-documenting: skip comments, blanks,
-            // and anything that is not KEY=VALUE
-            char *setting = line;
-            while (*setting == ' ' || *setting == '\t')
-               ++setting;
-            if (*setting == '\0' || *setting == '#' || *setting == ';' ||
-                strchr(setting, '=') == NULL)
-               continue;
-            putenv(setting);
-         }
-      }
-      fclose(file);
-   }
+   //
+   // environ.ini: written on first run and read here. The exe owns the
+   // template rather than the packaging script laying one down on every
+   // unzip, so a tester can drop a new build over an old folder and keep
+   // their settings. See rpl4environ.h.
+   //
+   RPL4Environ_Load();
 
-   DEBUG_STREAM << "Red Planet 4.12.7" << std::endl << std::flush;
    DEBUG_STREAM << "L4CONTROLS=" << getenv("L4CONTROLS") << std::endl << std::flush;
 
 #ifdef RP412_STEAM

RP_L4/RPL4CONSOLE.cpp

@@ -352,6 +352,55 @@ namespace
 		gPhase = PhaseStopped;
 	}
 
+	//---------------------------------------------------------------
+	// The countdown the engine shows, taken from the clock that will
+	// actually end the race (gMissionClockHook - see APPMGR.h).
+	//
+	// Called on the game thread, reading two volatile LONGs the console
+	// thread writes with InterlockedExchange. Aligned 32-bit reads, and
+	// a torn value could only mistime the cockpit clock by one tick of
+	// a countdown nobody reads to the millisecond - not worth a lock on
+	// the frame path.
+	//---------------------------------------------------------------
+	Logical MissionClock(Scalar *seconds_remaining)
+	{
+		//
+		// Only answer for the race this console is actually marshalling.
+		// Nothing ever uninstalls the hook, so a player who hosts a race
+		// and then joins somebody else's lobby still has it wired up -
+		// and in that race the console is a bystander whose gLengthMs and
+		// gRunStartTick belong to the previous mission entirely.
+		//
+		if (gWatchedApp == NULL || gWatchedApp != application)
+		{
+			return False;
+		}
+		if (!gMissionRunning)
+		{
+			return False;		// not started, or already stopped
+		}
+		LONG length_ms = gLengthMs;
+		if (length_ms <= 0)
+		{
+			return False;		// endless: nothing to count down
+		}
+
+		// DWORD subtraction, so a GetTickCount wrap costs nothing
+		LONG elapsed_ms = (LONG)(GetTickCount() - (DWORD) gRunStartTick);
+		LONG left_ms = length_ms - elapsed_ms;
+		if (left_ms < 0)
+		{
+			//
+			// The console polls at 250 ms, so the clock reaches zero
+			// slightly before the stop is dispatched. Hold at zero
+			// rather than showing negative time in the cockpit.
+			//
+			left_ms = 0;
+		}
+		*seconds_remaining = (Scalar) left_ms / 1000.0f;
+		return True;
+	}
+
 	//---------------------------------------------------------------
 	// The game-thread tick: state reporting + engine-safe execution
 	//---------------------------------------------------------------
@@ -522,6 +571,10 @@ namespace
 		// game-thread execution point
 		gPerFrameHook = &ConsoleTick;
 
+		// the cockpit clock now counts down the same clock that will stop
+		// the race, rather than the engine's own reckoning of it
+		gMissionClockHook = &MissionClock;
+
 		// results intake from the RP layer
 		gConsoleScoreSink = &CollectFinalScore;
 

RP_L4/RPL4ENVIRON.cpp

@@ -0,0 +1,516 @@
+#include "rpl4.h"
+#pragma hdrstop
+
+#include "rpl4environ.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+//########################################################################
+// environ.ini - see rpl4environ.h for why the exe owns this rather than
+// the packaging script.
+//########################################################################
+
+namespace
+{
+	const char kEnvironFileName[] = "environ.ini";
+
+	//-------------------------------------------------------------------
+	// The shipped configuration, verbatim. Lifted out of pack-dist.ps1
+	// so there is one source of truth and the exe alone can produce a
+	// working install.
+	//-------------------------------------------------------------------
+	const char kEnvironTemplate[] =
+"# ============================================================================\n"
+"#  environ.ini - Red Planet 4.12 configuration\n"
+"# ============================================================================\n"
+"#  One KEY=VALUE per line, read at game start. Lines starting with # or ;\n"
+"#  are comments; anything without an = is ignored. Delete a line (or\n"
+"#  comment it out) to fall back to the built-in default.\n"
+"#\n"
+"#  Input bindings live in bindings.txt beside the exe (written with the\n"
+"#  full documented layout on first run; delete it to restore defaults).\n"
+"#\n"
+"#  Your callsign and loadout are remembered in pilot.cfg beside the exe.\n"
+"#  Set them on the setup screen once and they come back every session,\n"
+"#  however you left - launching, joining a lobby, or quitting. Delete\n"
+"#  that file to start over.\n"
+"\n"
+"# ---- Core (the shipped configuration) --------------------------------------\n"
+"\n"
+"# Control stack: tokens separated by ; or , processed left to right.\n"
+"#   PAD            the virtual RIO (XInput controller + keyboard,\n"
+"#                  rebindable via bindings.txt)\n"
+"#   RIO            real serial cockpit hardware on COM1\n"
+"#   RIO:COMn       same, on another port (RIO:COM3, ...)\n"
+"#   KEYBOARD       the engine keyboard handler\n"
+"#   MOUSE, JOYSTICK, FLIGHTSTICKPRO, THRUSTMASTER, DIJOYSTICK\n"
+"#                  legacy pointer/joystick drivers (untested here)\n"
+"# Unset falls back to KEYBOARD alone.\n"
+"L4CONTROLS=PAD;KEYBOARD\n"
+"\n"
+"# Renderer bring-up argument. Only its presence is checked (the DPL\n"
+"# resolution parsing it once fed is gone) and the game refuses to start\n"
+"# without it - any non-empty value works. Leave as shipped.\n"
+"DPLARG=1\n"
+"\n"
+"# DPL (renderer/scene) configuration file, searched beside the exe.\n"
+"# Any notation file name; RPDPL.INI is the one that ships.\n"
+"L4DPLCFG=RPDPL.INI\n"
+"\n"
+"# Gauge (MFD/instrument) canvas. Must name a page of GAUGE\\L4GAUGE.INI:\n"
+"#   640x480x8 | 640x480x16 | 800x600x16\n"
+"# Unset disables the gauge renderer (and with it all MFDs).\n"
+"L4GAUGE=640x480x16\n"
+"\n"
+"# Plasma display.\n"
+"#   SCREEN         render the pod's plasma glass in-window (currently\n"
+"#                  parked off-layout)\n"
+"#   COM1, COM2...  drive real plasma glass on that serial port\n"
+"#                  (9600 baud, N81)\n"
+"# Unset = no plasma display.\n"
+"L4PLASMA=SCREEN\n"
+"\n"
+"# 0 = classic separate gauge windows; 1 = the single-window glass\n"
+"# cockpit (all seven displays composed on a locked 1920x1080 canvas\n"
+"# around the viewscreen); 2 = exploded diagnostic view (each display\n"
+"# in its own native-resolution desktop window - MFDs 640x480, map\n"
+"# 480x640 - decoded exactly as the pod's VDB split them, no downscale).\n"
+"L4MFDSPLIT=1\n"
+"\n"
+"# The game window - and in the exploded view (L4MFDSPLIT=2) each display\n"
+"# window - is placed fresh every launch, so moving one somewhere useful\n"
+"# never survived the menu-race-menu loop. This remembers where you put\n"
+"# them, in mfd_layout.cfg beside this file:\n"
+"#   off / 0 / unset   computed placement only, no file (default)\n"
+"#   load              put the windows back where they were saved\n"
+"#   save              the same, and re-save on every finished drag\n"
+"# The game window gets its size back too, so you can size the cockpit to\n"
+"# suit your monitor once and keep it. The display windows get position\n"
+"# only: their size follows their content and their button banks, so an\n"
+"# old one is never restored over them. Arrange everything once with\n"
+"# save, then leave it on load.\n"
+"#\n"
+"# The plasma display window takes part too, under \"Plasma Display\".\n"
+"#\n"
+"# Each line in mfd_layout.cfg reads <title>=<x>,<y>,<w>,<h>, and you can\n"
+"# append ,noframe to take that window's title bar and border off - a\n"
+"# cockpit that fills the monitor edge to edge without -fit taking the\n"
+"# whole screen. Put the window where you want it first: a bare window\n"
+"# has nothing to drag by. Delete the flag to get the frame back.\n"
+"#RP412MFDLAYOUT=off\n"
+"\n"
+"# Size of the six secondary displays in the glass cockpit, as a\n"
+"# percentage of their pod size. The pod bolted them down at one size;\n"
+"# on a big panel there is room to trade viewscreen for instrument, so\n"
+"# turn these up if you want to actually read the other displays while\n"
+"# you fly. 100 = as the pod had them. Range 25-200 (out-of-range and\n"
+"# unreadable values fall back to the group setting, then to 100).\n"
+"#\n"
+"# The scaling is applied in canvas units, before the cockpit is fitted\n"
+"# to your window, so a given number looks the same on every monitor.\n"
+"# The layout stays legal whatever you ask for - the panes are clamped\n"
+"# against their actual neighbours, shrinking uniformly so a display\n"
+"# never comes out stretched. They do overlap the viewscreen, exactly\n"
+"# as the pod's bezels did, but never each other.\n"
+"#\n"
+"# L4MFDSCALE sets all five green MFDs at once.\n"
+"L4MFDSCALE=100\n"
+"\n"
+"# ...and any single display can override it. Uncomment one to size it\n"
+"# on its own - useful if you only care about, say, the damage readout.\n"
+"#   UL upper left     UC upper center    UR upper right\n"
+"#   LL lower left     LR lower right\n"
+"#L4MFDSCALE_UL=100\n"
+"#L4MFDSCALE_UC=100\n"
+"#L4MFDSCALE_UR=100\n"
+"#L4MFDSCALE_LL=100\n"
+"#L4MFDSCALE_LR=100\n"
+"\n"
+"# The portrait radar/map, sized on its own (it already sits at 1.35x\n"
+"# the MFDs by default). It shares the canvas with whichever MFD is\n"
+"# above it, so at extreme settings one of the two gives way.\n"
+"L4RADARSCALE=100\n"
+"\n"
+"# Where the radar sits:\n"
+"#   CENTER    bottom centre, under the viewscreen, as the pod had it\n"
+"#             (default; BOTTOM and CENTRE mean the same)\n"
+"#   LEFT      bottom left corner      (or BOTTOMLEFT)\n"
+"#   RIGHT     bottom right corner     (or BOTTOMRIGHT)\n"
+"#   MIDLEFT   left edge, halfway up   (or LEFTCENTER / LEFTCENTRE)\n"
+"#   MIDRIGHT  right edge, halfway up  (or RIGHTCENTER / RIGHTCENTRE)\n"
+"# Anywhere but CENTER stops it blocking the middle of the road, which\n"
+"# is worth having on a wide screen.\n"
+"#\n"
+"# In a bottom corner it is one of three panes along the bottom, and the\n"
+"# lower MFD whose corner it takes slides inboard beside it. Halfway up\n"
+"# a side it leaves the bottom row entirely and sits between that side's\n"
+"# two MFDs - roomy on a tall radar, but if the MFDs on that side are\n"
+"# also scaled up, the radar is the one that gives way (it has to clear\n"
+"# both of them, and it grows from the middle in both directions).\n"
+"L4RADARPOS=CENTER\n"
+"\n"
+"# The Winners Circle: at the end of a race the finishers are stood on\n"
+"# the award platform in finishing order, with each pilot's callsign on\n"
+"# the plate beside their spot, and held there for a few seconds before\n"
+"# the results screen. 1 = show it, 0 = straight to the results.\n"
+"RP412PODIUM=1\n"
+"\n"
+"# The shot is framed for you, but these move the camera if you want it\n"
+"# somewhere else. Distances are in game units, measured from the middle\n"
+"# of the group of finishers.\n"
+"#   STANDOFF  how far out in front of the stand the camera sits\n"
+"#   HEIGHT    how far above the group\n"
+"#   AIM       height of the point it looks at, relative to the group -\n"
+"#             negative tilts down, positive tilts up\n"
+"#   ASPECT    the stand was composed for a 4:3 pod monitor, so the shot\n"
+"#             is cropped to that shape with black either side. 0 runs it\n"
+"#             full width instead.\n"
+"#   FADEIN    seconds to come up out of the black after the race fades\n"
+"#   CAM       0 watches from your own cockpit rather than off the stand\n"
+"#RP412PODIUMSTANDOFF=36\n"
+"#RP412PODIUMHEIGHT=12\n"
+"#RP412PODIUMAIM=2\n"
+"#RP412PODIUMASPECT=1.333\n"
+"#RP412PODIUMFADEIN=0.45\n"
+"#RP412PODIUMCAM=1\n"
+"\n"
+"# Override the game length the menu picked, in seconds. The shortest the\n"
+"# menu offers is 3:00, which is a long wait when what you are testing is\n"
+"# what happens at the buzzer. Unset = use the menu's choice.\n"
+"#RP412MISSIONSECONDS=20\n"
+"\n"
+"# Simulation/render frame rate, integer frames/second. The desktop\n"
+"# default is 60; the arcade pods shipped at 25.\n"
+"TARGETFPS=60\n"
+"\n"
+"# 1 = Steam networking (lobbies, FakeIP mesh). Needs the Steam client\n"
+"# running and steam_appid.txt beside the exe; without them the game\n"
+"# logs the reason and falls back to plain TCP. 0 = TCP only.\n"
+"RP412STEAM=1\n"
+"\n"
+"# Line up each remote player's clock with ours, so their vehicle is\n"
+"# extrapolated from when its update was SENT rather than when it\n"
+"# arrived. Without it every remote pod sits one network latency behind\n"
+"# where it should be - invisible on the 1ms arcade LAN the engine was\n"
+"# written for, a constant 50-150ms of lag over the internet. 0 restores\n"
+"# the old arrival-time behaviour if you want to compare.\n"
+"#RP412NETCLOCK=0\n"
+"\n"
+"# ---- Optional ---------------------------------------------------------------\n"
+"\n"
+"# RGB keyboard lamp mirror (Windows Dynamic Lighting): keys bound to\n"
+"# lamp buttons glow with the panel, flash modes and all.\n"
+"# Unset or nonzero = on (the default); 0 = off.\n"
+"#RP412KEYLIGHT=0\n"
+"\n"
+"# Invert the stick on top of whatever bindings.txt produces:\n"
+"# X = invert X only, Y = invert Y only, XY = both (case-insensitive).\n"
+"#L4PADFLIP=XY\n"
+"\n"
+"# Anti-aliasing sample count, passed straight to Direct3D 9:\n"
+"# 0 = off, else 2..16 as the GPU supports (1 selects the driver's\n"
+"# \"nonmaskable\" mode; unsupported counts fail device creation).\n"
+"#MULTISAMPLE=0\n"
+"\n"
+"# Particle budget, integer. Default 8192.\n"
+"#MAXPARTICLES=8192\n"
+"\n"
+"# On-screen plasma glass (L4PLASMA=SCREEN only). SCALE = integer pixel\n"
+"# size 1..16, default 4 (out-of-range values are ignored). POS = window\n"
+"# top-left as X,Y screen coordinates; unset = auto, parked below the\n"
+"# main window.\n"
+"#L4PLASMASCALE=4\n"
+"#L4PLASMAPOS=0,0\n"
+"\n"
+"# Fixed random seed (repeatable runs): any unsigned integer.\n"
+"# Unset seeds from the clock.\n"
+"#RANDOM=12345\n"
+"\n"
+"# ---- LAN play without Steam -------------------------------------------------\n"
+"# Host a race over plain TCP: list the member pods' console channels\n"
+"# (members run: rpl4opt.exe -windowed -res 1920 1080 -net 1501).\n"
+"#   RP412HOSTPODS  comma-separated IP[:port] list, one entry per member\n"
+"#                  pod; port defaults to 1501 per entry\n"
+"#   RP412HOSTPORT  this machine's console port, integer > 0\n"
+"#                  (default 1501)\n"
+"#   RP412HOSTADDR  this machine's LAN IP as members can reach it\n"
+"#                  (default 127.0.0.1)\n"
+"#RP412HOSTPODS=192.168.1.20:1501,192.168.1.21:1501\n"
+"#RP412HOSTPORT=1501\n"
+"#RP412HOSTADDR=192.168.1.10\n"
+"\n"
+"# ---- Developer / testing ----------------------------------------------------\n"
+"\n"
+"# Nonzero arms the debug keys: Alt+W wireframe, Alt+V predator vision,\n"
+"# Alt+F frame dump, Alt+/ perf stats, Alt+E event-queue dump.\n"
+"# 0 or unset = off. (Alt+Q, the mission abort, is always live.)\n"
+"#RP412DEVKEYS=1\n"
+"\n"
+"# Console race-length override, integer seconds (short test races).\n"
+"# Values <= 0 are ignored.\n"
+"#L4CONSOLELEN=30\n"
+"\n"
+"# Nonzero = Steam transport loopback self-test at boot (logs PASS/FAIL).\n"
+"#RP412STEAMSELFTEST=1\n"
+"\n"
+"# ---- Arcade heritage (multi-monitor pods; not used on the desktop) ----------\n"
+"# PRIMGAUGE / SECGAUGE / MFDGAUGE / MFDGAUGE2 pin a display to a monitor\n"
+"# by adapter index (0, 1, 2...). SPANDISABLE: 0 = let the MFDs span one\n"
+"# wide surface, nonzero = separate windows (setting MFDGAUGE2 alone also\n"
+"# forces spanning off). L4EYES = \"x y z xrot yrot zrot [type]\" floats\n"
+"# for a detached camera; a type starting with r offsets it relative to\n"
+"# the pod. L4INTERCOM enables the crew intercom - only its presence\n"
+"# matters (traditionally COM2). NOMODES skips the mode/lamp programming;\n"
+"# presence alone triggers it, even NOMODES=0. LOGSIZE > 0 sizes the\n"
+"# trace log in dev builds compiled with tracing.\n"
+"#PRIMGAUGE=1\n"
+"#SECGAUGE=2\n"
+"#MFDGAUGE=3\n"
+"#MFDGAUGE2=4\n"
+"#SPANDISABLE=1\n"
+"#L4EYES=1\n"
+"#L4INTERCOM=COM2\n"
+"#NOMODES=1\n"
+"#LOGSIZE=1000000\n"
+		;
+
+	//-------------------------------------------------------------------
+	// Does the player's file mention this key at all - set, or commented
+	// out, or with whitespace in front of it?
+	//
+	// Deliberately generous: a key that is mentioned in ANY form is left
+	// alone. The alternative failure is worse than a missed notice, since
+	// environ.ini is applied line by line and a second copy of a key
+	// further down the file would silently override the player's own.
+	//-------------------------------------------------------------------
+	Logical FileMentionsKey(const char *text, const char *key, int key_length)
+	{
+		const char *cursor = text;
+		while ((cursor = strstr(cursor, key)) != NULL)
+		{
+			//
+			// Must be a whole key: preceded by start-of-line, whitespace
+			// or a comment mark, and followed by '='.
+			//
+			const char *after = cursor + key_length;
+			Logical starts_token =
+				(cursor == text) ||
+				(cursor[-1] == '\n') || (cursor[-1] == '\r') ||
+				(cursor[-1] == ' ')  || (cursor[-1] == '\t') ||
+				(cursor[-1] == '#')  || (cursor[-1] == ';');
+			if (starts_token)
+			{
+				const char *scan = after;
+				while (*scan == ' ' || *scan == '\t')
+				{
+					++scan;
+				}
+				if (*scan == '=')
+				{
+					return True;
+				}
+			}
+			cursor = after;
+		}
+		return False;
+	}
+
+	//-------------------------------------------------------------------
+	// Name every template key the player's file has never heard of. Not
+	// a fix - their file stays theirs - but it puts the reason for a
+	// missing feature in the log we already ask testers for.
+	//-------------------------------------------------------------------
+	void ReportUnmentionedKeys(const char *file_text)
+	{
+		char missing[1024];		// what gets printed
+		char seen[1024];		// the same keys as "KEY=", so the mention
+								// test above can dedupe against them
+		missing[0] = '\0';
+		seen[0] = '\0';
+		int count = 0;			// how many are missing
+		int listed = 0;			// how many fitted in the line
+
+		const char *cursor = kEnvironTemplate;
+		while (*cursor != '\0')
+		{
+			const char *line = cursor;
+			const char *end = strchr(line, '\n');
+			int length = (end != NULL) ? (int)(end - line) : (int) strlen(line);
+			cursor = (end != NULL) ? (end + 1) : (line + length);
+
+			//
+			// A template key line is "KEY=..." or "#KEY=..." - the
+			// commented ones are options that ship switched off, and a
+			// player who has never seen them wants to know they exist.
+			//
+			const char *scan = line;
+			int remaining = length;
+			if (remaining > 0 && *scan == '#')
+			{
+				++scan;
+				--remaining;
+			}
+			if (remaining <= 0 || !(isalpha((unsigned char) *scan) || *scan == '_'))
+			{
+				continue;
+			}
+			int key_length = 0;
+			while (key_length < remaining &&
+				(isalnum((unsigned char) scan[key_length]) || scan[key_length] == '_'))
+			{
+				++key_length;
+			}
+			if (key_length >= remaining || scan[key_length] != '=' || key_length > 60)
+			{
+				continue;
+			}
+
+			char key[64];
+			memcpy(key, scan, key_length);
+			key[key_length] = '\0';
+
+			if (FileMentionsKey(file_text, key, key_length))
+			{
+				continue;
+			}
+			//
+			// Templates list some keys twice (documented once, shown
+			// again in an example); do not name one twice.
+			//
+			if (FileMentionsKey(seen, key, key_length))
+			{
+				continue;
+			}
+			++count;
+			if (strlen(seen) + key_length + 3 < sizeof(seen))
+			{
+				strcat(seen, key);
+				strcat(seen, "=\n");
+			}
+			if (strlen(missing) + key_length + 3 < sizeof(missing))
+			{
+				if (missing[0] != '\0')
+				{
+					strcat(missing, ", ");
+				}
+				strcat(missing, key);
+				++listed;
+			}
+		}
+
+		if (count > 0)
+		{
+			//
+			// Say when the list is short of the count rather than letting
+			// a full buffer quietly shorten the answer.
+			//
+			DEBUG_STREAM << "Environ: " << kEnvironFileName << " does not mention "
+				<< count << " option(s) this build knows: " << missing;
+			if (listed < count)
+			{
+				DEBUG_STREAM << ", and " << (count - listed) << " more";
+			}
+			DEBUG_STREAM << "\nEnviron: they are at their built-in defaults - delete "
+				<< kEnvironFileName << " to get the documented file back\n"
+				<< std::flush;
+		}
+	}
+}
+
+void
+	RPL4Environ_Load()
+{
+	//
+	// First run: lay down the documented default. From here on the file
+	// belongs to whoever is sitting at this machine.
+	//
+	FILE *file = fopen(kEnvironFileName, "rb");
+	if (file == NULL)
+	{
+		FILE *out = fopen(kEnvironFileName, "wb");
+		if (out != NULL)
+		{
+			fwrite(kEnvironTemplate, 1, strlen(kEnvironTemplate), out);
+			fclose(out);
+			DEBUG_STREAM << "Environ: wrote default " << kEnvironFileName
+				<< "\n" << std::flush;
+		}
+		else
+		{
+			DEBUG_STREAM << "Environ: could not write " << kEnvironFileName
+				<< " - running on built-in defaults\n" << std::flush;
+		}
+		file = fopen(kEnvironFileName, "rb");
+	}
+	if (file == NULL)
+	{
+		return;
+	}
+
+	fseek(file, 0, SEEK_END);
+	long size = ftell(file);
+	fseek(file, 0, SEEK_SET);
+	if (size <= 0)
+	{
+		fclose(file);
+		return;
+	}
+	char *text = new char[size + 1];
+	size_t read = fread(text, 1, size, file);
+	text[read] = '\0';
+	fclose(file);
+
+	//
+	// One KEY=VALUE per line. Comments, blanks and anything without an
+	// '=' are skipped; everything else goes into the environment, which
+	// is why a line here beats a variable set in the shell.
+	//
+	int applied = 0;
+	char line[1024];
+	const char *cursor = text;
+	while (*cursor != '\0')
+	{
+		int length = 0;
+		while (cursor[length] != '\0' && cursor[length] != '\n' &&
+			length < (int) sizeof(line) - 1)
+		{
+			line[length] = cursor[length];
+			++length;
+		}
+		line[length] = '\0';
+		cursor += length;
+		while (*cursor == '\n' || *cursor == '\r')
+		{
+			++cursor;
+		}
+		for (int i = length - 1; i >= 0; --i)
+		{
+			if (line[i] == '\r' || line[i] == '\n')
+			{
+				line[i] = '\0';
+			}
+		}
+
+		char *setting = line;
+		while (*setting == ' ' || *setting == '\t')
+		{
+			++setting;
+		}
+		if (*setting == '\0' || *setting == '#' || *setting == ';' ||
+			strchr(setting, '=') == NULL)
+		{
+			continue;
+		}
+		putenv(setting);
+		++applied;
+	}
+
+	DEBUG_STREAM << "Environ: " << applied << " setting(s) from "
+		<< kEnvironFileName << "\n" << std::flush;
+
+	ReportUnmentionedKeys(text);
+
+	delete[] text;
+}

RP_L4/RPL4ENVIRON.h

@@ -0,0 +1,44 @@
+//===========================================================================//
+// File:    rpl4environ.h                                                    //
+// Project: MUNGA           Brick: Red Planet LBE Application                //
+// Contents: environ.ini - written on first run, then the player's           //
+//---------------------------------------------------------------------------//
+// Copyright (C) 1994-1995, Virtual World Entertainment, Inc.                //
+//                      PROPRIETARY AND CONFIDENTIAL                         //
+//===========================================================================//
+
+#pragma once
+
+#include "..\munga\style.h"
+
+//########################################################################
+//
+// environ.ini is the game's configuration: one KEY=VALUE per line, read
+// once at startup and pushed into the environment, so every option the
+// engine reads through getenv can be set from a file a player can open.
+//
+// The exe owns the template and writes it when the file is absent, the
+// same way bindings.txt works, rather than the packaging script laying
+// one down on every unzip. That is what lets a tester drop a new build
+// over an old folder and keep their settings: the file is theirs from
+// the moment it exists, and nothing overwrites it.
+//
+// It cannot simply be optional. Without it L4GAUGE is unset, which
+// disables the gauge renderer and takes every MFD with it, and
+// L4MFDSPLIT is unset, which is the packed-window arcade layout rather
+// than the glass cockpit. The shipped values are the desktop game; the
+// built-in getenv fallbacks are the 1995 pod.
+//
+// The cost of a file that is never overwritten is that a tester carrying
+// one across many builds stops being offered new options. Options added
+// later default to "behave as before", so nothing breaks - but it does
+// go unnoticed, so the load names any template key the player's file
+// does not mention. That line in rpl4.log is what turns "the podium does
+// not work" into "your environ.ini predates RP412PODIUM".
+//
+//########################################################################
+
+// Write environ.ini if it is not there, then read it into the
+// environment. Call once, before anything reads a setting.
+void
+	RPL4Environ_Load();

RP_L4/RPL4FE.cpp

@@ -231,6 +231,241 @@ namespace
 	Logical	gHavePersist = False;
 	char	gLastPilotName[24] = "Pilot";
 
+	//---------------------------------------------------------------
+	// What the player set last time, in pilot.cfg beside bindings.txt:
+	// the callsign they typed and the loadout they picked.
+	//
+	// The loadout has always survived a race - gPersistSelection below
+	// is why the menu reopens the way you left it - but only for as
+	// long as the process lives. BT411 keeps the same things in
+	// fe_last.ini and had to, since it relaunches between missions;
+	// RP412 stayed in one process and so never needed a file. Closing
+	// the game was still a reset, which is what this fixes.
+	//
+	// KEY=VALUE like environ.ini, one line per group.
+	//---------------------------------------------------------------
+	const char kPilotFileName[] = "pilot.cfg";
+
+	//
+	// Stable file keys, independent of the on-screen headings - those
+	// carry spaces ("TIME OF DAY") and are free to be reworded.
+	//
+	struct GroupKey
+	{
+		int			group;
+		const char	*key;
+	};
+	const GroupKey kGroupKeys[] =
+	{
+		{ GroupScenario, "scenario" }, { GroupMap,      "track"    },
+		{ GroupVehicle,  "vehicle"  }, { GroupColor,    "color"    },
+		{ GroupBadge,    "badge"    }, { GroupTeam,     "team"     },
+		{ GroupPosition, "position" }, { GroupTime,     "time"     },
+		{ GroupWeather,  "weather"  }, { GroupLength,   "length"   },
+	};
+
+	//
+	// How many rows a group offers, so a stale or hand-edited index
+	// cannot select past the end of a list. The track list is the one
+	// that moves - football and the death race carry different maps -
+	// so it answers for whichever scenario is selected.
+	//
+	int GroupSize(int group, const int *selection)
+	{
+		switch (group)
+		{
+		case GroupScenario:	return FE_COUNT(kScenarios);
+		case GroupMap:
+			{
+				int count = 0;
+				ActiveMaps(selection, &count);
+				return count;
+			}
+		case GroupVehicle:	return FE_COUNT(kVehicles);
+		case GroupColor:	return FE_COUNT(kColors);
+		case GroupBadge:	return FE_COUNT(kBadges);
+		case GroupTeam:		return FE_COUNT(kTeams);
+		case GroupPosition:	return FE_COUNT(kPositions);
+		case GroupTime:		return FE_COUNT(kTimes);
+		case GroupWeather:	return FE_COUNT(kWeather);
+		case GroupLength:	return FE_COUNT(kLengths);
+		}
+		return 0;
+	}
+
+	//
+	// A callsign is quoted into frontend.egg, joined into a
+	// comma-separated list for the results screen, and published as
+	// Steam lobby member data. Anything that could end a token early
+	// therefore has to go - a comma alone would split one pilot into
+	// two on the score sheet. Applied to what is typed as well as to
+	// what is read back, so the file cannot hold what the game will
+	// not accept.
+	//
+	void SanitizeCallsign(char *name, int size)
+	{
+		char clean[64];
+		int out = 0;
+		for (int i = 0; name[i] != '\0' && out < (int) sizeof(clean) - 1; ++i)
+		{
+			unsigned char c = (unsigned char) name[i];
+			if (c < 32 || c > 126)		continue;	// controls, high bytes
+			if (c == ',' || c == '"')	continue;	// egg and CSV delimiters
+			if (c == '#' || c == ';')	continue;	// pilot.cfg comment marks
+			clean[out++] = (char) c;
+		}
+		clean[out] = '\0';
+
+		char *start = clean;
+		while (*start == ' ' || *start == '\t')
+		{
+			++start;
+		}
+		int end = (int) strlen(start);
+		while (end > 0 && (start[end - 1] == ' ' || start[end - 1] == '\t'))
+		{
+			start[--end] = '\0';
+		}
+
+		if (start[0] == '\0')
+		{
+			strcpy(start, "Pilot");
+		}
+		strncpy(name, start, size - 1);
+		name[size - 1] = '\0';
+	}
+
+	void SavePilotSettings(const char *name, const int *selection)
+	{
+		FILE *file = fopen(kPilotFileName, "wt");
+		if (file == NULL)
+		{
+			DEBUG_STREAM << "FrontEnd: could not write " << kPilotFileName
+				<< "\n" << std::flush;
+			return;
+		}
+		fputs("# RP412 pilot settings, written by the game on the way out of\n"
+			  "# the setup screen. Delete this file to start over.\n", file);
+		fprintf(file, "callsign=%s\n", name);
+		if (selection != NULL)
+		{
+			for (int i = 0; i < FE_COUNT(kGroupKeys); ++i)
+			{
+				fprintf(file, "%s=%d\n", kGroupKeys[i].key,
+					selection[kGroupKeys[i].group]);
+			}
+		}
+		fclose(file);
+		DEBUG_STREAM << "FrontEnd: saved callsign \"" << name << "\""
+			<< ((selection != NULL) ? " and loadout" : "")
+			<< " to " << kPilotFileName << "\n" << std::flush;
+	}
+
+	//
+	// Read once per run. Absent or unreadable simply leaves the
+	// built-in defaults in place - a missing file is a first run, not
+	// an error, and every value is range-checked so a hand-edited or
+	// out-of-date file cannot select past the end of a list.
+	//
+	void EnsurePilotSettingsLoaded()
+	{
+		static Logical loaded = False;
+		if (loaded)
+		{
+			return;
+		}
+		loaded = True;
+
+		FILE *file = fopen(kPilotFileName, "rt");
+		if (file == NULL)
+		{
+			return;
+		}
+
+		int selection[GroupCount];
+		memset(selection, 0, sizeof(selection));
+		selection[GroupLength] = 2;			// 5:00, as the menu defaults
+		Logical have_loadout = False;
+
+		char line[256];
+		while (fgets(line, sizeof(line), file) != NULL)
+		{
+			char *cursor = line;
+			while (*cursor == ' ' || *cursor == '\t')
+			{
+				++cursor;
+			}
+			if (*cursor == '#' || *cursor == ';')
+			{
+				continue;
+			}
+			char *equals = strchr(cursor, '=');
+			if (equals == NULL)
+			{
+				continue;
+			}
+			*equals = '\0';
+			char *key = cursor;
+			char *value = equals + 1;
+			while (*value == ' ' || *value == '\t')
+			{
+				++value;
+			}
+			char *newline = strpbrk(value, "\r\n");
+			if (newline != NULL)
+			{
+				*newline = '\0';
+			}
+
+			if (_stricmp(key, "callsign") == 0)
+			{
+				char candidate[24];
+				strncpy(candidate, value, sizeof(candidate) - 1);
+				candidate[sizeof(candidate) - 1] = '\0';
+				SanitizeCallsign(candidate, sizeof(candidate));
+				strcpy(gLastPilotName, candidate);
+				continue;
+			}
+			for (int i = 0; i < FE_COUNT(kGroupKeys); ++i)
+			{
+				if (_stricmp(key, kGroupKeys[i].key) != 0)
+				{
+					continue;
+				}
+				int index = atoi(value);
+				if (index >= 0 && index < GroupSize(kGroupKeys[i].group, selection))
+				{
+					selection[kGroupKeys[i].group] = index;
+					have_loadout = True;
+				}
+				break;
+			}
+		}
+		fclose(file);
+
+		//
+		// The track list belongs to the scenario, and the file is read in
+		// whatever order it was written, so re-check the track once the
+		// scenario is settled - the same clamp the menu applies when the
+		// scenario is switched by hand.
+		//
+		if (have_loadout)
+		{
+			int map_count = 0;
+			ActiveMaps(selection, &map_count);
+			if (selection[GroupMap] >= map_count)
+			{
+				selection[GroupMap] = 0;
+			}
+			memcpy(gPersistSelection, selection, sizeof(gPersistSelection));
+			gHavePersist = True;
+		}
+
+		DEBUG_STREAM << "FrontEnd: callsign \"" << gLastPilotName << "\""
+			<< (have_loadout ? " and loadout" : "")
+			<< " from " << kPilotFileName << "\n" << std::flush;
+	}
+
 	// [pilots]-order names of the last launched race (owner first),
 	// comma separated - the network console labels results with them
 	char	gLastPilotNamesCsv[256] = "";
@@ -1219,6 +1454,10 @@ Logical
 {
 	gLastLaunchMode = FELaunchSingle;
 
+	// before the lobby branch below: a member rejoining a room publishes
+	// the callsign as member data without the menu ever opening
+	EnsurePilotSettingsLoaded();
+
 	//---------------------------------------------------------------
 	// Coming back from a race while still in a lobby: straight to
 	// the room (the lobby outlives races - single binary payoff)
@@ -1248,6 +1487,7 @@ Logical
 	{
 		FEState fe;
 		memset(&fe, 0, sizeof(fe));
+		EnsurePilotSettingsLoaded();
 		strcpy(fe.pilotName, gLastPilotName);
 		if (gHavePersist)
 		{
@@ -1346,20 +1586,41 @@ Logical
 		}
 
 		//---------------------------------------------------------------
-		// Harvest the loadout whichever way we leave the menu - the
-		// lobby publishes it as member data, launches build from it
+		// Harvest the callsign whichever way we leave the menu, INCLUDING
+		// a close: typing a name and then quitting is how somebody sets it
+		// for next time, and losing it there would be the one case that
+		// makes the whole thing feel unreliable. The loadout still only
+		// persists on a real exit - it is picked, not typed, and the menu
+		// reopens with it visible anyway.
 		//---------------------------------------------------------------
-		if (!fe.closed)
+		if (fe.nameEdit != NULL)
 		{
+			fe.pilotName[0] = '\0';
 			GetWindowTextA(fe.nameEdit, fe.pilotName, sizeof(fe.pilotName) - 1);
-			if (fe.pilotName[0] == '\0')
-			{
-				strcpy(fe.pilotName, "Pilot");
-			}
-			strcpy(gLastPilotName, fe.pilotName);
-			memcpy(gPersistSelection, fe.selection, sizeof(gPersistSelection));
-			gHavePersist = True;
+			SanitizeCallsign(fe.pilotName, sizeof(fe.pilotName));
 		}
+		else
+		{
+			strcpy(fe.pilotName, gLastPilotName);
+		}
+
+		strcpy(gLastPilotName, fe.pilotName);
+		memcpy(gPersistSelection, fe.selection, sizeof(gPersistSelection));
+		gHavePersist = True;
+
+		//
+		// Written on the way out however the player leaves - launching,
+		// stepping into a lobby, or quitting. BT411 saves only on a
+		// launch, which loses a callsign typed by somebody who then
+		// changed their mind, and that is the one moment this feature
+		// exists for.
+		//
+		// Unconditionally, rather than only when something changed: the
+		// file is a few hundred bytes, and writing it every time means a
+		// value that was hand-edited out of range comes back corrected
+		// instead of being quietly re-rejected on every launch forever.
+		//
+		SavePilotSettings(gLastPilotName, gPersistSelection);
 
 		Logical launched = fe.launched;
 		Logical closed = fe.closed;
@@ -1825,6 +2086,10 @@ Logical
 		return False;
 	}
 
+	// this screen labels a row with the pilot's own callsign, and in the
+	// -egg and lobby paths it can be the first screen of the session
+	EnsurePilotSettingsLoaded();
+
 	ResultsState rs;
 	memset(&rs, 0, sizeof(rs));
 

RP_L4/RPL4PB.cpp

@@ -357,8 +357,20 @@ Logical
 	//
 	if (GetApplicationState() == RunningMission)
 	{
-		secondsRemainingInGame =
-			currentMission->GetGameLength() - (Now() - gameStarted);
+		// same rule as Application::ExecuteForeground - the console's
+		// countdown when there is one, our own reckoning otherwise. There
+		// is no console in mission review, so this takes the fallback.
+		Scalar console_remaining;
+		if (gMissionClockHook != NULL &&
+			(*gMissionClockHook)(&console_remaining))
+		{
+			secondsRemainingInGame = console_remaining;
+		}
+		else
+		{
+			secondsRemainingInGame =
+				currentMission->GetGameLength() - (Now() - gameStarted);
+		}
 	}
 
 	CLEAR_FOREGROUND_PROCESSING();

RP_L4/RP_L4.vcxproj

@@ -70,6 +70,15 @@
       <RandomizedBaseAddress>false</RandomizedBaseAddress>
       <GenerateDebugInformation>true</GenerateDebugInformation>
     </Link>
+    <!-- rpl4build.h is generated, not committed: the patch number is the
+         repository's commit count, so a hardcoded one would be stale the
+         moment it was committed. The script rewrites the header only when
+         the stamp actually changes, so this does not drag RPL4.CPP through
+         a recompile on every build. -->
+    <PreBuildEvent>
+      <Command>powershell -NoProfile -ExecutionPolicy Bypass -File "$(ProjectDir)..\stamp-version.ps1"</Command>
+      <Message>Stamping the build version from git</Message>
+    </PreBuildEvent>
   </ItemDefinitionGroup>
   <ItemDefinitionGroup Condition="'$(Configuration)'=='Debug'">
     <ClCompile>
@@ -109,6 +118,7 @@
     <ClCompile Include=".\RPL4APP.cpp" />
     <ClCompile Include=".\RPL4CONSOLE.cpp" />
     <ClCompile Include=".\RPL4FE.cpp" />
+    <ClCompile Include=".\RPL4ENVIRON.cpp" />
     <ClCompile Include=".\RPL4LOBBY.cpp" />
     <ClCompile Include=".\RPL4ARND.cpp" />
     <ClCompile Include=".\RPL4GAUG.cpp" />
@@ -147,6 +157,7 @@
     <ClInclude Include=".\RPL4APP.h" />
     <ClInclude Include=".\RPL4CONSOLE.h" />
     <ClInclude Include=".\RPL4FE.h" />
+    <ClInclude Include=".\rpl4environ.h" />
     <ClInclude Include=".\RPL4LOBBY.h" />
     <ClInclude Include=".\RPL4ARND.h" />
     <ClInclude Include=".\RPL4GAUG.h" />

docs/rp412-handbook.html

@@ -1,4 +1,4 @@
-<title>Red Planet 4.12.7 — Controls</title>
+<title>Red Planet 4.12.7 — Handbook</title>
 
 <style>
   :root {
@@ -755,12 +755,13 @@
 
   <header class="masthead">
     <p class="eyebrow">Virtual World Entertainment · Tesla pod · RP 4.12.7</p>
-    <h1>Red Planet<br>Controls Map</h1>
+    <h1>Red Planet<br>Handbook</h1>
     <p class="lede">
-      Every input the pod answers to, on the gamepad and the keyboard. The
-      keyboard is the pod's button board: the letter and number rows are the
-      MFD banks laid out as they are printed on the panel, and flight moved to
-      the number pad so the board stays free.
+      Every input the pod answers to, on the gamepad and the keyboard, and
+      every file it keeps beside the exe. The keyboard is the pod's button
+      board: the letter and number rows are the MFD banks laid out as they are
+      printed on the panel, and flight moved to the number pad so the board
+      stays free.
     </p>
     <p class="provenance">Generated from the default <code>bindings.txt</code> · all of it rebindable</p>
   </header>
@@ -1149,6 +1150,119 @@
     </p>
   </section>
 
+  <section>
+    <h2>Bring your own stick</h2>
+    <p class="sub">
+      A gamepad speaks XInput, and the game reads it without being asked.
+      Everything else — a flight stick, a HOTAS throttle, a twist grip,
+      rudder pedals, a wheel — speaks <b>DirectInput</b>, which names its axes
+      <span class="mono">X Y Z RX RY RZ SL0 SL1</span> and says nothing about
+      what they are <i>for</i>. Somebody has to decide that your twist grip is
+      the rudder and that pushing it right means right. That is what
+      <code>joyconfig.bat</code> is.
+    </p>
+
+    <div class="panel">
+      <dl class="glance">
+        <div>
+          <dt>Run it once</dt>
+          <dd>joyconfig.bat<small>beside the exe; re-run any time</small></dd>
+        </div>
+        <div>
+          <dt>It asks</dt>
+          <dd>Move that one<small>steer · pitch · pedals · throttle · buttons</small></dd>
+        </div>
+        <div>
+          <dt>It watches</dt>
+          <dd>Which way<small>the direction you moved sets the sign</small></dd>
+        </div>
+        <div>
+          <dt>Then</dt>
+          <dd>Straight in<small>the game carries on to the setup screen</small></dd>
+        </div>
+      </dl>
+    </div>
+
+    <div class="callout">
+      <p>
+        <strong>The direction is the whole point.</strong> A stick that reads
+        positive pushed right and one that reads negative are equally common,
+        and nothing printed on the box tells you which you own. So the wizard
+        does not ask you to know — it asks you to <i>move</i>, and reads the
+        answer off the movement. Skip a prompt with <code>SPACE</code> if you
+        have no such control, <code>ESC</code> to abort without writing.
+      </p>
+    </div>
+
+    <p class="sub">
+      It writes only its own section of <code>bindings.txt</code>, between two
+      marker lines, so anything you have written yourself is kept — including a
+      deadzone you tuned by hand after trying it. Before it starts it prints
+      every axis <i>at rest</i>: a stick whose driver reports an odd range
+      shows up there as <span class="mono">X +1.00</span> on an untouched
+      stick, rather than as a mystery later. Xbox-class pads are excluded from
+      all of this, so nothing ever counts twice.
+    </p>
+
+    <div class="two-col">
+      <pre><i># what it writes</i>
+<b>joydev</b> 0 Logitech Extreme 3D
+<b>joyaxis</b> X   <b>axis</b> JoystickX invert deadzone 0.08
+<b>joyaxis</b> Y   <b>axis</b> JoystickY deadzone 0.08
+<b>joyaxis</b> RZ  <b>axis</b> Pedals deadzone 0.08
+<b>joyaxis</b> SL0 <b>axis</b> Throttle invert deadzone 0
+<b>joybutton</b> 0 <b>button</b> 0x40
+<b>joyhat</b> 0 up <b>button</b> 0x42</pre>
+
+      <pre><i># grammar</i>
+<b>joydev</b> &lt;slot&gt;    [product-name substring]
+<b>joyaxis</b> &lt;src&gt;   <b>axis</b> &lt;axis&gt; [invert]
+                    [deadzone &lt;d&gt;] [rate &lt;n&gt;]
+<b>joybutton</b> &lt;n&gt;   <b>button</b> &lt;addr&gt; [toggle]
+<b>joyhat</b> &lt;n&gt; &lt;up|down|left|right&gt;
+                    <b>button</b> &lt;addr&gt;
+
+<i># a named slot binds that product; a bare
+# one binds the Nth stick Windows lists</i></pre>
+    </div>
+
+    <div class="tbl-scroll" style="margin-top:22px">
+      <table>
+        <caption>Two rules the pod's shape asks for</caption>
+        <tbody>
+          <tr>
+            <th class="mono">Pedals</th>
+            <td>
+              A <b>signed</b> axis that works the pedal <b>pair</b> — positive
+              for the right pedal, negative for the left. The pod has one
+              under each foot; a twist grip or rudder bar is a single control
+              that presses one or the other and never both, which is exactly
+              what this says. It is a channel name like any other, so a gamepad
+              stick can drive the turn with it too.
+            </td>
+          </tr>
+          <tr>
+            <th class="mono">Throttle</th>
+            <td>
+              A <span class="mono">joyaxis</span> on the throttle with no
+              <span class="mono">rate</span> is treated as a <b>real lever</b>
+              and owns the channel: its full travel <i>is</i> the throttle
+              range. Spring-centred sticks have to nudge a position instead,
+              which is what <span class="mono">rate</span> does — a lever that
+              stays where you put it needs none of that.
+            </td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+
+    <p class="sub" style="margin-bottom:0">
+      A twist grip is usually <span class="mono">RZ</span>; a HOTAS throttle is
+      usually <span class="mono">Z</span> or <span class="mono">SL0</span>. Set
+      <code>RP412JOYLOG=1</code> to log devices as they attach and drop away.
+    </p>
+  </section>
+
   <section>
     <h2>Rebinding</h2>
     <p class="sub">
@@ -1166,6 +1280,8 @@
 <b>pad</b> &lt;button&gt;    <b>button</b> &lt;addr&gt; [toggle]
 <b>padaxis</b> &lt;src&gt;   <b>axis</b> &lt;axis&gt; [invert]
                     [deadzone &lt;d&gt;] [rate &lt;n&gt;]
+<b>joydev joyaxis joybutton joyhat</b>
+                    <i>see above</i>
 
 <i># deflect springs back, rate sticks where
 # you leave it (that is the throttle)</i></pre>
@@ -1185,12 +1301,98 @@
       <table>
         <caption>Reference — axes, address space, key names</caption>
         <tbody>
-          <tr><th>Axes</th><td class="mono">Throttle · LeftPedal · RightPedal · JoystickX · JoystickY</td></tr>
+          <tr><th>Axes</th><td class="mono">Throttle · LeftPedal · RightPedal · JoystickX · JoystickY · Pedals</td></tr>
           <tr><th>Buttons</th><td class="addr">0x00 – 0x47</td></tr>
           <tr><th>Keypads</th><td class="addr">0x50 – 0x6F <span style="color:var(--ink-quiet);font-family:var(--sans)">— unbound by default; the game never reads them</span></td></tr>
           <tr><th>Key names</th><td class="mono">A–Z · D0–D9 · F1–F12 · NumPad0–9 · Up Down Left Right · Space · Return · Shift · Ctrl · Alt · OemMinus · Oemplus · Oemcomma · OemPeriod</td></tr>
           <tr><th>Pad</th><td class="mono">A B X Y · DPadUp/Down/Left/Right · Start · Back · LeftShoulder · RightShoulder · LeftThumb · RightThumb</td></tr>
           <tr><th>Pad axes</th><td class="mono">LeftStickX/Y · RightStickX/Y · LeftTrigger · RightTrigger</td></tr>
+          <tr><th>Joystick axes</th><td class="mono">X · Y · Z · RX · RY · RZ · SL0 · SL1 <span style="color:var(--ink-quiet);font-family:var(--sans)">— DirectInput's own names</span></td></tr>
+        </tbody>
+      </table>
+    </div>
+  </section>
+
+  <section>
+    <h2>Files beside the exe</h2>
+    <p class="sub">
+      Four files in the game folder are yours. <b>None of them ship.</b> The
+      game writes each one the first time it needs it and then never touches
+      it again, so a new build dropped over this folder keeps everything you
+      have set — and deleting any of them simply starts that part over with
+      the current defaults.
+    </p>
+
+    <div class="tbl-scroll">
+      <table>
+        <caption>Yours to edit</caption>
+        <tbody>
+          <tr>
+            <th class="mono">environ.ini</th>
+            <td>
+              Every engine option, commented in place — displays, renderer,
+              Steam, the podium, the lot. The one to read first. Written on
+              first run; without it the MFDs do not come up at all, so the
+              game will always put one back.
+            </td>
+          </tr>
+          <tr>
+            <th class="mono">bindings.txt</th>
+            <td>
+              Every key, pad button, axis and joystick row. Written with the
+              full documented default layout the first time the game runs.
+            </td>
+          </tr>
+          <tr>
+            <th class="mono">pilot.cfg</th>
+            <td>
+              Your callsign and loadout, saved on the way out of the setup
+              screen so they are there next time.
+            </td>
+          </tr>
+          <tr>
+            <th class="mono">mfd_layout.cfg</th>
+            <td>
+              Where you dragged the windows, and the <code>,noframe</code>
+              flag. Only written when <code>RP412MFDLAYOUT=save</code>.
+            </td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+
+    <div class="callout">
+      <p>
+        <strong>Two that catch people out.</strong>
+        <code>environ.ini</code> is applied <i>over</i> the environment, so a
+        variable you set in a shell loses to an uncommented line in the file —
+        comment the line out rather than fighting it. And nothing here is ever
+        overwritten once it exists, which is exactly what lets you keep a
+        folder across builds — but it means a file carried through several
+        updates stops being offered new options. The game names any it has not
+        heard of in <code>rpl4.log</code>; <b>delete the file</b> to get the
+        fully documented current one back.
+      </p>
+    </div>
+
+    <h3>The rest of the folder</h3>
+    <p class="sub">
+      Shipped data the engine reads. Nothing here is meant to be edited, but
+      it is worth knowing what is what.
+    </p>
+
+    <div class="tbl-scroll">
+      <table>
+        <caption>Engine data</caption>
+        <tbody>
+          <tr><th class="mono">RPDPL.INI</th><td>Renderer and scene configuration. Named by <code>L4DPLCFG=</code>, so it can be swapped.</td></tr>
+          <tr><th class="mono">GAUGE\L4GAUGE.INI</th><td>Gauge canvas pages. <code>L4GAUGE=</code> picks one by name — a name that is not in here switches the MFDs off entirely.</td></tr>
+          <tr><th class="mono">GAUGE\L4GAUGE.CFG</th><td>The gauge layout data that page points at.</td></tr>
+          <tr><th class="mono">AUDIO\AUDIO.INI</th><td>Sound banks. <span class="mono">AUDIOMR.INI</span> is the mission-review twin.</td></tr>
+          <tr><th class="mono">JOYSTICK.INI</th><td>The 1995 single-stick calibration, for the legacy <code>L4CONTROLS=DIJOYSTICK</code> path only. Modern sticks are configured in <code>bindings.txt</code> — see above.</td></tr>
+          <tr><th class="mono">*.CFG <span style="color:var(--ink-quiet);font-family:var(--sans)">in AUDIO\</span></th><td>Pod audio-hardware mixer tables. Dead weight on a desktop; kept because the arcade path still reads them.</td></tr>
+          <tr><th class="mono">RPL4.RES</th><td>Resource blob, not text.</td></tr>
+          <tr><th class="mono">steam_appid.txt</th><td>Steam runs under Spacewar (480) until Red Planet has its own AppID.</td></tr>
         </tbody>
       </table>
     </div>
@@ -1199,7 +1401,7 @@
   <footer>
     <span>Red Planet 4.12.7</span>
     <span>gitea.mysticmachines.com/VWE/RP412</span>
-    <span>docs/CONTROLS.md · CONTROLS.txt ships with the game</span>
+    <span>docs/rp412-handbook.html · HANDBOOK.html ships with the game</span>
     <span>RGB keyboards mirror the pod lamps · RP412KEYLIGHT=0 to disable</span>
   </footer>
 </div>

pack-dist.ps1

@@ -8,13 +8,15 @@
 #      TEST.EGG) - but not the arcade launch scripts or the old 4.10 exe
 #    - libsndfile-1.dll beside the exe; OpenAL32.dll copied from the system
 #      when installed, with oalinst.exe included as the fallback installer
-#    - a desktop environ.ini (PAD;KEYBOARD controls, on-screen plasma)
-#    - start-windowed.bat and a README
+#    (environ.ini is NOT shipped - the exe writes it on first run)
+#    - start/joyconfig scripts, HANDBOOK.html, CONTROLS.txt and a README
 #
-#  Usage:  powershell -ExecutionPolicy Bypass -File pack-dist.ps1 [-Zip]
+#  Usage:  powershell -ExecutionPolicy Bypass -File pack-dist.ps1 [-Zip] [-Fresh]
 #
 param(
-    [switch]$Zip
+    [switch]$Zip,
+    # Wipe the player's files too, for testing what a first run does.
+    [switch]$Fresh
 )
 
 $ErrorActionPreference = 'Stop'
@@ -27,6 +29,23 @@ if (-not (Test-Path $exe)) {
     throw "Release\rpl4opt.exe not found - build first (see BUILD.md 2)."
 }
 
+# --- version ---------------------------------------------------------------
+# Read the stamp the exe was BUILT with rather than asking git again: a
+# commit between the build and the pack would otherwise have the package
+# claiming a version the binary inside it does not report.
+$buildHeader = Join-Path $root 'RP_L4\rpl4build.h'
+if (-not (Test-Path $buildHeader)) {
+    throw "RP_L4\rpl4build.h not found - build first, or run stamp-version.ps1."
+}
+$stamp = Get-Content $buildHeader -Raw
+$version = ([regex]::Match($stamp, '#define\s+RP412_VERSION\s+"([^"]+)"')).Groups[1].Value
+$versionLong = ([regex]::Match($stamp, '#define\s+RP412_VERSION_LONG\s+"([^"]+)"')).Groups[1].Value
+if (-not $version) { throw "could not read RP412_VERSION from $buildHeader" }
+if ($stamp -match '#define\s+RP412_BUILD_DIRTY\s+1') {
+    Write-Warning "packing a build made from a modified tree ($versionLong)"
+}
+Write-Host "Version $versionLong"
+
 # Refuse to touch a dist the game is currently running from.
 $running = Get-Process rpl4opt -ErrorAction SilentlyContinue |
     Where-Object { $_.Path -like "$dist\*" }
@@ -35,6 +54,27 @@ if ($running) {
 }
 
 Write-Host "Packing into $dist"
+
+# --- the player's own files ------------------------------------------------
+# None of these ship: the game writes each one the first time it needs it and
+# then leaves it alone, so a new build dropped over a folder keeps every
+# setting. This script rebuilds dist\ from scratch, which would throw exactly
+# those away - the one place the promise did not hold, and it is the folder we
+# do most of our own testing in. Carry them across. -Fresh to start over.
+$keepFiles = @('environ.ini', 'bindings.txt', 'pilot.cfg', 'mfd_layout.cfg')
+$kept = @{}
+if (-not $Fresh) {
+    foreach ($name in $keepFiles) {
+        $path = Join-Path $dist $name
+        if (Test-Path $path) { $kept[$name] = [System.IO.File]::ReadAllBytes($path) }
+    }
+    if ($kept.Count -gt 0) {
+        Write-Host "  keeping $($kept.Keys -join ', ')"
+    }
+} elseif (Test-Path $dist) {
+    Write-Host "  -Fresh: the player's files go too"
+}
+
 if (Test-Path $dist) { Remove-Item -Recurse -Force $dist }
 New-Item -ItemType Directory -Force "$dist\SPOOLS" | Out-Null
 
@@ -64,9 +104,8 @@ foreach ($file in 'RPDPL.INI', 'JOYSTICK.INI', 'RPL4.RES', 'TEST.EGG',
     Copy-Item (Join-Path $assets $file) $dist
 }
 
-# The controls map travels with the game (players get the diagrams
-# without needing the repo). Flattened to ASCII so it reads correctly
-# in Notepad - the markdown source keeps its typography.
+# The controls half as plain text, for Notepad. Flattened to ASCII so it
+# reads correctly there - the markdown source keeps its typography.
 $controls = Get-Content (Join-Path $root 'docs\CONTROLS.md') -Raw -Encoding UTF8
 foreach ($pair in @(
         @([char]0x2014, '-'), @([char]0x2013, '-'), @([char]0x2018, "'"),
@@ -76,13 +115,18 @@ foreach ($pair in @(
 }
 Set-Content -Path "$dist\CONTROLS.txt" -Encoding ascii -Value $controls
 
-# The same map as a page, for anyone who would rather look at the
-# diagrams than read them. Its source is the published artifact, which is
-# a fragment - the publisher supplies the document shell - so wrap it to
+# The handbook as a page: the controls map with the diagrams, plus the
+# joystick setup and what every file in the folder is for. Its source is
+# the published artifact, which is a fragment - the publisher supplies
+# the document shell - so wrap it to
 # stand alone: without a doctype the browser drops into quirks mode, and
 # without a charset the typography arrives as mojibake. Written without a
 # BOM so the charset declaration is the only thing speaking.
-$controlsPage = Get-Content (Join-Path $root 'docs\rp412-controls.html') -Raw -Encoding UTF8
+$handbookPage = Get-Content (Join-Path $root 'docs\rp412-handbook.html') -Raw -Encoding UTF8
+# Stamp the shipped copy with the build's own version. The source keeps a
+# readable one for publishing; only "4.12.<n>" is touched, which on this
+# page is always the version and never anything else.
+$handbookPage = [regex]::Replace($handbookPage, '4\.12\.\d+', $version)
 $page = @"
 <!doctype html>
 <html lang="en">
@@ -91,12 +135,12 @@ $page = @"
 <meta name="viewport" content="width=device-width, initial-scale=1">
 </head>
 <body>
-$controlsPage
+$handbookPage
 </body>
 </html>
 "@
 [System.IO.File]::WriteAllText(
-    "$dist\CONTROLS.html", $page, (New-Object System.Text.UTF8Encoding $false))
+    "$dist\HANDBOOK.html", $page, (New-Object System.Text.UTF8Encoding $false))
 
 # --- OpenAL runtime --------------------------------------------------------
 # The exe links OpenAL32.dll (32-bit). Prefer shipping the already-installed
@@ -113,247 +157,12 @@ if (Test-Path $openal) {
 }
 
 # --- desktop configuration -------------------------------------------------
-Set-Content -Path "$dist\environ.ini" -Encoding ascii -Value @"
-# ============================================================================
-#  environ.ini - Red Planet 4.12 configuration
-# ============================================================================
-#  One KEY=VALUE per line, read at game start. Lines starting with # or ;
-#  are comments; anything without an = is ignored. Delete a line (or
-#  comment it out) to fall back to the built-in default.
-#
-#  Input bindings live in bindings.txt beside the exe (written with the
-#  full documented layout on first run; delete it to restore defaults).
-
-# ---- Core (the shipped configuration) --------------------------------------
-
-# Control stack: tokens separated by ; or , processed left to right.
-#   PAD            the virtual RIO (XInput controller + keyboard,
-#                  rebindable via bindings.txt)
-#   RIO            real serial cockpit hardware on COM1
-#   RIO:COMn       same, on another port (RIO:COM3, ...)
-#   KEYBOARD       the engine keyboard handler
-#   MOUSE, JOYSTICK, FLIGHTSTICKPRO, THRUSTMASTER, DIJOYSTICK
-#                  legacy pointer/joystick drivers (untested here)
-# Unset falls back to KEYBOARD alone.
-L4CONTROLS=PAD;KEYBOARD
-
-# Renderer bring-up argument. Only its presence is checked (the DPL
-# resolution parsing it once fed is gone) and the game refuses to start
-# without it - any non-empty value works. Leave as shipped.
-DPLARG=1
-
-# DPL (renderer/scene) configuration file, searched beside the exe.
-# Any notation file name; RPDPL.INI is the one that ships.
-L4DPLCFG=RPDPL.INI
-
-# Gauge (MFD/instrument) canvas. Must name a page of GAUGE\L4GAUGE.INI:
-#   640x480x8 | 640x480x16 | 800x600x16
-# Unset disables the gauge renderer (and with it all MFDs).
-L4GAUGE=640x480x16
-
-# Plasma display.
-#   SCREEN         render the pod's plasma glass in-window (currently
-#                  parked off-layout)
-#   COM1, COM2...  drive real plasma glass on that serial port
-#                  (9600 baud, N81)
-# Unset = no plasma display.
-L4PLASMA=SCREEN
-
-# 0 = classic separate gauge windows; 1 = the single-window glass
-# cockpit (all seven displays composed on a locked 1920x1080 canvas
-# around the viewscreen); 2 = exploded diagnostic view (each display
-# in its own native-resolution desktop window - MFDs 640x480, map
-# 480x640 - decoded exactly as the pod's VDB split them, no downscale).
-L4MFDSPLIT=1
-
-# The game window - and in the exploded view (L4MFDSPLIT=2) each display
-# window - is placed fresh every launch, so moving one somewhere useful
-# never survived the menu-race-menu loop. This remembers where you put
-# them, in mfd_layout.cfg beside this file:
-#   off / 0 / unset   computed placement only, no file (default)
-#   load              put the windows back where they were saved
-#   save              the same, and re-save on every finished drag
-# The game window gets its size back too, so you can size the cockpit to
-# suit your monitor once and keep it. The display windows get position
-# only: their size follows their content and their button banks, so an
-# old one is never restored over them. Arrange everything once with
-# save, then leave it on load.
-#
-# The plasma display window takes part too, under "Plasma Display".
-#
-# Each line in mfd_layout.cfg reads <title>=<x>,<y>,<w>,<h>, and you can
-# append ,noframe to take that window's title bar and border off - a
-# cockpit that fills the monitor edge to edge without -fit taking the
-# whole screen. Put the window where you want it first: a bare window
-# has nothing to drag by. Delete the flag to get the frame back.
-#RP412MFDLAYOUT=off
-
-# Size of the six secondary displays in the glass cockpit, as a
-# percentage of their pod size. The pod bolted them down at one size;
-# on a big panel there is room to trade viewscreen for instrument, so
-# turn these up if you want to actually read the other displays while
-# you fly. 100 = as the pod had them. Range 25-200 (out-of-range and
-# unreadable values fall back to the group setting, then to 100).
-#
-# The scaling is applied in canvas units, before the cockpit is fitted
-# to your window, so a given number looks the same on every monitor.
-# The layout stays legal whatever you ask for - the panes are clamped
-# against their actual neighbours, shrinking uniformly so a display
-# never comes out stretched. They do overlap the viewscreen, exactly
-# as the pod's bezels did, but never each other.
-#
-# L4MFDSCALE sets all five green MFDs at once.
-L4MFDSCALE=100
-
-# ...and any single display can override it. Uncomment one to size it
-# on its own - useful if you only care about, say, the damage readout.
-#   UL upper left     UC upper center    UR upper right
-#   LL lower left     LR lower right
-#L4MFDSCALE_UL=100
-#L4MFDSCALE_UC=100
-#L4MFDSCALE_UR=100
-#L4MFDSCALE_LL=100
-#L4MFDSCALE_LR=100
-
-# The portrait radar/map, sized on its own (it already sits at 1.35x
-# the MFDs by default). It shares the canvas with whichever MFD is
-# above it, so at extreme settings one of the two gives way.
-L4RADARSCALE=100
-
-# Where the radar sits:
-#   CENTER    bottom centre, under the viewscreen, as the pod had it
-#             (default; BOTTOM and CENTRE mean the same)
-#   LEFT      bottom left corner      (or BOTTOMLEFT)
-#   RIGHT     bottom right corner     (or BOTTOMRIGHT)
-#   MIDLEFT   left edge, halfway up   (or LEFTCENTER / LEFTCENTRE)
-#   MIDRIGHT  right edge, halfway up  (or RIGHTCENTER / RIGHTCENTRE)
-# Anywhere but CENTER stops it blocking the middle of the road, which
-# is worth having on a wide screen.
-#
-# In a bottom corner it is one of three panes along the bottom, and the
-# lower MFD whose corner it takes slides inboard beside it. Halfway up
-# a side it leaves the bottom row entirely and sits between that side's
-# two MFDs - roomy on a tall radar, but if the MFDs on that side are
-# also scaled up, the radar is the one that gives way (it has to clear
-# both of them, and it grows from the middle in both directions).
-L4RADARPOS=CENTER
-
-# The Winners Circle: at the end of a race the finishers are stood on
-# the award platform in finishing order, with each pilot's callsign on
-# the plate beside their spot, and held there for a few seconds before
-# the results screen. 1 = show it, 0 = straight to the results.
-RP412PODIUM=1
-
-# The shot is framed for you, but these move the camera if you want it
-# somewhere else. Distances are in game units, measured from the middle
-# of the group of finishers.
-#   STANDOFF  how far out in front of the stand the camera sits
-#   HEIGHT    how far above the group
-#   AIM       height of the point it looks at, relative to the group -
-#             negative tilts down, positive tilts up
-#   ASPECT    the stand was composed for a 4:3 pod monitor, so the shot
-#             is cropped to that shape with black either side. 0 runs it
-#             full width instead.
-#   FADEIN    seconds to come up out of the black after the race fades
-#   CAM       0 watches from your own cockpit rather than off the stand
-#RP412PODIUMSTANDOFF=36
-#RP412PODIUMHEIGHT=12
-#RP412PODIUMAIM=2
-#RP412PODIUMASPECT=1.333
-#RP412PODIUMFADEIN=0.45
-#RP412PODIUMCAM=1
-
-# Override the game length the menu picked, in seconds. The shortest the
-# menu offers is 3:00, which is a long wait when what you are testing is
-# what happens at the buzzer. Unset = use the menu's choice.
-#RP412MISSIONSECONDS=20
-
-# Simulation/render frame rate, integer frames/second. The desktop
-# default is 60; the arcade pods shipped at 25.
-TARGETFPS=60
-
-# 1 = Steam networking (lobbies, FakeIP mesh). Needs the Steam client
-# running and steam_appid.txt beside the exe; without them the game
-# logs the reason and falls back to plain TCP. 0 = TCP only.
-RP412STEAM=1
-
-# ---- Optional ---------------------------------------------------------------
-
-# RGB keyboard lamp mirror (Windows Dynamic Lighting): keys bound to
-# lamp buttons glow with the panel, flash modes and all.
-# Unset or nonzero = on (the default); 0 = off.
-#RP412KEYLIGHT=0
-
-# Invert the stick on top of whatever bindings.txt produces:
-# X = invert X only, Y = invert Y only, XY = both (case-insensitive).
-#L4PADFLIP=XY
-
-# Anti-aliasing sample count, passed straight to Direct3D 9:
-# 0 = off, else 2..16 as the GPU supports (1 selects the driver's
-# "nonmaskable" mode; unsupported counts fail device creation).
-#MULTISAMPLE=0
-
-# Particle budget, integer. Default 8192.
-#MAXPARTICLES=8192
-
-# On-screen plasma glass (L4PLASMA=SCREEN only). SCALE = integer pixel
-# size 1..16, default 4 (out-of-range values are ignored). POS = window
-# top-left as X,Y screen coordinates; unset = auto, parked below the
-# main window.
-#L4PLASMASCALE=4
-#L4PLASMAPOS=0,0
-
-# Fixed random seed (repeatable runs): any unsigned integer.
-# Unset seeds from the clock.
-#RANDOM=12345
-
-# ---- LAN play without Steam -------------------------------------------------
-# Host a race over plain TCP: list the member pods' console channels
-# (members run: rpl4opt.exe -windowed -res 1920 1080 -net 1501).
-#   RP412HOSTPODS  comma-separated IP[:port] list, one entry per member
-#                  pod; port defaults to 1501 per entry
-#   RP412HOSTPORT  this machine's console port, integer > 0
-#                  (default 1501)
-#   RP412HOSTADDR  this machine's LAN IP as members can reach it
-#                  (default 127.0.0.1)
-#RP412HOSTPODS=192.168.1.20:1501,192.168.1.21:1501
-#RP412HOSTPORT=1501
-#RP412HOSTADDR=192.168.1.10
-
-# ---- Developer / testing ----------------------------------------------------
-
-# Nonzero arms the debug keys: Alt+W wireframe, Alt+V predator vision,
-# Alt+F frame dump, Alt+/ perf stats, Alt+E event-queue dump.
-# 0 or unset = off. (Alt+Q, the mission abort, is always live.)
-#RP412DEVKEYS=1
-
-# Console race-length override, integer seconds (short test races).
-# Values <= 0 are ignored.
-#L4CONSOLELEN=30
-
-# Nonzero = Steam transport loopback self-test at boot (logs PASS/FAIL).
-#RP412STEAMSELFTEST=1
-
-# ---- Arcade heritage (multi-monitor pods; not used on the desktop) ----------
-# PRIMGAUGE / SECGAUGE / MFDGAUGE / MFDGAUGE2 pin a display to a monitor
-# by adapter index (0, 1, 2...). SPANDISABLE: 0 = let the MFDs span one
-# wide surface, nonzero = separate windows (setting MFDGAUGE2 alone also
-# forces spanning off). L4EYES = "x y z xrot yrot zrot [type]" floats
-# for a detached camera; a type starting with r offsets it relative to
-# the pod. L4INTERCOM enables the crew intercom - only its presence
-# matters (traditionally COM2). NOMODES skips the mode/lamp programming;
-# presence alone triggers it, even NOMODES=0. LOGSIZE > 0 sizes the
-# trace log in dev builds compiled with tracing.
-#PRIMGAUGE=1
-#SECGAUGE=2
-#MFDGAUGE=3
-#MFDGAUGE2=4
-#SPANDISABLE=1
-#L4EYES=1
-#L4INTERCOM=COM2
-#NOMODES=1
-#LOGSIZE=1000000
-"@
+# --- desktop configuration -------------------------------------------------
+# environ.ini is NOT shipped. The exe carries the template and writes it on
+# first run (RPL4ENVIRON.cpp), the same way it writes bindings.txt - so a
+# tester can drop a new build over an old folder and keep every setting they
+# have changed. Laying one down here would overwrite their file on every
+# unzip, which is the whole problem.
 
 Set-Content -Path "$dist\start-windowed.bat" -Encoding ascii -Value @"
 @echo off
@@ -396,7 +205,7 @@ set RP412JOYCONFIG=
 "@
 
 Set-Content -Path "$dist\README.txt" -Encoding ascii -Value @"
-Red Planet 4.12.7
+Red Planet $version
 =================
 
 Run start-fullscreen.bat for borderless over the whole monitor, or
@@ -446,13 +255,32 @@ at its left, and the lower MFDs flanking the portrait map. The red
 buttons around each MFD and the amber buttons beside the map are the
 pod's real button banks: click them with the mouse, and they light up
 as the game commands their lamps.
-environ.ini is self-documenting: every option ships in the file with
-a comment (Steam networking, keyboard lighting, stick inversion, LAN
-hosting, developer keys, display scaling and radar placement, and more).
+environ.ini is self-documenting: the game writes it on first run with
+every option in it and a comment on each (Steam networking, keyboard
+lighting, stick inversion, LAN hosting, developer keys, display scaling
+and radar placement, and more).
 
-CONTROLS.html is the full controls map - open it in a browser for the
-pad, keyboard and pod-panel diagrams. CONTROLS.txt is the same thing as
-plain text.
+HANDBOOK.html is the full manual - open it in a browser for the pad,
+keyboard and pod-panel diagrams, the joystick setup, and what every file
+in this folder is for. CONTROLS.txt is the controls half as plain text.
+
+Four files here are yours. None of them ship - the game writes each one
+the first time it needs it and then leaves it alone, so a new build
+unzipped over this folder keeps everything you have set. Delete any of
+them to start that part over:
+
+  environ.ini      every engine option, commented in place
+  bindings.txt     every key, pad button, axis and joystick row
+  pilot.cfg        your callsign and loadout
+  mfd_layout.cfg   where you dragged the windows (RP412MFDLAYOUT)
+
+Two that catch people out: environ.ini is applied OVER the environment,
+so a variable set in a shell loses to an uncommented line in the file;
+and none of these four is ever overwritten once it exists, which is what
+lets you keep a folder across builds. The trade is that a file carried
+through several updates stops being offered new options - rpl4.log names
+any it has not heard of, and deleting the file brings back the fully
+documented current one.
 
 Known prototype notes: pods race untextured (the player1-8 skins come
 from the presets system, not shipped data), and text drawn on the plasma
@@ -466,9 +294,13 @@ $size = (Get-ChildItem $dist -Recurse | Measure-Object Length -Sum).Sum
 Write-Host ("dist ready: {0:N1} MB" -f ($size / 1MB))
 
 if ($Zip) {
-    $zipPath = Join-Path $root 'RedPlanet-4.12.7.zip'
+    $zipPath = Join-Path $root "RedPlanet-$version.zip"
     Write-Host "zipping to $zipPath..."
 
+    # Taken BEFORE the player's files go back, so a release never carries
+    # somebody's callsign, key bindings or window positions to everyone who
+    # downloads it. A fresh unzip must look like a first run.
+    #
     # Everything lives under a single RP412\ folder inside the zip, so
     # unpacking anywhere gives one self-contained game directory instead
     # of scattering files into the extraction folder.
@@ -479,3 +311,14 @@ if ($Zip) {
     Compress-Archive -Path "$stage\RP412" -DestinationPath $zipPath -Force
     Remove-Item -Recurse -Force $stage
 }
+
+# --- the player's own files, back where they were --------------------------
+# Last of all: after the rebuilt tree, so nothing the pack writes can land on
+# top of them, and after the zip, so the release stays clean. Zipping should
+# not cost you your own settings.
+if ($kept.Count -gt 0) {
+    foreach ($name in $kept.Keys) {
+        [System.IO.File]::WriteAllBytes((Join-Path $dist $name), $kept[$name])
+    }
+    Write-Host "  restored $($kept.Keys -join ', ')"
+}

stamp-version.ps1

@@ -0,0 +1,103 @@
+# ============================================================================
+#  stamp-version.ps1 - write RP_L4\rpl4build.h from the repository's own state
+# ============================================================================
+#
+#  The patch number IS the commit count, so a build names the commit it came
+#  from and there is never a question about which changes are in a binary
+#  somebody is holding. Run as RP_L4's pre-build step; also readable by
+#  pack-dist.ps1, so the package and the exe cannot disagree.
+#
+#  A hardcoded version could not do this: the commit that records "4.12.96"
+#  is itself commit 96, so the file is stale the moment it is committed.
+#
+#  Usage:  powershell -ExecutionPolicy Bypass -File stamp-version.ps1
+#
+$ErrorActionPreference = 'Stop'
+
+# The product line. Bump this by hand when the line moves; the patch
+# number after it looks after itself.
+$line = '4.12'
+
+$root   = Split-Path -Parent $MyInvocation.MyCommand.Path
+$header = Join-Path $root 'RP_L4\rpl4build.h'
+
+$count  = 0
+$commit = 'nogit'
+$dirty  = 0
+
+#
+# Every git call goes through cmd so that stderr never reaches PowerShell's
+# error stream. Windows PowerShell turns a native command's stderr into
+# ErrorRecords, and with $ErrorActionPreference = 'Stop' git's routine
+# "LF will be replaced by CRLF" warning is enough to throw - which silently
+# skipped the dirty check and stamped every modified build as clean.
+#
+try {
+    Push-Location $root
+    $c = cmd /c "git rev-list --count HEAD 2>NUL"
+    if ($LASTEXITCODE -eq 0 -and $c) {
+        $count  = [int]$c
+        $commit = (cmd /c "git rev-parse --short HEAD 2>NUL").Trim()
+        #
+        # Tracked modifications only. An untracked scratch file in the tree
+        # is not in the binary, and marking every build dirty for one would
+        # make the marker mean nothing.
+        #
+        cmd /c "git diff --quiet HEAD -- 2>NUL"
+        if ($LASTEXITCODE -ne 0) { $dirty = 1 }
+    }
+} catch {
+    # no git, or not a repository: fall through to the placeholder below
+} finally {
+    Pop-Location
+}
+
+if ($count -eq 0) {
+    # Built outside the repository (a source drop, say). Say so plainly
+    # rather than inventing a number that would sort against real ones.
+    $version = "$line.x"
+    $long    = "$line.x (no repository)"
+} else {
+    $version = "$line.$count"
+    $long    = "$version ($commit$(if ($dirty) { '+' } else { '' }))"
+}
+
+$content = @"
+//===========================================================================//
+// File:    rpl4build.h            GENERATED - do not edit, do not commit    //
+//---------------------------------------------------------------------------//
+// Written by stamp-version.ps1 as RP_L4's pre-build step. The patch number   //
+// is the repository's commit count and the hash beside it names the exact    //
+// commit, so a running build always says where it came from. A trailing '+'  //
+// means the tree had uncommitted changes to tracked files when it was built. //
+//===========================================================================//
+
+#pragma once
+
+#define RP412_BUILD_COUNT   $count
+#define RP412_BUILD_COMMIT  "$commit"
+#define RP412_BUILD_DIRTY   $dirty
+#define RP412_VERSION       "$version"
+#define RP412_VERSION_LONG  "$long"
+"@
+
+#
+# Only rewrite when something actually changed: an unconditional write
+# would touch the header on every build and drag RPL4.CPP through a
+# recompile each time.
+#
+$existing = if (Test-Path $header) { [IO.File]::ReadAllText($header) } else { '' }
+if ($existing -ne $content) {
+    [IO.File]::WriteAllText($header, $content, (New-Object System.Text.ASCIIEncoding))
+    Write-Host "stamp-version: $long"
+} else {
+    Write-Host "stamp-version: $long (unchanged)"
+}
+
+#
+# Explicitly: this runs as a pre-build step, and the last thing above it is
+# "git diff --quiet", which exits 1 to mean "there are changes". Letting that
+# escape would fail the build on every modified tree - the exact case a
+# developer builds in.
+#
+exit 0