goldeneye-pc-port/tools_pc/abpad/README.md

abpad — 1964 vs PC port A/B input harness

One millisecond timeline drives both sides of a faithful-vs-port comparison:

• 1964 reads a ViGEmBus virtual Xbox 360 pad (vgamepad) through NRage 2.3c in XInput mode. abpad reads NRage's own mapping file and presses whatever Xbox input your profile maps to each N64 input, so you can keep your normal play profile.
• The port is launched with the same timeline converted to its own GE_INPUTSCRIPT (exact N64 bits, works unfocused, reproducible). It does not read the virtual pad. Its default pad layout (Jinx 1.1) maps buttons by context: in a level Y = N64 A and pad A = N64 B, while in menus A/X = N64 A. A single NRage mapping can't follow that switch.

Runs are not frame-identical: 1964 has no seed pin or frame dump, and the port's script counts controller reads, not milliseconds. Use it to compare timing and feel (fire rates, AI reactions, menus), not pixels.

One-time setup

1. ViGEmBus 1.22 installed (it is: Sunshine's driver). pip install vgamepad is done. Note that a plain pip install vgamepad runs its bundled ViGEmBus 1.17 MSI if it doesn't recognise the installed bus. On 2026-10-02 that downgraded the bus and had to be reverted.
2. 1964 → Plugins → Input = NRage_Input_V2.dll (2.3c), Controller 1 with XInput ticked. Any button layout works. abpad inverts plugin/XInput Controller 1 Config.xcc (--nrage-dir, default the ge-port-reference 1964 copy) and errors if a timeline needs an N64 input that the profile leaves unmapped. File format, from NRage's XInputController.cpp (libertyernie/nrage-input):
   • Button keys (A=, Z=, DUp=, ...) are XInput button bitmasks.
   • LeftTrigger=/RightTrigger= are N64 button codes (Z = 0x20, L = 0x2000, ...).
   • Each *Axis= is either the N64 analog axis (0x4000 X, 0x8000 Y) or (positive-direction code << 16) | negative-direction code for a stick used as C or D buttons.
3. The virtual pad must be XInput slot 0. NRage reads N64 controller 1 from XInput slot 0 only, and a real pad that is already connected holds it. Switch the real pad off, or unplug it, before a run. abpad probes slot 0 at startup and refuses to run otherwise.
4. Stick range is handled automatically. The port's script deflects the stick to ±80. abpad computes the thumb value that NRage turns into 80 after its PadDeadZone (21248 at the default 5%); --stick changes the target.
5. 1964.cfg: PauseWhenInactive 0 (set 2026-10-02). Only one window has focus, and 1964 pauses when it's in the background.

Timeline

<ms>:<tok>[,<tok>...] entries separated by ; or newlines; # starts a comment. Times are from harness start.

Tokens	Meaning
A B Z START L R UP DOWN LEFT RIGHT CUP CDOWN CLEFT CRIGHT	50 ms press (the port's INPUTSCRIPT_PULSE_MS)
SUP SDOWN SLEFT SRIGHT (combinable) / SNONE	analog stick, held until changed / recentre
ZHOLD / ZREL	hold / release fire
RHOLD / LHOLD / RREL	hold R or L (one aim hold) / release

Port-only GE_INPUTSCRIPT tokens (MDX/MDY, CHOLD, UHOLD, RELOADHOLD, ...) are rejected. The port caps a script at 64 entries.

Running

The full side-by-side run (PowerShell; the real pad must be off):

tools_pc\abpad\run_ab.ps1 -Timeline "19000:START;25000:SRIGHT;25300:SNONE;27000:SLEFT;27300:SNONE;29000:A" `
    -QuitFrame 2400 -Seconds 36 -Step 0.5
python tools_pc\abpad\sheet.py $env:TEMP\abpad-run 16 36 1   # side-by-side contact sheet

run_ab.ps1 starts abpad (which launches the port), then 1964 with -c NRage_Input_V2.dll -g <Rom> 1.2 s later, and screenshots both windows every -Step seconds on one clock (capture.ps1, DPI-aware PrintWindow, so overlapping windows are fine). 1964's -g takes a file name inside its configured ROM directory and can't contain spaces, so keep a copy such as GoldenEyeUSA.n64 there. The port exits by itself through GE_QUITFRAME; the script closes 1964 normally.

abpad on its own:

python tools_pc/abpad/abpad.py t.txt --print-script   # the port's GE_INPUTSCRIPT
python tools_pc/abpad/abpad.py t.txt --quitframe 2400  # both sides
python tools_pc/abpad/abpad.py t.txt --no-port         # 1964 only
python tools_pc/abpad/abpad.py t.txt --no-pad          # port only

• Port timing: abpad sets GE_INPUTSCRIPT_MS=1, so the port reads entry times as milliseconds since its SDL init instead of controller reads. Read rates vary through the intro and menus, so read counts can't be lined up with 1964. --reads-per-ms converts to a read-count script instead, for exes that don't have the millisecond mode.
• 1964 lags by ~2 s (measured 2026-10-02): the 1.2 s launch gap plus 1964's slower startup. run_ab.ps1 defaults -PadOffset 2000, which delivers each input at the same game state on both sides. The screenshots then show 1964 about 2 s behind the port throughout.
• Menus use the analog stick (SUP/SDOWN/SLEFT/SRIGHT + SNONE), not the D-pad.
• The port is build-pc/ge007.x86_64.exe, launched from the repo root, so it uses the repo's data/ (SkipIntro = 0). build-pc/data has the maintainer's play settings and skips the intro.

Verified 2026-10-02: START during the gun-barrel dots skipped to the title, file select came up, stick right and left moved the folder cursor, and A opened the folder. Both sides went through the same sequence.

Checks before trusting a run

1. With --no-port and a long 0:ZHOLD timeline, NRage's XInput dialog (or 1964 firing in a level) should show the profile's Z input held.
2. The port side needs no pad check. GE_INPUTSCRIPT is the port's sole controller-0 source when set, focused or not.
3. The two sides use different save files (the port's data/ge007.eep, 1964's save/), so file-select contents can differ.

Live A/B (one real pad)

live_ab.ps1 launches 1964 GEPD and the port side by side at 1280x720 each (1964: GLideN64 windowed size; port: data/ge007.ini [Window]; the script only moves windows, never resizes), driven by ONE real gamepad: the port reads it unfocused (GE_PAD_BACKGROUND=1), 1964 gets it on click. 1964 starts ~0.8 s slower, so it launches first and the port follows after -PortDelayMs (tune if the intros drift).

powershell -ExecutionPolicy Bypass -File tools_pc\abpad\live_ab.ps1 [-PortDelayMs 800] [-NoArrange]

The real pad must be ON (no virtual pad), and the NRage profile should match the port's pad layout. -DryRun prints the launch lines without launching.