horizon/docs/windows-allocators.md

Windows allocator experiments

The normal client already uses mimalloc through horizon_threads::Allocator, including its startup configuration and memory-release behavior. It does not request Windows Segment Heap. An off-by-default Cargo feature allows a separate experiment with the Win32 heap used by native libraries:

Feature	Effect on Windows
windows-segment-heap	Embeds a manifest requesting Segment Heap for Win32 heap APIs in this package's executables.
windows-mimalloc	Compatibility no-op for earlier experiment commands; the client already uses mimalloc without this feature.

Neither feature changes non-Windows builds relative to the current main branch. Segment Heap is a build option, not a mod or runtime setting; changing it requires rebuilding and restarting the client. It does not replace or reconfigure the Rust allocator. Native libraries can still use Windows heap APIs even though Rust uses mimalloc. No frame-rate improvement is guaranteed.

# Current mimalloc baseline, then add Segment Heap. Keep the same profile.
cargo build --profile fast -p horizon-client --bin horizon-client
cargo build --profile fast -p horizon-client --bin horizon-client --features windows-segment-heap
# Older commands still build, but these repeat the two variants above.
cargo build --profile fast -p horizon-client --bin horizon-client --features windows-mimalloc
cargo build --profile fast -p horizon-client --bin horizon-client --features windows-segment-heap,windows-mimalloc

Copy each executable to a separate experiment directory before building the next variant, or use a separate CARGO_TARGET_DIR. Keep prepared resources and worlds outside version control. Use disposable copies of a world and isolated data directories for tests, following AGENTS.md.

Segment Heap is supported starting with Windows 10 version 2004 (build 19041), according to Microsoft's application manifest documentation. The manifest leaves the optional architecture unspecified and keeps the usual asInvoker execution level. The existing icon and version resources are compiled together with it through the existing Windows-host resource build step. Cross-compiling that manifest from a non-Windows host is not supported by this build step. Builds on earlier Windows versions have not been tested.

Validate the executable

On Windows, extract the manifest from a built executable using the Windows SDK's mt.exe (PowerShell syntax):

mt.exe '-inputresource:target/fast/horizon-client.exe;#1' '-out:client.manifest'
mt.exe -manifest client.manifest -validate_manifest

Check that the feature build contains SegmentHeap in the http://schemas.microsoft.com/SMI/2020/WindowsSettings namespace. The baseline must not contain this element. Confirm Explorer still shows Horizon's icon for both builds. Inspecting the final executable matters: a valid source XML file alone does not prove that the linker embedded it.

Measure separately

Use the same commit, compiler, profile, settings, driver configuration, world copy, warm-up period and flight route for both variants. Alternate their order across repeated sessions. Capture individual frame times, their p99 and maximum, memory use and average FPS. Record game FPS limits, the display refresh rate and driver-level VSync: a driver override can cap FPS even when game VSync is disabled.

Compare the current mimalloc baseline with that same build plus Segment Heap. The compatibility feature cannot measure system allocation versus mimalloc. Results from older system-allocator builds, or builds that also change meshing or LOD retirement, cannot establish the benefit of Segment Heap on current main.