Turn on a debug log

The DLL writes several logs. Some are on for every player. Others are tester switches. This page says which section turns on which log, where the file lands, and what to read first.

Status partial: keys, defaults and file names were read from config.rs, the example toml and the module headers. Nothing was run in game for this page. Several logs are marked in their own source as not proven in game; that is repeated below.

Before you start

You edit debug-nightreign.toml beside the DLL (in the package's natives\ folder). Copy debug-nightreign.toml.example if there is none.
A key in debug-nightreign.release.toml wins over the same key in your file. If your change does nothing, look there.
The game reads the files once, at start. Stan restarts the game; you do not.
All paths below are relative to the DLL's folder.

Steps

Pick the log from the table.

You want to know	Section	Default	File
What a boss was doing: animations, speed, SpEffects, idle stalls	`[debug_log]`	on	`eclipse-logs/eclipse-anim.jsonl`, `eclipse-logs/eclipse-debug.jsonl`
Poise drops and breaks, hits on the player, boss fight summaries	`[debug_log]` (`combat`, `poise_*`)	on	`eclipse-logs/eclipse-poise.jsonl`
Exact poise damage per hit	`[debug_log] poise_hooks = true`	off	`eclipse-logs/eclipse-poise.jsonl`
Restage phantoms and the Restage crash	`[debug_log] phantom_log`, `restage_trace`	on, off	`eclipse-logs/eclipse-debug.jsonl`
What an enemy's AI aims at when it attacks	`[attack_trace] enabled = true`	off	`eclipse-logs/eclipse-anim.jsonl`
Enemy AI script errors, goals, Lua memory	`[ai_debug] enabled = true`	off	`ai-debug.log`; `lua_state` lines in `eclipse-logs/eclipse-events.log`
Why a character sound does not play	`[sound_debug] enabled = true`	off	`sound-debug.log`
Event flags changing	`[events] enabled = true` with `watch_flags`	off	`flag-events.log`
Which seed a run got	no switch: written by the seed hooks, one line per expedition	on	`seed-run-log.jsonl`, `seed-boss-log.jsonl`
The path walked in a run	`[runs]`	on	`runs/<UTC date>_seed<pattern>.json`
Crashes	`[crash]`	on	`eclipse-logs/crash-reports/`, `eclipse-logs/eclipse-events.log`
Freezes	`[hang]`	on	`%LOCALAPPDATA%\Nightreign Eclipse\crash-reports\`
The game's server traffic	`[net_capture] enabled = true`	off	`net-capture.jsonl`

Set the keys. Every key with its default is in the reference. The usual [debug_log] edit is to watch the character you care about:
```
[debug_log]
watch_models = ["c9897"]        # by model
watch_rows = [529716000]        # by NpcParam row; the only way to pick a human (model c0000)
poise_models = ["c9897"]
fight_models = ["c9897"]
```
Setting one of these lists replaces its default (the eight port bosses, or the three evergaol humans and their Boss Menu clones).
Tell Stan what to do in game and which files to send back.
Read chr_layout_check first (next section). Then read the log.

Read `chr_layout_check` first

The first chr_layout_check line of each launch is in eclipse-logs/eclipse-debug.jsonl. It shows what the DLL reads for the local player: local.row, local.model, local.type, pos, anim, poise, hp, blocks, and how many characters it found (chrs).

These values come from fixed offsets found by static reverse engineering. Nightreign's layout differs from Elden Ring's. If the row, model, poise, HP or animation look wrong, the offsets are wrong for this exe build, and nothing else in the logs can be trusted.
The local player reads row 0.
"poise": null means the poise module was not recognised. Then the poise_* lines mean nothing.
The chr_watch_ready line next to it says which newer offsets passed their checks: layout.super_armor, layout.hp, layout.hand. A failed one turns off only the lines that need it.
Each log file starts with a log_start line (Eclipse version, me3, exe). Check it is the build you expect.

The `[debug_log]` keys

Key	Default	Meaning
`enabled`	`true`	The logs in `eclipse-logs/`. With only this, no hooks: a thread reads memory.
`max_file_kb`	2048	Size at which each log rotates.
`keep_files`	1	Rotated copies kept per log.
`watch_models`	the 8 port bosses	Models sampled per animation (`c9897` or `9897`).
`watch_rows`	3 evergaol humans + their Boss Menu clones	NpcParam rows watched the same way.
`watch_radius`	40.0	Only within this many metres of the player.
`watch_max_chrs`	4	At most this many of the nearest.
`skip_frozen_s`	10.0	Pass over a watched character whose animation has not moved this long (hidden menu clones). 0 = off.
`sample_ms`	33	How often watched characters are read.
`anim_log_ms`	250	One `anim` line per character at least this often; a change logs at once.
`poise_rows`	`[]`	NpcParam rows whose poise is logged on each change.
`poise_models`	the 8 port bosses	The same, by model.
`combat`	`true`	The combat channel: `hit`, `player_state`, `fight_start`, `fight`, `run_summary`.
`fight_models`, `fight_rows`	as `watch_*`	Characters whose fights are summed up.
`fight_min_hp`	0	Any character with at least this max HP also counts as a boss. 0 = off.
`fight_radius`	40.0	A fight starts when the boss is this close and loses HP or hits the player.
`fight_idle_s`	60.0	A fight ends after this long with neither.
`boss_idle`	`true`	One line when a watched character holds one animation in place near you.
`idle_s`, `idle_move_m`, `idle_radius`	6.0, 0.5, 25.0	The limits for `boss_idle`.
`speffect_watch`	12 ids	SpEffect ids logged on any character when they come or go.
`local_speffects`	`true`	The player's own SpEffects, added and removed.
`npc_gates`	`true`	The sound handler's gate fields of `watch_rows` characters, on change.
`pos_log_ms`	1000	`player_pos` lines this often in an expedition. 0 = off. Not in the example toml.
`poise_hooks`	`false`	Testers: exact poise damage and each hit's raw data. Adds two hooks.
`phantom_log`	`true`	Restage phantoms seen and gone.
`restage_trace`	`false`	Testers: Restage overlap counters, phantom spawn and destroy. Adds six hooks.
`skip_replay_gc`	`false`	Testers, with `restage_trace`: skips the script GC job on phantoms. Changes behaviour.

[debug_log.caps] raises or lowers the lines-per-launch cap of one line kind, for example hit = 5000. A capped kind stops with one log_capped line. Built-in caps are listed in the example toml.

What the three files hold

eclipse-debug.jsonl: sessions (session: solo, host or guest), seed runs, hook repairs, phantoms, the Restage trace, and the rare kinds boss_idle, npc_gates, speffect_watch, local_speffects, frozen_near, watch_chr. Also hitbox_draw, storm_control and drive_slow lines.
eclipse-anim.jsonl: anim and speffects lines of watched characters; attack_start, ai_target, anim_change from [attack_trace].
eclipse-poise.jsonl: the combat channel. The file keeps its old name.

In an anim line, rate is measured animation speed, spd is ground speed in m/s, near is within 20 m. Beyond 20 m characters update in bursts, so rate is noise there. A line with "stale": true was written while the game's frames stood still.

Steam IDs, user names and computer names are scrubbed from these logs. They stay on the PC unless the player opts in to the launcher's upload.

What goes wrong

No eclipse-logs folder. The DLL is older than the logging, or it did not load.
A kind stops mid-run. It hit its cap. Look for log_capped, then raise it in [debug_log.caps].
anim lines are missing for a human boss. Humans are model c0000. Watch them by watch_rows.
[attack_trace] writes nothing. It needs [debug_log] enabled = true.
[stance_log] in an old toml. That section is gone. It never logged anything. The poise_* lines replace it. An old toml with the section still loads.
Other logs went quiet after you set [ai_debug] exclusive = true. exclusive installs only the AI hooks (plus hot reload, sound debug and [events]). Most other features of the DLL are then off, by design.
No lua_state lines. They need [ai_debug] enabled = true and lua_budget = true.