Mirror upstream PR #11: client performance pass

[web3dev1337]

Mirrors upstream PR #11 (hytopiagg#11).

Validation:

• npm --prefix client run build currently fails on origin/master as well (TS6133 unused serverHealthy in client/src/network/NetworkManager.ts), so this PR can’t be “green” without an unrelated fix.

[web3dev1337]

Review (client perf pass)

This is a solid set of CPU/GPU hot-path optimizations. Biggest wins look like: (1) adaptive render resolution on high-DPI, (2) less scene-graph churn from chunk view-distance, (3) much cheaper InstancedMesh attribute updates, and (4) avoiding per-mesh shader define churn in the outline mask.

What looks good

• client/src/core/Renderer.ts: caps internal render-target pixel count on high-DPI fullscreen (Retina/4K), and avoids running the outline pass when there are no outline targets.
• client/src/chunks/ChunkManager.ts + client/src/chunks/ChunkMeshManager.ts: view-distance now adds/removes batch meshes from the scene and only refreshes when the camera crosses an 8-block “visibility cell” (plus settings changes). Also provides a cached solidMeshesInScene list for raycasts.
• client/src/entities/EntityManager.ts: cached dynamic entity list + multi-pass update ordering (local update → view distance → frustum → anim/local matrices → world matrices), and skips light-level work until a light volume actually exists.
• client/src/gltf/GLTFManager.ts: replaces “always upload full instance buffers” with dirty-range updates + fewer allocations; adds periodic depth sorting for transparent instanced meshes; avoids redundant layer toggles.
• client/src/three/postprocessing/SelectiveOutlinePass.ts: pre-creates mask material variants (map/alphaMap combinations) instead of mutating defines per mesh on onBeforeRender().

Potential behavior changes / things to verify

• StaticEntity auto-selection for environmental glTF entities (EntityManager._updateEntity): anything created as StaticEntity can’t be removed and ignores later transform/opacity/texture/animation changes.
  • If any existing games use isEnvironmental entities dynamically (spawn/move/remove, parent/attach, node overrides, opacity fades, etc.), this could be a breaking change.
  • Safer option would be to gate this behind an explicit “static” flag/feature from the server, rather than inferring from spawn data.
• Chunk worker race / stale batch results (ChunkManager._onChunkBatchBuilt): the new guard only checks “at least one chunk still exists”. If the batch’s chunk set changed while the worker was building, a stale geometry result can still be applied (ghost blocks until the next rebuild).
  • Consider discarding results unless payload.chunkIds matches the registry’s current getBatchChunkIds(batchId) (or track a per-batch build version).
• View distance quantization: refreshing visibility only when crossing 8-block cells reduces CPU, but can make culling “sticky” near the boundary (more noticeable at very low view distances). Probably acceptable, but worth testing.
• Adaptive pixel ratio cap: fullscreen on high-DPI desktops will be softer (expected). Might be worth surfacing the effective pixel ratio in the debug panel so people understand why.
• Transparent instanced sorting: projected-depth sorting every N frames is a good compromise, but there can still be ordering artifacts; also note the code comment about potential flicker when hovering around the transparent instancing threshold.

Mobile vs desktop

• The pixel ratio cap should mostly help high-res desktop/retina fullscreen; phones/tablets often fall under the pixel budget already.
• Chunk scene add/remove + reduced shader churn should help both; less per-frame allocations is especially good on mobile.

Validation note

• npm --prefix client run build currently fails on master too (TS6133: 'serverHealthy' is declared but its value is never read in client/src/network/NetworkManager.ts), and this PR doesn’t touch that file.

(Upstream PR #11 head: d4723fc3d33aaf24ca40276b602d334b3473498b, last updated 2026-03-03.)