logan/onion-mc
1
0 Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
611a1a5952178cd10524010dcad5c8ce7d34e77f
onion-mc/analysis/client-perf/research/r2-dh-xaero.md
T
logan 611a1a5952 docs: client-perf analysis, bench harness and work journal 
Everything the next agent needs to run the Phase 2 optimisation loop on a
machine that can launch the client:

- analysis/client-perf/: LEVERS (ranked levers + corrections), BENCH-MATRIX
  (world, scenes, config IDs, blocks B0-B14 with decision rules),
  PLAYER-TUNING, SPAWN-TUNING, research briefs, the jar scanner and its
  output, observed default configs, and proposed-configs/ (build.py
  generates tiers and bench variants and fails on unknown keys;
  apply_variant.py applies a variant and merges options.txt).
- analysis/client-perf/bench/onion-bench/: bench-world datapack (scene
  teleports, Create grid, mob pen, sound storm, 120 s teleport tour).
- analysis/audit/: the static recipe/dependency audit, including gen_fixes.py,
  which generates the shipped Paxi datapack and was never tracked.
- phase0/: per-machine measurement harness (Steam Deck, 7700K/1060,
  6700K/1080 Ti).
- .pi/journal.md: running work log; read it first.

All of it is packwizignored, so nothing here ships to players.
2026-10-14 18:15:32 -04:00

186 lines
30 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Research: Distant Horizons 3.3.x (client) + Xaero's Minimap 26.5.0 / World Map 1.46.0 — client-side performance
Pack context: Onion MC, MC 1.21.1 / NeoForge 21.1.251, pinned `DistantHorizons-3.3.2-1.21.1-fabric-neoforge.jar`, `xaerominimap-neoforge-1.21.1-26.5.0.jar`, `xaeroworldmap-neoforge-1.21.1-1.46.0.jar` (verified against `mods/*.pw.toml` in this repo). Dedicated server with DH; Iris 1.8.14-beta.1; shaderpacks Complementary Reimagined r5.9.3 + MakeUp Ultra Fast 9.5f. All 3 fleet machines are 4C/8T.
## Summary
DH 3.3.2's client cost splits into (a) CPU: LOD building/generation threads (thread preset; on 8 logical CPUs BALANCED = 4 threads, Minimal = 1), and (b) GPU/VRAM: LOD render distance × quality preset (distance is the dominant term; DH docs say >512 chunks gets "difficult due to high VRAM/GPU usage"; a 1.x-era dev-tracker data point put 1024 chunks at ~4 GB VRAM). In multiplayer the client cannot generate LODs at all — the server sends them (default 500 KB/s per player) — so client-side "distant generation" settings are singleplayer-only; server pregen via `/dh pregen` is the officially recommended path, and running Chunky alongside DH generation is explicitly warned against (holes). Xaero's pair is cheap: the minimap reuses world-map textures by default, world-map disk data grows with exploration but in-RAM region cache is bounded (cappable via a "max loaded regions" setting added in 1.41.2), and the map screen skips world rendering by default.
## Findings — Distant Horizons 3.3.2
### 1. What each client setting actually costs (keys verified from the pinned jar's `assets/distanthorizons/lang/en_us.json` + DH core source)
GUI path and TOML key names below were read from the 3.3.2 jar and DH core `Config.java`; every listed key exists in 3.3.2. [Config.java (DH core, main/3.3.x line)](https://gitlab.com/distant-horizons-team/distant-horizons-core/-/raw/main/core/src/main/java/com/seibel/distanthorizons/core/config/Config.java), [lang file in jar 3.3.2](https://modrinth.com/mod/distanthorizons/version/3.3.2-1.21.1)
| Concern | Key (GUI path) | Verified facts |
|---|---|---|
| LOD render distance | `client.advanced.graphics.quality.lodChunkRenderDistanceRadius` | min 32 / **default 256** / max 4096 chunks; "best effort" number [Config.java](https://gitlab.com/distant-horizons-team/distant-horizons-core/-/raw/main/core/src/main/java/com/seibel/distanthorizons/core/config/Config.java); official gallery: "By default DH renders 256 chunks wide… anything above 512 may become difficult due to high VRAM/GPU usage" [Modrinth gallery](https://modrinth.com/mod/distanthorizons/gallery) |
| Quality preset | `client.qualityPresetSetting` (MINIMUM/LOW/MEDIUM/HIGH/EXTREME) | Preset just sets the sub-options below; **generation is independent** — "DH will always generate LODs at the maximum possible quality so you can use any Quality preset you want later" (no regen needed) [DH FAQ General](https://gitlab.com/distant-horizons-team/distant-horizons/-/wikis/1-user-guide/1-frequently-asked-questions/1-general/General) |
| Horizontal quality / resolution | `…quality.horizontalQuality`, `…quality.maxHorizontalResolution` | "Higher settings will … increase memory and GPU usage"; resolution BLOCK = 256 LODs/chunk (fanciest) vs CHUNK = 1 LOD/chunk (fastest) [Config.java](https://gitlab.com/distant-horizons-team/distant-horizons-core/-/raw/main/core/src/main/java/com/seibel/distanthorizons/core/config/Config.java) |
| Vertical quality | `…quality.verticalQuality` | HEIGHT_MAP (cheapest) → PIXEL_ART; "higher options … increase memory and GPU usage"; too-low vertical quality causes flat/discolored LODs [Config.java + Problems & Solutions](https://gitlab.com/distant-horizons-team/distant-horizons/-/wikis/1-user-guide/1-frequently-asked-questions/2-problems-and-solutions/Problems-and-Solutions) |
| Transparency | `…quality.transparency` | Only `DISABLED` or `COMPLETE` in 3.3.2 (fake transparency removed in 3.1.0-b); DISABLED = opaque LODs = cheaper; **3.1.1-b+ forces transparency ON when Iris is present** [changelog 3.1.0-b/3.1.1-b](https://modrinth.com/mod/distanthorizons/version/3.1.1-b-1.21.1) |
| Cave culling | `…culling.enableCaveCulling`, `…culling.caveCullingHeight` (default 60) | "culls all faces with skylight value of 0 under the cave culling height" — big face-count saver in mountains/overhangs [lang tooltip, jar 3.3.2] |
| Overdraw | `…culling.overdrawPrevention` (default −1 = auto), `…culling.reduceOverdrawWithFastMovement` | % of vanilla RD where DH starts rendering behind vanilla terrain; −1 auto-scales; holes-at-edge tradeoff documented; auto reduce while flying [Config.java + P&S quick guide](https://gitlab.com/distant-horizons-team/distant-horizons/-/wikis/1-user-guide/1-frequently-asked-questions/2-problems-and-solutions/Problems-and-Solutions) |
| Frustum culling | `…culling.disableFrustumCulling` (default false = culling ON), `…culling.disableShadowPassFrustumCulling` | Culling "increasing GPU performance"; leave enabled (disabled only if LODs pop at screen corners) [lang tooltip] |
| Vanilla fade mode | `…quality.vanillaFadeMode` (NONE/SINGLE_PASS/DOUBLE_PASS) | NONE "Fastest… pronounced border"; DOUBLE_PASS "Slowest… smoothest" (MEDIUM+ default) [Config.java] |
| DH SSAO / AA | `client.advanced.graphics.enableSsao`, `…enableAntiAliasing` | 3.3.0 added TAA; SSAO/AA off in MINIMUM/LOW presets [changelog 3.3.0](https://modrinth.com/mod/distanthorizons/version/3.3.0-1.21.1) + preset handler source |
| LOD textures | `…texture.enableTexturedLods`, `maxTexturedLodDetailLevel` | 3.2.0 feature; "Only available for base DH rendering, **Iris shaders will render LODs as untextured**" → no shader cost under Iris either way [changelog 3.2.0-b](https://modrinth.com/mod/distanthorizons/version/3.2.0-b-1.21.1) |
| DH clouds/beacons | `…genericRendering.enableCloudRendering`, `enableMultiLayerClouds`, `enableBeaconRendering` | DH renders its own 3-layer clouds; GPU filler; Complementary sets `dhClouds = off` (see §4) |
| Zoom quality | `…quality.increaseQualityWhenZoomedIn`, `maxZoomQualityIncrease` (default 4) | Loading crisper LODs while zoomed costs CPU/memory while zoomed [Config.java; 3.3.0 fixed "massive lag when zoomed in and spinning the camera"] |
| CPU threads | `client.threadPresetSetting` → `common.multiThreading.numberOfThreads`, `threadRunTimeRatio`, `threadPriority`, `useC2meThreadCount` | Preset = % of **logical** CPUs (source has table: 1.0 ⇒ 8 threads on 8 logical) + runtime ratio [ThreadPresetConfigEventHandler](https://gitlab.com/distant-horizons-team/distant-horizons-core/-/raw/main/core/src/main/java/com/seibel/distanthorizons/core/config/eventHandlers/presets/ThreadPresetConfigEventHandler.java) |
| LOD storage | `common.lodBuilding.dataCompression` (LZ4/ZSTD…), `worldCompression` (MERGE_SAME_BLOCKS/VISUALLY_EQUAL), `databaseSyncMode` (FULL/NORMAL/OFF), `disableUnchangedChunkCheck` | LODs live in SQLite (`.minecraft/Distant_Horizons_server_data/<server>/` in MP); NORMAL sync default since 3.3.0 cut disk work ~50%; OFF risks corruption on power loss [General FAQ](https://gitlab.com/distant-horizons-team/distant-horizons/-/wikis/1-user-guide/1-frequently-asked-questions/1-general/General), [changelog 3.3.0](https://modrinth.com/mod/distanthorizons/version/3.3.0-1.21.1) |
| World gen (SP only) | `common.worldGenerator.enableDistantGeneration`, `generatorPlan` (SURFACE_THEN_CHUNKS/SURFACE_ONLY/CHUNKS_ONLY/DISABLED), `chunkGeneratorMode` (…/SURFACE/FEATURES/INTERNAL_SERVER), `enableFastSurfaceGenerator`, `limitIfServerUnhealthy`, `pauseIfMovingQuickly` | 3.3.0 added fast surface gen + "pause world gen if server thread overloaded or moving quickly — both options can be toggled… if faster world gen is desired over smoothness" [changelog 3.3.0](https://modrinth.com/mod/distanthorizons/version/3.3.0-1.21.1) |
Quality preset → what it sets (from [RenderQualityPresetConfigEventHandler.java](https://gitlab.com/distant-horizons-team/distant-horizons-core/-/raw/main/core/src/main/java/com/seibel/distanthorizons/core/config/eventHandlers/presets/RenderQualityPresetConfigEventHandler.java)) — note the trap that **HIGH/EXTREME turn cave culling OFF**:
| Preset | maxHorizRes | Vertical | Horizontal | Transparency | SSAO | AA | Vanilla fade | Cave culling | Biome blending |
|---|---|---|---|---|---|---|---|---|---|
| Minimum | 2-block | Height map | Lowest | Disabled | off | off | None | on | 0 |
| Low | Block | Low | Low | Disabled | off | on | Single pass | on | 1 |
| Medium | Block | Medium | Medium | Complete | on | on | Double pass | on | 3 |
| High | Block | High | High | Complete | on | on | Double pass | **off** | 3 |
| Extreme | Block | Extreme | Extreme | Complete | on | on | Double pass | **off** | 3 |
Thread presets on the fleet's 4C/8T (source: `ThreadPresetConfigEventHandler` — percentages of `availableProcessors` = 8 logical):
| Preset | Threads | Runtime ratio |
|---|---|---|
| Minimal Impact | 1 | 0.5 |
| Low Impact | 2 | 1.0 |
| Balanced (default) | 4 | 1.0 |
| Aggressive | 6 | 1.0 |
| I Paid For The Whole CPU | 8 | 1.0 |
### 2. GPU upload settings — removed in 3.x
The old 2.x-era `gpuUploadMethod` (Direct / Single draw / Multi draw / Buffer storage) **no longer exists in 3.3.2**: the full option list in the pinned jar contains no upload-method key, and the 3.0.0-b changelog states "Remove instanced rendering config option — instanced rendering will always be used if available". The only related control left is `client.advanced.graphics.experimental.renderingEngine` (Auto / OpenGL / Blaze3D); Blaze3D is only for newer MC — on 1.21.1 it's effectively OpenGL/Auto, and DH ≥3.3 renders with reverse-Z depth. [jar lang file](https://modrinth.com/mod/distanthorizons/version/3.3.2-1.21.1), [changelog 3.0.0-b](https://modrinth.com/mod/distanthorizons/version/3.0.0-b-1.21.1), [changelog 3.1.0-b](https://modrinth.com/mod/distanthorizons/version/3.1.0-b-1.21.1). VERIFIED.
### 3. VRAM / RAM vs distance (no first-party table exists)
- Official qualitative: memory & GPU usage rise with horizontal/vertical quality, max resolution and LOD distance (config comments); >512 chunks "difficult due to high VRAM/GPU usage" [Config.java](https://gitlab.com/distant-horizons-team/distant-horizons-core/-/raw/main/core/src/main/java/com/seibel/distanthorizons/core/config/Config.java), [Modrinth gallery](https://modrinth.com/mod/distanthorizons/gallery). DOCUMENTED.
- Only quantitative tracker data point is old (DH 1.x, 2022): "1024 with default settings uses ~4 GB VRAM and more than 8 GB RAM should be allocated to JRE or else there will be intense stuttering" [GitLab issue #157](https://gitlab.com/distant-horizons-team/distant-horizons/-/issues/157). COMMUNITY/dev-tracker, dated — treat as order-of-magnitude only.
- Heap guidance is first-party: 4–8 core CPUs → allocate 6–8 GB; 10+ cores → 12–16 GB; prefer ZGC (`-XX:+UseZGC`) over G1GC on Java 21 "known to cause stuttering"; DH even warns in-chat if G1GC is used [DH FAQ General](https://gitlab.com/distant-horizons-team/distant-horizons/-/wikis/1-user-guide/1-frequently-asked-questions/1-general/General), [P&S](https://gitlab.com/distant-horizons-team/distant-horizons/-/wikis/1-user-guide/1-frequently-asked-questions/2-problems-and-solutions/Problems-and-Solutions). VERIFIED.
- Community starting profile for mid hardware: LOD 96–192 chunks at Medium quality [distanthorizonsguide calculator](https://distanthorizonsguide.com/calculator). COMMUNITY.
- Official troubleshooting maps symptom→setting: CPU pegged → lower CPU preset or disable world gen; GPU pegged → lower quality preset or LOD distance; VRAM pegged → same [P&S](https://gitlab.com/distant-horizons-team/distant-horizons/-/wikis/1-user-guide/1-frequently-asked-questions/2-problems-and-solutions/Problems-and-Solutions). VERIFIED.
### 4. Iris shader cost & which packs support DH
- Iris ≥1.7 required; DH terrain renders through dedicated `dh_terrain`, `dh_water` and `dh_shadow` programs defined by the shaderpack — i.e. LODs are drawn with full shader effects, so shader cost scales to the LOD distance too; the DH shadow pass can be toggled per-pack via `dhShadow.enabled` [Iris docs — Distant Horizons](https://shaders.properties/current/reference/mod-support/distant_horizons/). VERIFIED.
- **Complementary Reimagined r5.x supports DH**: its `shaders.properties` has a `#ifdef DISTANT_HORIZONS` block with `blend.dh_water=…` and, importantly, `dhShadow.enabled = false` + `dhClouds = off` — the DH shadow pass and DH clouds are disabled, trimming shader work over distant terrain [Complementary Reimagined source](https://raw.githubusercontent.com/ComplementaryDevelopment/ComplementaryReimagined/main/shaders/shaders.properties). VERIFIED.
- **MakeUp Ultra Fast also has DH support**: `#ifdef DISTANT_HORIZONS: dhShadow.enabled = false; blend.dh_water=…` [MakeUp Ultra Fast source](https://raw.githubusercontent.com/javiergcim/MakeUpUltraFast/master/shaders/shaders.properties). VERIFIED. Both pack shaders therefore avoid the most expensive DH-over-shader path (DH shadows render *all* chunks into the shadow map).
- Shaders that don't support DH prevent LODs from rendering entirely [P&S](https://gitlab.com/distant-horizons-team/distant-horizons/-/wikis/1-user-guide/1-frequently-asked-questions/2-problems-and-solutions/Problems-and-Solutions). VERIFIED.
### 5. Client-generated vs server-provided LODs (this pack: server-provided)
- In multiplayer, clients **cannot** generate LODs: "Can clients generate instead? No, world generation is coupled with server-side logic" — the client requests and receives LODs (normal generation), gets real-time updates near players, and sync-on-load with timestamps [Server Owners wiki](https://gitlab.com/distant-horizons-team/distant-horizons/-/wikis/1-user-guide/1-frequently-asked-questions/5-server-owners/Server-Owners). VERIFIED.
- Server must have the same DH version; `Distant Generator Plan` must not be `DISABLED` on either side. Defaults allow **500 KB/s (4 Mbit/s) per player** of LOD traffic (`server.playerBandwidthLimit`); other keys: `generationRequestRateLimit`, `maxGenerationRequestDistance`, `enableRealTimeUpdates` + `realTimeUpdateDistanceRadiusInChunks`, `synchronizeOnLoad` + `syncOnLoadRateLimit` + `maxSyncOnLoadRequestDistance`, `globalBandwidthLimit`, `enableAdaptiveTransferSpeed` [Server Owners wiki + jar lang](https://gitlab.com/distant-horizons-team/distant-horizons/-/wikis/1-user-guide/1-frequently-asked-questions/5-server-owners/Server-Owners). VERIFIED. Client-side keys: `client.advanced.multiplayer.serverFolderNameMode` (local LOD DB naming).
- "Pre-generating LODs is strongly recommended to avoid performance issues" — command `/dh pregen start <dimension> <origin> <chunkRadius>`; avoid pregen on a live server. Client-side pregen alternative: copy server world, generate AFK, ship the SQLite DB back [Server Owners wiki](https://gitlab.com/distant-horizons-team/distant-horizons/-/wikis/1-user-guide/1-frequently-asked-questions/5-server-owners/Server-Owners). VERIFIED.
- World-gen mode notes: default `FEATURES` mode doesn't save generated chunks, so trees/structures can pop in/out at LOD borders; `INTERNAL_SERVER`/`FULL` prevents it [P&S](https://gitlab.com/distant-horizons-team/distant-horizons/-/wikis/1-user-guide/1-frequently-asked-questions/2-problems-and-solutions/Problems-and-Solutions). VERIFIED.
### 6. Known warnings relevant to this pack
- **DH + Chunky**: "Running Chunky will also generate & update LODs, but it's not recommended to rely on this… by loading a lot of chunks quickly you risk overloading DH and ending up with a lot of holes. Either use DH's pre-generation, or temporarily disable the mod entirely" [Server Owners wiki](https://gitlab.com/distant-horizons-team/distant-horizons/-/wikis/1-user-guide/1-frequently-asked-questions/5-server-owners/Server-Owners). DH 3.3.x also changed thread linking: "Don't link DH thread count to C2ME unless Chunky is also present… Using Chunky and DH isn't recommended due to the possibility of holes" [changelog 3.3.0](https://modrinth.com/mod/distanthorizons/version/3.3.0-1.21.1); 3.3.3 added auto-disable of DH worldgen while Chunky worldgen runs (3.3.2 does **not** have that guard). VERIFIED.
- **DH + Alex's Caves**: LODs fail to render; fix = set `biome_ambient_light_coloring = false` in `config/alexscaves-client.toml` (DH bug tracker issue #566) [DH wiki Mod Support](https://gitlab.com/distant-horizons-team/distant-horizons/-/wikis/1-user-guide/1-frequently-asked-questions/4-mod-support/Mod-Support). VERIFIED.
- **DH 3.3.2 + SSRD**: "Mark SSRD (Separate Sable Render Distance) 1.8.6 and below as incompatible — due to DH's change to rendering with Reverse Z depth". Pack has SSRD 1.8.7 → OK, but don't downgrade it [changelog 3.3.2](https://modrinth.com/mod/distanthorizons/version/3.3.2-1.21.1). VERIFIED.
- **Steam Deck / Mesa**: DH+ Sodium crash on Linux AMD/Intel Mesa GPUs → disable Sodium's "Use No Error context" (and delete DH config once) [P&S](https://gitlab.com/distant-horizons-team/distant-horizons/-/wikis/1-user-guide/1-frequently-asked-questions/2-problems-and-solutions/Problems-and-Solutions). DH 3.2.0 raised min OpenGL 3.2→3.3 (AMD fix) [changelog 3.2.0-b](https://modrinth.com/mod/distanthorizons/version/3.2.0-b-1.21.1). VERIFIED. Deck players run 128–256 LOD with Iris shaders at 30–40 FPS at 1200×800 [r/DistantHorizons](https://www.reddit.com/r/DistantHorizons/comments/1by5v4u/how_to_get_distant_horizons_working_on_steam_deck/), [r/SteamDeck](https://www.reddit.com/r/SteamDeck/comments/1lak2s5/how_i_got_minecraft_running_with_distant_horizons/). COMMUNITY.
- Black LODs from light-map mods; "Mod Compatibility Warnings" exist at `Advanced → Logging → Warnings` if a known-bad combo is present [P&S + jar lang]. VERIFIED (key exists).
### 7. Recommended starting settings per fleet machine
All values use verified keys; distances assume server VD 8 (vanilla) and server-side pregen so the client isn't starved of LODs. (INFERENCE from the verified mechanics + community profiles above.)
| Setting | (a) Steam Deck (RDNA2 8CU, 1280×800, shared RAM) | (b) P1 GTX 1060 6GB (VRAM-bound) | (c) P2 4C + ~8GB free RAM (heap-bound) |
|---|---|---|---|
| LOD render distance | 96–128 | 128–192 (step up slowly; shaders over 512-chunk LODs is where VRAM dies) | 96–128 (lower if heap spikes) |
| Quality preset | LOW | LOW–MEDIUM (watch VRAM; MEDIUM re-enables transparency+SSAO) | MEDIUM or LOW (quality is render-only cost; cheap to lower) |
| Cave culling | ON (do **not** use HIGH/EXTREME presets without re-enabling) | ON | ON |
| Thread preset | Minimal/Low Impact (leave headroom for Deck's APU) | Low Impact/Balanced | Balanced (4 threads) while playing; Minimal if stutter |
| SSAO / DH anti-aliasing | off (LOW preset) | off unless headroom | default |
| Transparency | Disabled (if no shader) | forced Complete under Iris | forced Complete under Iris |
| Vanilla fade mode | Single pass | Double pass (visual seam vs GPU) | Double pass |
| DH clouds/beacons | off if GPU-bound (Complementary already disables DH clouds) | off | default |
| JVM heap | 6–8 GB `-Xmx` + `-XX:+UseZGC` (wiki guidance) | 6–8 GB | ≤6 GB; prefer cutting LOD distance over heap |
| Generation | server provides LODs; keep `enableDistantGeneration` irrelevant in MP | same | same; keep client DB sync NORMAL |
## Findings — Xaero's Minimap 26.5.0 / World Map 1.46.0
### 8. Where the cost is, and the verified settings that control it
Field names below were extracted from the pinned jars' settings classes (`xaero/common/settings/ModSettings.class`, `xaero/map/settings/ModSettings.class`) — the mods are closed-source but NeoForge builds ship Mojang-mapped symbols. VERIFIED (jar extraction).
| Cost center | Mechanism | Relevant verified settings/keys |
|---|---|---|
| Minimap terrain | Chunk-to-pixel updates as you move; renders into its own FBO (`MinimapFBORenderer`, `bufferSize`) | `minimapSize` (bigger = more fill rate), `zoom`, `caveZoom` |
| Cave mode | Renders below-ground slices; needs roof search + extra depth scanning | `caveMaps` (on/off), `caveMapsDepth`, `caveMapsDisabled`, `manualCaveModeStart`, `autoCaveMode` (WM), per-dimension `defaultCaveModeType`, `legibleCaveMaps` |
| Shading | Extra per-chunk color math | `terrainDepth`, `terrainSlopes`, `biomeBlending`, `blockColours`, `ambientLightColored` |
| Entity radar | Per-frame entity scan + icon rendering (model-based icons are pre-rendered; heavy entity mods = more types) | `entityRadar`, `mainEntityAs`, `dotsStyle`, `smoothDots`, `radarHideInvisibleEntities`, display-names toggles; categories in `xaero/minimap` config |
| Overlays | Extra scans | `displayRedstone`, `displayStainedGlass`, `slimeChunks`, `lightOverlay*` |
| World Map rendering | Full-screen map; **skips world rendering by default while the map is open** — turning that off "significantly reduces your framerate" (official changelog) | world-map-screen "world render skip" option; `openMapAnimation`, `zoomButtons` |
| World Map writing | Client converts explored chunks into region data; "Optimized map writing… less useless chunk iteration" (26.2.0/1.42.0) | `mapWritingDistance` (limit writing distance; option exists since 1.35.0), **"Force Fast Writing"** — official: "Bad for game performance" |
Official changelog anchors: world map 1.42.0 (fast-writing "bad for game performance", world-render skip, optimized map writing), 1.41.2 ("Added a new option… for setting the **maximum number of loaded regions**"), 1.35.0 (map writing distance option), 1.37.2 ("Slightly optimised region unloading"); minimap 26.2.0 ("Optimized map writing"), 25.3.12 (BatchableBufferSource / ImmediatelyFast interplay) — [chocolateminecraft update pages](https://chocolateminecraft.com/update.php?mod_id=2) and [mod_id=0](https://chocolateminecraft.com/update.php?mod_id=0). DOCUMENTED.
### 9. Does world map memory scale with explored area?
- **On disk: yes, unbounded-ish** — regions are saved as `.zip` files per dimension/map under `xaero/world-map/…` (plus separate cache folders the FAQ says can be deleted) [Modrinth FAQ](https://modrinth.com/mod/xaeros-world-map). VERIFIED.
- **In RAM: bounded** — the mod keeps a *region cache* (region-cache fields exist in 1.46.0 bytecode; "Reload Regions"/"Reload All Regions" options manage the cache), region unloading is automatic, and since world map 1.41.2 there is a user setting for the **maximum number of loaded regions** (present in 1.46.0) — so heap use is a function of that cap + zoom level, not of total exploration [changelog 1.41.2](https://chocolateminecraft.com/update.php?mod_id=2). VERIFIED (mechanism) — a third-party benchmark measured roughly flat ~45–85 MB for the pair even with heavy exploration [Oreate guide](https://create.oreateai.com/create/performance-vs-features-the-real-difference-between-journeymap-and-xaeros). COMMUNITY (small blog, directionally consistent with the bounded-cache design).
- Resource pack changes force a full map regeneration (disk churn) [Modrinth description](https://modrinth.com/mod/xaeros-world-map). DOCUMENTED.
### 10. Minimap↔world map integration (perf-positive, keep defaults)
"By default uses the map textures generated by the world map mod instead of generating its own. This improves performance when using both mods" [Minimap description](https://modrinth.com/mod/xaeros-minimap). Also, config moved to `/config/xaero/minimap`, `/config/xaero/world-map`, shared `/config/xaero/lib` (25.3.2/1.40.2 config rework) — the pack can ship enforced defaults per machine there [changelog 25.3.2](https://chocolateminecraft.com/update.php?mod_id=0). VERIFIED. The world map screen's default world-render skipping + auto framerate limit (~625 fps cap) when skipped is another official perf behavior [changelog 1.42.0](https://chocolateminecraft.com/update.php?mod_id=2). VERIFIED.
### 11. Alternatives, briefly
- Community consensus ranks Xaero's as the lightest full-featured pair; JourneyMap is "slightly heavier on system resources" with more RAM/CPU headroom needed; FTB Chunks is often called the most performant but feature-poor and its map/claim data lives in the server world save (server TPS exposure) [r/feedthebeast comparison](https://www.reddit.com/r/feedthebeast/comments/1pnr3bo/for_modded_minecraft_which_minimap_has_more/), [Enigmatica6 issue #1340](https://github.com/EnigmaticaModpacks/Enigmatica6/issues/1340), [Astroworld guide](https://guide.astroworldmc.com/best-minecraft-minimap-mods). COMMUNITY — no first-party benchmarks either way; keep Xaero's.
## Sources
Kept:
- DH GitLab wiki (Server Owners; Problems & Solutions; Mod Support; General FAQ) — primary, maintained by the mod author. https://gitlab.com/distant-horizons-team/distant-horizons/-/wikis/home
- DH core source (Config.java, preset handlers, enums) — authoritative key/behavior definitions. https://gitlab.com/distant-horizons-team/distant-horizons-core
- Pinned jars' embedded lang/setting symbols (DH 3.3.2, XaeroMinimap 26.5.0, XaeroWorldMap 1.46.0) — exact-version config surface. https://modrinth.com/mod/distanthorizons/version/3.3.2-1.21.1
- Iris docs, DH mod-support reference — how shaderpacks integrate DH passes. https://shaders.properties/current/reference/mod-support/distant_horizons/
- Complementary Reimagined + MakeUp Ultra Fast `shaders.properties` — proof of DH support and of disabled DH shadow pass. (GitHub raw links above)
- Xaero's official descriptions + chocolateminecraft changelogs — feature/perf changes per version. https://chocolateminecraft.com/update.php?mod_id=2
- GitLab issues #157 (RAM/VRAM data point), #566 (Alex's Caves fix via wiki) — tracker history.
Dropped:
- distanthorizonsguide.com — useful but third-party SEO-adjacent; kept only its calculator profile as one COMMUNITY data point.
- Sportskeeda/best-settings listicles — no original data, stale version references.
- Steveplays28 shader-compat gist — 1.19.2-era, superseded by per-pack source verification.
- Older Reddit optimization threads (DH 1.18.2 era) — settings names/values changed in 3.x.
## Gaps
- No first-party per-distance VRAM/RAM table for DH 3.3.x exists; the only numbers are 2022-era (issue #157) and community profiles. Benchmark: F3 overlay + RTSS/`radeontop` at 64/128/256 chunks × LOW/MEDIUM with each shaderpack, per machine.
- Actual FPS/VRAM delta of Complementary's DH programs (`dh_terrain`/`dh_water`) vs base renderer, and whether its disabled `dhShadow` fully avoids DH shadow cost (it should by contract, but verify).
- Xaero's minimap cost with heavy entity mods (Alex's Mobs etc.) and with cave mode on — no measurements found; icon pre-rendering burst at first-encounter may stutter on Deck.
- World map "maximum number of loaded regions" default value on 1.46.0 and its heap effect (setting exists; default not visible without running the game).
- Whether the pack's server actually enables `enableRealTimeUpdates`/sync radius ≤ client LOD distance (affects client bandwidth/CPU when riding Create trains).
## Top levers
| # | Lever | Expected impact | Helps | Risk | Confidence |
|---|---|---|---|---|---|
| 1 | Cut DH LOD render distance to 96–128 (Deck/P2) or 128–192 (P1) — keep ≤512 always | High (GPU+VRAM+CPU all scale with it) | All three; most on P1 VRAM & Deck | Visual only | High |
| 2 | Quality preset LOW/MEDIUM **with cave culling re-checked ON** (never leave HIGH/EXTREME presets' culling-off in mountains) | High on GPU-heavy scenes, Med general | Deck, P1 | Slightly flatter distant terrain | High (preset mapping verified) |
| 3 | Server-side `/dh pregen` + keep per-player LOD bandwidth/rate limits (500 KB/s default) so clients stream prebuilt LODs instead of stressing CPU | High (client smoothness), Med (server) | All three; P2 CPU | Server disk/IO during pregen; don't pregen while playing | High |
| 4 | Thread preset: Minimal/Low while exploring fast, Balanced otherwise; keep `pauseIfMovingQuickly`/`limitIfServerUnhealthy` on | Med (stutter elimination on 4C/8T) | P2, Deck | Slower LOD fill-in | High |
| 5 | Heap: `-Xmx6–8G` + `-XX:+UseZGC` (≤6G on P2), keep DH DB sync NORMAL | Med (stutter/GC) | P2 most, Deck (shared RAM) | Lower heap on P2 may thrash if LOD RD kept high | High (official guidance) |
| 6 | Steam Deck: Sodium "Use No Error context" OFF (Mesa fix) + stay on OpenGL rendering engine | Med (crash/stability, some perf) | Deck | None | High (official wiki) |
| 7 | Xaero's: cap world-map "max loaded regions" + keep `mapWritingDistance` default; never enable Force Fast Writing; keep world-render skip ON | Low–Med (heap spikes on P2 when opening map) | P2, Deck | Slower mapping while flying fast | Med |
| 8 | Xaero's minimap: modest `minimapSize`, radar to dots + hide invisible entities, cave mode off above ground for users who don't need it | Low | Deck, P2 | Feature loss (QoL) | Low–Med (mechanism verified, magnitude not) |
| 9 | Keep both shaderpacks' built-in DH integration (dhShadow off) — do not swap in packs without `DISTANT_HORIZONS` support | Prevents catastrophic regressions | All | None (status quo) | High |
| 10 | Pack fixes: Alex's Caves `biome_ambient_light_coloring = false`; pin SSRD ≥1.8.7 with DH 3.3.2 | Prevents broken LODs/rendering | All | AC loses biome tint ambience | High |
## Open questions to verify by benchmark
1. VRAM at 128 vs 192 vs 256 LOD chunks with Complementary Reimagined r5.9.3 on the GTX 1060 6GB — where does the 6 GB budget break?
2. Steam Deck: 30 fps target — LOW preset @128 LOD vs MEDIUM @96 LOD with MakeUp Ultra Fast (which is cheaper per visual quality?).
3. Client thread occupancy (F3 "Show Thread Pools") with thread preset Minimal vs Balanced during flight — does P2's main thread still stutter at 4 DH threads?
4. Heap profile on P2 (8 GB free): peak JVM RSS with ZGC `-Xmx5G` at 128 LOD + world map opened after 2h exploration vs DH SQLite flush behavior.
5. Xaero's: minimap FPS cost with entity radar ON vs OFF in a mob-dense Alex's Caves area; cave-mode ON cost while caving.
6. Bandwidth/latency: server LOD streaming rate when teleporting (Create train) with `realTimeUpdateDistanceRadiusInChunks` at default vs reduced — any client hitching from sync-on-load bursts?
7. Does `enableFastSurfaceGenerator` on the server reduce time-to-filled-horizon for new areas enough to matter for clients joining fresh regions?
Reference in new issue View Git Blame Copy Permalink