feat(macos): WASD camera controls + Cmd key-up fix

Opt-in WASD camera panning (GEN_WASD_CAMERA / launcher toggle). Bare
W/A/S/D pan the battlefield camera like the arrow keys (which keep
working); the commands those keys displace relocate to Cmd+key.

- LookAtXlat: mirror W/A/S/D onto the camera scroll directions; no-op
  when the flag is off.
- MetaEvent: in WASD mode bare W/A/S/D pass through to pan instead of
  firing/eating their meta command; Cmd+W/S fire the bare-key command
  via a targeted lookup (the localized Data\English\CommandMap.ini binds
  W=SelectAllAircraft and S=Stop, which were consuming the keys before
  the camera translator saw them).
- HotKey: bare W/A/S/D never fire command-bar buttons; only Cmd+A/D fire
  the relocated Attack-Move / Dozer button (W/S are handled as meta).
- metal_backend: synthesize an immediate key-up for any Cmd+key press.
  macOS does not deliver keyUp while Command is held, which left the
  camera stuck scrolling after Cmd+W/S and stopped Cmd+A/D (fire on
  key-up) from ever triggering. General macOS input fix.
- launcher: "WASD camera controls" checkbox (Play tab, persisted,
  default off) + GEN_WASD_CAMERA env; help text documents the Cmd remap.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: dvcdsys

GeneralsMD/Code/GameEngine/Source/GameClient/MessageStream/HotKey.cpp

@@ -66,6 +66,23 @@
 // PUBLIC FUNCTIONS ///////////////////////////////////////////////////////////
 //-----------------------------------------------------------------------------
 
+// TheSuperHackers @port macOS @feature GEN_WASD_CAMERA: when the launcher's
+// "WASD camera controls" toggle is on, W/A/S/D pan the camera (see LookAtXlat).
+// W is unused by the command bar, but A/S/D collide with build/order shortcuts
+// (Attack-Move, Stop, Dozer, ...). To avoid losing them we relocate those bare
+// shortcuts to Cmd+A/S/D — on macOS the Cmd key already maps to the engine's
+// Ctrl (CocoaKeyboard.cpp), so Cmd+letter arrives here as a CTRL-modified key.
+static Bool wasdCameraEnabled()
+{
+	static int s_enabled = -1;
+	if (s_enabled < 0)
+	{
+		const char *e = ::getenv("GEN_WASD_CAMERA");
+		s_enabled = (e && e[0] && e[0] != '0') ? 1 : 0;
+	}
+	return s_enabled ? TRUE : FALSE;
+}
+
 //-----------------------------------------------------------------------------
 GameMessageDisposition HotKeyTranslator::translateGameMessage(const GameMessage *msg)
 {
@@ -96,13 +113,41 @@ GameMessageDisposition HotKeyTranslator::translateGameMessage(const GameMessage
 		{
 			newModState |= ALT;
 		}
-		if(newModState != 0)
-			return disp;
+
 		WideChar key = TheKeyboard->getPrintableKey((KeyDefType)msg->getArgument(0)->integer, 0);
 		UnicodeString uKey;
 		uKey.concat(key);
 		AsciiString aKey;
 		aKey.translate(uKey);
+
+		// TheSuperHackers @port macOS @feature GEN_WASD_CAMERA conflict handling.
+		if (wasdCameraEnabled())
+		{
+			AsciiString lowKey = aKey;
+			lowKey.toLower();
+			const char *k = lowKey.str();
+			const Bool isWasdLetter = (k && k[0] && k[1] == '\0' &&
+				(k[0] == 'w' || k[0] == 'a' || k[0] == 's' || k[0] == 'd'));
+			if (isWasdLetter)
+			{
+				// Bare W/A/S/D belong to the camera now: don't fire a command button,
+				// leave the message so LookAtXlat can stop the scroll. On Cmd, only
+				// the command-bar letters A and D fire their relocated button here;
+				// W (SelectAllAircraft) and S (Stop) are meta commands already fired
+				// by MetaEventTranslator, so firing a button for them too would e.g.
+				// build a &Sniper on Cmd+S.
+				const Bool isCmdButtonLetter = (k[0] == 'a' || k[0] == 'd');
+				if (newModState == CTRL && isCmdButtonLetter &&
+						TheHotKeyManager && TheHotKeyManager->executeHotKey(aKey))
+				{
+					disp = DESTROY_MESSAGE;
+				}
+				return disp;
+			}
+		}
+
+		if(newModState != 0)
+			return disp;
 		if(TheHotKeyManager && TheHotKeyManager->executeHotKey(aKey))
 			disp = DESTROY_MESSAGE;
 	}

GeneralsMD/Code/GameEngine/Source/GameClient/MessageStream/LookAtXlat.cpp

@@ -65,6 +65,23 @@ enum
 
 static Bool scrollDir[4] = { false, false, false, false };
 
+// TheSuperHackers @port macOS @feature GEN_WASD_CAMERA=1 lets W/A/S/D pan the
+// camera exactly like the arrow keys (arrows keep working too). Opt-in, set by
+// the macOS launcher's "WASD camera controls" toggle. W is free in the retail/CWC
+// key layout; A/S/D normally trigger command-bar shortcuts (Attack-Move, Stop,
+// Dozer, ...), so when this mode is on those are relocated to Cmd+A/S/D in
+// HotKey.cpp and the bare keys are freed up here to scroll.
+static Bool wasdCameraEnabled()
+{
+	static int s_enabled = -1;
+	if (s_enabled < 0)
+	{
+		const char *e = ::getenv("GEN_WASD_CAMERA");
+		s_enabled = (e && e[0] && e[0] != '0') ? 1 : 0;
+	}
+	return s_enabled ? TRUE : FALSE;
+}
+
 // TheSuperHackers @tweak Introduces the SCROLL_MULTIPLIER for all scrolling to
 //
 //  1. bring the RMB scroll speed back to how it was at 30 FPS in the retail game version
@@ -231,6 +248,36 @@ GameMessageDisposition LookAtTranslator::translateGameMessage(const GameMessage
 				break;
 			}
 
+			// TheSuperHackers @port macOS @feature GEN_WASD_CAMERA: mirror W/A/S/D
+			// onto the same scroll directions as the arrow keys. On press we only
+			// START a pan when no Cmd/Ctrl and no Alt is held, so Cmd+A/S/D (the
+			// relocated command-bar shortcuts, see HotKey.cpp) reach the command bar
+			// instead of panning. On release we always CLEAR, so adding/removing a
+			// modifier mid-press can never leave the camera stuck scrolling.
+			if (wasdCameraEnabled())
+			{
+				const Bool modBlocksStart =
+					(state & KEY_STATE_CONTROL) || (state & KEY_STATE_ALT);
+				if (!isPressed || !modBlocksStart)
+				{
+					switch (key)
+					{
+					case KEY_W:
+						scrollDir[DIR_UP] = isPressed;
+						break;
+					case KEY_S:
+						scrollDir[DIR_DOWN] = isPressed;
+						break;
+					case KEY_A:
+						scrollDir[DIR_LEFT] = isPressed;
+						break;
+					case KEY_D:
+						scrollDir[DIR_RIGHT] = isPressed;
+						break;
+					}
+				}
+			}
+
 			if (TheInGameUI->isSelecting() || (m_isScrolling && m_scrollType != SCROLL_KEY))
 				break;
 

GeneralsMD/Code/GameEngine/Source/GameClient/MessageStream/MetaEvent.cpp

@@ -436,6 +436,23 @@ static Bool isMessageUsable(CommandUsableInType usableIn)
 }
 
 //-------------------------------------------------------------------------------------------------
+// TheSuperHackers @port macOS @feature GEN_WASD_CAMERA: see LookAtXlat.cpp. The
+// localized CommandMap (Data\<lang>\CommandMap.ini) binds bare W = SELECT_ALL_AIRCRAFT
+// and bare S = STOP as meta-events, which this translator (priority 20) would fire
+// and destroy before the camera translator (priority 60) ever sees the key. When
+// WASD mode is on we let bare W/A/S/D fall through to pan, and move those meta
+// commands to Cmd+W/S (macOS Cmd maps to the engine's Ctrl, CocoaKeyboard.cpp).
+static Bool wasdCameraEnabled()
+{
+	static int s_enabled = -1;
+	if (s_enabled < 0)
+	{
+		const char *e = ::getenv("GEN_WASD_CAMERA");
+		s_enabled = (e && e[0] && e[0] != '0') ? 1 : 0;
+	}
+	return s_enabled ? TRUE : FALSE;
+}
+
 GameMessageDisposition MetaEventTranslator::translateGameMessage(const GameMessage *msg)
 {
 	GameMessageDisposition disp = KEEP_MESSAGE;
@@ -465,8 +482,36 @@ GameMessageDisposition MetaEventTranslator::translateGameMessage(const GameMessa
 			newModState |= ALT;
 		}
 
+		// TheSuperHackers @port macOS @feature GEN_WASD_CAMERA conflict handling.
+		// Bare W/A/S/D now pan the camera, so they must not fire/eat their meta
+		// command here. Cmd(Ctrl)+W/A/S/D fires the command the bare key used to map
+		// to — done with a targeted lookup of the un-modified binding rather than by
+		// mutating newModState (which would trip the "mods-only" special case below
+		// and spuriously destroy Cmd+A / Cmd+D, blocking their command-bar relocation).
+		Bool wasdSkipMetaMatch = FALSE;
+		if (wasdCameraEnabled() &&
+				(key == MK_W || key == MK_A || key == MK_S || key == MK_D) &&
+				!(keyState & KEY_STATE_ALT))
+		{
+			wasdSkipMetaMatch = TRUE;
+			if (keyState & KEY_STATE_CONTROL)
+			{
+				for (const MetaMapRec *m = TheMetaMap->getFirstMetaMapRec(); m; m = m->m_next)
+				{
+					if (m->m_key == key && m->m_modState == NONE && isMessageUsable(m->m_usableIn) &&
+							( (m->m_transition == DOWN && (keyState & KEY_STATE_DOWN)) ||
+								(m->m_transition == UP   && (keyState & KEY_STATE_UP)) ))
+					{
+						if (!(keyState & KEY_STATE_AUTOREPEAT))
+							TheMessageStream->appendMessage(m->m_meta);
+						disp = DESTROY_MESSAGE;
+						break;
+					}
+				}
+			}
+		}
 
-		for (const MetaMapRec *map = TheMetaMap->getFirstMetaMapRec(); map; map = map->m_next)
+		for (const MetaMapRec *map = TheMetaMap->getFirstMetaMapRec(); !wasdSkipMetaMatch && map; map = map->m_next)
 		{
 			if (!isMessageUsable(map->m_usableIn))
 				continue;

cmake/dx8_stub/metal_backend.mm

@@ -571,7 +571,18 @@ - (BOOL)acceptsFirstResponder { return YES; }
 // NOTE: do NOT call [super keyDown:] / [super keyUp:] — the default impl
 // forwards up the chain to NSWindow, which beeps on unhandled ESC.
 - (void)keyDown:(NSEvent*)e {
-    if (!e.isARepeat) MetalView_PushKeyEvent((int)e.keyCode, 1);
+    if (!e.isARepeat) {
+        MetalView_PushKeyEvent((int)e.keyCode, 1);
+        // TheSuperHackers @port macOS @bugfix: macOS does NOT deliver -keyUp: for a
+        // key released while Command (Cmd) is held. Without the matching up the
+        // engine thinks the key stays down and auto-repeats it forever — e.g. with
+        // GEN_WASD_CAMERA, Cmd+W fires "select all aircraft" but W then sticks and
+        // the camera scrolls up endlessly; likewise Cmd+A/Cmd+D never fire because
+        // the command-bar hotkey triggers on key-up. A Cmd+key can't be held-repeated
+        // on macOS anyway, so treat it as a tap: synthesize the up immediately.
+        if (e.modifierFlags & NSEventModifierFlagCommand)
+            MetalView_PushKeyEvent((int)e.keyCode, 0);
+    }
     // Text-entry input: NSEvent has already applied the live system keyboard
     // layout + shift/caps/option/dead-keys, so -characters is the correct typed
     // character (unlike the raw keyCode path, which only knows a handful of

launcher/Sources/GeneralsZHLauncher/GameInstaller.swift

@@ -62,6 +62,19 @@ final class LauncherModel: ObservableObject {
         didSet { UserDefaults.standard.set(disableMenuShellMap, forKey: "disableMenuShellMap") }
     }
 
+    /// Pan the battlefield camera with W/A/S/D as well as the arrow keys. Sets the
+    /// GEN_WASD_CAMERA env hook (LookAtXlat.cpp), which mirrors W/A/S/D onto the
+    /// camera scroll directions. The arrow keys keep working too. Those keys are
+    /// normally bound: W=SelectAllAircraft and S=Stop are meta commands (localized
+    /// CommandMap.ini), A/D and the build shortcut on each letter are command-bar
+    /// buttons; while this mode is on all of them relocate to Cmd+key (MetaEvent.cpp
+    /// + HotKey.cpp), so nothing is lost from the keyboard. Defaults to OFF
+    /// (original arrow-only behaviour). Persisted.
+    @Published var wasdCamera: Bool =
+        (UserDefaults.standard.object(forKey: "wasdCamera") as? Bool) ?? false {
+        didSet { UserDefaults.standard.set(wasdCamera, forKey: "wasdCamera") }
+    }
+
     // Update state (populated by checkForUpdates).
     @Published var latestEngineVersion: String? = nil
     @Published var latestLauncherVersion: String? = nil
@@ -661,6 +674,11 @@ final class LauncherModel: ObservableObject {
         // GEN_NO_SHELLMAP is applied after INI and sticks.
         env.removeValue(forKey: "GEN_NO_SHELLMAP")
         if disableMenuShellMap { env["GEN_NO_SHELLMAP"] = "1" }
+        // Pan the camera with W/A/S/D as well as the arrow keys (LookAtXlat.cpp).
+        // When on, the engine relocates the A/S/D command-bar shortcuts to
+        // Cmd+A/S/D (HotKey.cpp) so nothing is lost from the keyboard.
+        env.removeValue(forKey: "GEN_WASD_CAMERA")
+        if wasdCamera { env["GEN_WASD_CAMERA"] = "1" }
         proc.environment = env
         proc.terminationHandler = { [weak self] _ in
             Task { @MainActor in

launcher/Sources/GeneralsZHLauncher/PlayTab.swift

@@ -147,6 +147,19 @@ struct PlayTab: View {
                         + "the animated scene. (Sets GEN_NO_SHELLMAP for the engine.)")
                 Spacer()
             }
+            HStack {
+                Toggle("WASD camera controls", isOn: $model.wasdCamera)
+                    .toggleStyle(.checkbox)
+                    .disabled(model.gameRunning)
+                    .help("Pan the battlefield with W/A/S/D as well as the arrow keys "
+                        + "(arrows keep working). Those keys normally do other things — "
+                        + "W selects all aircraft, S stops, A is attack-move, D builds a "
+                        + "dozer, plus the build shortcut on each letter — so while this "
+                        + "is on they move to \u{2318} (Command): \u{2318}W, \u{2318}S, "
+                        + "\u{2318}A, \u{2318}D. Nothing is lost from the keyboard. "
+                        + "Off by default. (Sets GEN_WASD_CAMERA for the engine.)")
+                Spacer()
+            }
             if model.gameRunning {
                 Text("Quit the game to change display settings.")
                     .font(.caption2).foregroundColor(.secondary)