[sea4-18]

What this adds

• dm/tools/w4_to_glslc.py: a standalone script (needs pip install zstandard) that extracts the game's shaders into extract/<version>/glslc_capture/ and sets four memory keys in the provisional profile.
• docs/unrailed2-w4-bringup.md: notes on the engine, the shader format and the failure chain.

No engine files (scripts/, shader_split.py) are changed, and no game files, keys or extracted shaders are included. There is no registered profile: a registered profile folder was tried and fails, because the engine then wants a generated shader_map.tsv.

Game

Unrailed 2: Back on Track, update v327680 (v925.eab7b7d5). Godot 4.4.1 (W4 Games console build, mono) on NintendoSDK 20.5.28, NVN "Forward Mobile". The RomFS is a Godot PCK with 1,138 .godot/w4_shaders/*.nvn.w4_shader files.

What was wrong

1. The build stopped at the GLSLC capture ("captured only 0 run-time shaders"). main imports glslcCompile and holds 93 GLSL sources, but the game does not compile at boot. Its shaders ship in the RomFS, and the capture boot aborts after about 3 s because no shader map exists yet.
2. The shader split then found nothing. Each .w4_shader file has a short header (GRSC / NVNC) followed by concatenated zstd frames, and each frame decompresses to one complete GLSLC output (magic 0x19866891, length at +0x44). There are 39,068 frames and 2,884 unique outputs.
3. The provisional memory values were too small:

key	survey	working	symptom with the survey value
mem_stack	0x10000000	0x100000000	thread creation aborted after 512 QueryMemory calls
mem_reserve	0x140000000	0x230000000	grows with mem_stack
mem_alias	0x118000000	0x118000000	unchanged
app_pool	0xCD500000	0x180000000	the windowed run read a null pointer after MemoryPoolInitialize: non-virtual pool has no storage flags=0x22 size=0x8000000

The stack and pool values are working guesses, larger than needed and not tuned.

How to build

1. Run the NSP script once. It stops early (at the address-region check) but has extracted the game and written the provisional profile.
2. pip install zstandard, then python3 dm/tools/w4_to_glslc.py <the _build folder> v327680.
3. Run the NSP script again. The capture step says "reused", the split finds 2,884 shaders, all 2,884 Mac shaders compile and the build finishes.

Tested

Apple M3 Max, macOS 26.6.2, Xcode 27.2. From a clean checkout of this branch with a fresh work folder, the two-step flow above finished all 8 build stages. The game then ran 5 min headless and 10 min in a window with sound, with no aborts or crashes, and reached its title screen. Gameplay beyond the title screen, controls, saves and long sessions are not checked. [RED] texture format 0x22 has no Metal equivalent is logged once and its visual effect is unchecked.

Suggested follow-ups

• A W4/Godot PCK reader in shader_split.py, which would make the extractor unnecessary.
• A detector fix so a game with GLSL text in main but shipped shaders is not sent through the capture step.
• A registered profile with a generated shader map, and tuning the memory values.

[sea4-18]

Related to #2584.