jackrayner · Oct 24, 2026 · Oct 24, 2026 · Oct 24, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,6 +1,6 @@
 # AGENTS.md
 
-Guidance for AI coding agents (and humans) working in this repo. `CLAUDE.md` just imports this file.
+Guidance for AI coding agents (and humans) working in this repo. `CLAUDE.md` just imports this file. Human contributors: see `CONTRIBUTING.md`.
 
 ## What this is
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,25 @@
+# Contributing
+
+Thanks for helping. This is a maintained fork of [bolrog/d2dx](https://github.com/bolrog/d2dx) (see the README). Planned and declined work is in [DEVELOPMENT.md](DEVELOPMENT.md); check it before starting something big. `AGENTS.md` has more detail on the code layout, written for coding agents but useful to anyone.
+
+## Build
+
+D2DX is a Win32 (x86) Visual C++ project: open `src/d2dx.sln` in Visual Studio and build `Release|Win32` (the project targets the v142 toolset; CI retargets to v143). The `d2dx` project's post-build step copies `glide3x.dll` to the original author's game folder (`C:\games\Diablo II\`); change that locally, don't commit it.
+
+## Test
+
+- **Windows CI** (`.github/workflows/tests.yml`) builds the DLL and the test project and runs the unit tests on every pull request. Docs-only changes skip the Windows job.
+- **Locally on Linux or macOS:** `tests/linux/run.sh` runs the pure-logic tests in a container (podman or docker). It covers logic only, not MSVC behaviour or the game.
+- Nothing automated plays the game. If you change rendering, hooks or game-version handling, run the DLL in a Diablo II folder (`-3dfx`) and say in the pull request what you tried.
+
+## Pull requests
+
+- Branch from `main` and open a pull request. The `build-and-test` check must pass.
+- Use **conventional commit titles** (`fix:`, `feat:`, `perf:`, `docs:`, `build:`, `ci:`, `chore:`). Releases are automated from them; see "Releasing" in `AGENTS.md`. Squash merges work best.
+- Add or update unit tests for logic that doesn't need the game (`src/d2dxtests`).
+- Port other people's work with `git cherry-pick -x` and keep their authorship and licence headers (GPLv3, see `AGENTS.md`, "Licensing and attribution").
+- Don't write issue or pull request numbers or links from other people's repositories in commit messages or PR text: GitHub posts a "mentioned in" note on their thread that can't be removed.
+
+## Reporting problems
+
+Open an [issue](https://github.com/jackrayner/d2dx/issues) with your game version, OS (and Wine/Proton if used), and the `d2dx_log.txt` from your Diablo II folder.
diff --git a/README.md b/README.md
@@ -30,15 +30,10 @@ This is a maintained fork of [bolrog/d2dx](https://github.com/bolrog/d2dx), whic
   - Integrated graphics or discrete GPU with DirectX 10.1 support.
 
 ## Compatibility
-Game versions supported:
-  - All features: 1.09d, 1.13c, 1.13d and 1.14d.
-  - Without resolution switching: 1.10f, 1.12.
-  - Other versions are unsupported, will display a warning at startup and exhibit glitches.
-
-For compatibility with mods, see the [wiki](https://github.com/bolrog/d2dx/wiki/Compatibility-with-other-mods).
+Supported game versions: 1.09d, 1.10f, 1.12, 1.13c, 1.13d and 1.14d. Custom resolutions work on 1.09d, 1.13c, 1.13d and 1.14d; high FPS (motion prediction) works on every one except 1.10f. Only 1.14d, under Wine/Proton, has been played with this fork's build so far. See [docs/compatibility.md](https://github.com/jackrayner/d2dx/blob/main/docs/compatibility.md) for the per-version table, Windows/Wine notes and mods.
 
 ## Documentation
-  This readme contains basic information to get you started. [`d2dx-defaults.cfg`](https://github.com/jackrayner/d2dx/blob/main/d2dx-defaults.cfg) documents the settings. More is on the original project's [wiki](https://github.com/bolrog/d2dx/wiki/), which describes upstream and may be out of date for this fork.
+  This readme has the basics. [Configuration](https://github.com/jackrayner/d2dx/blob/main/docs/configuration.md) lists every setting and command-line option, [compatibility](https://github.com/jackrayner/d2dx/blob/main/docs/compatibility.md) has the per-version notes, and [CONTRIBUTING.md](https://github.com/jackrayner/d2dx/blob/main/CONTRIBUTING.md) covers building and contributing. The original project's [wiki](https://github.com/bolrog/d2dx/wiki/) describes upstream and may be out of date for this fork.
 
 ## Installation
   Download `d2dx.zip` from the [latest release](https://github.com/jackrayner/d2dx/releases/latest) and copy `glide3x.dll` into your Diablo II folder.
@@ -52,35 +47,28 @@ To start the game with D2DX enabled, just provide -3dfx, e.g.
   ```
 Windowed/fullscreen mode can be switched at any time by pressing ALT-Enter. The normal -w command-line option works too.
 
-Many of the default settings of D2DX can be changed. To use a configuration file, rename `d2dx-defaults.cfg` to `d2dx.cfg` and edit it. A list of command-line options is on the original project's [wiki](https://github.com/bolrog/d2dx/wiki/).
+Many of the default settings of D2DX can be changed. To use a configuration file, rename `d2dx-defaults.cfg` to `d2dx.cfg` and edit it. Every setting and command-line option is listed in [docs/configuration.md](https://github.com/jackrayner/d2dx/blob/main/docs/configuration.md).
 
 ## Troubleshooting
 
 ### I get a message box saying "Diablo II is unable to proceed. Unsupported graphics mode."
   You are running the download version of Diablo II from blizzard.com. It can be modified to work with D2DX, but this fork does not document how yet.
 
-### It's ugly/slow/buggy.
+### Something looks wrong or runs badly
   Check [DEVELOPMENT.md](https://github.com/jackrayner/d2dx/blob/main/DEVELOPMENT.md) to see whether it is a known or planned item, then [open an issue](https://github.com/jackrayner/d2dx/issues) and include `d2dx_log.txt` from your Diablo II folder, your game version and your OS.
 
 ## Credits
-Original author: bolrog
-Patch contributions: Xenthalon
-Fork maintenance: Jack Rayner
-
-The research of many people in the Diablo II community over twenty years made this project possible.
+D2DX was written by bolrog, with patches from Xenthalon. This fork is maintained by Jack Rayner.
 
-Thanks to Mir Drualga for making the fantastic SGD2FreeRes mod!
-Thanks also to everyone who contributes bug reports.
-
-D2DX uses the following third party libraries:
-- FNV1a hash reference implementation, which is in the public domain.
+D2DX embeds and uses the following third-party code:
+- SGD2FreeRes (the resolution mod) by Mir Drualga, licensed under Affero GPL v3.
 - Detours by Microsoft.
-- SGD2FreeRes by Mir Drualga, licensed under Affero GPL v3.
+- FNV1a hash reference implementation, which is in the public domain.
 - FXAA implementation by Timothy Lottes. (This software contains source code provided by NVIDIA Corporation.)
-- stb_image by Sean Barrett
-- pocketlzma by Robin Berg Pettersen
-- tomlc99 by CK Tan, MIT licensed.
 - 9-tap Catmull-Rom texture filtering by TheRealMJP.
+- stb_image by Sean Barrett.
+- pocketlzma by Robin Berg Pettersen.
+- tomlc99 by CK Tan, MIT licensed.
 
 ## Release history
 This fork's releases are in [CHANGELOG.md](https://github.com/jackrayner/d2dx/blob/main/CHANGELOG.md). The original project's history up to 0.99.529 is in [docs/upstream-changelog.md](https://github.com/jackrayner/d2dx/blob/main/docs/upstream-changelog.md).
diff --git a/docs/compatibility.md b/docs/compatibility.md
@@ -0,0 +1,28 @@
+# Compatibility
+
+## Game versions
+
+Derived from the source: which versions get the built-in resolution mod is decided in `BuiltinResMod.cpp`, and which get motion prediction (the high-FPS feature) in `D2DXContext.cpp`. "Tested" means somebody has actually played it with this fork's build. CI builds the DLL and runs unit tests but cannot run the game.
+
+| Game version | Custom resolutions | High FPS (motion prediction) | Tested with this fork |
+|---|---|---|---|
+| 1.09d | yes | units, weather | no |
+| 1.10f | no | no | no |
+| 1.12 | no | units, weather | no |
+| 1.13c | yes | units, weather, text | no |
+| 1.13d | yes | units, weather, text | no |
+| 1.14d | yes | units, weather, text | yes, under Wine/Proton (0.0.1) |
+
+Other versions are not supported. The rest of D2DX (scaling, anti-aliasing, windowed/fullscreen handling) is not limited by version in the same way, but only 1.14d has been tried.
+
+Please report results for the untested versions through the [issue tracker](https://github.com/jackrayner/d2dx/issues) (include `d2dx_log.txt`).
+
+## Windows and Wine
+
+- **Windows 10** is recommended. Upstream supported Windows 7 SP1 and later; this fork's DLL is built with the newer v143 toolset and has not been tried on Windows 7 or 8.1.
+- **Linux (Wine/Proton):** 0.0.1 was played on 1.14d through Lutris with Proton on Fedora and ran fine, using `nocompatmodefix=true` in `d2dx.cfg` (see [configuration](https://github.com/jackrayner/d2dx/blob/main/docs/configuration.md)). That is one report on one setup.
+- The DLL is statically linked and uses only Windows system DLLs, so no Visual C++ runtime install should be needed.
+
+## Mods
+
+Other mods change the game files and addresses D2DX hooks, so results vary. Upstream kept a list on its [wiki](https://github.com/bolrog/d2dx/wiki/Compatibility-with-other-mods); it describes upstream's builds. Project Diablo 2 is detected and has its own handling of the suggested resolution.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -0,0 +1,58 @@
+# Configuring D2DX
+
+Written from the source (`src/d2dx/Options.cpp`) and `d2dx-defaults.cfg`. The original project's [wiki](https://github.com/bolrog/d2dx/wiki/) has more background but describes upstream and may be out of date for this fork.
+
+## Config file
+
+Copy `d2dx-defaults.cfg` from the release zip, rename it to `d2dx.cfg`, edit it, and put it in your Diablo II folder. It is [TOML](https://toml.io). Every setting is optional; anything you leave out keeps its default. Settings given on the command line (below) are applied after the file.
+
+### `[window]`
+| Key | Default | Meaning |
+|---|---|---|
+| `scale` | `1` | Integer scale factor for the window, 1 to 3. |
+| `position` | `[-1,-1]` | Window position as `[x,y]`. `[-1,-1]` centres the window. |
+| `frameless` | `false` | Remove the window frame (caption bar etc). |
+
+### `[game]`
+| Key | Default | Meaning |
+|---|---|---|
+| `size` | `[-1,-1]` | In-game resolution as `[width,height]`. `[-1,-1]` lets D2DX choose a suitable size. |
+| `filtering` | `0` | Scaling filter: `0` high quality (sharp, more pixelated), `1` bilinear (blurry), `2` Catmull-Rom (higher quality than bilinear). |
+
+Custom sizes need the built-in resolution mod, which only runs on some game versions (see [compatibility](https://github.com/jackrayner/d2dx/blob/main/docs/compatibility.md)).
+
+### `[optouts]`
+All default to `false`. Setting one to `true` turns the matching D2DX behaviour off.
+
+| Key | Effect when `true` |
+|---|---|
+| `noclipcursor` | Don't lock the mouse cursor to the game window. |
+| `nofpsfix` | Don't apply the basic FPS fix (this also rules out high FPS). |
+| `noresmod` | Don't use the built-in resolution mod (this rules out widescreen). |
+| `nowide` | Don't choose a widescreen resolution (does nothing if `noresmod` is `true`). |
+| `nologo` | Don't show the D2DX logo on the title screen. |
+| `novsync` | Don't use vertical sync. |
+| `noaa` | Don't apply anti-aliasing to jagged edges. |
+| `nocompatmodefix` | Don't block Windows XP compatibility mode. Needed under Wine/Proton: Wine reports Windows 6.2 to one API and 10.0 to another, which D2DX would otherwise take for compatibility mode. (This is from a report of a 1.14d run under Proton, not from reading the Wine source.) |
+| `notitlechange` | Don't change the window title. |
+| `nomotionprediction` | Don't run the game graphics at high FPS. |
+
+### `[debug]`
+| Key | Default | Meaning |
+|---|---|---|
+| `dumptextures` | `false` | Write every texture D2DX uploads to `dump/<category>/<hash>.bmp` in the game folder. For debugging only; it writes a lot of files. |
+
+## Command line
+
+Options are matched anywhere in the command line. Besides the game's own `-3dfx` (required to use D2DX) and `-w` (windowed):
+
+| Option | Same as |
+|---|---|
+| `-dxnoclipcursor`, `-dxnofpsfix`, `-dxnoresmod`, `-dxnowide`, `-dxnologo`, `-dxnovsync`, `-dxnoaa`, `-dxnocompatmodefix`, `-dxnotitlechange` | the `[optouts]` key of the same name, set to `true` |
+| `-dxnomop` | `nomotionprediction = true` |
+| `-dxscale2`, `-dxscale3` | `[window] scale = 2` or `3` |
+| `-dxdbg_dump_textures` | `[debug] dumptextures = true` |
+
+## Log file
+
+D2DX writes `d2dx_log.txt` in the game folder at startup. Attach it when reporting a problem; it shows the detected game version, which features were enabled, and the render size.