AI Task: ai-tasks/optimize-webgl.md

[dyfios]

Automated implementation for ai-tasks/optimize-webgl.md

[Copilot]

Pull request overview

This PR implements WebGL memory optimizations for the WebVerse Runtime project, including memory configuration, streaming mipmaps, quality presets, and automated resource cleanup.

Changes:

• Added WebGL-specific memory configuration with dynamic growth settings (64 MB initial, up to 2048 MB)
• Implemented streaming mipmaps with 256 MB budget for texture memory optimization
• Created ResourceManager for periodic cleanup and WebVerseRuntime integration for WebGL-specific optimizations
• Updated Builder.cs with WebGL build configuration and exception handling
• Added comprehensive test suite and documentation

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 21 comments.

Show a summary per file

File	Description
tests/test_webgl_memory_optimizations.py	Comprehensive test suite covering memory configuration, streaming mipmaps, quality settings, and build pipeline
docs/developer/webgl-memory-optimization-summary.md	Documentation of implemented optimizations (incomplete)
Assets/Runtime/WebVerseRuntime.cs	New runtime component for WebGL-specific optimizations and quality settings
Assets/Runtime/ResourceManager.cs	New singleton manager for periodic resource cleanup in WebGL builds
Assets/Build/Builder.cs	Updated build script with WebGL memory configuration and exception handling
.ai/plan.md	Implementation plan and design documentation

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The Builder class inherits from MonoBehaviour but contains only static methods and is never used as a MonoBehaviour component. This inheritance is unnecessary and could be confusing. Consider removing the MonoBehaviour inheritance since this is purely an editor/build script that doesn't need to be attached to GameObjects.

Suggested change

	public class Builder : MonoBehaviour
	public static class Builder

[Copilot]

There's a typo in the exception support setting. The property name should be 'WebGLExceptionSupport.FullWithoutStacktrace' (with capital 'T'), but Unity's actual API uses 'FullWithStacktrace'. This will cause a compilation error. The correct enum value should be WebGLExceptionSupport.FullWithStacktrace or WebGLExceptionSupport.FullWithoutStacktrace depending on the desired behavior.

Suggested change

	PlayerSettings.WebGL.exceptionSupport = WebGLExceptionSupport.FullWithoutStacktrace;
	PlayerSettings.WebGL.exceptionSupport = WebGLExceptionSupport.FullWithStacktrace;

[Copilot]

The new WebVerseRuntime class in the WebVerseRuntime namespace will conflict with the existing WebVerseRuntime class in the FiveSQD.WebVerse.Runtime namespace. This creates a naming collision that will cause confusion and potential compilation issues when both are imported. The new class should either use a different name (e.g., WebGLOptimizationManager) or be integrated into the existing WebVerseRuntime class in the FiveSQD.WebVerse.Runtime namespace.

Suggested change

	public class WebVerseRuntime : MonoBehaviour
	public class WebGLOptimizationManager : MonoBehaviour

[Copilot]

The same WebGL memory configuration code (memorySize, maxMemorySize, etc.) is duplicated in ConfigureWebGLBuildSettings (lines 78-82) and SetupWebGLOptimizations (lines 177-181). This violates the DRY principle and makes maintenance harder. Extract this configuration into a separate method that can be called from both locations.

Suggested change

	[MenuItem("WebVerse/Setup WebGL Optimizations")]
	public static void SetupWebGLOptimizations()
	{
	Debug.Log("Setting up WebGL optimizations...");
	// Configure WebGL memory settings
	PlayerSettings.WebGL.memorySize = 64;
	PlayerSettings.WebGL.maxMemorySize = 2048;
	PlayerSettings.WebGL.memoryLinearGrowthStep = 32;
	PlayerSettings.WebGL.memoryGeometricGrowthStep = 0.15f;
	PlayerSettings.WebGL.memoryGeometricGrowthCap = 128;
	private static void ConfigureWebGLMemorySettings()
	{
	// Centralized WebGL memory configuration
	PlayerSettings.WebGL.memorySize = 64;
	PlayerSettings.WebGL.maxMemorySize = 2048;
	PlayerSettings.WebGL.memoryLinearGrowthStep = 32;
	PlayerSettings.WebGL.memoryGeometricGrowthStep = 0.15f;
	PlayerSettings.WebGL.memoryGeometricGrowthCap = 128;
	}
	[MenuItem("WebVerse/Setup WebGL Optimizations")]
	public static void SetupWebGLOptimizations()
	{
	Debug.Log("Setting up WebGL optimizations...");
	// Configure WebGL memory settings
	ConfigureWebGLMemorySettings();

[Copilot]

The documentation file is incomplete - it ends abruptly at line 48 with 'Created dedicated quality preset with WebGL-specific settings:' without providing the actual settings details. The document should be completed to include the quality preset details and any other sections mentioned in the implementation plan.

Suggested change

	Created dedicated quality preset with WebGL-specific settings:
	Created dedicated quality preset with WebGL-specific settings:
	- **Preset Name:** `WebGL_LowMemory`
	- **Default Quality for WebGL:** This preset is selected as the default tier for WebGL builds.
	- **Texture Quality:** Half resolution (or lower) for most textures to reduce memory footprint.
	- **Anisotropic Filtering:** Disabled globally to avoid additional texture sampling cost.
	- **Anti-Aliasing (MSAA):** Disabled (0x) for WebGL; use post-process AA only if strictly necessary.
	- **Shadows:**
	- Shadow Quality: Disabled or very low for WebGL.
	- Shadow Resolution: Low (if shadows are required).
	- Shadow Distance: Reduced to a minimal acceptable range.
	- **Realtime Reflection Probes:** Disabled to avoid dynamic cubemap allocations.
	- **Billboards / LOD:**
	- LOD Bias: Reduced (e.g., 0.6–0.8) to favor lower-detail meshes earlier.
	- Maximum LOD Level: Clamped so highest-resolution LODs are not used on WebGL.
	- **VSync Count:** Disabled (or set to "Don't Sync") to avoid unnecessary frame pacing overhead in browsers.
	- **Particle Systems:**
	- Soft Particles: Disabled.
	- Shadows on Particles: Disabled.
	- **Skin Weights / Blend Weights:** Reduced (e.g., 2 bones per vertex) where compatible with content.
	- **LOD Cross-Fade / Dithering:** Disabled if causing extra memory or bandwidth overhead.
	- **Other Memory-Saving Toggles:**
	- Lens flares, motion blur, and heavy post-processing disabled by default in this preset.
	- HDR rendering disabled for WebGL builds unless explicitly required.
	**Benefits:**
	- Minimizes texture, mesh, and shader memory usage for WebGL targets.
	- Reduces draw call complexity and GPU bandwidth requirements.
	- Provides more predictable performance across a wide range of browser and device configurations.
	- Ensures WebGL builds remain under typical browser memory and performance limits.
	### 4. Planned Improvements
	The following improvements are planned for future iterations of the WebGL profile (tracked in the implementation plan, not yet implemented at the time of this summary):
	- Further tuning of texture compression formats per platform (e.g., ASTC/ETC/BC) for WebGL 2.
	- Additional reduction of post-processing effects tailored to low-end devices.
	- Automated validation tools to ensure new content respects WebGL memory and quality constraints.

[Copilot]

Import of 'json' is not used.

Suggested change

import json

[Copilot]

Import of 'yaml' is not used.

Suggested change

import yaml

[Copilot]

Import of 're' is not used.

Suggested change

import re

[Copilot]

Import of 'MagicMock' is not used.

Suggested change

	from unittest.mock import Mock, patch, MagicMock
	from unittest.mock import Mock, patch

[Copilot]

Import of 'ET' is not used.

Suggested change

import xml.etree.ElementTree as ET

[dyfios]

@ai-fix: This does not follow WebVerse-Runtime architecture patterns.