Troubleshooting

Troubleshooting

The problems the release launcher, the game and the scripts in tools\windows already diagnose, and what each message means. If a message is not listed here, the launcher or script that printed it usually explains itself in the lines that follow.

Release package

Sightline: sightline.exe is not beside this launcher. Extract the whole ZIP.

Sightline.cmd runs sightline.exe from its own folder. Extract the entire ZIP (not just the .cmd) and keep the folder's layout: the executable, the two DLLs, data\ and LICENSES\ all sit beside the launcher.

The launcher asks for a ROM path

Sightline.cmd looks for your ROM at SL_ROM, then the first *.z64 beside the launcher, then the path it remembered from an earlier run (%LOCALAPPDATA%\sightline\rom-path.txt). If none exists it asks once. The simplest setup is to copy your .z64 into the extracted folder, beside Sightline.cmd. If you previously typed a path and the file has since moved, delete rom-path.txt or put the ROM beside the launcher.

Sightline: "<file>" is <N> bytes; a GoldenEye 007 (USA) .z64 dump is 12582912.

The launcher checks the size before starting the game. A different size is usually still an archive (Sightline does not read archives; extract it first), a different region, or a file with a header added. See ROM Setup.

sightline ucode: cannot derive the audio microcode tables from the ROM: ...

The game checks the ROM at start-up and stops with this message on the console when the file is wrong. The reason follows the colon:

• the file does not start with the big-endian .z64 magic (a .n64 / .v64 dump is byte-swapped; convert or re-dump) — the dump is byte-swapped. Convert it to a big-endian .z64 with a ROM tool, or re-dump.
• no 1172 container header at ROM 0x21990 (not a GoldenEye 007 (U) image) — a different game or region.
• ... has SHA-1 ..., not the supported dump's (a patched or corrupt ROM) — a modified or damaged dump. Only the unmodified NTSC-U dump is supported.

Sightline ships no ROM-derived data: the two audio-microcode tables are read out of your own dump at start-up, and there is no fallback table, so a ROM that fails these checks cannot run.

Sightline.cmd opens no window when sightline.exe is run directly

Running sightline.exe on its own is not the supported path: without the launcher's environment it opens no window and finds no ROM. Use Sightline.cmd.

name.z64.z64 — the hidden-extension trap

Windows Explorer hides known extensions by default, so renaming an extracted 007 - GoldenEye (USA).z64 in Explorer can silently produce name.z64.z64. The release launcher still finds it (it takes the first *.z64 beside itself), but baserom.u.z64 in a source checkout will not be found. Check the real name in PowerShell:

Get-ChildItem .\*.z64

Checking the ROM yourself

(Get-Item .\your.z64).Length                    # 12582912
(Get-FileHash .\your.z64 -Algorithm SHA1).Hash  # ABE01E4AEB033B6C0836819F549C791B26CFDE83

Size and hash must both match; a wrong hash with the right size usually means a byte-swapped or modified dump. On Linux, make verify-rom tests size, magic, region and hash separately and names the actual cause.

Verifying the download

(Get-FileHash .\Sightline-v0.3.0-win32.zip -Algorithm SHA256).Hash

must equal the hash in Sightline-v0.3.0-win32.zip.sha256 from the release page (substitute the version you downloaded). VERSION.txt inside the package lists the SHA-256 of every shipped file, including sightline.exe.

COMMUNITY HD or XBLA looks exactly like ORIGINAL

The selected set was not found, so every texture falls back to the game's own. The console says which folder was looked for, once per run:

sl_texprov: TEXTURES=COMMUNITY HD root=...\sightline\assets\texpacks (player data) set-folder=...\texpacks\community NOT FOUND - every texture falls back to ORIGINAL

• Release package: run Get-Textures.cmd (COMMUNITY HD). XBLA needs a texture pack and world assets prepared with a source checkout and written to %LOCALAPPDATA%\sightline\assets\texpacks and ...\worldassets (the -TexturesOut / -WorldOut parameters of prepare-all.ps1).
• Source checkout: run .\tools\windows\prepare-all.ps1 and launch with play.ps1, which points the game at the checkout's texpacks\ and worldassets\.

A texture the pack does not cover is always drawn as the game's own, so a COMMUNITY HD scene can mix both; that is expected.

FRAME RATE is set higher but the counter stays at the game's rate

Extra frames are drawn only when one fits before the next game frame and the camera pair is continuous. A view too heavy to draw twice in a game frame (dense XBLA views, for one), VSYNC on a 60 Hz display, a camera cut or a minimised window all present at the game's own rate. Try ORIGINAL or COMMUNITY HD, or turn VSYNC off, to see the extra frames.

Controls and settings

The mouse does not look around

In play the pointer is not captured until you click in the window. That first click only captures; it does not fire. Alt-tabbing away releases the pointer until you come back, and opening the watch (Tab or Esc) gives it back on purpose. If you want the pointer never taken at all — for example to play on the keyboard alone — set SL_MOUSE=0 in the environment before launching.

Esc does not quit

By design. Tab and Esc open the watch. To quit, use 4. QUIT GAME on the main menu or close the window (the X, or Alt+F4).

A key or button does nothing, or does the wrong thing

Check the binding table: OPTIONS → SETTINGS → CONTROL → BINDINGS on the front end, or the watch's SIGHTLINE → BINDINGS in a mission. A source can sit in one slot only, so binding a key that another action held empties that slot (TAKEN FROM ...). RESET DEFAULTS restores the compiled defaults for the bindings alone. On a controller, Y / Triangle and R3 are unbound in the DEFAULT layout and shown as UNBOUND; the bumpers mirror the triggers and the d-pad carries the weapon cycle and the zoom. See Running the Game.

Left Shift does not sprint

SPRINT is off by default (the cartridge's movement). Switch it on under OPTIONS → SETTINGS → GAMEPLAY.

Settings do not survive a restart

The native settings live in %LOCALAPPDATA%\sightline\config.ini, written whenever a value changes. The cartridge's own options (per save folder) live in %LOCALAPPDATA%\sightline\eeprom.bin. A missing or unwritable config.ini is not fatal: the game runs from defaults, and a malformed value falls back to that setting's default.

The window is wider than expected

The ASPECT RATIO setting decides the window's width from its height: 960x720 at 4:3 becomes 1280x720 at 16:9, 1680x720 at 21:9 and 2560x720 at 32:9. SL_WINDOW_SIZE names only the initial (4:3) window. Change the aspect under OPTIONS → SETTINGS → DISPLAY.

Source checkout

sightline: no ROM at '...'

play.ps1 and test.ps1 look for the ROM at SL_ROM, falling back to baserom.u.z64 in the repository root, and stop with this message when neither exists. Nothing ROM-derived ships in the repository, so there is no fallback. Either copy your dump to baserom.u.z64 or set SL_ROM:

$env:SL_ROM = "D:\Games\GoldenEye\baserom.u.z64"

setup.ps1 reports the ROM too (ROM (for play.ps1)), but a missing ROM is not a build failure — build.ps1 does not read it. See ROM Setup.

setup.ps1 reports MISS on a toolchain component

setup.ps1 without arguments only reports. Each MISS line names what is missing and the summary lists the packages that would fix it:

.\tools\windows\setup.ps1 -Install       # installs them with pacman
.\tools\windows\setup.ps1 -Install -Yes  # without prompting

If MSYS2 itself is not found, install it (winget install --id MSYS2.MSYS2) or name where it lives with -Msys2Root <path> or SL_MSYS2_ROOT. A named root is authoritative; the script will not fall back to another installation.

matching-build map build\u\ge007.u.map is absent

setup.ps1 still reports this line, but build.ps1 no longer reads the raw map: it places symbols from the tracked extraction tools\native\ge007.u.linkmap.txt, which is in the clone. You can build without the matching build. See Building.

build.ps1: missing ...ge007.u.linkmap.txt

The tracked link-map extraction is not where build.ps1 expects it (or SL_LINKMAP points somewhere wrong). It is part of the repository; restore it from Git.

sightline: no Python to resolve the level name with

play.ps1 -Level <name> and test.ps1 resolve the level name through tools\native\levelstage.py, so they need a Python interpreter: .venv\Scripts\python.exe, the path in SL_PYTHON, or python.exe on PATH. Create the repository venv with python -m venv .venv, or set SL_PYTHON. setup.ps1 reports which Python it found under python.

sightline: unknown level '<name>'

The name is not one the resolver knows. Use the harness names — facility, dam, runway, surface, bunker1, silo, archives, and so on; the full list is in Running the Game.

test.ps1 fails with no survived line

The headless acceptance passes only when the binary itself prints sightline native: survived <N> pumped frames and exits 0. A run that exits 0 without that line, or that has not exited within -TimeoutSeconds (default 180), is reported as a failure. On failure test.ps1 prints the tail of the run's output and the path of the full log under build\win32\tmp\.

Related

• Releases
• Getting Started
• Running the Game