spoint 0.1.629 → 0.1.630

package/client/app.js

@@ -52,7 +52,6 @@ import { createRenderGraph } from './core/RenderGraph.js'
 import { buildRenderSectionNodes } from './core/RenderGraph.nodes.js'
 import { buildSSAONodes, installSSAO } from './core/SSAO.js'
 import { buildSSRNodes, installSSR } from './core/SSR.js'
-import { buildHalfResTransparentsNodes, installHalfResTransparents } from './core/HalfResTransparents.js'
 import { buildBloomNodes, installBloom, registerBloomWebGPU } from './core/Bloom.js'
 import { buildFSR1Nodes, installFSR1, registerFSR1WebGPU } from './core/FSR1.js'
 import { installRenderControls, RenderControls } from './core/RenderControls.js'
@@ -535,14 +534,7 @@ function _ensureWeather(tb) {
   const wcfg = _terrainCfg.weather
   if (!wcfg || wcfg === false) return null
   try {
-    // window.__halfResTransparentsDebug is populated by installHalfResTransparents at module-level
-    // boot (client/app.js, before this async _buildWorldScenery path ever runs) -- read lazily via
-    // the window handle rather than a captured module const, since _ensureWeather's own definition
-    // runs before that module-level install line executes (function bodies don't evaluate until
-    // called; by call time the install has already happened). See HalfResTransparents.js header.
-    const hrt = (typeof window !== 'undefined') ? window.__halfResTransparentsDebug : null
-    const tagHalfRes = hrt ? (obj) => hrt.tagHalfRes(obj) : null
-    weather = createWeather({ renderer, scene, frame: tb && tb.frame, cfg: wcfg, tagHalfRes })
+    weather = createWeather({ renderer, scene, frame: tb && tb.frame, cfg: wcfg })
     if (window.__app) window.__app.weather = weather
   } catch (e) { console.error('[weather] init failed:', e?.message || e) }
   return null
@@ -2702,7 +2694,7 @@ function tickPlayerAnimators(lid, frameDt, isEditor) {
 // window.__renderGraph = live inspection surface (stats()/capture()/disable(id)/toMermaid()).
 // _graphCtx is PERSISTENT so ctx.res carries last-frame resources (the deliberate one-frame
 // near/far lag + shouldRun-skip semantics depend on it).
-const renderGraph = createRenderGraph([...buildRenderSectionNodes(), ...buildSSAONodes(), ...buildBloomNodes(), ...buildSSRNodes(), ...buildHalfResTransparentsNodes(), ...buildFSR1Nodes()])
+const renderGraph = createRenderGraph([...buildRenderSectionNodes(), ...buildSSAONodes(), ...buildBloomNodes(), ...buildSSRNodes(), ...buildFSR1Nodes()])
 // pm (PlayerManager, declared above) exposes pm.playerMeshes (Map<id, THREE.Group>, real live
 // per-player world positions, local + remote, server-snapshot-reconciled) -- foliage-lod-sync's grass
 // player-bend wiring reads ctx.pm.playerMeshes every frame to feed Grass.js's nearby-bender buffer.
@@ -2732,11 +2724,6 @@ installBloom(_graphCtx, renderer)
 // SSR shares SSAO's G-buffer when available (see SSR.js buildSSRNodes' ssr-compute node), so it
 // pays zero extra scene-render cost beyond SSAO's own existing pass.
 installSSR(_graphCtx, renderer, scene, camera)
-// Half-res transparents/particles GPU resources are built lazily too (RenderControls
-// ('halfResTransparents') gate, same discipline as SSAO/Bloom/SSR above) -- installed once here so
-// ctx.halfResTransparents is populated before the first frame the flag might be on, and so
-// _ensureWeather (below) can tag its particle pools onto the half-res layer as soon as they exist.
-installHalfResTransparents(_graphCtx, renderer, scene, camera)
 // FSR1 GPU resources are built lazily too (RenderControls('fsr1') gate, same discipline as
 // SSAO/Bloom/SSR above) -- installed once here so ctx.fsr1 is populated before the first frame the
 // flag might be on. Only actually runs while the DPR controller has genuinely downscaled (see

package/client/core/QualityPresets.js

@@ -40,7 +40,7 @@ const PRESETS = {
     vegAllOff: false,
     vegHideFar: null,
     grassWind: false,
-    halfResWater: true,
+    halfResWater: false,
     thc: false,
     ssao: false,
     bloom: false,
@@ -60,7 +60,7 @@ const PRESETS = {
     vegAllOff: false,
     vegHideFar: null,
     grassWind: true,
-    halfResWater: true,
+    halfResWater: false,
     thc: false,
     ssao: true,
     bloom: true,
@@ -76,7 +76,7 @@ const PRESETS = {
     vegAllOff: false,
     vegHideFar: null,
     grassWind: true,
-    halfResWater: true,
+    halfResWater: false,
     thc: false,
     ssao: true,
     bloom: true,

package/client/core/RenderControls.js

@@ -168,16 +168,6 @@ const CONTROLS = [
   { key: 'bloomBlurPasses', group: 'bloom', type: 'number', default: 1,
     doc: 'Number of full horizontal+vertical separable-blur passes applied to the bright-pass texture. Higher = smoother/wider glow, more GPU cost.' },
 
-  // ---- Half-res transparents/particles (see HalfResTransparents.js -- half-resolution offscreen
-  //      composite of THREE.Layers-tagged transparent/particle content, e.g. Weather.js rain/snow;
-  //      does NOT touch the shared canvas depth contract documented in DepthComposite.js) ----
-  { key: 'halfResTransparents', group: 'half-res-transparents', type: 'boolean', default: false,
-    doc: 'Render THREE.Layers-tagged transparent/particle content (see HalfResTransparents.HALFRES_LAYER, currently Weather.js rain/snow particle pools) into a half-resolution offscreen target instead of full-res, composited back with real depth-tested occlusion against the opaque scene. Perf win on overdraw-heavy particle scenes (weather); default off pending a device-tier default decision.' },
-  { key: 'halfResTransparentsScale', group: 'half-res-transparents', type: 'number', default: 0.5,
-    doc: 'Render-target resolution scale (fraction of canvas size) for the half-res transparents target. Lower = cheaper, softer/blurrier particle edges.' },
-  { key: 'halfResTransparentsDepthSigma', group: 'half-res-transparents', type: 'number', default: 2.0,
-    doc: 'Depth-delta scale (metres) at which the composite bilateral upsample halves a neighbor tap\'s weight (see HalfResTransparents.js _compositeFrag). Lower = more aggressive edge-preservation (sharper depth-discontinuity cutoff, more prone to single-texel dropout on noisy depth); higher = softer, closer to plain bilinear.' },
-
   // ---- FSR1 spatial upscale/sharpen (see FSR1.js -- companion to the DPR controller below: a DPR
   //      drop shrinks the WebGL drawing buffer, which the browser then bilinear-stretches back up
   //      to CSS size; this pass replaces that dumb stretch with an EASU+RCAS upscale+sharpen so a
@@ -207,8 +197,8 @@ const CONTROLS = [
     doc: 'READ-ONLY mirror of the live VRAM budget tracker (ModelPoolAdapter.getVramStats()), refreshed once per frame: {usedMB, estimatedVramMB, currentRatio, peakRatio, byteBudgetMB, totalBytes, unloadedCount, visibleEntities, invisibleEntities, recentEvents}. recentEvents is a real ring-buffer log (real vram-warning/vram-critical/budget-pressure/budget-relaxed/budget-adjust events the pool actually emitted, not synthetic). window.__vramBudget mirrors the same data plus setBudgetMB()/log() convenience calls.' },
 
   // ---- mapspinner-side knobs (read in packages/mapspinner/src/gl-render.js; documented here for discovery) ----
-  { key: 'halfResWater', group: 'mapspinner-water', type: 'boolean', default: true,
-    doc: 'mapspinner half-res water pass (near sea level). When active the scene renders into a single-sample VDRS FBO then upscales. Set false to force the scene straight to the MSAA canvas.' },
+  { key: 'halfResWater', group: 'mapspinner-water', type: 'boolean', default: false,
+    doc: 'mapspinner water-occlusion depth-share pass (near sea level). When active the scene renders into a single-sample VDRS FBO (losing MSAA) then upscales, purely so the water-occlusion depth test has a real depth buffer to blit (the default framebuffer cannot be read via blitFramebuffer). Default off (every quality preset sets this false) since the MSAA loss reads as a visible quality drop across the whole frame, not just water -- set true only to re-enable the occlusion-depth-share mechanism at the cost of full-frame MSAA.' },
   { key: 'vdrs', group: 'mapspinner-resolution', type: 'boolean', default: false,
     doc: 'mapspinner explicit viewport dynamic-resolution mode (independent of the half-res-water-forced path): true routes terrain+water into a fixed-size offscreen FBO, renders it at a flexed __vdrsScale<1 sub-viewport, then LINEAR-upscales that sub-rect to the canvas at its actual (unchanged) size -- terrain renders fewer pixels, the canvas/presented frame stays full resolution. Pairs with vdrsScale. Normally driven automatically by the vdrsAuto controller (see resolution group above); settable directly for manual testing.' },
   { key: 'vdrsUpscaleFsr1', group: 'mapspinner-resolution', type: 'boolean', default: false,

package/client/core/VegImpostorTier.js

@@ -111,6 +111,25 @@ export function createSharedImpostorMesh(renderer, atlas, dims, opts = {}) {
   mat.polygonOffsetUnits = -8
   // Base geo must be zero-area below nearCutoff (near trees draw the full branch mesh instead) or every near tree double-draws; plane is the far LOD.
   const nearCutoff = opts.nearCutoff
+  const IMPOSTOR_DISSOLVE_FADE_BAND_M = 3.0
+  if (Number.isFinite(nearCutoff) && nearCutoff > 0) {
+    const baseCompile = mat.onBeforeCompile
+    mat.onBeforeCompile = (shader, r) => {
+      baseCompile?.call(mat, shader, r)
+      shader.uniforms.uImpNearCutoff = { value: nearCutoff }
+      shader.vertexShader = 'uniform float uImpNearCutoff;\nvarying float vImpCamDist;\n' + shader.vertexShader
+      shader.vertexShader = shader.vertexShader.replace('#include <begin_vertex>',
+        '#include <begin_vertex>\nvImpCamDist = distance(cameraPosition, (modelMatrix * instanceMatrix * vec4(0.0, 0.0, 0.0, 1.0)).xyz);')
+      shader.fragmentShader = 'uniform float uImpNearCutoff;\nvarying float vImpCamDist;\n' + shader.fragmentShader
+      shader.fragmentShader = shader.fragmentShader.replace('#include <dithering_fragment>',
+        '#include <dithering_fragment>\n' +
+        `float _impFade = clamp(abs(vImpCamDist - uImpNearCutoff) / ${IMPOSTOR_DISSOLVE_FADE_BAND_M.toFixed(1)}, 0.0, 1.0);\n` +
+        'float _impDither = fract(52.9829189 * fract(dot(gl_FragCoord.xy, vec2(0.06711056, 0.00583715))));\n' +
+        'if (_impDither > _impFade) discard;')
+    }
+    const baseKey = mat.customProgramCacheKey
+    mat.customProgramCacheKey = () => baseKey() + '_impfade'
+  }
   let baseGeo
   if (Number.isFinite(nearCutoff) && nearCutoff > 0) {
     baseGeo = new THREE.BufferGeometry()

package/client/core/Vegetation.js

@@ -75,7 +75,16 @@ const _vanMat = new THREE.Matrix4(), _vanProj = new THREE.Matrix4(), _vanFrustum
 // shared wind uniform (one per veg system); advancing one .value per frame sways all LODs of all species with zero per-instance JS
 function makeWindUniforms() { return { uVegTime: { value: 0 }, uVegWind: { value: 1 } } }
 
-function applyWind(material, wind) {
+function _dissolveBoundaryDistanceShaderChunk(boundaries) {
+  const uniforms = boundaries.map((_, i) => `uniform float uVegLodB${i};`).join('\n')
+  const mindist = boundaries.map((_, i) => `_vegDistToB = min(_vegDistToB, abs(_vegCamDist - uVegLodB${i}));`).join('\n      ')
+  return { uniforms, mindist }
+}
+
+const VEG_DISSOLVE_FADE_BAND_M = 3.0
+
+function applyWind(material, wind, lodBoundaries) {
+  const chunk = lodBoundaries && lodBoundaries.length ? _dissolveBoundaryDistanceShaderChunk(lodBoundaries) : null
   material.onBeforeCompile = (shader) => {
     shader.uniforms.uVegTime = wind.uVegTime
     shader.uniforms.uVegWind = wind.uVegWind
@@ -90,8 +99,23 @@ function applyWind(material, wind) {
     // per-instance shade: multiply the lit diffuse by the instance tint (brightness variation).
     shader.fragmentShader = shader.fragmentShader.replace('#include <color_fragment>',
       '#include <color_fragment>\n diffuseColor.rgb *= tint;')
+    if (chunk) {
+      lodBoundaries.forEach((d, i) => { shader.uniforms['uVegLodB' + i] = { value: d } })
+      shader.vertexShader = chunk.uniforms + '\nvarying float vVegCamDist;\n' + shader.vertexShader
+      shader.vertexShader = shader.vertexShader.replace('#include <begin_vertex>',
+        '#include <begin_vertex>\nvVegCamDist = distance(cameraPosition, (modelMatrix * instanceMatrix * vec4(0.0, 0.0, 0.0, 1.0)).xyz);')
+      shader.fragmentShader = chunk.uniforms + '\nvarying float vVegCamDist;\n' + shader.fragmentShader
+      shader.fragmentShader = shader.fragmentShader.replace('#include <dithering_fragment>',
+        '#include <dithering_fragment>\n' +
+        `float _vegCamDist = vVegCamDist;\n` +
+        `float _vegDistToB = 1e9;\n` +
+        `      ${chunk.mindist}\n` +
+        `float _vegFade = clamp(_vegDistToB / ${VEG_DISSOLVE_FADE_BAND_M.toFixed(1)}, 0.0, 1.0);\n` +
+        'float _vegDither = fract(52.9829189 * fract(dot(gl_FragCoord.xy, vec2(0.06711056, 0.00583715))));\n' +
+        'if (_vegDither > _vegFade) discard;')
+    }
   }
-  material.customProgramCacheKey = () => 'vegwind2'
+  material.customProgramCacheKey = () => 'vegwind3' + (chunk ? '_fade' + lodBoundaries.join('_') : '')
   return material
 }
 
@@ -286,8 +310,8 @@ export async function createVegetation(opts = {}) {
       const _treeSph = _treeBox.getBoundingSphere(new THREE.Sphere())
       branchGeo0.boundingBox = _treeBox.clone(); leafGeo0.boundingBox = _treeBox.clone()
       branchGeo0.boundingSphere = _treeSph.clone(); leafGeo0.boundingSphere = _treeSph.clone()
-      const branch = new InstancedMesh2(branchGeo0, applyWind(sp.branchMat, wind), { capacity: INIT_CAP, renderer })
-      const leaf = new InstancedMesh2(leafGeo0, applyWind(sp.leafMat, wind), { capacity: INIT_CAP, renderer })
+      const branch = new InstancedMesh2(branchGeo0, applyWind(sp.branchMat, wind, [D1, D2, D3]), { capacity: INIT_CAP, renderer })
+      const leaf = new InstancedMesh2(leafGeo0, applyWind(sp.leafMat, wind, [D1, D2]), { capacity: INIT_CAP, renderer })
       for (const m of [branch, leaf]) {
         m.initUniformsPerInstance({ vertex: { windPhase: 'float' }, fragment: { tint: 'float' } })
         m.perObjectFrustumCulled = true

package/client/core/Weather.js

@@ -243,20 +243,12 @@ const _camPos = new THREE.Vector3(), _camQuat = new THREE.Quaternion()
 
 // opts: { renderer, scene, frame (terrain frame, for ground-height sampling -- optional, falls back
 // to a fixed splash plane if absent), cfg: { type: 'rain'|'snow'|'clear', intensity: 0..1,
-// particleCount, farParticleCount, boxRadius, boxHeight, fallSpeed, snowAccumulation },
-// tagHalfRes: optional (object) => void -- called once per particle pool right after scene.add(),
-// see client/core/HalfResTransparents.js (half-res-transparents-particles-pass). Weather's own
-// rain/snow/splash/far-sheet InstancedMesh2 pools are the first (and, at this row's first-slice
-// scope, only) opt-in consumer of that half-res compositing pass -- exactly the "particle-heavy
-// scenes (e.g. weather rain/snow tier)" case the PRD row names. Optional/no-op when absent so
-// Weather.js has zero dependency on HalfResTransparents existing (dual-import-safe, matches every
-// other opts.* callback in this module). }
+// particleCount, farParticleCount, boxRadius, boxHeight, fallSpeed, snowAccumulation } }
 export function createWeather(opts = {}) {
   const { renderer, scene } = opts
   if (!renderer || !scene) throw new Error('createWeather: renderer/scene required')
   const cfg = opts.cfg || {}
   const frame = opts.frame || null
-  const tagHalfRes = typeof opts.tagHalfRes === 'function' ? opts.tagHalfRes : null
 
   const BOX_RADIUS = Number.isFinite(cfg.boxRadius) ? cfg.boxRadius : 22   // XZ half-extent of the near-tier falling-volume box, camera-centered
   const BOX_HEIGHT = Number.isFinite(cfg.boxHeight) ? cfg.boxHeight : 18   // Y extent above the camera near-tier particles fall through
@@ -328,7 +320,6 @@ export function createWeather(opts = {}) {
   im.frustumCulled = false
   im.visible = false
   scene.add(im)
-  if (tagHalfRes) tagHalfRes(im)
 
   const geoSplash = makeSplashGeo()
   const matSplash = makeSplashMaterial()
@@ -338,7 +329,6 @@ export function createWeather(opts = {}) {
   imSplash.frustumCulled = false
   imSplash.visible = false
   scene.add(imSplash)
-  if (tagHalfRes) tagHalfRes(imSplash)
 
   const geoFlake = makeFlakeGeo()
   const matSnow = makeSnowMaterial()
@@ -347,7 +337,6 @@ export function createWeather(opts = {}) {
   imSnow.frustumCulled = false
   imSnow.visible = false
   scene.add(imSnow)
-  if (tagHalfRes) tagHalfRes(imSnow)
 
   // Far sheet: one pool, re-skinned (material swapped) per type rather than two separate meshes --
   // only one of rain/snow is ever active at a time (type is a single enum), so there is no benefit to
@@ -362,7 +351,6 @@ export function createWeather(opts = {}) {
   imFar.frustumCulled = false
   imFar.visible = false
   scene.add(imFar)
-  if (tagHalfRes) tagHalfRes(imFar)
   let _farGeoIsSnow = false
 
   // Snow ground accumulation: a REUSED src/terrain/GrassDecal.js sparse cell store (see file header --

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spoint",
-  "version": "0.1.629",
+  "version": "0.1.630",
   "description": "Physics and netcode SDK for multiplayer game servers",
   "type": "module",
   "workspaces": [

package/client/core/HalfResTransparents.js

@@ -1,456 +0,0 @@
-// HalfResTransparents -- half-resolution transparent/particle compositing pass, gated behind
-// RenderControls('halfResTransparents'). Roadmap #37 (half-res-transparents-particles-pass).
-//
-// WHY: overdraw-heavy transparent content (rain/snow particle volumes, future smoke/muzzle-flash
-// sprites) costs the SAME per-pixel fragment-shader work as opaque geometry but contributes far
-// less to perceived detail -- a classic half-res-offscreen-composite win (the exact discipline
-// SSAO.js/Bloom.js/mapspinner's own half-res-water VDRS path already use in this codebase, see
-// AGENTS.md water-depth-share-not-terrain-only). This module applies the same discipline to
-// THREE-side transparent/particle objects: render them into a quarter-area (half-width x
-// half-height) offscreen target instead of the full canvas, then composite back with a
-// depth-aware upsample so the half-res edge doesn't bleed through nearer opaque geometry.
-//
-// HOW OBJECTS OPT IN: THREE.Layers, not a material/type check. Any object (or its material) that
-// should render half-res sets `object.layers.set(HALFRES_LAYER)` (or `.layers.enable(HALFRES_LAYER)`
-// if it also needs to stay on layer 0 for other purposes, e.g. raycasting) -- see `tagHalfRes(obj)`
-// helper. The main scene camera then EXCLUDES that layer (camera.layers.disable(HALFRES_LAYER)) so
-// scene-color's normal full-res render skips it entirely, and this module's own half-res camera
-// (cloned near/far/fov from the main camera every frame, so projections match exactly) INCLUDES
-// ONLY that layer. Layer-based opt-in (vs. a scene-graph split or a material flag) was chosen
-// because it needs zero change to how/where an object is parented (Weather.js's InstancedMesh2
-// pools stay `scene.add`-ed exactly where they are; the RenderGraph node here calls
-// `installHalfResTransparents(...).tagHalfRes(im)` once at construction) and composes cleanly with
-// THREE's own existing frustum-cull/raycast layer semantics.
-//
-// DEPTH-AWARE COMPOSITE: unlike Bloom (whole-canvas copy, no occlusion concern) this pass MUST NOT
-// let a half-res particle draw over nearer opaque geometry it should be occluded by (e.g. rain
-// behind a wall). DepthComposite.js's contract is that the ONLY depth buffer is the shared canvas
-// depth (mapspinner + THREE, no offscreen scene depth texture exists) -- so, matching SSAO.js's own
-// solved-this-already approach, this module renders its OWN small half-res depth-only pre-pass of
-// the OPAQUE scene (camera.layers default, i.e. layer 0 only -- excludes HALFRES_LAYER) into the
-// same-size target's depth attachment, then renders the half-res-layer objects against that depth
-// (real GPU depth-test, not a shader trick) before compositing color back.
-//
-// BILATERAL (DEPTH-REJECT) UPSAMPLE (bilateral-upsample-fps-delta follow-up): the composite step
-// that brings the half-res color target back onto the full-res canvas is a real bilateral filter,
-// not plain bilinear -- the depth-only pre-pass ALSO encodes its linear view-space depth into a
-// second small texture (_depthTarget, blitted from the pre-pass's color output each compute(), see
-// step 1.5), and the composite shader (_compositeFrag) weights each of the 4 bilinear-neighborhood
-// taps by how close ITS recorded opaque-scene depth is to the tap nearest the pixel being upsampled
-// -- a tap on the far side of a depth discontinuity (e.g. a thin foreground rail) is down-weighted
-// so its transparent color doesn't bleed across the edge. This uses the pass's OWN half-res depth as
-// the edge/discontinuity proxy (documented option (b) from the original follow-up row) rather than a
-// full-resolution THREE-only depth reference, since no such texture exists in this pipeline (see
-// DepthComposite.js's shared-canvas-depth contract above) and standing one up purely for this would
-// cost a second full-res depth-only scene render -- against the entire point of this pass being a
-// perf win. uDepthSigma (RenderControls('halfResTransparentsDepthSigma')) tunes the rejection
-// sensitivity.
-//
-// OVERRIDE MATERIAL, NOT EACH OBJECT'S REAL MATERIAL (live-debugged this session): the depth
-// pre-pass uses `scene.overrideMaterial` with a single shared minimal depth-only ShaderMaterial --
-// the SAME technique SSAO.js's G-buffer pass already uses (`_gbufferMat`) -- rather than letting
-// each opaque object render through its own normal material with color writes masked off. Tried the
-// real-material approach first; it produced a real, live-witnessed
-// "GL_INVALID_OPERATION: glDrawArraysInstanced: Vertex shader input type does not match the type of
-// the bound vertex attribute" storm, root-caused to InstancedMesh2's onBeforeRender/bindTextures
-// hook (see node_modules/@three.ez/instanced-mesh's InstancedMesh2.js): it snapshots and restores
-// `gl.CURRENT_PROGRAM` around a manual texture-uniform bind per draw call, and rendering the SAME
-// InstancedMesh2 objects (vegetation/rocks/grass) through their normal per-object materials in TWO
-// separate renderer.render() calls within one frame (once here, once in scene-color) left stale
-// attribute-pointer state from the wrong program bound on the second pass. A single shared
-// override material sidesteps this entirely -- InstancedMesh2's onBeforeRender still runs (needed
-// for its own instance-index/matrix-texture update), but every opaque object now renders through
-// the IDENTICAL program, so there is no per-object program churn within this pre-pass to desync.
-
-import * as THREE from 'three'
-import { RenderControls } from './RenderControls.js'
-
-// Layer index reserved for half-res-transparent content. Layers 0 (default) and the small set THREE
-// itself never reserves are otherwise free in this codebase (codesearch: no other `.layers.` use
-// exists yet) -- 1 chosen as the first non-default layer, documented here as the ONE place this
-// number is decided.
-export const HALFRES_LAYER = 1
-
-const _fullscreenVert = /* glsl */`
-  varying vec2 vUv;
-  void main() { vUv = uv; gl_Position = vec4(position.xy, 0.0, 1.0); }
-`
-
-// Plain nearest-sample copy, used ONCE per compute() to blit the depth pre-pass's color output
-// (linear-depth-in-alpha) from _target into the separate _depthTarget before _target's color gets
-// overwritten by the transparent-layer draw -- see compute() step 1.5. depthTest/depthWrite off,
-// opaque blending (source overwrites destination fully, no accumulation).
-const _copyFrag = /* glsl */`
-  precision highp float;
-  varying vec2 vUv;
-  uniform sampler2D tSrc;
-  void main() { gl_FragColor = texture2D(tSrc, vUv); }
-`
-
-// Depth-reject BILATERAL upsample (bilateral-upsample-fps-delta follow-up to
-// half-res-transparents-particles-pass). This codebase has no full-resolution THREE-only depth
-// texture to reject against (DepthComposite.js's contract: the only depth buffer is the shared
-// mapspinner+THREE canvas depth) -- so per that row's documented option (b), this uses the pass's
-// OWN half-res opaque-scene depth (already rendered every compute() as a real GPU depth-test pre-
-// pass, see _depthOnlyMat below) as a cheap edge/discontinuity proxy: the depth pre-pass now ALSO
-// encodes linear view-space depth into a second half-res texture (tHalfDepth, same technique SSAO.js
-// already uses -- pack raw metres into a color channel, no depth-curve reconstruction needed since
-// this module owns the encode AND decode end to end), and the composite shader does a real bilateral
-// filter over the 2x2 texel neighborhood around each upsampled sample: taps whose depth diverges from
-// the others are down-weighted (Gaussian falloff on depth delta, uDepthSigma controls sensitivity),
-// so a half-res transparent silhouette crossing a depth discontinuity (e.g. rain partially behind a
-// thin foreground rail) samples mostly from the texel(s) on the SAME side of the discontinuity as the
-// pixel being upsampled, instead of plain-bilinear's blend-across-the-edge blur/bleed.
-const _compositeFrag = /* glsl */`
-  precision highp float;
-  varying vec2 vUv;
-  uniform sampler2D tColor;
-  uniform sampler2D tHalfDepth;
-  uniform vec2 uHalfTexelSize; // 1/halfResTargetSize, in the SAME uv space as tColor/tHalfDepth
-  uniform float uDepthSigma;   // metres -- depth-delta scale at which a bilateral tap's weight halves
-
-  float sampleDepth(vec2 uv) { return texture2D(tHalfDepth, uv).a; }
-
-  void main() {
-    // Center depth at the exact half-res texel nearest this full-res pixel (nearest, not bilinear --
-    // this is the reference depth the 4 corner taps below get weighted against).
-    float centerDepth = sampleDepth(vUv);
-
-    // 2x2 bilinear-neighborhood taps, offset a half-texel in each diagonal direction so the four
-    // samples straddle the standard bilinear interpolation square around vUv.
-    vec2 o = uHalfTexelSize * 0.5;
-    vec2 uv00 = vUv + vec2(-o.x, -o.y);
-    vec2 uv10 = vUv + vec2( o.x, -o.y);
-    vec2 uv01 = vUv + vec2(-o.x,  o.y);
-    vec2 uv11 = vUv + vec2( o.x,  o.y);
-
-    vec4 c00 = texture2D(tColor, uv00);
-    vec4 c10 = texture2D(tColor, uv10);
-    vec4 c01 = texture2D(tColor, uv01);
-    vec4 c11 = texture2D(tColor, uv11);
-
-    float d00 = sampleDepth(uv00);
-    float d10 = sampleDepth(uv10);
-    float d01 = sampleDepth(uv01);
-    float d11 = sampleDepth(uv11);
-
-    // Depth-reject weights: a tap whose opaque-scene depth is far from centerDepth sits on the OTHER
-    // side of a discontinuity from the pixel being upsampled -- down-weight it so its transparent
-    // color does not bleed across the edge. Gaussian falloff, uDepthSigma tunes sensitivity; a tap
-    // with zero recorded depth (nothing opaque drawn there, e.g. sky) is never rejected (weight 1) so
-    // sky-only half-res regions still get plain bilinear quality.
-    float w00 = d00 <= 0.0 ? 1.0 : exp(-pow((d00 - centerDepth) / uDepthSigma, 2.0));
-    float w10 = d10 <= 0.0 ? 1.0 : exp(-pow((d10 - centerDepth) / uDepthSigma, 2.0));
-    float w01 = d01 <= 0.0 ? 1.0 : exp(-pow((d01 - centerDepth) / uDepthSigma, 2.0));
-    float w11 = d11 <= 0.0 ? 1.0 : exp(-pow((d11 - centerDepth) / uDepthSigma, 2.0));
-
-    float wSum = w00 + w10 + w01 + w11;
-    vec4 c;
-    if (wSum < 1e-5) {
-      // All 4 taps rejected (shouldn't normally happen since same-side-as-center always weight~1) --
-      // fall back to the plain nearest-center sample rather than dividing by zero.
-      c = texture2D(tColor, vUv);
-    } else {
-      c = (c00 * w00 + c10 * w10 + c01 * w01 + c11 * w11) / wSum;
-    }
-
-    if (c.a < 0.003) discard;
-    gl_FragColor = c;
-  }
-`
-
-// Depth-only override material for the opaque-scene pre-pass (see header's OVERRIDE MATERIAL note).
-// Fragment output now encodes LINEAR VIEW-SPACE DEPTH (raw metres, this module's own camera -- same
-// packing convention as SSAO.js's G-buffer, see that file for why: cheap and exact since encode+decode
-// are both owned here, no depth-curve reconstruction needed) into the alpha channel, read back by the
-// bilateral composite above as the edge/discontinuity proxy. rgb is unused (kept 0) -- only .a matters.
-const _depthOnlyVert = /* glsl */`
-  varying float vViewDepth;
-  void main() {
-    vec4 mvPosition = modelViewMatrix * vec4(position, 1.0);
-    vViewDepth = -mvPosition.z;
-    gl_Position = projectionMatrix * mvPosition;
-  }
-`
-const _depthOnlyFrag = /* glsl */`
-  varying float vViewDepth;
-  void main() { gl_FragColor = vec4(0.0, 0.0, 0.0, vViewDepth); }
-`
-function _makeDepthOnlyMaterial() {
-  return new THREE.ShaderMaterial({ vertexShader: _depthOnlyVert, fragmentShader: _depthOnlyFrag, side: THREE.DoubleSide })
-}
-
-export class HalfResTransparents {
-  constructor(renderer, scene, camera) {
-    this.renderer = renderer
-    this.scene = scene
-    this.camera = camera
-    this._w = 0
-    this._h = 0
-    this._built = false
-    this._hasContent = false
-
-    // Own camera clone kept in sync (near/far/fov/aspect/position/quaternion) every frame from the
-    // main camera -- a SEPARATE object (not the same camera instance) so this pass's layer mask
-    // never has to be swapped on/off the live main camera mid-frame (which would race the
-    // scene-color node if node ordering ever changed).
-    this._halfCam = camera.clone()
-    this._halfCam.layers.set(HALFRES_LAYER)
-
-    this._depthCam = camera.clone()
-    this._depthCam.layers.disableAll()
-    this._depthCam.layers.enable(0) // opaque scene only -- everything NOT tagged half-res
-
-    this._depthOnlyMat = _makeDepthOnlyMaterial()
-
-    this._quadScene = new THREE.Scene()
-    this._quadCamera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1)
-    this._quadGeo = new THREE.PlaneGeometry(2, 2)
-    this._compositeMat = new THREE.ShaderMaterial({
-      vertexShader: _fullscreenVert,
-      fragmentShader: _compositeFrag,
-      uniforms: {
-        tColor: { value: null },
-        tHalfDepth: { value: null },
-        uHalfTexelSize: { value: new THREE.Vector2(1, 1) },
-        // Depth-delta scale (metres) at which a bilateral tap's weight halves. 2m default: tight
-        // enough to reject across a thin-object discontinuity (e.g. a ~0.1-0.3m rail/post) without
-        // over-rejecting on smoothly-varying terrain/foliage depth gradients within one half-res texel
-        // footprint. Exposed as a RenderControls knob (halfResTransparentsDepthSigma) rather than
-        // hardcoded so it can be tuned per-scene without a source edit.
-        uDepthSigma: { value: 2.0 },
-      },
-      transparent: true,
-      depthTest: false,
-      depthWrite: false,
-      blending: THREE.NormalBlending,
-    })
-    this._quad = new THREE.Mesh(this._quadGeo, this._compositeMat)
-    this._quad.frustumCulled = false
-    this._quadScene.add(this._quad)
-
-    this._copyMat = new THREE.ShaderMaterial({
-      vertexShader: _fullscreenVert,
-      fragmentShader: _copyFrag,
-      uniforms: { tSrc: { value: null } },
-      depthTest: false,
-      depthWrite: false,
-    })
-    this._copyQuad = new THREE.Mesh(this._quadGeo, this._copyMat)
-    this._copyQuad.frustumCulled = false
-    this._copyScene = new THREE.Scene()
-    this._copyScene.add(this._copyQuad)
-  }
-
-  // Marks an object (and, when it has one, its immediate children -- InstancedMesh2 pools are a
-  // single object so this is usually a one-call tag) to render ONLY in this half-res pass. `also0`
-  // (default false) additionally keeps layer 0 enabled -- use when the object still needs to
-  // participate in a layer-0-scoped system (raycast pick, occlusion query) that this codebase does
-  // not yet route through a custom layer; Weather.js's particle pools have no such requirement
-  // (perObjectFrustumCulled=false, no raycast target), so the default (layers.set = layer-0 OFF)
-  // is correct for them.
-  tagHalfRes(object, also0 = false) {
-    if (also0) object.layers.enable(HALFRES_LAYER)
-    else object.layers.set(HALFRES_LAYER)
-  }
-
-  untagHalfRes(object) {
-    object.layers.set(0)
-  }
-
-  _ensureTargets(fullW, fullH) {
-    const scale = RenderControls.get('halfResTransparentsScale') || 0.5
-    const w = Math.max(4, Math.floor(fullW * scale))
-    const h = Math.max(4, Math.floor(fullH * scale))
-    if (this._built && w === this._w && h === this._h) return
-    this._disposeTargets()
-    this._w = w; this._h = h
-    // depthBuffer:true -- this target owns a REAL depth attachment so the transparent-layer render
-    // gets genuine GPU depth-testing against the opaque-depth pre-pass below, not a shader-side
-    // approximation. Depth is never read back (no DepthTexture attached) -- only used internally by
-    // the depth-test/depth-write state during the two render calls into this same target.
-    this._target = new THREE.WebGLRenderTarget(w, h, {
-      type: THREE.HalfFloatType,
-      format: THREE.RGBAFormat,
-      minFilter: THREE.LinearFilter,
-      magFilter: THREE.LinearFilter,
-      depthBuffer: true,
-      wrapS: THREE.ClampToEdgeWrapping,
-      wrapT: THREE.ClampToEdgeWrapping,
-    })
-    // Separate small target the depth-only pre-pass's color output (linear-depth-in-alpha, see
-    // _depthOnlyFrag) is captured INTO, distinct from _target -- _target's own color attachment gets
-    // overwritten by the transparent-layer draw in step 2 of compute(), so the depth-reject composite
-    // needs its own place to read the pre-pass's depth from. NearestFilter (not Linear): this texture
-    // is sampled at exact texel centers by the composite's own 2x2-neighborhood taps, a bilinear
-    // sample here would blur two different opaque-scene depths together before the bilateral filter
-    // ever sees them, defeating the point of a depth-aware upsample.
-    this._depthTarget = new THREE.WebGLRenderTarget(w, h, {
-      type: THREE.HalfFloatType,
-      format: THREE.RGBAFormat,
-      minFilter: THREE.NearestFilter,
-      magFilter: THREE.NearestFilter,
-      depthBuffer: false,
-      wrapS: THREE.ClampToEdgeWrapping,
-      wrapT: THREE.ClampToEdgeWrapping,
-    })
-    this._compositeMat.uniforms.uHalfTexelSize.value.set(1 / w, 1 / h)
-    this._built = true
-  }
-
-  _disposeTargets() {
-    if (this._target) this._target.dispose()
-    if (this._depthTarget) this._depthTarget.dispose()
-  }
-
-  _syncCam(src, dst) {
-    dst.near = src.near; dst.far = src.far
-    if (src.fov !== undefined) dst.fov = src.fov
-    if (src.aspect !== undefined) dst.aspect = src.aspect
-    dst.position.copy(src.position)
-    dst.quaternion.copy(src.quaternion)
-    dst.updateProjectionMatrix()
-    dst.updateMatrixWorld(true)
-  }
-
-  // Renders the half-res-layer content (opaque-depth pre-pass + transparent-layer draw) into the
-  // offscreen target. Does not composite -- callers read this._target.texture and composite
-  // explicitly (mirrors SSAO/Bloom's compute()/composite() split, one RenderGraph node per resource).
-  compute() {
-    const size = new THREE.Vector2()
-    this.renderer.getSize(size)
-    if (size.x <= 0 || size.y <= 0) { this._hasContent = false; return }
-    this._ensureTargets(size.x, size.y)
-    this._syncCam(this.camera, this._halfCam)
-    this._syncCam(this.camera, this._depthCam)
-
-    const prevTarget = this.renderer.getRenderTarget()
-    const prevAutoClear = this.renderer.autoClear
-    const prevClearColor = new THREE.Color()
-    this.renderer.getClearColor(prevClearColor)
-    const prevClearAlpha = this.renderer.getClearAlpha()
-
-    this.renderer.setRenderTarget(this._target)
-    this.renderer.autoClear = true
-    this.renderer.setClearColor(0x000000, 0)
-    this.renderer.clear(true, true, false)
-
-    // 1. Opaque-depth pre-pass: draw the NON-half-res scene through the shared depth-only override
-    //    material (see header's OVERRIDE MATERIAL note -- NOT each object's own material, and NOT a
-    //    colorMask trick), so the depth buffer is populated -- gives the transparent-layer draw below
-    //    real occlusion against nearer walls/terrain-proxy geometry without a second full-color render
-    //    and without the per-object program churn that broke InstancedMesh2's texture-bind cache when
-    //    this pre-pass used to render through real materials. The color output now ALSO encodes linear
-    //    view-space depth (see _depthOnlyFrag) -- read below by the blit step for the bilateral
-    //    composite's depth-reject reference.
-    const prevOverride = this.scene.overrideMaterial
-    this.renderer.autoClear = false
-    this.scene.overrideMaterial = this._depthOnlyMat
-    this.renderer.render(this.scene, this._depthCam)
-    this.scene.overrideMaterial = prevOverride
-
-    // 1.5. Blit _target's just-rendered depth-encoded color into the separate _depthTarget, BEFORE
-    //      step 2 overwrites _target's color with the transparent draw -- one small nearest-filtered
-    //      fullscreen-quad copy at half-res, cheap relative to the scene draw in step 1 it depends on.
-    this.renderer.setRenderTarget(this._depthTarget)
-    this._copyMat.uniforms.tSrc.value = this._target.texture
-    this.renderer.render(this._copyScene, this._quadCamera)
-    this.renderer.setRenderTarget(this._target)
-
-    // 2. Transparent/particle layer: real depth-test against the pre-pass above, normal blending,
-    //    depthWrite left as each material already configures it (Weather.js's particle materials
-    //    already set depthWrite:false, matching how they draw in the full-res path today).
-    this.renderer.render(this.scene, this._halfCam)
-
-    this.renderer.setRenderTarget(prevTarget)
-    this.renderer.autoClear = prevAutoClear
-    this.renderer.setClearColor(prevClearColor, prevClearAlpha)
-    this._hasContent = true
-  }
-
-  // Composites the half-res target back onto whatever is currently bound as the render target (the
-  // canvas, called from the RenderGraph composite node after scene-color).
-  composite() {
-    if (!this._hasContent || !this._target) return
-    this._compositeMat.uniforms.tColor.value = this._target.texture
-    this._compositeMat.uniforms.tHalfDepth.value = this._depthTarget.texture
-    this._compositeMat.uniforms.uDepthSigma.value = RenderControls.get('halfResTransparentsDepthSigma') ?? 2.0
-    const prevAutoClear = this.renderer.autoClear
-    this.renderer.autoClear = false
-    this.renderer.render(this._quadScene, this._quadCamera)
-    this.renderer.autoClear = prevAutoClear
-  }
-
-  dispose() {
-    this._disposeTargets()
-    this._compositeMat.dispose()
-    this._depthOnlyMat.dispose()
-    this._copyMat.dispose()
-    this._quadGeo.dispose()
-  }
-}
-
-// RenderGraph nodes -- declared-resource, gated behind RenderControls('halfResTransparents'),
-// composited AFTER scene-color (same position as SSAO/Bloom). ctx.halfResTransparents is a lazily-
-// built instance (see installHalfResTransparents) so a session that never enables the flag pays
-// zero construction cost.
-//
-// CAMERA LAYER GATING: scene-color (RenderGraph.nodes.js) renders with `ctx.camera` UNCHANGED --
-// when this pass is OFF, ctx.camera's layer mask must include layer 0 only (THREE's default,
-// nothing tagged HALFRES_LAYER is ever added unless installHalfResTransparents' caller tags it), so
-// half-res-tagged objects simply do not exist as far as the main camera/scene-color is concerned
-// UNLESS the pass is enabled, in which case `hrt-gate-main-camera` (below) disables HALFRES_LAYER on
-// the real ctx.camera so scene-color skips it (this pass draws it instead) -- and re-enables it the
-// moment the flag is turned off so a live toggle never permanently hides tagged content.
-export function buildHalfResTransparentsNodes() {
-  return [
-    {
-      id: 'hrt-gate-main-camera',
-      reads: [],
-      writes: ['hrtGated'],
-      // hrtGated is a pure on/off stamp -- no other node reads it; the real effect is entirely
-      // external (ctx.camera.layers enable/disable state consumed by THREE's own render() call in
-      // scene-color, not by another RenderGraph node's declared `reads`). See RenderGraph.js's NODE
-      // CONTRACT `terminal` doc.
-      terminal: true,
-      shouldRun: ctx => !!ctx.halfResTransparents,
-      run(ctx) {
-        const on = RenderControls.get('halfResTransparents') === true
-        if (on) ctx.camera.layers.disable(HALFRES_LAYER)
-        else ctx.camera.layers.enable(HALFRES_LAYER)
-        ctx.res.hrtGated = on
-      },
-    },
-    {
-      id: 'hrt-compute',
-      reads: ['sceneColor'],
-      writes: ['hrtComputed'],
-      shouldRun: ctx => RenderControls.get('halfResTransparents') === true && !!ctx.halfResTransparents,
-      run(ctx) {
-        ctx.halfResTransparents.compute()
-        ctx.res.hrtComputed = ctx.frameId
-      },
-    },
-    {
-      id: 'hrt-composite',
-      reads: ['hrtComputed'],
-      writes: ['hrtComposited'],
-      targets: { hrtComposited: 'canvas' },
-      shouldRun: ctx => RenderControls.get('halfResTransparents') === true && !!ctx.halfResTransparents && ctx.res.hrtComputed === ctx.frameId,
-      run(ctx) {
-        ctx.halfResTransparents.composite()
-        ctx.res.hrtComposited = ctx.frameId
-      },
-    },
-  ]
-}
-
-// Lazy installer: constructs GPU resources on first call and stashes the instance on
-// ctx.halfResTransparents. NAMING TRAP AVOIDED (same discipline as SSAO/Bloom): the debug instance
-// handle is window.__halfResTransparentsDebug, NEVER window.__halfResTransparents -- RenderControls
-// mirrors the boolean flag onto that exact global name.
-export function installHalfResTransparents(ctx, renderer, scene, camera) {
-  if (!ctx.halfResTransparents) ctx.halfResTransparents = new HalfResTransparents(renderer, scene, camera)
-  if (typeof window !== 'undefined') window.__halfResTransparentsDebug = ctx.halfResTransparents
-  return ctx.halfResTransparents
-}