@@ -40,10 +40,9 @@ The game boots, reaches the menus, and races are playable with sound.
 
 ### Known limitations
 
-- **Exactly one build of `SPEED2.EXE` is supported**, the European v1.2 one
-  (see [Game versions](#game-versions)).
-  Game addresses are hard-coded in the runtime, and the pipeline relies on a
-  property of that particular file (below).
+- **Two builds of `SPEED2.EXE` are supported**, the European and the North
+  American v1.2 ones (see [Game versions](#game-versions)); each has its own
+  engine. Other builds would need their own lifting pass and address map.
 - Videos are skipped: there is no VP6 decoder.
 - Keyboard and mouse only; no gamepad or wheel support. No network play.
 - Structured exception handling is not implemented (`RtlUnwind` /
@@ -154,27 +153,27 @@ HD build draws about 18 W.
 - Xcode Command Line Tools (`clang`; `swiftc` for the launcher window).
 - Python 3 with `capstone` 5.x and `pefile` (`requirements.txt`).
 - Rosetta 2, only for `tools/fuzzisa.py`.
-- Your own installation of the game, with this exact executable:
+- Your own installation of the game, with one of these executables (both v1.2
+  without the CD check, built Feb 9 2005):
 
-  | | |
-  |---|---|
-  | File | `SPEED2.EXE`, 4,788,224 bytes |
-  | Build | **European** (PAL) v1.2 executable without the CD check, built Feb 9 2005 |
-  | SHA-256 | `8f6a9ae2c4cfa01181d2fd755d99c6f4b7103f60273908ea1de1e719dfe2a297` |
+  | Build | `SPEED2.EXE` size | SHA-256 |
+  |---|---|---|
+  | **European** (PAL) v1.2 | 4,788,224 bytes | `8f6a9ae2c4cfa01181d2fd755d99c6f4b7103f60273908ea1de1e719dfe2a297` |
+  | **North American** v1.2 | 4,800,512 bytes | `f9dd86c054878ce6276beb07c1fd61874f7a1e4bf1f241b084c65b73e24168a7` |
 
-  The app checks the file at startup and says so instead of crashing;
-  `NFSU2_ANY_EXE=1` skips the check.
+  The app checks the file at startup, picks the matching engine and says so
+  instead of crashing on any other file; `NFSU2_ANY_EXE=1` skips the check.
 
 ### Game versions
 
-The recompiled code and the addresses in the runtime belong to one executable,
-so every other build of `SPEED2.EXE` needs its own lifting pass and address
-table. The game *data* is a separate matter (see the note under the table).
+The recompiled code belongs to one executable, so every build of `SPEED2.EXE`
+gets its own lifting pass and engine. The game *data* is a separate matter (see
+the note under the table).
 
 | `SPEED2.EXE` | Size | SHA-256 | Status |
 |---|---|---|---|
-| European v1.2, no CD check | 4,788,224 | `8f6a9ae2c4cfa01181d2fd755d99c6f4b7103f60273908ea1de1e719dfe2a297` | **Supported** |
-| North American v1.2, no CD check (the build most PC mods target) | 4,800,512 | `f9dd86c054878ce6276beb07c1fd61874f7a1e4bf1f241b084c65b73e24168a7` | Not supported yet. Same Feb 9 2005 build; the data addresses match ours, the code is shifted by small amounts. Planned. |
+| European v1.2, no CD check | 4,788,224 | `8f6a9ae2c4cfa01181d2fd755d99c6f4b7103f60273908ea1de1e719dfe2a297` | **Supported** (the reference build) |
+| North American v1.2, no CD check (the build most PC mods target) | 4,800,512 | `f9dd86c054878ce6276beb07c1fd61874f7a1e4bf1f241b084c65b73e24168a7` | **Supported** (engines `nfsu2-engine-na`, `-na-hd`). Tested on US disc data from the menus into a Quick Race, original and HD. |
 | US v1.0 retail disc | 5,987,981 | `2cbd698fee8338a13d1891bc17d27e6641b4b9dd40580de818594b9140222899` | **Cannot be supported.** Protected by SafeDisc: the code section is encrypted on disc and only decrypted at run time, so there is nothing to recompile. |
 
 The retail disc executable carries the disc's copy protection, and the official
@@ -210,10 +209,36 @@ python3 tools/install_from_discs.py ~/Games/NFSU2 "Disc 1.cue" "Disc 2.cue"
 ```
 
 This writes a normal game folder (about 1.7 GB) that the launcher can point at.
-It copies the disc's `SPEED2.EXE` too, but see the table above: the launcher
-accepts only the supported executable. With that executable in the folder, the
-US disc data plays in the US region (see "US data works with the supported
-executable" above).
+It copies the disc's `SPEED2.EXE` too, but see the table above: the disc
+executable cannot run, so put a supported one in its place. The North American
+v1.2 executable is the natural match for US disc data; the European one also
+works with it (see "US data works with the supported executable" above).
+
+### How the North American build is made
+
+The European executable is the reference: the runtime was written against it.
+`tools/addrmap.py` matches the two executables function by function (a byte
+signature with the parts that move between builds masked, aligned in order) and
+collects data-address pairs from the matched code: 23,276 of 23,277 functions
+match, most code is 16 bytes away from the European build, most data is at the
+same address. Every game address in the runtime is written as `GA(0x…)` in
+European terms; for the North American engine `runtime/build_na.h` (generated
+from the map) turns each one, and each `sub_XXXXXXXX` name the runtime uses, into
+the North American one. An address the map cannot place stops the build.
+
+Two things differ at run time:
+
+- The North American no-CD executable still looks for a CD-ROM drive (its disc
+  contents check is patched out, the drive check is not) and otherwise asks for
+  "Disc 2" forever. Its engine reports `D:` as an empty CD-ROM drive; paths on
+  `D:` resolve to the game folder like those on `C:`.
+- Its region variable is in `.bss` (0, the US) rather than a constant, see
+  "US data works with the supported executable".
+
+Function discovery missed eight call targets in this executable (its linear scan
+stops on bytes an earlier, misaligned scan covered), which became traps;
+`LIFT_MISSING=1` (set by `tools/gen_v2.sh` for this build) lifts such targets in
+extra shards.
 
 ## Build and run
 
@@ -243,6 +268,22 @@ tools/gen_v2.sh "$EXE"
 ./pack.sh --embed    # out/personal/NFSU2.app with your game inside (do not share)
 ```
 
+For the North American v1.2 executable the same steps build a second pair of
+engines; `tools/gen_v2.sh` recognises the file by its SHA-256 and writes `gen/na`,
+`run.sh` picks the engine by the executable, and `pack.sh` adds the engines to the
+app when they are built:
+
+```bash
+tools/gen_v2.sh "/path/to/NA/SPEED2.EXE"       # -> gen/na
+BUILD=na ./build.sh && BUILD=na ./link.sh       # -> out/nfsu2_na_boot, out/nfsu2_na_hd_boot
+```
+
+`runtime/build_na.h` is committed. `link.sh` regenerates it from
+`out/na/addrmap.json` when that file exists, which takes both executables:
+`tools/addrmap.py build <European SPEED2.EXE> <North American SPEED2.EXE> out/na/addrmap.json`.
+Do this after adding a `GA(...)` address or a `sub_` name to the runtime; game
+addresses written without `GA(...)` would be wrong in the North American engine.
+
 The app opens a small launcher window first (`launcher/`, built by `pack.sh`
 with `swiftc`): it finds and checks `SPEED2.EXE`, offers Original or HD graphics
 and full screen, opens the saves and logs folders, and **Make Copy…** builds a
@@ -297,10 +338,10 @@ game files inside (about 1.4 GB). It runs on its own; saves stay in
 so keep it for yourself.
 
 **Which version of the game does it need?**
-The Windows PC version, with the European v1.2 `SPEED2.EXE` listed under
-[Requirements](#requirements). The North American v1.2 executable is not
-supported yet; the US v1.0 disc executable cannot be (it is copy-protected).
-Console versions are not supported. See [Game versions](#game-versions).
+The Windows PC version, with the European or the North American v1.2
+`SPEED2.EXE` listed under [Requirements](#requirements). The US v1.0 disc
+executable cannot be supported (it is copy-protected). Console versions are not
+supported. See [Game versions](#game-versions).
 
 **I only have the PC discs. Can I install them on a Mac?**
 Yes, without Windows: `tools/install_from_discs.py` unpacks the disc images
 
@@ -19,8 +19,15 @@ MINOS="${MINOS:-11.0}"
 # without the flag clang's GVN can miscompile it.  See LIFTER_EFFICIENCY.md section 4.
 OPT="${OPT:--O3 -mcpu=$MCPU -mmacosx-version-min=$MINOS -fno-strict-aliasing}"
 J="${J:-$(sysctl -n hw.ncpu)}"
-mkdir -p "$ROOT/out/obj"
-cd "$ROOT/gen/all"
+# BUILD=eu (default): gen/all -> out/obj    BUILD=na: gen/na -> out/obj_na
+# (North American v1.2 executable; see README "Game versions", tools/gen_v2.sh)
+case "${BUILD:-eu}" in
+  eu) GEN=gen/all; OBJ=out/obj ;;
+  na) GEN=gen/na;  OBJ=out/obj_na ;;
+  *)  echo "BUILD must be eu or na"; exit 1 ;;
+esac
+mkdir -p "$ROOT/$OBJ"
+cd "$ROOT/$GEN"
 # DON'T EMBED $OPT in the xargs command line: the length of a line built with
 # -I{} is limited ("command line cannot be assembled, too long").  Pass it in
 # from the environment and let the inner shell expand it.
@@ -31,11 +38,11 @@ cd "$ROOT/gen/all"
 # returned 0 -> the link broke with "symbol(s) not found".  The output is first
 # captured in a variable, then truncated; clang's exit code is kept (if any shard
 # fails to compile, xargs and therefore build.sh return an error).
-export OPT ROOT
+export OPT ROOT OBJ
 ls shard_*.c fntab.c stubs.c 2>/dev/null | \
   xargs -P "$J" -n 1 sh -c '
     o=$(clang $OPT -c -I"$ROOT/runtime" -I. -Wno-unused-label -Wno-parentheses-equality \
-          -o "$ROOT/out/obj/$(basename "$1" .c).o" "$1" 2>&1); r=$?
+          -o "$ROOT/$OBJ/$(basename "$1" .c).o" "$1" 2>&1); r=$?
     [ -z "$o" ] || printf "%s\n" "$o" | head -5
     [ $r -eq 0 ] || echo "COMPILE FAILED: $1" >&2
     exit $r' sh
@@ -7,15 +7,28 @@
 import Foundation
 import CryptoKit
 
+/// A build of SPEED2.EXE the port has an engine for (README "Game versions").
+struct ExeBuild: Equatable {
+    let name: String
+    let size: UInt64
+    let sha256: String
+    let engineSuffix: String      // Contents/MacOS/nfsu2-engine<suffix>[-hd]
+}
+
 enum SupportedExe {
-    static let size: UInt64 = 4_788_224
-    static let sha256 = "8f6a9ae2c4cfa01181d2fd755d99c6f4b7103f60273908ea1de1e719dfe2a297"
+    static let builds = [
+        ExeBuild(name: "European v1.2", size: 4_788_224,
+                 sha256: "8f6a9ae2c4cfa01181d2fd755d99c6f4b7103f60273908ea1de1e719dfe2a297", engineSuffix: ""),
+        ExeBuild(name: "North American v1.2", size: 4_800_512,
+                 sha256: "f9dd86c054878ce6276beb07c1fd61874f7a1e4bf1f241b084c65b73e24168a7", engineSuffix: "-na"),
+    ]
     static let names = ["SPEED2.EXE", "speed2.exe", "Speed2.exe"]
 }
 
 struct GameLocation: Equatable {
     let exe: URL
     let embedded: Bool
+    var build: ExeBuild? = nil    // set by Locator.check
     var folder: URL { exe.deletingLastPathComponent() }
 }
 
@@ -35,6 +48,16 @@ enum Paths {
     static var saves: URL { home.appendingPathComponent("Library/Application Support/NFSU2 Saves") }
     static var logs: URL { home.appendingPathComponent("Library/Logs/NFSU2") }
     static var registry: URL { home.appendingPathComponent(".nfsu2_registry") }
+
+    /// The engine binary for a build of SPEED2.EXE (nil: the European one).
+    static func engine(_ build: ExeBuild?, hd: Bool) -> URL {
+        macOS.appendingPathComponent("nfsu2-engine" + (build?.engineSuffix ?? "") + (hd ? "-hd" : ""))
+    }
+    static func hasEngine(_ build: ExeBuild?) -> Bool {
+        let fm = FileManager.default
+        return fm.isExecutableFile(atPath: engine(build, hd: false).path)
+            || fm.isExecutableFile(atPath: engine(build, hd: true).path)
+    }
 }
 
 enum Prefs {
@@ -102,17 +125,24 @@ enum Locator {
         ((try? FileManager.default.attributesOfItem(atPath: u.path))?[.size] as? NSNumber)?.uint64Value ?? 0
     }
 
-    /// true when this is the one SPEED2.EXE the port was built from.
-    static func isSupported(_ exe: URL) -> Bool {
-        if ProcessInfo.processInfo.environment["NFSU2_ANY_EXE"] == "1" { return true }
-        guard fileSize(exe) == SupportedExe.size,
-              let data = try? Data(contentsOf: exe, options: .mappedIfSafe) else { return false }
+    /// Which supported build this SPEED2.EXE is, if any.
+    static func identify(_ exe: URL) -> ExeBuild? {
+        let size = fileSize(exe)
+        guard SupportedExe.builds.contains(where: { $0.size == size }),
+              let data = try? Data(contentsOf: exe, options: .mappedIfSafe) else { return nil }
         let hex = SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined()
-        return hex == SupportedExe.sha256
+        return SupportedExe.builds.first { $0.sha256 == hex }
     }
 
+    /// Ready when the file is a supported build and this app has its engine.
     static func check(_ loc: GameLocation) -> GameState {
-        isSupported(loc.exe) ? .ready(loc) : .unsupported(loc, fileSize(loc.exe))
+        var l = loc
+        l.build = identify(loc.exe)
+        if l.build == nil && ProcessInfo.processInfo.environment["NFSU2_ANY_EXE"] == "1" {
+            l.build = SupportedExe.builds[0]
+        }
+        guard let b = l.build, Paths.hasEngine(b) else { return .unsupported(l, fileSize(loc.exe)) }
+        return .ready(l)
     }
 }
 
 
@@ -29,18 +29,16 @@ final class LauncherModel: ObservableObject {
     var isCopying: Bool { builder != nil }
     private var quitWhenCopyStops = false
 
-    let hasOriginal: Bool
-    let hasHD: Bool
-    var canChooseEngine: Bool { hasOriginal && hasHD }
-
-    static func engineURL(_ e: Engine) -> URL {
-        Paths.macOS.appendingPathComponent(e == .hd ? "nfsu2-engine-hd" : "nfsu2-engine")
+    /// Engines for the found SPEED2.EXE (European ones until it is known).
+    func hasEngine(_ e: Engine) -> Bool {
+        FileManager.default.isExecutableFile(atPath: Paths.engine(location?.build, hd: e == .hd).path)
     }
+    var canChooseEngine: Bool { hasEngine(.original) && hasEngine(.hd) }
 
     init() {
         let fm = FileManager.default
-        hasOriginal = fm.isExecutableFile(atPath: Self.engineURL(.original).path)
-        hasHD = fm.isExecutableFile(atPath: Self.engineURL(.hd).path)
+        let hasOriginal = fm.isExecutableFile(atPath: Paths.engine(nil, hd: false).path)
+        let hasHD = fm.isExecutableFile(atPath: Paths.engine(nil, hd: true).path)
         defaults.register(defaults: [Prefs.showAtStartup: true])
         var e = Engine(rawValue: defaults.string(forKey: Prefs.engine) ?? "") ?? .original
         if let env = ProcessInfo.processInfo.environment["NFSU2_ENGINE"], let f = Engine(rawValue: env) { e = f }
@@ -111,7 +109,9 @@ final class LauncherModel: ObservableObject {
         if !engineForced { defaults.set(engine.rawValue, forKey: Prefs.engine) }
         defaults.synchronize()
         if !fromEnv { setenv("NFSU2_DATA", loc.exe.path, 1) }
-        let path = Self.engineURL(engine).path
+        var e = engine
+        if !hasEngine(e) { e = (e == .hd) ? .original : .hd }
+        let path = Paths.engine(loc.build, hd: e == .hd).path
         // A child process, not exec(): macOS attributes the child's file access to
         // this launcher (the "responsible" process), so folder permissions the
         // player granted here (Downloads, Documents...) are not asked for again.
 
@@ -74,11 +74,15 @@ struct GameCard: View {
             return (Theme.warn, "Game files not found",
                     "Choose the folder where Need for Speed Underground 2 is installed (the folder with SPEED2.EXE in it). Your own copy of the PC game is needed.")
         case .ready(let l):
-            return (Theme.accent, l.embedded ? "Ready · the game is inside this app" : "Ready · supported version",
+            return (Theme.accent, l.embedded ? "Ready · the game is inside this app" : "Ready · \(l.build?.name ?? "supported version")",
                     l.embedded ? "This is a portable copy: it needs no separate game folder." : l.folder.path)
         case .unsupported(let l, let size):
+            if let b = l.build {
+                return (Theme.bad, "No engine for this version in this app",
+                        "\(l.folder.path) has the \(b.name) SPEED2.EXE, but this copy of the app has no engine for it. Use a release that includes it.")
+            }
             return (Theme.bad, "This SPEED2.EXE is a different version",
-                    "Found \(formatBytes(Int64(size))) at \(l.folder.path). The port runs only the European v1.2 SPEED2.EXE without the CD check (4,788,224 bytes); other versions, such as the US one, would crash.")
+                    "Found \(formatBytes(Int64(size))) at \(l.folder.path). The port runs the European v1.2 (4,788,224 bytes) and North American v1.2 (4,800,512 bytes) SPEED2.EXE without the CD check; other versions, such as the US disc one, would crash.")
         }
     }