logan/onion-mc
1
0 Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cf7ea5617e9b97ffe3bc2b4aca47fd0974bb8950
onion-mc/analysis/client-perf/research/r9-sweep-libs-ui-misc.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

72 lines
16 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: R9 — Libraries / UI / Misc client hooks sweep (Onion MC, 1.21.1 NeoForge 21.1.251)
## Summary
This group is mostly low-cost UI/QoL/library mods: for the large majority **no known client perf issues found** (searched GitHub issue trackers for lag/fps/memory/stutter/sodium/iris). The real, actionable items are: **Puzzles Lib 21.1.62 predates a hot-path event-dispatch fix shipped in 21.1.64**; **Fancy World Animations** has a documented history of heavy chain/lantern animation cost under Iris/Sodium (mitigated in the pinned 1.2.31 via frustum culling + EntityCulling occlusion compat); and **Jade** is the most common *hidden* cost driver here, since its tooltip providers (incl. reading Sophisticated Backpack contents) run on the client while pointing at blocks.
## Findings table
| Mod | What it does (1 line) | Client cost type | Known perf issues (URL, fixed?) | Perf-relevant config levers (exact keys only if seen) | Value vs cost |
|---|---|---|---|---|---|
| Fancy World Animations (fwa) 1.2.31 | Animates doors/trapdoors/chests/chains/lanterns etc. (mixes into BlockRenderer, ShadowRenderer, RenderChunkRegion) | **Frame** (per-animated-block render work, worst w/ 3D-texture chain packs + shaders) | DOCUMENTED: 3D chains/lanterns caused ~2× FPS loss under Iris/Sodium pre-1.1.17 (https://github.com/maDU59/FancyWorldAnimations/issues/24 — fixed via frustum culling in 1.1.17, EntityCulling occlusion-culling compat + cached bounding boxes in **1.2.31**, per issue #24 and #74). CPU-temp complaint: https://github.com/maDU59/FancyWorldAnimations/issues/83 (closed). Sodium visual-only bugs #27/#34/#64/#78 (closed). Embeddium duplicate-render #91 (https://github.com/maDU59/FancyWorldAnimations/issues/91) — **not applicable**: dev states Embeddium unsupported, "use Sodium"; pack uses real Sodium 0.8.13 | Per-animation toggles in FWA config (chains / lanterns / doors…) — seen in issue #24 discussion, not read from the config file itself | **Keep** (pin ≥1.2.31; already pinned). **Tune on Steam Deck**: consider disabling chain/lantern animations in mineshaft-heavy exploration; they are the documented hot path |
| Moonlight Lib 3.7.1 | MehVahdJukaar library (Supplementaries-family APIs, dynamic asset caching) | Startup (conditional) | DOCUMENTED: dynamic-asset cache system massively slowed modpack startup (160→320s) when paired with asset-generating mods (EveryCompat) — https://github.com/MehVahdJukaar/Moonlight/issues/382 (open, but traced to EveryCompat generation-mode config + zip listing behavior). No Moonlight-modded mods of that family appear in this pack's list | `everycomp-*.toml` generation modes — only relevant if EveryCompat/Supplementaries present (not in this topic's list) | **Keep** if a listed mod needs it; else **candidate-remove** (verify dependents first) |
| Iceberg 1.3.2 | Grend_G modding library (events/helpers, animated texture utils) | none-known | No known client perf issues found (issue tracker shows crashes/compat, not perf) | — | Keep (required by dependents) |
| Puzzles Lib 21.1.62 | Fuzss multiloader framework (events, config screens, GUI helpers) used by several UI mods | **Frame** (event-dispatch overhead) + startup | VERIFIED: ~8% of render thread spent in `EntityRenderer.handler$…$puzzleslib$createRenderState()` via dynamic-proxy/MethodHandle dispatch (per-entity per-frame hot path) — https://github.com/Fuzss/puzzles-lib/issues/202 (fixed). **Fix backported to 1.21.1 in v21.1.64 (2026-10-11): "Cache method handles in FabricEventFactory to reduce event listener invocation overhead"** — changelog: https://modrinth.com/mod/puzzles-lib (versions 21.1.63/21.1.64 for 1.21.1 NeoForge). **Pack pins 21.1.62 (2026-09-29) → predates the fix.** Note the ~8% figure was measured on MC 26.2/Fabric; the 1.21.1 changelog entry confirms the same dispatch path exists in this line | — | **Tune → update 21.1.62 → 21.1.64+** (highest-value single change in this group) |
| Balm 21.0.66 | BlayTheNinth cross-version library (Waystones etc.) | none-known | No known client perf issues found | — | Keep (Waystones dep) |
| Chalk 2.0.2 | Draws chalk marks on blocks | none-known | No known client perf issues found | — | Keep |
| Charta 1.2.5 | Card-game mod (playable card tables) | Startup / VRAM (INFERENCE: registers ~31 core shaders at resource load); frame only at card tables | Server-side lag-spike on player join: https://github.com/lucaargolo/charta/issues/14 (closed). No client perf issues found | — | **Candidate-remove** if the group doesn't play cards (client+server mod — must be removed on both sides); shaders tax startup/VRAM regardless of use |
| Client Sort 3.89.1 | Sort/move items in any inventory screen (client-only) | Frame (only inside container screens) | No known client perf issues found | — | Keep |
| Sounds (sounds) 2.4.22 | UI/ambient sound polish mod | none-known | No known client perf issues found | — | Keep |
| Now Playing 1.5.16 | Shows currently playing music track (HUD/toast) | Frame (tiny, HUD element) | No known client perf issues found | — | Keep |
| Music Disc Maker 3.0.5 | Creates custom music discs | none-known | No known client perf issues found | — | Keep |
| cat_jam | Cats bob heads to music (cosmetic) | Frame (negligible) | No known client perf issues found | — | Keep |
| PlayerRevive 2.1.2 (+ CreativeCore 2.13.48) | Downed/revive multiplayer mechanic | Frame (downed-player overlays) | No known client perf issues found | — | Keep |
| Jade 15.10.6 | WAILA-style "what am I looking at" tooltip | **Client-tick + frame** while pointing at blocks/entities; tooltip providers can read container contents | VERIFIED: FPS→0 ~1s when looking at player heads — https://github.com/Snownee/Jade/issues/742 (closed not-planned on 1.21.10 branch, but **workaround applies to 1.21.1**: add `player_head` to `hide-blocks.json`). Freeze looking at containers documented but tied to ViaFabricPlus server-version bridging (https://github.com/Snownee/Jade/issues/783, dup https://github.com/Snownee/Jade/issues/790) — not applicable to a native 1.21.1 server. SB-content reading implicated as the real cost in https://github.com/P3pp3rF1y/SophisticatedBackpacks/issues/1352 (owner: "another mod that shows backpack contents (like Jade)"). Historical client-disconnect memory leak PR: https://github.com/Snownee/Jade/pull/405 (long since in 15.x line) | `hide-blocks.json` (config file, exact name seen in #742); provider/plugin toggles in Jade's in-game config (key names not verified — do not guess) | **Keep + tune**: hide player heads/decor blocks in `hide-blocks.json`; if profiling shows tooltip cost, disable container-contents display — biggest overlap is with Sophisticated Backpacks |
| Patchouli 1.21-88 line | Guide-book framework (botania-style books) | Client-tick / frame inside books; startup (parses book JSONs) | DOCUMENTED: excessive client lag spike on advancement toasts — https://github.com/VazkiiMods/Patchouli/issues/481 (1.18.1 era, closed; not confirmed still present in 1.21.1). Crash-after-days on 1.21.1 NeoForge: https://github.com/VazkiiMods/Patchouli/issues/795 (stability, not perf) | — | Keep (needed by guide books); only re-check #481-class advancement stutter if it reproduces |
| Modonomicon | kli_kli data-driven guide-book mod (Patchouli alternative) | Client-tick / frame inside books | No known client perf issues found | — | Keep |
| Sophisticated Backpacks/Storage/Core | Upgradeable backpacks + storage drawers | Client-tick when tooltip/Jade reads contents; frame on heavy-content tooltips | VERIFIED interplay: "Massive Lag when Looking at Backpack" traced by the SB owner to content-display mods (Jade), not SB itself — https://github.com/P3pp3rF1y/SophisticatedBackpacks/issues/1352 (closed). NBT-heavy-content tooltip stutter pattern documented for other backpack mods: https://github.com/AllTheMods/ATM-6/issues/490 | — | Keep; **tune**: if Jade+SB tooltips stutter on the Deck, hide backpack/stack contents in Jade or stop shift-hover previews |
| Zume 1.2.2 | Smooth zoom keybind | none-known | No known client perf issues found | — | Keep |
| Quick Skin 3.0.1 | Reload own skin without relog | none-known | No known client perf issues found | — | Keep |
| Room For Two 0.3.0 | Two players share one bed / sit together | none-known | No known client perf issues found | — | Keep |
| Keybind Atlas | Searchable keybind manager screen | none-known | No known client perf issues found | — | Keep |
| FindMe | Hover-item search/highlight across nearby inventories | Client-tick (search scope) | No known client perf issues found | — | Keep |
| OctoLib/ShatterLib 0.6.2 | Small library dependency | none-known | No known client perf issues found | — | Keep (if listed as dependency; verify consumer mod before removing) |
| Fragmentum 5.2.0 | Small library dependency | none-known | No known client perf issues found | — | Keep (same caveat) |
| Mino++ 1.4.0 | Small library/utility mod | none-known | No known client perf issues found | — | Keep (verify consumer mod) |
| Comforts | Sleeping bags/hammocks | none-known | No known client perf issues found | — | Keep |
| MRU 1.0.41 | Mrthomas20121 utility library | none-known | No known client perf issues found | — | Keep (verify consumer mod) |
| Blueprint 8.2.0 | TeamAbODE library (Chipped/variant mods family) | none-known | No known client perf issues found | — | Keep |
| YACL | YetAnotherConfigLib — config screens | none-known | No known client perf issues found | — | Keep |
| Extreme Sound Muffler | Muffle selected sounds | none-known | No known client perf issues found | — | Keep |
| Loot Journal | Journal of looted items | Client-tick (event log) | No known client perf issues found | — | Keep |
| Enchantment Descriptions | Enchant descriptions in tooltips | Frame (tooltip text only) | No known client perf issues found | — | Keep |
| Mouse Tweaks | Drag-scroll inventory manipulation | none-known | No known client perf issues found | — | Keep |
| Clumps | Merges XP orbs into single entities | **Negative cost** (reduces entity render/tick load client & server) | Old server-side orb flood w/ Apotheosis: https://github.com/jaredlll08/Clumps/issues/22 (2019-era, closed) | — | **Keep** — net perf positive |
| Gravestone (henkelmax) | Places grave with inventory on death | none-known | No known client perf issues found | — | Keep |
| Waystones | Fast-travel waystones | none-known (client) | Server-side worldgen/save hangs: https://github.com/TwelveIterations/Waystones/issues/428 + #448 — **fixed Nov 2021**, not client-applicable | — | Keep |
| Lootr | Per-player instanced loot chests | none-known (client) | Server-side SavedData disk-write lag spikes: https://github.com/LootrMinecraft/Lootr/issues/804 (closed Jun 2026; author: general SavedData/IO issue, improved by data-system rewrite — server concern, not client) | — | Keep (note for the *server* perf report) |
| Open Parties and Claims (client side) | Chunk claims/parties + claim overlay (uses Xaero maps) | Frame (claim outline overlay) | VERIFIED: client-side claim-coloring optimization was implemented in 2022 — https://github.com/thexaero/open-parties-and-claims/issues/67 (closed completed Sep 2022). #758 boat-collision and #816 1M-claim-crash items are server-side | — | Keep |
| Apothic Combat | Combat overhaul module (Apotheosis-family) | Frame (particle/affix rendering in fights) | DOCUMENTED (adjacent, Apotheosis 1.20.1): dual-wield affixed weapons + Better Combat tank FPS — https://github.com/Shadows-of-Fire/Apotheosis/issues/804. **Better Combat is not in this pack**, so not directly applicable — INFERENCE | — | Keep |
| Explorer's / Nature's Compass | Locate biomes/structures, HUD display | Client-tick (search runs server-side + synced result) | No known client perf issues found | — | Keep |
## Notable
1. **Bump Puzzles Lib 21.1.62 → 21.1.64.** The pinned version predates the "cache method handles in FabricEventFactory" fix (v21.1.64, 2026-10-11) that resolved a measured ~8% render-thread hot-path overhead in per-entity render-state creation ([issue #202](https://github.com/Fuzss/puzzles-lib/issues/202); 1.21.1 changelog on [Modrinth](https://modrinth.com/mod/puzzles-lib)). This is the only confirmed actionable perf bug in this entire group.
2. **FWA 1.2.31 is the right version to be on, but it is not free.** Chains/lanterns with 3D-texture packs + shaders were a documented ~2× FPS loss; frustum culling (1.1.17) and EntityCulling occlusion-culling compat + cached bounding boxes (1.2.31) address exactly this ([#24](https://github.com/maDU59/FancyWorldAnimations/issues/24)). On the Steam Deck (weakest GPU), toggling chain/lantern animations in FWA config for mineshaft-heavy play is the cheap lever. The Embeddium duplicate-render issue [#91](https://github.com/maDU59/FancyWorldAnimations/issues/91) does not apply — dev explicitly supports Sodium, which this pack uses.
3. **Jade is the hidden cost driver of this group, not the mods it points at.** The SB "looking at backpack = 20-30 FPS" report was attributed by the SB author to Jade's content display ([SB #1352](https://github.com/P3pp3rF1y/SophisticatedBackpacks/issues/1352)); player-head tooltips could drop FPS to 0, fixed for users via `hide-blocks.json` ([Jade #742](https://github.com/Snownee/Jade/issues/742)). Pre-tune Jade (hide player heads; trim container-contents display) before blaming Sophisticated Backpacks in benchmarks.
4. **Charta is a plausible small startup/VRAM tax for a mod most players rarely use** (~31 core shaders registered at resource load — INFERENCE from pack file listing; no client perf issue reported in its tracker). If the card tables are unused, remove it on client+server.
5. **Most of the scary issues in these trackers are server-side** (Lootr SavedData writes, Waystones worldgen, OPAC boat collisions/claim-crash, Charta join-lag) — they belong in the server perf report, not the client one. For the client, "no known client perf issues found" genuinely applies to ~30 of these 40 mods.
## Sources
- Kept: FWA issue tracker + #24/#74/#91/#83 (github.com/maDU59/FancyWorldAnimations) — authoritative on the pinned version's perf history
- Kept: Puzzles Lib #202 + Modrinth 1.21.1 version changelogs (api.modrinth.com/v2/project/puzzles-lib) — proves fix version vs pinned version
- Kept: Jade #742/#783/#790 (github.com/Snownee/Jade) — real client-tick/frame costs + the `hide-blocks.json` lever
- Kept: SophisticatedBackpacks #1352 (github.com/P3pp3rF1y/SophisticatedBackpacks) — attributes the cost to Jade-style content display
- Kept: Moonlight #382 (github.com/MehVahdJukaar/Moonlight) — startup cost mechanism, conditional on asset-gen mods
- Kept: Lootr #804, Waystones #428/#448, OPAC #67/#758/#816, Charta #14 — confirm server-side classification
- Dropped: Reddit threads (r/feedthebeast "which mods cause most lag", UsefulMods wiki) — generic, not version-pinned, uncorroborated for these exact versions
- Dropped: Iceberg/Clumps unrelated repos (apache/iceberg, moonlight-stream) — name collisions, not the MC mods
## Gaps
- Could not find per-mod client benchmarks; magnitudes are from individual user spark profiles, not controlled tests — validate Puzzles Lib gain and FWA chain cost with a spark profile on one Deck before/after.
- Exact config key names for Jade (hide-blocks list location beyond `hide-blocks.json`), FWA per-animation toggles, and any Sophisticated Backpacks tooltip toggle were not read from the mods' source/config files (only referenced in issues) — do not write keys into pack configs without opening the jars.
- Several tiny mods (Mino++, OctoLib/ShatterLib, Fragmentum, MRU, Keybind Atlas, Room For Two, Music Disc Maker) have little public issue activity at all; their "none-known" verdicts reflect absence of evidence. Before removal, verify which installed mod consumes each library (check each jar's `META-INF/neoforge.mods.toml` dependency list).
Reference in new issue View Git Blame Copy Permalink