Model Cache Fixes (February 2026)

Overview

Two critical bugs in the IndexedDB processed model cache were fixed in February 2026. These bugs caused missing objects (altars, trees) and lost textures (white/wrong colors) after browser restarts. The fixes ensure reliable model caching without visual corruption.

Bug #1: Missing Objects

Symptoms

Objects disappear after browser restart (altars, trees, buildings)
Scene hierarchy incomplete
Console errors about missing meshes
Inconsistent object counts between sessions

Root Cause

The serializeNode() function used findIndex-by-name to map hierarchy nodes to mesh data:

// ❌ BROKEN: Name-based lookup
const meshIndex = meshes.findIndex((m) => m.name === node.name);

Problem: Models with duplicate mesh names (common: "", "Cube", "Cube") all resolved to the same index. During deserialization, Three.js add() auto-removes objects from their previous parent, so only the last reference survived. Example Failure:

Model hierarchy:
  Root
    ├─ Mesh (name: "Cube")      // meshIndex = 0
    ├─ Mesh (name: "Cube")      // meshIndex = 0 (duplicate!)
    └─ Mesh (name: "Cube")      // meshIndex = 0 (duplicate!)

After deserialization:
  Root
    └─ Mesh (name: "Cube")      // Only last one survives

Fix

Use object-identity map instead of name-based lookup:

// ✅ FIXED: Identity-based lookup
const meshNodeToIndex = new Map<THREE.Object3D, number>();

scene.traverse((node) => {
  if (node instanceof THREE.Mesh || node instanceof THREE.SkinnedMesh) {
    meshNodeToIndex.set(node, meshes.length);
    meshes.push(serializeMesh(node));
  }
});

const hierarchy = serializeNode(scene, meshNodeToIndex);

function serializeNode(
  node: THREE.Object3D,
  meshNodeToIndex: Map<THREE.Object3D, number>
): SerializedNode {
  const meshIndex = meshNodeToIndex.get(node);  // Identity lookup
  return {
    name: node.name,
    type: node.type,
    meshIndex,
    children: node.children.map(child => serializeNode(child, meshNodeToIndex))
  };
}

Result: All objects preserved correctly, regardless of duplicate names.

Bug #2: Lost Textures

Symptoms

White or grey materials after browser restart
Textures not loading
Correct geometry but wrong colors
Trees appear grey instead of green

Root Cause

Textures were serialized as ephemeral blob: URLs but never reloaded during deserialization:

// ❌ BROKEN: Blob URLs don't persist
const mapSrc = material.map?.source?.data?.src;  // "blob:http://..."
if (mapSrc) props.mapUrl = mapSrc;

// On deserialization:
// Blob URL is invalid (blob was released), texture never loads

Problem: Blob URLs are ephemeral and only valid during the current page session. After restart, the blob is gone and the texture fails to load.

Fix

Extract raw RGBA pixel data via canvas and restore as THREE.DataTexture:

// ✅ FIXED: Extract raw pixels
private textureToPixelData(texture: THREE.Texture): SerializedTextureData | null {
  const image = texture.source?.data ?? texture.image;
  if (!image) return null;

  const w = image.naturalWidth || image.width || 0;
  const h = image.naturalHeight || image.height || 0;
  if (w === 0 || h === 0) return null;

  const canvas = document.createElement('canvas');
  canvas.width = w;
  canvas.height = h;
  const ctx = canvas.getContext('2d')!;
  ctx.drawImage(image, 0, 0);
  const imageData = ctx.getImageData(0, 0, w, h);
  
  return { 
    pixels: imageData.data.buffer,  // Raw RGBA bytes
    width: w, 
    height: h 
  };
}

// On deserialization:
const restoreTex = (td: SerializedTextureData, srgb: boolean): THREE.DataTexture => {
  const tex = new THREE.DataTexture(
    new Uint8ClampedArray(td.pixels),
    td.width,
    td.height,
    THREE.RGBAFormat
  );
  tex.colorSpace = srgb ? THREE.SRGBColorSpace : THREE.LinearSRGBColorSpace;
  tex.needsUpdate = true;
  return tex;
};

if (props.mapData) mat.map = restoreTex(props.mapData, true);
if (props.normalMapData) mat.normalMap = restoreTex(props.normalMapData, false);

Result: Textures persist correctly across browser restarts with no async loading race conditions.

Bug #3: Grey Tree Materials (WebGPU)

Symptoms

Trees appear grey in WebGPU renderer
Dissolve effect not working
instanceof MeshStandardMaterial check fails

Root Cause

The createDissolveMaterial() function used instanceof MeshStandardMaterial which fails for MeshStandardNodeMaterial in the WebGPU build:

// ❌ BROKEN: instanceof check fails for NodeMaterial
if (source instanceof THREE.MeshStandardMaterial) {
  material.color.copy(source.color);
  // ...
}

Problem: ModelCache converts all materials to MeshStandardNodeMaterial for WebGPU compatibility, but they don’t pass instanceof MeshStandardMaterial checks.

Fix

Use duck-type property check instead of instanceof:

// ✅ FIXED: Duck-type check
const src = source as THREE.MeshStandardMaterial & {
  map?: THREE.Texture | null;
  normalMap?: THREE.Texture | null;
  // ...
};

if (src.color && src.roughness !== undefined) {
  material.color.copy(src.color);
  material.roughness = src.roughness;
  material.metalness = src.metalness;
  // ...
}

Result: Dissolve materials work correctly in both WebGL and WebGPU renderers.

Cache Version Bump

The PROCESSED_CACHE_VERSION was bumped from 2 to 3 to invalidate broken cache entries:

const PROCESSED_CACHE_VERSION = 3;  // Was: 2

Effect: All users automatically rebuild their cache with the fixed serialization on first load after update.

Debugging Tools

Disable Cache

Bypass the cache entirely for debugging:

// In browser console
localStorage.setItem('disable-model-cache', 'true');
// Reload page

Use Cases:

Verify cache is causing the issue
Test model loading without cache
Force fresh model processing

Clear Cache

Delete the entire cache database:

// In browser console
indexedDB.deleteDatabase('hyperscape-processed-models');
// Reload page - cache will rebuild

Inspect Cache

View cached models:

// In browser console
const req = indexedDB.open('hyperscape-processed-models', 3);
req.onsuccess = () => {
  const db = req.result;
  const tx = db.transaction('models', 'readonly');
  const store = tx.objectStore('models');
  const getAllReq = store.getAll();
  getAllReq.onsuccess = () => {
    console.log('Cached models:', getAllReq.result);
  };
};

Verify Texture Data

Check if textures are properly serialized:

// After cache rebuild, inspect a cached model
const req = indexedDB.open('hyperscape-processed-models', 3);
req.onsuccess = () => {
  const db = req.result;
  const tx = db.transaction('models', 'readonly');
  const getReq = tx.objectStore('models').get('your-model-url');
  getReq.onsuccess = () => {
    const cached = getReq.result;
    console.log('Meshes:', cached.meshes.length);
    cached.meshes.forEach((mesh, i) => {
      const mat = Array.isArray(mesh.material) ? mesh.material[0] : mesh.material;
      console.log(`Mesh ${i}:`, {
        name: mesh.name,
        hasMapData: !!mat.mapData,
        hasNormalMapData: !!mat.normalMapData,
        mapSize: mat.mapData ? `${mat.mapData.width}x${mat.mapData.height}` : 'none'
      });
    });
  };
};

Performance Impact

Cache Size

Before: ~2-5 MB per model (blob URLs + metadata) After: ~5-15 MB per model (raw RGBA pixels + metadata) Trade-off: Larger cache size for reliability and instant texture availability.

Load Time

Before:

Cache hit: 50-100ms (blob URL loading + async texture decode)
Cache miss: 500-2000ms (GLTF parse + texture load)

After:

Cache hit: 20-50ms (synchronous DataTexture creation)
Cache miss: 500-2000ms (unchanged)

Improvement: 50-80% faster cache hits, zero async loading race conditions.

Testing

Verify Fix

Load a model with duplicate mesh names (e.g., altar, tree)
Verify all objects are visible
Reload page (cache hit)
Verify all objects still visible
Check textures are correct colors

Regression Test

# Run model cache tests
cd packages/shared
bun test src/utils/rendering/__tests__/ModelCachePriority.test.ts

Expected: All tests pass, no missing objects or white textures.

Rollback

If you encounter issues with the new cache:

// Disable cache and use direct loading
localStorage.setItem('disable-model-cache', 'true');
// Report issue with model URL and browser console logs

Files Modified:

packages/shared/src/utils/rendering/ModelCache.ts - Core cache implementation
packages/shared/src/systems/shared/world/GPUVegetation.ts - Dissolve material fix

Cache Version History:

Version 1: Original implementation (pre-2025)
Version 2: Added collision data caching (2025)
Version 3: Fixed missing objects and texture persistence (February 2026)

Arena Performance Optimizations - Related rendering improvements
Terrain Height Cache Fix - Another cache-related fix
ClientLoader.ts - Model loading system

Configuration

Operations

Model cache fixes

Model Cache Fixes (February 2026)

Overview

Bug #1: Missing Objects

Symptoms

Root Cause

Fix

Bug #2: Lost Textures

Symptoms

Root Cause

Fix

Bug #3: Grey Tree Materials (WebGPU)

Symptoms

Root Cause

Fix

Cache Version Bump

Debugging Tools

Disable Cache

Clear Cache

Inspect Cache

Verify Texture Data

Performance Impact

Cache Size

Load Time

Testing

Verify Fix

Regression Test

Rollback

​Model Cache Fixes (February 2026)

​Overview

​Bug #1: Missing Objects

​Symptoms

​Root Cause

​Fix

​Bug #2: Lost Textures

​Symptoms

​Root Cause

​Fix

​Bug #3: Grey Tree Materials (WebGPU)

​Symptoms

​Root Cause

​Fix

​Cache Version Bump

​Debugging Tools

​Disable Cache

​Clear Cache

​Inspect Cache

​Verify Texture Data

​Performance Impact

​Cache Size

​Load Time

​Testing

​Verify Fix

​Regression Test

​Rollback

​Related Changes

​Related Documentation

Model Cache Fixes (February 2026)

Overview

Bug #1: Missing Objects

Symptoms

Root Cause

Fix

Bug #2: Lost Textures

Symptoms

Root Cause

Fix

Bug #3: Grey Tree Materials (WebGPU)

Symptoms

Root Cause

Fix

Cache Version Bump

Debugging Tools

Disable Cache

Clear Cache

Inspect Cache

Verify Texture Data

Performance Impact

Cache Size

Load Time

Testing

Verify Fix

Regression Test

Rollback

Related Changes

Related Documentation