Building

This page explains how to build the patch and run its tests. To play, download the zip file from the releases page, which contains the .kpatch, and follow Installing.

Build the patch

The patch is a 32-bit Windows DLL. You can build it on any machine, natively or by cross compiling, if you have the Rust target and a linker for it. If your machine doesn’t already have a linker for that target, install MinGW-w64.

1. Add the Rust target:

   rustup target add i686-pc-windows-gnu
   

2. Build the DLL and write the .kpatch:

   cargo xtask package
   

To build the zip files that a release publishes, run cargo xtask release for the standard install and cargo xtask release --standalone for the standalone install. The minimum Rust version is in rust-version in the workspace’s Cargo.toml.

Run the tests

The tests check the patch’s shading programs against the game’s own programs, which they read from a copy of the game’s executable each time they run. This repository stores nothing from the game, so the tests that need the game skip unless you point them at your copy:

K1DC_SWKOTOR_EXE=/path/to/swkotor.exe cargo test

Which tests run on which driver

The tests that compare with the game’s ATI programs need a driver that still runs GL_ATI_fragment_shader, which means Mesa or an older AMD/ATI driver. They render the game’s program and the patch’s in the same process and compare the images pixel for pixel. 7 These tests pass on Mesa’s radeonsi driver.

You can also run them without a GPU on llvmpipe, Mesa’s software rasteriser, by setting LIBGL_ALWAYS_SOFTWARE=1. On llvmpipe, one comparison fails: accumulationBlur rounds one step differently from the game’s program on about 6% of the pixels.

The tests that compare with the game’s register combiner setups and NVIDIA vertex programs need NVIDIA’s driver, the only driver that still runs them.

Make skipped tests fail

A test that can’t run on your machine skips, and a skipped test counts as a pass. No single machine runs every test, because the ATI comparisons need Mesa and the NVIDIA comparisons need NVIDIA’s driver.

To make sure the tests your machine can run do run, list what your machine has in K1DC_REQUIRE, separated by commas. A test that skips for lack of a listed item then fails instead. For example, on a Mesa machine:

K1DC_REQUIRE=game,context,framebuffers,texture-units,GL_ATI_fragment_shader,GL_ARB_vertex_program \
K1DC_SWKOTOR_EXE=/path/to/swkotor.exe cargo test

On NVIDIA’s driver, remove texture-units and GL_ATI_fragment_shader, and add GL_NV_register_combiners and GL_NV_vertex_program.

Compare images

Most comparisons write an image to target/differential/, whether they pass or fail. Each image shows the game’s program, the patch’s program, and the difference between them, amplified so that a difference of one step is visible.

Test both looks

The tests on Mesa check the Radeon look, look = ati. The tests on NVIDIA’s driver check the GeForce look, look = nvidia, which is the default. If you change one of the programs that differ between the looks, run the tests on both drivers.

Build this documentation

The chapters are Markdown files in docs/, which you can read directly. mdBook builds them into a website in target/book:

mdbook build docs

To rebuild the website each time you save a change, and view it at http://localhost:3000:

mdbook serve docs