PGR4-Recomp v2 (Windows PC and Steam Deck)
===========================================

Well, its that time, v2 is FINALLY out! A HEAP of features have been implemented, such as:
* Native Rendering (D3D12) - up to 4K internal resolution, ultrawide (21:9 / 32:9) and HDR output
* Online Multiplayer (something may be changing related to that soon...) - no VPN needed, public and private rooms, System Link and Xbox LIVE modes
* Local Multiplayer
* A CUT 4 Player split screen feature!
* Title Update & DLC Support - just drop the files on the launcher
* Wheel support - pedals, shifters, button boxes, and remappable wheel buttons
* Controller button remapping
* Adjustable FOV + chase camera height
* Internal digital dash for interior view
* FXAA + MSAA Support
* Frame rate limit (30 / 60 / 120 / unlimited) + a VSync toggle, with fixes for the race clock, camera shake and manual shifting at high frame rates
* Radio fully fixed - With custom music support (MP3, WMA, FLAC, OGG, WAV, APE, TTA and SACD rips), plus a song tag editor in the launcher
* Menu music volume slider (yes, it was too loud)
* Preliminary Online Voice Chat support (only with the people in your lobby), along with message support and friend message support!
* An Xbox 360-style Guide - friends, recent players, game invites, room chat and the proper 360 on-screen keyboard (or just type on your PC keyboard)
* Online leaderboards
* Geometry Wars is playable from the in-game arcade
* In-game settings menu (Game Adjustments) for all the new options
* A brand new launcher - extracts your PGR4 disc image (.iso) for you, and now updates itself when a new release is out
* Steam Deck / Linux (Proton) support

Everything below explains how to set it up and use it.

You need
--------
- Your own copy of Project Gotham Racing 4: either the extracted game
  folder (with default.xex in it) or your disc image (.iso). The
  launcher can extract the .iso for you (see below).
- Title Update #2 for PGR4 (a file named TU_16L61VP_...).
- Optional: DLC packs you own (e.g. Vehicle Pack 1).

Nothing else needs installing. The C++ runtime DLLs are included.


Windows PC
----------
1. Unzip this folder anywhere.
2. Run pgr4_launcher.exe.
3. Play tab: click Browse... and pick your PGR4 game folder.
   Only have a disc image? Drag your PGR4 .iso onto the launcher window
   (or onto pgr4_launcher.exe, or click "From ISO..."). It copies the game
   files into a folder next to the .iso, or one you choose, and sets
   that as the game folder. This needs about 7 GB free. The .iso
   isn't changed, so you can delete it afterwards if you like.
4. Content tab: click "Add packages..." and pick the Title Update file
   (and any DLC). They are copied into the game folder's Content folder
   and installed the first time the game starts.
5. Click Play.

The Graphics tab lets you pick a GPU and the shader type. Leave Shaders on
Auto unless the game shows a white or broken screen. Then try the other
one and tell us which worked.


Steam Deck
----------
1. In Desktop Mode, copy this folder to the Deck (e.g. ~/Games/PGR4) and
   your PGR4 game files somewhere too (e.g. ~/Games/PGR4-Files).
2. Steam > Games > "Add a Non-Steam Game to My Library..." and choose
   pgr4_launcher.exe from this folder (pick "All Files" if it isn't listed).
3. In Steam, open the new entry's Properties > Compatibility, tick
   "Force the use of a specific Steam Play compatibility tool" and choose
   Proton Experimental (or Proton 9 or newer).
4. Launch it once in Desktop Mode to set it up:
   - Play tab > Browse...: your game folder appears under Z:\home\deck\...
     (or "From ISO..." to extract your disc image).
   - Content tab > Add packages...: pick the Title Update (and DLC).
5. After that it works from Gaming Mode with the controller:
   D-pad / left stick to move, A to select, B to go back,
   LB / RB to switch tabs, Start to play.

If the game doesn't start from the launcher in Gaming Mode, set the Steam
entry's target to pgr4_recompiled.exe instead and add these launch options
(using your own game folder path):

  --game_data_root "Z:\home\deck\Games\PGR4-Files"


Multiplayer (new)
-----------------
Split-screen for 3 and 4 players (new): plug in 3 or 4 controllers; they
sign in as extra players and Multiplayer > Play on this Xbox 360 console
takes them all. With 3 players, player 1 gets the whole top half and
players 2 and 3 share the bottom (set split3_wide to false for the old
quarters, with the bottom-right one empty).
Split-screen: plug in a second controller. It signs in as "Player 2"
automatically, and you can start a 2-player split-screen race.

System Link (two PCs, or PC + Steam Deck):
- Same home network: nothing to set up. One player hosts a System Link
  race, the other finds it.
- Over the internet: use Hamachi, ZeroTier, Radmin VPN (Windows) or
  Tailscale (works on the Deck). In the launcher's Advanced tab set
  net_bind_address to this machine's VPN address (Hamachi: 25.x.x.x).
- If the host doesn't show up: set net_broadcast_targets to the OTHER
  machine's address (on both machines), e.g. 25.1.2.3. Tailscale always
  needs this.
- Allow pgr4_recompiled.exe through Windows Firewall, on Public networks
  too (Windows treats VPN adapters as Public).
Online play over the internet (no VPN, new):
- On by default now (net_transport = eos): the game joins the online
  room by itself. Set net_transport to lan (launcher Advanced tab, or
  --net_transport=lan) to play System Link on your own network only.
- Leave net_room EMPTY to join the public online room: everyone playing
  online without a code meets there, for System Link and Xbox Live
  matches alike.
- Set net_room to a code (e.g. pgr4-bea-race) for a PRIVATE room: only
  players with exactly the same code can see and join your games.
- Then host / join through System Link or Xbox Live as usual. Epic Online
  Services connects the PCs (through Epic's relay if needed), so no
  Hamachi or port forwarding.
- The log shows "eos: virtual IP 10.77.0.x" once you're in a room.
- Xbox Guide: press the Guide (Xbox) button, Back + Start together, or
  Enter on the keyboard, at any time (Start on the keyboard is now X only).
  It works like the Xbox 360 one:
    LB / RB (or left / right)  switch blades: Friends, you, Recent Players,
                               Online Room
    A  select      B  back / close      Guide  close
  The game pauses its input while the Guide is open.
  Pick a player to Join Game, Invite to Game or Add / Remove Friend
  (friends are saved in friends.txt next to the exe).
- Your gamertag: set it in the launcher (Play tab) or in the Guide >
  Change Gamertag. Both save it in gamertag.txt next to the game, so it
  sticks even when the game is started without the launcher (Steam Deck).
  Other players see a new name straight away; saves and settings stay.
  Extract the zip before running: settings can't be saved from inside it.
- Private rooms from the Guide (Online Room):
    Make a Private Room  suggests a code (keep it or type your own), checks
                         nobody uses it yet, then puts you in a new room
                         with that code. Share the code with friends.
    Join a Private Room  type the code your friends gave you.
  The on-screen keyboard works with the pad (Done = Start) or just type
  on your keyboard. In chat and messages, LT (or the Symbols key) opens
  the Symbols page and RT (Alphabet) goes back.
  "Go to the Public Room" goes back. Codes ignore
  upper/lower case. Change rooms from the menus, not mid-race.
- Invites: you get a notice at the bottom of the screen. Open the Guide >
  Game Invites to accept or decline (invites last 10 minutes).
- Notices also show when friends come online / go offline.
- If the Guide button opens Windows' Game Bar instead, turn off "Open Xbox
  Game Bar using this button on a controller" in Windows Settings > Gaming,
  or use Back + Start. On Steam Deck use Back + Start, or map a spare
  button (a back grip) to the Enter key in Steam Input (Steam keeps the
  Steam button).

System Link is new and untested between two machines; please send the
logs from both if it doesn't connect.


Chat, messages and voice (new)
------------------------------
Everything here is in the Guide (Guide button, or Enter on the keyboard).
This build has its own online rooms: players on older builds won't see you
or your games, so everyone should update.

Room chat: Online Room > Room Chat > Send a Message, type, then Enter (or
Start on a controller). Messages from the room pop up at the bottom as
"Name: message"; Room Chat lists them.

Messages (like the 360's): pick a player (Online Room, Friends or Recent
Players) > Send Message. It waits for them if they're offline. New ones pop
up as "Message from ..."; Guide or Enter opens it, with Reply. The Guide's
Messages row lists them, along with announcements from the PGR4-Recomp team
and the messages you sent ("To <name>").

Voice chat (off until you turn it on): Online Room > Voice Chat: On. You hear
(and are heard by) the players in your game lobby, Xbox LIVE or System Link,
not everyone in the room (open mic). Y in the Guide mutes / unmutes your mic
while still hearing others ("Mic muted" shows top right). Pick your mic under
Online Room > Microphone, and mute someone from their player page. Whoever
is talking shows in the top-right corner, you included. Rooms with voice
hold up to 16 players (an Epic limit); a full room sends you to another.
Settings are remembered in voice.txt. Needs xaudio2_9redist.dll (included).


In-game settings (new)
----------------------
Options and the pause menu now have GAME ADJUSTMENTS. Its first row,
Category, picks what the page shows:
  Display        HDR output, HDR brightness and highlights, field of view
                 (50% - 300%), chase camera height (25% - 300%),
                 rendering resolution (720p - 4K, supersampling) and
                 multisampling (MSAA 2x / 4x / 8x), both after a restart,
                 anti-aliasing (FXAA), frame rate limit, and "Speedometer (in-car
                 view)": the chase view's speed / rev dial, shown in the
                 cockpit view too
                 "Kudos display position": Default, Top in in-car view
                 (only the view with the big dials; the cockpit view is
                 left alone) or Top (every view). At the top the Kudos
                 combo sits over the rear-view mirror instead of above
                 the middle of the screen. Set kudos_hud_top (launcher
                 Advanced tab, default 0.11) to move it higher or lower.
  Controller buttons  what each controller button does (A, B, bumpers,
                 triggers, Back, Start, D-pad...), or None
  Wheel          steering / accelerator / brake axis, pedals at rest,
                 steering sensitivity and dead zone, reverse steering
  Wheel buttons  which wheel button gives each pad button (A, B, bumpers,
                 triggers, Back, Start, D-pad...)
  Music          Custom soundtrack: Off / Mixed with stations / Custom only
                 (from the next race; see "Custom soundtrack" below), and
                 Menu music volume (Off - 100%, applied at once; "Game's
                 setting" leaves the profile's own)
  Developer      Debug menu: with it on, press Y on the title screen
                 ("Press START") for the developers' race setup (any city,
                 route, weather, race mode, up to 4 split-screen players).
                 RT there opens the car screen; start the race with A on
                 the CAR screen, not the first one (A on the first screen
                 starts without cars set up and the car flies off at the
                 first bump).
                 3-4 viewports now work (each its own car); viewports 3
                 and 4 have no minimap and no light glows yet, and their
                 speed bar may be missing.
Up / down picks a row, left / right changes it, A saves, B leaves it
unchanged. The page follows the game's language.
Choices are saved in pgr4_recompiled.toml next to the game. Settings passed
by the launcher (its Frame Rate Limit, and anything in the Advanced tab) win
at start-up, so leave those empty if you set them in game.
Wheel numbers count across all parts (wheel base first, then pedals and
shifter). If you don't know which axis is which, set hid_wheel_log_axes =
true in the launcher: the log then names every axis and button you move.


Custom soundtrack (new)
-----------------------
Play your own music on the in-race radio: MP3, WMA, FLAC, OGG (Vorbis), WAV,
APE (Monkey's Audio), TTA (TrueAudio) and SACD rips as DSF / DFF files (SACD
.iso images aren't supported). In the launcher's Music tab:
- Pick Mixed (your songs added to the game's stations) or Custom only.
- Choose your music folder (default: the "Music" folder next to the game;
  "Open" creates it). Files in the folder play on every station; each
  subfolder (sorted by name) plays on the next station, so you can make
  your own stations.
- The song list shows each song's artist / title / album from its tags
  (or its file name, e.g. "Artist - Title.mp3"). Pick a song to type your
  own artist, title or album; "IN GAME" shows exactly what the radio popup
  will say. Your files are never changed: the names are kept in
  soundtrack.tsv inside the music folder, and the game picks up changes on
  the next song, even mid-race.
- The game's font has Latin (with most European accents) and Russian.
  Other text is converted: Japanese kana and Korean become romaji /
  romanised, Greek and other accents become plain letters. Chinese
  characters / kanji and emoji can't be shown and are left out; such songs
  are marked CHECK in the list so you can type a version yourself.
The same Off / Mixed / Custom only switch is in GAME ADJUSTMENTS > Music.
Very long files (over 30 minutes) play their first half hour.


HDR (new, untested on HDR screens)
----------------------------------
With Windows HDR turned on, the game now outputs real HDR (you no longer
need ForceAutoHDR / Auto HDR). Settings (launcher Advanced tab, PGR4):
  hdr_output = auto          auto / on / off
  hdr_paper_white = 200      brightness of white in nits; raise it if the
                             game looks dim, lower it if too bright
  hdr_peak = 0               brightest highlight in nits (0 = the screen's)
  hdr_highlights = 1.0       0 = no highlight boost, 1 = full
Overlays such as MSI Afterburner / RTSS may show blown-out colours in HDR;
that is the overlay's HDR setting, not the game.
The log line "PGR4 D3D12: display HDR ..." shows what was detected.


Racing wheels (new, untested)
-----------------------------
Wheels that work as an Xbox controller (Logitech G920/G923 Xbox, Xbox-mode
Thrustmasters) work like a normal pad. Other wheels (Logitech G29/G27,
Thrustmaster T300/T150, Fanatec, ...) are now picked up too and shown to the
game as an Xbox 360 wheel:
  steering = left stick, accelerator = right trigger, brake = left trigger,
  wheel buttons = pad buttons, D-pad / hat = D-pad.

The log says which axes it chose, e.g.
  SDL wheel: "G29 Driving Force Racing Wheel", ... 4 axes [0=0 1=32767 ...]
  ... steering axis 0, accelerator axis 1, brake axis 2
If the pedals or buttons are wrong, set these in the launcher's Advanced tab
(Input section) or on the command line:
  hid_wheel_log_axes = true        logs every axis/button you move, so you
                                   can see which number is which
  hid_wheel_steer_axis = 0
  hid_wheel_throttle_axis = 1      (-1 = automatic)
  hid_wheel_brake_axis = 2         (-1 = automatic; same as throttle for
                                   combined pedals)
  hid_wheel_steer_scale = 1.0      2.0 = full lock at half the rotation
  hid_wheel_deadzone = 0           steering dead zone (0-32767)
  hid_wheel_invert_steering = false
  hid_wheel_pedals_rest = auto     high / low if a pedal reads backwards
  hid_wheel_buttons = A,B,X,Y,LB,RB,BACK,START,LS,RS
                                   pad button for wheel button 0, 1, 2, ...
                                   (also GUIDE UP DOWN LEFT RIGHT LT RT, or -)
  hid_wheel_as_360_wheel = true    false = report it as a normal pad
  hid_wheel_any_joystick = false   true if your wheel isn't detected at all
A wheel base with separate pedals / shifter / handbrake counts as ONE wheel:
axes and buttons are numbered across the devices, the wheel base first
(the log lists each "SDL wheel part"). If a pedal set or shifter isn't
picked up, check hid_wheel_any_joystick is true (now the default; it also
makes USB shifter adapters such as a G27 shifter part of the wheel).
Button boxes (buttons only, or "button box" in the name) join the wheel as
extra buttons and never become a controller of their own. If a device
still shows up as an extra controller, list it in hid_ignore_devices:
part of its name or its VID:PID from the log's "SDL JoystickAdded" line,
comma-separated (e.g. hid_ignore_devices = my box, 1209:2301).
A wheel and a controller connected together now count as ONE player (before,
a wheel plugged in at start signed in a second player and the game sat on
"Your profile has been loaded"). For split screen with a wheel as a separate
player, set signin_wheel_players = true.
Please send a log and what you changed, so we can make good defaults for
your wheel.


Performance (new)
-----------------
Crowds and grandstands draw a few thousand small objects a frame, and on
fast GPUs the renderer's own CPU time per draw was the limit there. The
renderer now records the GPU's commands on a second thread
(record_thread = true, the default) and also prepares 3D shader constants
there: in crowd scenes its main thread does about a quarter less work.
If you see crashes or broken graphics that go away with
record_thread = false (launcher Advanced tab), please send the log.
Also: the renderer's main thread does less per object (crowds about 30%
cheaper), and a slow leak of texture-sampler slots that could make some
objects vanish after 5-10 minutes of play is fixed. The frame report in
the frame report (perf_log) says "limit: frame rate cap" when the frame
rate limit is what holds the game back.
Fixed: photo mode's smeared/shaky picture. The renderer now places pixels
the way the 360 does (d3d9_pixel_center = true, the default), which the
photo needs as it builds up over many frames. Everything on screen moves
by half a pixel; if anything looks newly blurry or off by a line, try
d3d9_pixel_center = false and send the log.
Fixed: violent black flickers in races with 4 or more AI cars. The
renderer ran out of texture-sampler slots and skipped draws; draws now
share sampler tables.
Faster on the GPU: the final present is cheaper, and when the game copies
the whole scene into a texture and clears it straight after, the two now
swap places instead of copying (resolve_swap = true, the default). If
post-effects such as motion blur or bloom look wrong, try
resolve_swap = false and send the log.
Hitches: with perf_log = true the log gets a "hitch:" line for every
frame much slower than the ones around it, saying what the renderer did
in it (new GPU pipelines, texture uploads, new render targets, GPU wait).
If the game stutters for you, turn it on, play until it happens a few
times and send the log.
Fixed (probably): regular small hitches at high frame rates, about one a
second. Freeing old texture tables made the renderer redo every texture
setup for the rest of that frame. Please say whether the stutter is gone,
and send the log either way.
New: motion blur can be switched off (Game Adjustments > Display >
Motion blur, or motion_blur = false). The game reads it when a race
loads, so a change shows from the next race.
Fixed (Linux/Steam Deck, confirmed): a hitch every quarter second in
races. The renderer checked for debug files on disk far too often, and
that is slow under Proton.
Shorter logs: the performance lines (frame report every 600 frames, hitch
lines, pipeline build times) are now off unless perf_log = true (launcher
Advanced tab). Turn it on when reporting slowdowns or stutter.
Fixed: since the Geometry Wars update, a few game settings (the --tweaks
option and the post-process frame time) were switched off for PGR4 itself.
Fixed: hitches mid-race, worst on Steam Deck. Objects with slightly
different depth offsets each needed a new GPU pipeline built on the spot
(over a hundred a second in some races); they now share pipelines.
With perf_log = true the log notes every 500 pipelines and how long they
took to build, and every 600 frames the frame rate and where the time
goes (game thread, render thread, GPU) with a "limit:" verdict. If the
game runs slowly for you, turn it on, play a race for a minute and send
the log.
New: the game now draws its next frame while the renderer is still
recording the last one (render_overlap = true, the default), instead of
waiting for it. On fast GPUs this should raise the frame rate in busy
scenes, at the cost of up to one frame of extra input delay. If you see
broken graphics (wrong shapes, black or flashing objects, loading screens
especially) that go away with render_overlap = false (launcher Advanced
tab), please send the log.
Fixed (launcher): your gamertag sometimes vanished from the Play tab and
gamertag.txt was deleted when the launcher started. It is now only
removed if you clear the name yourself.
Changed: online play (net_transport = eos) is now on by default.
Changed: the launcher no longer passes --execute_unclipped_draw_vs_on_cpu
(it only ever applied to the old Xenos renderer).
Fixed: the screen flashing black for a few frames when a car loads in
(car select, and AI cars coming up behind or alongside you in a race).
Fixed (needs testing at high frame rates): the in-car view shook too fast
above 30 fps. The car body's vibration now runs at the 360's speed at any
frame rate; above 60 fps it was a fast buzz, now it is a slower rumble.
Fixed: car light glows (headlights, rear lights) showed through the cars
in front of them. The game now really tests whether each lamp is hidden,
as the 360 did, so a glow goes out behind a car or building. Like the 360,
lamps seen very close up (the pre-race close-ups) have no glow. On slow
GPUs the glow can take a moment to go out. If glows misbehave, try
edram_depth_sharing = false and tell us what changed.

Fixed (prerelease-7): rear-view mirrors were blank and the game stuttered
in prerelease-6 (a renderer change carried the scene's depth into other
passes on every draw; it now only does so for the car-light glow test).
Fixed: car light glows now go out as soon as a car or building covers
them, and headlight glows no longer flicker.
New: drop your PGR4 disc image (.iso) on the launcher to extract the game
(see "Windows PC" above).
New: chat, messages, voice chat and team announcements (see "Chat,
messages and voice" above).


Reporting problems
------------------
The log is shorter now. For performance reports set perf_log = true; for
renderer diagnostics (render targets and memory) set gpu_verbose_log = true.
Please send:
- the newest file in the "logs" folder next to pgr4_recompiled.exe
  (the launcher's Play tab > Last session > "Open logs" opens it)
- which device and GPU you used, and what went wrong.

With perf_log = true the game logs its frame rate and hitches, so a log
from a race also tells us how it performed.
