benilla-octo/Optional/sky-and-grading/README.md

Optional skyboxes and colour grading

This asset-free kit builds an optional MPQ on your machine. It adds zone skyboxes for Burning Steppes, Blasted Lands, and Mount Hyjal; project-authored per-zone colour grading for Elwynn Forest, Duskwood, Westfall, and Redridge; and, with --wf-colours, a moderated import of night colours from your own WoW Forever installation.

The repository contains only scripts and benilla's own grading LUTs/table. The Blizzard models, textures, and lighting tables are read from installations you own and appear only in your local build directory.

Requirements

• Windows and Python 3.8 or newer.
• A World of Warcraft 1.12.1 client and its Data directory.
• For skyboxes, a local WoW Forever _classic_beta_ or current retail install. Point the command at the shared World of Warcraft root (the directory with .build.info and Data), or at _classic_beta_ itself.
• Git and the external wowdev/pywowlib checkout pinned below. It is not redistributed here.
• 64-bit StormLib 9.40 (StormLib.dll) from the official StormLib releases. Download stormlib_dll.zip and use its x64 DLL. StormLib is not redistributed.
• Internet access on the first run for the public wow-listfile and public TACT key list, unless --listfile and --tact-keys name local copies.

Install, one command per step

Run these in PowerShell. Change the example paths for your machine.

1. Clone the exact pywowlib revision used by the converter.

   git clone https://github.com/wowdev/pywowlib.git C:\Tools\pywowlib
   

2. Pin it to the tested commit.

   git -C C:\Tools\pywowlib checkout 55276dc5c2195da7fe136638a2a59716622f8c65
   

3. Install the Python modules needed by the M2 reader. pywowlib remains an external checkout; this installs dependencies only.

   py -3 -m pip install bidict==0.23.1 multimethod numpy
   

4. Download StormLib 9.40's stormlib_dll.zip from the release linked above, extract the 64-bit StormLib.dll, and place it at C:\Tools\StormLib\StormLib.dll.

5. Close the game and build the candidate. The tool never writes to either input installation.

   py -3 .\tools\build_sky_patch.py --wow-forever "C:\Games\World of Warcraft" --client-data "C:\Games\WoW-1.12.1\Data" --pywowlib "C:\Tools\pywowlib" --stormlib "C:\Tools\StormLib\StormLib.dll" --out "C:\Temp\benilla-sky"
   

6. Verify an isolated Data copy before installation. C:\Temp\WoW-test\Data should be a copy or hard-link mirror in which only patch-Z.mpq is an ordinary copy; replace that copy with the newly built archive first.

   py -3 .\tools\verify_client_chain.py "C:\Temp\WoW-test\Data" --stage "C:\Temp\benilla-sky\stage" --stormlib "C:\Tools\StormLib\StormLib.dll"
   

7. Back up the live target archive if one exists.

   Copy-Item "C:\Games\WoW-1.12.1\Data\patch-Z.mpq" "C:\Games\WoW-1.12.1\Data\patch-Z.before-benilla.mpq.bak"
   

8. Copy the verified candidate into the client.

   Copy-Item -Force "C:\Temp\benilla-sky\patch-Z.MPQ" "C:\Games\WoW-1.12.1\Data\patch-Z.mpq"
   

If no patch-Z.mpq existed, skip step 7. The build report's archive_base field records whether the builder preserved an existing patch-Z.

Variants

Build only the project-owned grading table and LUTs; this needs no modern WoW install or pywowlib:

py -3 .\tools\build_sky_patch.py --grading-only --client-data "C:\Games\WoW-1.12.1\Data" --stormlib "C:\Tools\StormLib\StormLib.dll" --out "C:\Temp\benilla-grading"

Add moderated WoW Forever night colours. LightData is extracted directly from your installation; no derived LightData is shipped here:

py -3 .\tools\build_sky_patch.py --wow-forever "C:\Games\World of Warcraft" --client-data "C:\Games\WoW-1.12.1\Data" --pywowlib "C:\Tools\pywowlib" --stormlib "C:\Tools\StormLib\StormLib.dll" --wf-colours --out "C:\Temp\benilla-sky-wf"

Enable in game

Open Options → Advanced Graphics and enable Zone Skyboxes and Colour Grading. The equivalent console commands are:

/console zoneSkyboxes 1
/console colorGrading 1

Use 0 instead of 1 to disable either effect without removing the MPQ.

MPQ load order: read before copying

All five mutually dependent lighting DBCs must win from the same, highest letter patch that carries any of them. The default is patch-Z.mpq. If the client already has patch-Z, the builder copies that archive and overlays the new files so unrelated members survive; install the resulting candidate as a replacement, not as a second archive.

Do not blindly rename the output. A later-mounted archive that also contains Light.dbc, LightParams.dbc, LightIntBand.dbc, LightFloatBand.dbc, or LightSkybox.dbc can split the table set and break the sky. Some custom clients use punctuation after ordinary letters; in that case merge this stage into the actual last patch or remove the conflicting DBC copies, then run verify_client_chain.py --require-winner ANY. A conventional patch-Z setup should keep the default strict check.

The extended four-field LightSkybox.dbc is for benilla. Do not use this patch with an unmodified stock 1.12 executable that expects the two-field table.

Uninstall

Close the game. If the build preserved an existing patch-Z, restore the backup:

Move-Item -Force "C:\Games\WoW-1.12.1\Data\patch-Z.before-benilla.mpq.bak" "C:\Games\WoW-1.12.1\Data\patch-Z.mpq"

If there was no prior patch-Z and this kit created it, remove only that exact archive:

Remove-Item -LiteralPath "C:\Games\WoW-1.12.1\Data\patch-Z.mpq"

Deleting a pre-existing patch-Z would remove unrelated custom content, so use build-report.json and your backup to distinguish these cases.

Troubleshooting

• pywowlib revision mismatch: run the checkout command from step 2. The builder deliberately rejects another revision so M2 layout behaviour cannot drift silently.
• StormLib not found: pass --stormlib or set STORMLIB_PATH to the x64 DLL. A 32-bit DLL cannot load into 64-bit Python.
• No CASC build/config: point --wow-forever at the World of Warcraft root with .build.info and Data, or at its _classic_beta_ child.
• Missing/encrypted CASC block: update the public TACT key file or rerun without a stale --tact-keys copy. The tool uses public keys only.
• Unexpected source schema/clone start: another addon has already changed the winning lighting DBCs. Remove that conflict or merge deliberately; the tool refuses to guess.
• Sky does not appear: enable zoneSkyboxes, fully restart the client, and run verify_client_chain.py against the actual Data directory.
• Bands fail: run check_bands.py <Data directory> --stormlib <DLL>. Correct clone keys are (P-1)*18+b+1 and (P-1)*6+b+1.
• Output already exists: choose a fresh --out, or pass --force only when replacing the candidate archive in that output directory is intended.

Credits and rights

WoW Forever and retail skybox art is © Blizzard Entertainment and is extracted locally by the user from their own installation. No Blizzard art or client DBC is distributed here.

The colour-grading technique is based on WarcraftXL's wxl-retail-grading work by iThorgrim, used with attribution. The grading LUTs and MonkeyZoneGrade.dbc in data/ are original benilla project data, licensed MIT OR Apache-2.0.