Build and install the debug DLL

Status partial: the build command, the output path, the load path and the config file names were read from the code and from a shipped package. The build was not run for this page. The release worktree rule is a team rule; what could be checked of it is marked.

Before you start

• Rust, stable channel (rust-toolchain.toml in S:/fromsoftware-rs). Target x86_64-pc-windows-msvc.
• Decide what the DLL is for:
  • a test DLL for yourself or Stan: any worktree will do;
  • the DLL that ships in a release: a clean release worktree. See "The release rule" below.
• A cargo build is heavy. Run it through the build scheduler: eb.py run --mem <GB> -- <command>.

Steps

1. Build from the workspace root (or the worktree's root):

   cargo build -p debug-nightreign --release --target x86_64-pc-windows-msvc
   

   S:\souls-script-kt\scripts\tools\build-debug-nightreign.ps1 runs the same command; -FromSoftwareRsRoot <path> points it at another checkout or worktree.

2. Take the DLL from:

   <root>\target\x86_64-pc-windows-msvc\release\debug_nightreign.dll
   

   The crate is debug-nightreign; the library is debug_nightreign (a cdylib). The release profile is size-optimised, stripped, and panic = "abort".

3. Put it in the package's natives\ folder as natives\debug_nightreign.dll.

4. Check the me3 profile loads it. A shipped profile (depth6-online-mods.me3 of release 0.0.51) has:

   [[natives]]
   path = 'natives/debug_nightreign.dll'
   

   The same profile sets disable_arxan = true. Without it, the game's anti-tamper repairs its own code during a session and removes hooks; the DLL re-arms some of them, but not all.

5. Put the config beside the DLL:

   • natives\debug-nightreign.toml: the player's file. Start from debug-nightreign.toml.example. A missing file means defaults.
   • natives\debug-nightreign.release.toml: the release's file. Every key in it wins over the player's file, key by key. A setting that must hold for everyone goes here.
   • natives\debug-nightreign.seeds.toml: written by the launcher. It can only switch pool seeds off.

6. Stop. Tell Stan it is installed. Do not start the game. He launches Nightreign himself.

How to tell it worked

After Stan has started the game once, beside the DLL:

• chains-debug (the DLL's text log) exists. Startup lines say which file set which key.
• eclipse-logs\eclipse-events.log has a new start line with the exe timestamp and the Eclipse version.
• eclipse-logs\eclipse-debug.jsonl starts with a log_start line.

You can test crash capture without the game. Outside nightreign.exe the DLL installs only crash capture:

rundll32 debug_nightreign.dll,eclipse_crash_test
rundll32 debug_nightreign.dll,eclipse_crash_test overflow
rundll32 debug_nightreign.dll,eclipse_crash_test panic

These write real dumps. Windows keeps only its 10 newest crash dumps, so test crashes can push out a real Nightreign dump. Copy an important dump away first.

The release rule

The DLL that ships is built from a clean release worktree, not from the main checkout's working tree.

Why: the main checkout at S:/fromsoftware-rs usually holds uncommitted work from other sessions. A DLL built there would ship unreviewed code.

What could be checked on 2026-11-12:

• The main checkout does have uncommitted edits in tools/debug-nightreign and untracked source files there.
• Release worktrees exist beside the main checkout, one per release, on branches named debug-nightreign/release-<nnnn> (for example S:/fromsoftware-rs-wt-release100 on debug-nightreign/release-0100). git worktree list shows them.

How it is done (team note, last updated 2026-11-10; not re-run here):

1. Make a worktree for the release, branched from the last release's commit.
2. Bring in only the reviewed patches for this release.
3. Build there with the cargo command above.
4. Stage the DLL in its own stage. The note says the stage kind is binary; release.py rejects kind dll.
5. Two builds of the same commit are not byte-identical (link timestamp). The code is the same.

What goes wrong

• The DLL loads but a feature does nothing. Check chains-debug for the config notes. The release toml may be overriding the key you set.
• A setting you changed came back. The launcher never overwrites an edited debug-nightreign.toml, but every update replaces debug-nightreign.release.toml.
• The game crashes at load from a USB or network drive. build.rs links the DLL so Windows copies it to memory when it is loaded from removable or network media. A USB disk that reports as fixed is not covered by that flag.
• The bigger Lua heap did not apply. [lua_heap] must run while me3 loads the DLL, before the game creates the heap. The lua_heap event in eclipse-events.log gives the reason (exe_mismatch, heap_already_created and others).