docs: README overhaul for the v2.0.0 native renderer release

README.md

@@ -4,9 +4,11 @@
   <img alt="Skate 3 Native PC Recompilation" src="banner-light.png">
 </picture>
 
-An unofficial native recompilation of the Xbox 360 version of Skate 3, supporting Windows, Linux, and macOS. Built with a Skate-specific [rexglue SDK](https://github.com/rexglue/rexglue-sdk) fork.
+An unofficial native recompilation of the Xbox 360 version of Skate 3, supporting Windows, Linux, and macOS.
 
-The game is currently capable of running at ~165FPS at 4K with MSAA, using an RTX 4090.
+As of v2.0.0, the game runs on a native renderer built directly on Direct3D 12 and Vulkan instead of emulating the Xbox 360 GPU. Compared to the emulated renderer it delivers more than twice the frame rate at roughly a quarter of the GPU power draw, and on Apple Silicon the frame rate uplift is closer to 10x.
+
+The new native renderer is early and is likely to have issues, I haven't tested the game all the way through.
 
 The project does not include Skate 3 retail game files. To run or build the project, you must provide files from your own legally obtained Xbox 360 copy of Skate 3.
 
@@ -24,7 +26,7 @@ Notes:
 
 - The Windows version is the most tested, followed by Linux, and then macOS.
 - On some hardware configurations, you may have a better experience running the Windows version through a translation layer like Proton rather than the native Linux build itself.
-- The macOS ARM build is very experimental and therefore much more prone to issues.
+- The macOS ARM build is experimental and more prone to issues.
 
 ### Windows
 
@@ -54,6 +56,21 @@ Notes:
 6. Wait for the installer to extract the game files.
 7. Click "Start Game".
 
+## Native Renderer
+
+Since v2.0.0 the game no longer relies on emulating the Xbox 360 GPU. A native renderer draws the game directly through Direct3D 12 or Vulkan, covering the entire game: gameplay, menus, HUD, loading screens, videos, and the photo, replay, skater, and park editors. It runs exact ports of the game's own material shading for the world, characters, vehicles, and water, so the image stays at close visual parity with the original console output while running far faster and more efficiently.
+
+- The native renderer is on by default. Settings > Video > Renderer switches between Native and Emulated live, and F5 hot-toggles between them at any time. If the native renderer ever hits an unrecoverable error, the game falls back to the emulated renderer and shows a corner indicator; F5 retries the native path.
+- On Windows, a single build ships both graphics API backends: Settings > Video > Graphics API selects DirectX 12 or Vulkan (applied with Apply & Restart; DirectX 12 is preferred by default). Linux uses Vulkan, and macOS uses Vulkan through MoltenVK.
+- Optional enhancements beyond the original game live under Settings > Video: MSAA up to 8x, enhanced real-time sun shadows with contact-hardening soft shadows, ambient occlusion, bloom, volumetric lighting, extended draw distance and world streaming, render scale up to 3x, and true ultrawide.
+
+Known issues:
+
+- Occasional texture and asset pop-in or brief flicker while streaming quickly around the map (also present in the emulated renderer)
+- Issues with rendering skater customization options in the edit skater mode (skin, hair, clothing etc.)
+- Hall of Meat currently not rendered properly (missing bone highlights etc.)
+- Skate parks and park editing currently have some general visual parity / rendering issues
+
 ## Installing DLC
 
 To use DLC, you must provide package files from your own legally obtained Xbox 360 DLC.
@@ -62,6 +79,17 @@ Create a `dlc` folder either beside the executable, inside the installed game fo
 or in the user data folder. Place the DLC package files in that
 folder and start the game.
 
+## Saves and Portable Mode
+
+Saved games live in the user data folder by default (`%APPDATA%\skate3`, i.e.
+`AppData\Roaming\skate3`, on Windows). Two portable options are available:
+
+- Create a `saves` folder next to the executable and the game keeps saved games
+  there instead. The folder must exist before launch, and existing saves are not
+  migrated automatically - copy them over from the user data folder.
+- Create an empty `portable.txt` file next to the executable to keep all user
+  data in the executable's folder.
+
 ## True Ultrawide
 
 The builds include an experimental true ultrawide mode: the native renderer draws the world at your display's full aspect ratio (21:9 and wider) with a matching wider field of view, while the HUD and menus stay centered and undistorted. Enable it via the Aspect Ratio setting or `skate3_ultrawide = true`. It requires the native renderer; with the emulated renderer the game presents in standard 16:9. Rendering more of the scene costs proportionally more GPU time.
@@ -86,6 +114,10 @@ The builds include an experimental true ultrawide mode: the native renderer draw
 
 ## Building from Source
 
+All platforms build with CMake 3.25+, Ninja, and Clang 18 or newer - ReXGlue
+requires Clang, so MSVC and Apple Clang are not supported. On Windows, install
+[LLVM for Windows](https://releases.llvm.org/) and Ninja.
+
 Clone with submodules:
 
 ```sh
@@ -104,6 +136,17 @@ The build-time codegen needs an extracted game dump containing `default.xex` and
 `data/webkit/EAWebkit.xex`. Put that dump in `game/`, or pass a path with
 `SKATE3_GAME_DATA_ROOT`.
 
+The codegen should also be given the Skate 3 Title Update 3 package - the same
+`TU_12K2276_000000C000000.00000000000O3` file the in-game title update
+installer downloads. Place it in the repository root under its original name,
+or pass a path with `-DSKATE3_TITLE_UPDATE_PACKAGE=`. With the package
+present, the build extracts the update patches and recompiles the TU3-patched
+executables - the configuration used by release builds, whose runtime requires
+the title update to be staged before the game will boot. Without the package,
+codegen falls back to the unpatched retail image; that path is no longer
+regularly tested, and `generate-all` reporting unresolved calls on a clean
+retail dump is the usual symptom of building without the title update.
+
 Generate the recompiled source first:
 
 ```sh
@@ -118,8 +161,14 @@ cmake --preset relwithdebinfo -DSKATE3_GAME_DATA_ROOT="$PWD/game"
 cmake --build --preset relwithdebinfo --parallel
 ```
 
-For release packaging, use the `release` preset on Windows or the
+For release packaging, use the `release` preset on Windows, the
-`linux-release` preset on Linux.
+`linux-release` preset on Linux, or the `macos-release` preset on macOS.
+
+The native renderer's HLSL sources live in `src/native/shaders` and are
+embedded into the build automatically. The matching Vulkan SPIR-V binaries are
+pre-compiled offline with DXC and committed under `src/native/shaders/spirv`,
+so building needs no shader tooling; the SPIR-V header only needs regenerating
+after editing the HLSL.
 
 ## Ubuntu/Linux Build
 
@@ -154,13 +203,8 @@ Optional packages improve controller/input and diagnostics coverage in SDL:
 sudo apt install -y libusb-1.0-0-dev libunwind-dev libibus-1.0-dev liburing-dev
 ```
 
-Initialize submodules and verify the local environment:
+Initialize submodules as described above, then configure, generate,
-
+reconfigure, and build a development build:
-```sh
-./scripts/bootstrap-linux.sh
-```
-
-Configure, generate, reconfigure, and build a development build:
 
 ```sh
 cmake --preset linux-relwithdebinfo -DSKATE3_GAME_DATA_ROOT="$PWD/game"
@@ -185,41 +229,52 @@ out/build/linux-release/skate3
 out/build/linux-release/librexruntime.so
 ```
 
+## macOS Build (Apple Silicon)
+
+macOS builds use Homebrew LLVM - the `macos-*` presets expect the toolchain at
+`/opt/homebrew/opt/llvm`. Vulkan is provided by MoltenVK; the build copies the
+library next to the executable and writes a `MoltenVK_icd.json`, looking in
+`$VULKAN_SDK/lib`, `/opt/homebrew/lib`, and `/usr/local/lib`.
+
+```sh
+brew install llvm cmake ninja molten-vk
+```
+
+Configure, generate, reconfigure, and build a release:
+
+```sh
+cmake --preset macos-release -DSKATE3_GAME_DATA_ROOT="$PWD/game"
+cmake --build --preset macos-release --target generate-all --parallel
+cmake --preset macos-release -DSKATE3_GAME_DATA_ROOT="$PWD/game"
+cmake --build --preset macos-release --parallel
+```
+
+The release artifacts are `out/build/macos-release/skate3` and
+`librexruntime.dylib`, plus the MoltenVK library and ICD manifest beside them.
+
 ## Running a Development Build
 
-On Linux:
+Run the built executable directly with a game dump. On Linux:
-
-```sh
-./scripts/run-linux.sh
-```
-
-The launcher sets `LD_LIBRARY_PATH` for development builds, passes
-`--game_data_root="$PWD/game"`, and selects SDL controller input on Linux. To
-use a game dump outside the repository:
-
-```sh
-SKATE3_GAME_DATA_ROOT="/path/to/extracted/game" ./scripts/run-linux.sh
-```
-
-Keyboard-to-controller emulation is off by default. Pass `--mnk_mode` or set
-`SKATE3_MNK=1` to enable it:
-
-```sh
-SKATE3_MNK=1 ./scripts/run-linux.sh
-```
-
-Fullscreen is on by default. Pass `--no-fullscreen` to start windowed.
-On Windows, ultrawide displays are detected automatically in fullscreen. For an
-ultrawide window, pass matching `--window_width` and `--window_height` values;
-the native renderer then draws true widescreen frames at that aspect.
-
-To run the Linux development executable directly:
 
 ```sh
 LD_LIBRARY_PATH="$PWD/third_party/rexglue-sdk/out/linux-amd64${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" \
-  ./out/build/linux-relwithdebinfo/skate3 --game_data_root="$PWD/game" --input_backend=sdl
+  ./out/build/linux-relwithdebinfo/skate3 --game_data_root="$PWD/game"
 ```
 
+On Windows:
+
+```powershell
+.\out\build\relwithdebinfo\skate3.exe --game_data_root="$PWD\game"
+```
+
+Keyboard-to-controller emulation is off by default; enable it in
+Settings > Controls > Mouse & Keyboard Mode.
+
+Fullscreen is on by default. Pass `--fullscreen=false` to start windowed.
+On Windows, ultrawide displays are detected automatically in fullscreen. For an
+ultrawide window, pass matching `--window_width` and `--window_height` values;
+the native renderer then draws true widescreen frames at that aspect.
+
 ## rexglue Fork
 
 `third_party/rexglue-sdk` is pinned as a Git submodule to the
@@ -232,8 +287,9 @@ git submodule update --init --recursive --jobs "$(nproc 2>/dev/null || echo 4)"
 ```
 
 The fork is based on rexglue's 0.8.0 release line and contains the Skate 3
-runtime, codegen, input, graphics, timing, and Linux fixes needed by this
+runtime, codegen, input, timing, the Direct3D 12 and Vulkan backends used by
-project.
+the native renderer, the settings overlay, and the Linux and macOS fixes
+needed by this project.
 
 ## Credits