Implement per-kind light budgeting with device capability limits

[4ian]

Summary

This PR refactors the 3D light management system to budget lights separately by kind (point lights, spot lights, spot lights with projected textures) and enforce device-specific hardware limits. This prevents shader compilation failures when exceeding device capabilities.

Key Changes

• Device Budget Computation: Added computeDeviceLightBudget() function that calculates per-device limits based on WebGL capabilities (texture units, varyings, uniform vectors) rather than using fixed limits.

• Per-Kind Light Budgeting: Refactored LightManager to maintain separate visible and shadow light lists for each light kind, allowing the budget to be shared intelligently across kinds while keeping individual kind counts stable for shader compilation.

• Capacity Capping: Introduced makeDeviceCappedCapacity() to create capacities that respect both game-requested maximums and device limits, with dynamic getters to handle runtime changes.

• Improved CappedLightList:

  • Replaced weight-based system with count-based capacity to prevent shader recompilation from changing light counts
  • Removed __cameraDistance property from light objects (now stored in list entries)
  • Simplified insertion logic with trimToCapacity() method
  • Changed from weighted cost to simple distance-based sorting

• Light Kind Detection: Added LightManager.getLightKind() to distinguish between point lights, spot lights, and spot lights with projected textures, since three.js compiles these separately into shaders.

• Logging: Added logger for informing users when device limits are lower than requested.

• Documentation: Updated parameter descriptions to clarify that light counts are per-kind and subject to device limits.

Notable Implementation Details

• The device budget is recomputed when a new light kind is first encountered, allowing the budget to shrink and evict lights if necessary
• Spot lights with projected textures share the tighter of two budgets (count and map count)
• The system maintains shader stability by keeping the number of lights of each kind constant once a capacity is reached
• Three.js texture unit and varying constraints are the primary limiting factors on most devices

https://claude.ai/code/session_01GX7gMRj2UUgEFkBV4vpajs