tinyworld-render-performance

Tiny World Render Performance

Keep the renderer single-pass and predictable.

Current renderer contract:

• Default render path is direct except for two explicit render-target systems: the optional pixelation pass (low-res render target + depth/normal-edge fullscreen quad) and the enhanced-water planar reflection pass. The reflection pass renders the scene once from a mirrored camera into tw-water-planar-reflection, hides reflective water during capture, clips below-water geometry, and is disabled in XR / when enhanced water is off. Do not introduce any other always-on post passes (EffectComposer, screen shaders, additional render targets) without explicit approval.
• Cap DPR; do not return to uncapped devicePixelRatio. Dynamic resolution (renderDynamicResolution) is an adaptive multiplier below the user's Resolution slider ceiling: it adjusts effective pixel ratio slowly toward Target FPS and never persists its transient scale.
• Warn on software WebGL renderers (SwiftShader/llvmpipe/softpipe/WARP/etc.) with the dismissible hardware-acceleration banner; many FPS complaints come from browser hardware acceleration being disabled.
• Main WebGL context uses antialias: true; the old smoothing/post pass has been removed.
• Brightness/saturation/contrast are lightweight CSS filters on the WebGL canvas, not shader uniforms.

GPU caches (introduced for low-end GPU + visible-distance scaling):

• geomCache memoizes roundedSlab / roundedBox ExtrudeGeometries by their numeric args. Geometries are tagged userData.cached = true and shared across every mesh that asks for the same shape. Disposal goes through safeDisposeGeometry(geo) — never call geo.dispose() directly on these. If you add a new geometry helper that's called more than a handful of times, cache it the same way.
• getOpenBoxGeometry(w, h, d, skipTop, skipBottom, skipPX, skipNX, skipPZ, skipNZ) returns a cached BoxGeometry with selected face groups removed from the index buffer (matIdx 2 = top, matIdx 3 = bottom). Use it for risers, terrain caps, and hidden-face optimizations. Terrain caps should remain clean flat box slabs rather than roundedSlab bevels: flat top surfaces plus vertical cap thickness provide depth/substance without the repeated chevron artifacts caused by chamfered per-tile bevels. Grass caps should overhang the dirt body so exposed edges read as green lip over dirt. Open-box geometries are still userData.cached = true — never mutate or dispose.
• vbox() accepts skipTop / skipBottom / side-skip options and routes those pieces through cached open-box geometry. Use these flags for buried voxel faces in authored assemblies, especially floating-island underside slabs and inverted roof layers; do not render closed boxes for the inside of the island mass.
• Voxel terrain panels must stay batched inside each tile: bucket panels by cached open-box geometry and material, then emit one THREE.InstancedMesh per bucket. Strip panel bottoms, internal side faces, and neighbour-hidden edge sides with getOpenBoxGeometry; do not go back to one THREE.Mesh per small terrain panel at 8x8/12x12 resolutions.
• Object-free, level-1 grass tiles use the simple flat-grass fast path even when voxel terrain is enabled. A blank island must not spend hundreds of draw calls on per-cell voxel grass panels/details; reserve voxel terrain detail for edited, raised, non-grass, or occupied cells.
• Simple blank-grass terrain is receive-only for shadows. Do not put empty grass slabs into the shadow-map pass; they receive object shadows but should not double the blank-island draw call count.
• Preview/ghost board rendering is forced off by default: Preview distance/window/opacities persist as zero and the Settings controls are removed. Do not let hidden Preview settings create ghost boards or fade traversal on a blank island.
• When voxel terrain is enabled, keep the top surface voxelized but render exposed riser/body sides as solid shader-textured walls. Avoid thousands of side panels: they create cracks/transparent-looking corners and waste draw/instance budget. Keep same-or-higher neighbour side culling intact so shared internal sides are not rendered.
• Mesh Terrain's real-material path may greedily merge flat same-material top rectangles, but keep exposed bevel/chamfer edges and sculpted drops visibly chunky. Future side-wall greedy strips should merge only contiguous faces with identical material, top height, and bottom height.
• Pixelation shader AA should work in pixel mode, but only through edge/depth/normal detection. Do not use a broad fullscreen blur; it smears terrain texture and UI-like decals. Shader AA must not force the normal prepass by itself; only Pixel normal edge should allocate/render the normal target.
• Pixel post shaders are variant-built: the depth sampler uniform exists only when depth edge sampling is enabled, and the normal sampler uniform exists only when normal edge sampling is enabled. Depth edge sampling uses the separate RGBA-packed depth target; do not add unused sampler uniforms to the fullscreen material because WebGL warns when no target is bound.
• Pixel post shaders must preserve the renderer output color space. In Three r185 ShaderMaterial injects color-space helpers, so include/apply colorspace_fragment at the final gl_FragColor step; do not use the old encodings_fragment/encodings_pars_fragment chunks.
• Backdrop/game-screen vignette should remain a cheap CSS overlay variable, not another WebGL post pass. Keep it separate from scene brightness/lighting so it can frame the background without retuning materials.
• Sky/background colour controls are direct scene/CSS settings, not post passes: Sky blue depth darkens the shader sphere and CSS backdrop, Sky blue saturation pushes the same blue hue harder, and Undercloud width rebuilds the small under-island cloud ring. Cloud height also controls undercloud depth below the island, slightly farther than the upper cloud distance, so one height adjustment moves both cloud layers. Keep the undercloud layer as a handful of instanced cloud-puff groups attached below the floating island; do not make a full volumetric cloud field or reuse the full multi-mesh shadow-casting sky cloud factory there.
• Night star backgrounds use the single star-vault-equirect-sphere mesh and a procedural star-only canvas texture, blended only at dusk/night through renderStarVaultStrength. Keep it as a non-depth-writing sky sphere, not an EffectComposer/background pass. Do not load painted sky/land/cloud bitmaps into this sphere: equirect wrapping makes horizon imagery smear under/around the island. Keep the shader horizon mask so stars fade out below the island.
• Floating-island underside depth should use a small number of cached voxel/box slabs and cached utility cylinders attached to homeBorderGroup, not per-cell underside geometry. Treat underside/edge/rocket/utility dressing as decorative scenery: set castShadow = false and receiveShadow = false after building it so hundreds of tiny underside meshes do not enter the shadow-map pass.
• Floating-island shell sides must stay visible from underside/grazing angles, including secondary editable islands. Keep island underside materials double-sided, keep proxy side shells on double-sided cached material clones, and keep the persistent recessed side-backing ring behind edge greebles on home and duplicate island bases. Let the scene-level island culling hide/show the shell group; do not rely on per-mesh frustum culling for the shell slabs because it can clip side/back faces while the island itself is visible.
• Animated waterfall froth/chunks should stay batched as THREE.InstancedMesh pools per exposed water edge, not one mesh per puff/drop. Keep the instance matrix update inside updateWaterfallEffects() and mark the pools non-shadowing.
• Terrain/path storytelling details should be batched or rare. Wheel ruts, surface flecks, pavers, pebbles, grass-edge roots, and small path signs/crates belong in the voxel terrain surface-detail pass with cached geometries, InstancedMesh buckets where possible, and noShadow on decorative extras; do not scatter dozens of shadow-casting meshes per tile.
• Waterfall curtain/blade variety should come from the shared shader sheets (getWaterfallCurtainMaterial() / getWaterfallSurfaceMaterial()), so each exposed water edge uses one vertical sheet plus one surface-flow sheet instead of many blade/tail meshes. If a future pass merges whole rows of waterfalls, keep the same shader-sheet contract and aggregate spans above the per-cell tile factories.
• Voxel object factories that emit repeated vbox() pieces should finish with optimizeVoxelObjectGroup(...) so matching geometry/material pieces become local THREE.InstancedMesh buckets. Keep the legacy factory code intact; the optimization is a render-layer replacement for repeated live meshes, not a removal of the authored object.
• customParts sphere/ellipsoid primitives use the shared getCustomPartEllipsoidGeometry(...) cache and per-mesh scale. Do not create a fresh SphereGeometry for every generated rounded part; repeated domes, balloons, canopies, and tanks should share cached VBOs and be skipped by safeDisposeGeometry.
• disposeGroup(group) disposes geometries by default, but materials remain shared unless a mesh explicitly opts in with userData.ownMaterial, userData.ownedMaterial, or userData.disposeMaterial. Use those flags only for true per-instance material/texture ownership (scratch FX clones, imported unique assets, temporary previews). Never set them on shared M.*, cached fade materials, or cached shader/material singletons.
• Async texture/resource callbacks must repaint through renderSceneIfReady(), not direct renderScene() calls. These callbacks can fire while classic scripts are still loadi

Content truncated.