feat: Add 10 comprehensive feature modules for Pixi/Three expansion

[canerdogan]

Summary

• 10 new feature modules following Laravel-inspired ServiceProvider + Facade + Contract architecture: TickSystem, ResourceTracker, RaycastEventSystem, PerformanceAdvisor, InstanceManager, PostProcessingPipeline, EnvironmentSystem, PrefabSystem, SmartAssetPipeline, and GameSoundPresets
• SSOT/DRY compliance: All types defined canonically in src/contracts/, implementations import from there
• 7 code review fixes: DirectionalLight shadow null guard, EnvironmentSystem renderer reference, PostProcessing rebuild race condition, ModelLoader deep material clone, timestamped thermal detection, RaycastEventSystem leave events on destroy, corrected eviction docs

Key Architecture Decisions

Module	Approach
PostProcessing	pmndrs/postprocessing for automatic effect merging (~80% fewer render passes)
PerformanceAdvisor	Hysteresis thresholds (45/58 FPS dead zone) + exponential upgrade backoff + time-windowed thermal detection
RaycastEventSystem	Layer-based filtering with BVH acceleration support, pointer move throttling (20Hz mobile / 60Hz desktop)
SmartAssetPipeline	Priority queue loading, LRU eviction with frequency-boosted scoring, adaptive concurrency
InstanceManager	Three-tier strategy (clone → InstancedMesh → merged geometry) with frustum culling

Verification

• npx tsc --noEmit → 0 errors
• npm test → 215 tests passed (no regressions)
• 51 files changed, ~5000 lines added

Test plan

• Verify npx tsc --noEmit passes with zero errors
• Verify npm test passes all 215 tests
• Verify new service providers are registered in createGame()
• Verify tree-shaking: unused modules excluded from bundle
• Verify contracts are the single source of truth for all shared types

🤖 Generated with Claude Code

[claude]

Code Review Summary

Found 2 high-confidence issues that need to be addressed:

1. Missing package.json exports for new Three.js modules (CLAUDE.md violation)

The PR adds three new Three.js module subdirectories (lights, loaders, animation) but does not add corresponding granular export entries to package.json. This violates the tree-shaking architecture requirement in CLAUDE.md.

CLAUDE.md Rule (lines 46-51):

Yeni Modül Eklerken

1. Modül için index.ts oluştur (sadece o modülün export'ları)
2. package.json exports'a ekle
3. Ana src/index.ts'e de ekle (backwards compatibility)
4. Rollup config'de preserve modules aktif olmalı

Currently, package.json only has:

"./three-toolkit": {
  "import": "./dist/three/index.js",
  "types": "./dist/three/index.d.ts"
}

Required additions:

"./three/lights": {
  "import": "./dist/three/lights/index.js",
  "types": "./dist/three/lights/index.d.ts"
},
"./three/loaders": {
  "import": "./dist/three/loaders/index.js",
  "types": "./dist/three/loaders/index.d.ts"
},
"./three/animation": {
  "import": "./dist/three/animation/index.js",
  "types": "./dist/three/animation/index.d.ts"
}

This enables granular imports like:

import { DirectionalLight } from '@gamebyte/framework/three/lights';
import { ModelLoader } from '@gamebyte/framework/three/loaders';

Reference:

gamebyte-framework/CLAUDE.md

Lines 46 to 51 in c5be6db

	### Yeni Modül Eklerken
	1. Modül için `index.ts` oluştur (sadece o modülün export'ları)
	2. `package.json` exports'a ekle
	3. Ana `src/index.ts`'e de ekle (backwards compatibility)
	4. Rollup config'de preserve modules aktif olmalı

---

2. Bug: Inconsistent texture return behavior in TextureLoader3D

File: src/three/loaders/TextureLoader.ts (line 102)

The load() method has inconsistent behavior between cache hits and cache misses:

• Cache hit (line 92): Returns texture.clone()
• Cache miss (line 102): Returns the original texture that was also stored in cache

This means the first caller receives the exact texture object stored in the cache. If they modify it (e.g., change repeat, offset, wrapS), those modifications will persist in the cache and affect all subsequent clones.

Example of the bug:

const loader = new TextureLoader3D();

// First load - gets original (which IS the cached texture)
const texture1 = await loader.load('/texture.png');
texture1.wrapS = THREE.RepeatWrapping;  // Modifies cached texture!

// Second load - clone inherits the modified state
const texture2 = await loader.load('/texture.png');
// texture2 has unexpected wrapS setting

Fix: Change line 102 from resolve(texture); to resolve(texture.clone());

This ensures consistent behavior - all callers receive clones, and the cached texture remains pristine.

Reference:

gamebyte-framework/src/three/loaders/TextureLoader.ts

Lines 99 to 103 in c5be6db

	this.applyOptions(texture, { ...this.config.defaults, ...options });
	this.cache.set(fullUrl, texture);
	this.emit('load', texture, fullUrl);
	resolve(texture);
	},

[claude]

Code review completed. Please see individual inline comments for details.

[canerdogan]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[claude]

Code Review

Found 6 high-confidence issues that need to be addressed:

1. Missing Type Exports in src/index.ts (CLAUDE.md violation)

CLAUDE.md Rule: "Ana src/index.ts'e de ekle (backwards compatibility)" (CLAUDE.md L46-51)

The PR adds new Graphics types but doesn't export them from src/index.ts, breaking backwards compatibility. These types are exported from src/contracts/index.ts but users importing from 'gamebyte-framework' won't have access.

Missing exports:

• IFilter, IMask, BlendMode
• IBlurFilterOptions, IColorMatrixFilterOptions, IDropShadowFilterOptions, IGlowFilterOptions, IOutlineFilterOptions

Fix: Add these types to the Graphics export list in src/index.ts around line 559-575.

---

2. Phantom Package.json Exports (bug)

Location: package.json

8 new export paths point to non-existent source modules:

• ./tick, ./resources, ./three/events, ./three/instancing
• ./postprocessing, ./environment, ./prefabs, ./assets/pipeline

These will cause build failures and import errors. Only 3 exports have actual implementations:

• ✅ ./three/lights
• ✅ ./three/loaders
• ✅ ./three/animation

Fix: Remove the 8 phantom exports from package.json or implement the missing modules.

---

3. AnimationController.play() - reset() after crossFadeTo() corrupts animation (bug)

Location: src/three/animation/AnimationController.ts:168-173

The play() method calls action.reset() AFTER crossFadeTo(), which destroys the blend state that crossFadeTo just configured.

Code:

if (options.crossFade && this.currentAction) {
  this.currentAction.crossFadeTo(action, duration, true);  // Sets up blend state
}
// ...
action.reset();  // ❌ Destroys the blend state
action.play();

Issue: This is a known Three.js issue. The reset() clears weight interpolants and time scale that crossFadeTo configured, causing animations to snap to full weight instead of blending smoothly.

Fix: Move reset() to BEFORE the crossFadeTo() call, or skip it when crossfading.

---

4. ModelLoader.cloneModel() - Shared GPU resources cause disposal bugs (bug)

Location: src/three/loaders/ModelLoader.ts:192

cloneModel() uses scene.clone() which creates shallow clones that share geometry and material references with the original.

Issues:

1. SkinnedMesh not properly cloned: scene.clone() doesn't rebind skeletons. Animated characters will be broken. Use THREE.SkeletonUtils.clone() instead.
2. Shared GPU resources: Clones share BufferGeometry and Material instances. When clearCache() calls disposeModel() (lines 204-215), it disposes geometries/materials still in use by active clones, causing rendering corruption or crashes.

Fix: Use SkeletonUtils.clone() for proper skeleton cloning, and implement deep material/geometry cloning.

---

5. TextureLoader3D.loadCubeMap() - Race condition (bug)

Location: src/three/loaders/TextureLoader.ts:126

loadCubeMap() mutates shared this.cubeLoader state before async load:

this.cubeLoader.setPath(path);  // Mutates shared instance
return new Promise((resolve, reject) => {
  this.cubeLoader.load(urls, ...);  // Async operation
});

Issue: If two concurrent loadCubeMap() calls use different basePath values, the second call overwrites the first's path before its load begins, causing wrong textures to load.

Fix: Create a new CubeTextureLoader per call, or pass full URLs directly.

---

6. ModelLoader.enableDraco() - Memory leak (bug)

Location: src/three/loaders/ModelLoader.ts:100-107

Each enableDraco() call creates a new DRACOLoader without disposing the previous one:

enableDraco(decoderPath?: string): this {
  this.setupDraco();  // Creates new DRACOLoader, old one leaks
  return this;
}

private setupDraco(): void {
  this.dracoLoader = new DRACOLoader();  // Overwrites old reference
  // ...
}

Issue: DRACOLoader spawns Web Workers for decoding. Old instances are orphaned without disposal, leaking workers.

Fix: Add this.dracoLoader?.dispose() at the start of setupDraco().

[claude]

Infinite loop in texture fallback logic

When a texture has a WebP fallback URL and both the fallback and original URLs fail to load, this code creates an infinite loop.

The problem: The onerror handler checks fallbackUrl && textureUrl !== url, which is always true when a fallback exists because both fallbackUrl and textureUrl are const values captured in the closure. After the first fallback to url, if that also fails, the condition is still true and it sets img.src = url again, triggering another onerror indefinitely.

Impact: Browser tab hangs when both the WebP and original texture URLs are unreachable.

Fix: Track whether the fallback has been attempted:

let triedFallback = false;
img.onerror = () => {
  if (fallbackUrl && !triedFallback) {
    triedFallback = true;
    img.src = url;
  } else {
    reject(new Error(`Failed to load texture: ${textureUrl}`));
  }
};

[claude]

Direction always hardcoded to down

The setTier() method always emits the quality change event with direction down, regardless of whether the new tier is actually higher or lower than the current tier.

The problem: When manually setting a tier (e.g., from low to ultra), the event reports direction as down even though quality went up. Any code listening on quality:changed will receive incorrect direction information.

Impact: Event listeners cannot distinguish between upgrades and downgrades, breaking UI indicators or analytics that rely on the direction parameter.

Suggested fix:

setTier(tierName: string): void {
  const oldTier = this.tierManager.getCurrentTier();
  const newTier = this.tierManager.setTierByName(tierName);
  if (newTier && oldTier) {
    const direction = newTier.index > oldTier.index ? 'up' : 'down';
    this.emitQualityChange(newTier, direction);
  }
}

For reference, the automatic sample() method correctly uses down for downgrades (line 164) and up for upgrades (line 189).

[claude]

Race condition: async rebuild can miss effect changes

The render() method calls rebuildComposer() without awaiting it (fire-and-forget). Since rebuildComposer() is async and unconditionally sets needsRebuild = false at the end, any effects added/removed during the async rebuild window are silently lost.

The race condition:

1. Frame N: render() calls rebuildComposer() (not awaited). Rebuild starts and sets rebuilding = true.
2. rebuildComposer() hits await this.loadPmndrs() and yields execution.
3. Game code calls add() or remove(), setting needsRebuild = true.
4. Frames N+1 through N+k: render() skips rebuild because rebuilding = true.
5. The async rebuild completes and sets needsRebuild = false (line 308), erasing the flag that was set in step 3.
6. The pipeline is now permanently stale - the newly added/removed effects never get reflected.

Impact: Effects added or removed during the ~50-200ms rebuild window are never applied to the composer, leaving the pipeline with stale effects.

Suggested fix: Check if needsRebuild was set during the rebuild:

private async rebuildComposer(): Promise<void> {
  this.rebuilding = true;
  const rebuildStartedAt = performance.now();
  
  // ... rebuild logic ...
  
  this.rebuilding = false;
  // Only clear flag if no new changes occurred during rebuild
  if (!this.needsRebuild) {
    this.needsRebuild = false;
  }
  this.emit('pipeline:rebuilt', sortedEffects.length);
}

Or better: snapshot the flag before rebuilding and only clear it if unchanged.

[claude]

Missing cycle detection in prefab extends chain

The resolveConfig() method recursively follows the extends chain but has no cycle detection. If two or more prefabs form a circular dependency (e.g., prefab A extends B, prefab B extends A), this causes infinite recursion and a stack overflow.

The problem: The cache check on line 326 only helps if a prefab has already been fully resolved. During recursion, neither prefab in a cycle has been cached yet, so the recursion continues indefinitely.

Example that crashes:

prefabs.register({ id: 'A', extends: 'B' });
prefabs.register({ id: 'B', extends: 'A' });
prefabs.instantiate('A'); // Stack overflow

Impact: Any circular extends chain (even indirect like A→B→C→A) causes a crash.

Suggested fix: Add a visited set parameter:

private resolveConfig(prefabId: string, visited = new Set<string>()): PrefabConfig | null {
  if (visited.has(prefabId)) {
    console.warn(`Circular extends chain detected for prefab: ${prefabId}`);
    return null;
  }
  
  const cached = this.resolvedConfigs.get(prefabId);
  if (cached) return cached;

  const config = this.definitions.get(prefabId);
  if (\!config) return null;

  if (config.extends) {
    visited.add(prefabId);
    const parent = this.resolveConfig(config.extends, visited);
    // ... rest of logic
  }
}

[claude]

Memory leak: dispose() never decrements group.count

When an instance handle is disposed, it marks the instance as invisible but never decrements group.count. This causes capacity to grow unboundedly as instances are created and disposed.

The problem:

• Line 103 increments group.count when creating instances
• Lines 358-369 (dispose) mark instances as invisible but never decrement group.count
• Line 233 (ensureCapacity) doubles capacity when group.count > group.capacity
• Since count never shrinks, each create-dispose cycle permanently consumes capacity

Impact: In games with frequent spawn/despawn cycles (bullets, particles, enemies), the InstancedMesh buffer grows without bound, causing memory leaks and eventual performance degradation.

Example:

// Create and dispose 1000 times
for (let i = 0; i < 1000; i++) {
  const handle = instanceMgr.createInstance('enemy');
  handle.dispose(); // count stays at 1000 after loop
}
// group.count is now 1000, capacity has doubled multiple times
// but all instances are invisible/unused

Suggested fix: Implement free-list with swap-last removal or maintain a separate active count:

dispose() {
  // ... existing visibility code ...
  
  // Decrement count (or maintain separate activeCount)
  group.count--;
  
  // Update instancedMesh.count to reflect active instances
  if (group.instancedMesh) {
    group.instancedMesh.count = group.count;
  }
}

[claude]

Performance issue: new Fog objects created every frame during transitions

The lerpConfig() method creates a new THREE.Fog or THREE.FogExp2 object on every frame during transitions, causing unnecessary GC pressure.

The problem: During a transitionTo() call, lerpConfig() is called via requestAnimationFrame each frame. At 60fps over a 2-second transition, this allocates ~120 Fog objects that are immediately discarded, requiring garbage collection.

Impact: Frequent allocations in the game loop cause GC pauses that can lead to visible frame drops/stutters, particularly on mobile devices (which this framework explicitly targets as "mobile-first").

Note: The author already recognized this anti-pattern for THREE.Color objects by declaring reusable tempColor1, tempColor2, and tempColor3 fields - but failed to apply the same pattern to Fog objects.

Suggested fix: Reuse fog instances and mutate properties in-place:

// Class fields:
private currentFog: THREE.Fog | THREE.FogExp2 | null = null;
private currentFogType: 'linear' | 'exponential' | null = null;

// In lerpConfig():
const fogType = to.fog.type === 'exponential' ? 'exponential' : 'linear';

// Only create new fog if type changes
if (\!this.currentFog || this.currentFogType \!== fogType) {
  if (fogType === 'exponential') {
    this.currentFog = new THREE.FogExp2(fogColorStr, density);
  } else {
    this.currentFog = new THREE.Fog(fogColorStr, fogNear, fogFar);
  }
  this.currentFogType = fogType;
  this.scene.fog = this.currentFog;
} else {
  // Mutate in-place
  this.currentFog.color.setStyle(fogColorStr);
  if (this.currentFog instanceof THREE.Fog) {
    this.currentFog.near = fogNear;
    this.currentFog.far = fogFar;
  } else {
    this.currentFog.density = density;
  }
}

Both THREE.Fog and THREE.FogExp2 expose mutable properties (fog.color, fog.near, fog.far, fogExp2.density) that support in-place updates.