FAQ & Troubleshooting

This section compiles answers to the most frequent questions and solutions for typical issues encountered during WebGL optimization.

Installation and Demo Scene

Q: I opened the demo scene, but all materials and objects are pink!

A: Your project utilizes URP, while the demo scene is configured by default for BiRP. Simply unpack the package located at WebAdaptivePerformance/Demo/Import Me (URP).unitypackage. The shaders will update automatically.

Q: I installed the plugin, but visually, absolutely nothing changes in the game.

A: Review this checklist:

• Is the plugin enabled in Project Settings? Are the Scalers added and active?
• Are the Unity graphics initially set to maximum? The plugin has nothing to reduce if the settings are already low.
• Your device might just be handling the load effortlessly, and the FPS is stable. Add the Dashboard prefab to the scene to observe the Indexer's current decisions.
• If everything is configured correctly but there is no effect — reach out to us, and we'll help you troubleshoot.

Resolution and User Interface (UI)

Q: The resolution is not changing (Resolution Scaler is inactive).

A: The two most common causes:

1. If you are using BiRP and the RenderTextureScaling mode: inspect the Target Tags array in the Scaler settings. If your game's camera has a different name (not MainCamera), you must input its tag. Otherwise, the plugin will simply fail to locate it.
2. The NativeBrowserScaling mode operates exclusively in a compiled WebGL build. It performs no actions in the Unity Editor.

Q: When FPS drops, my UI also becomes blurry!

A: Verify that in BiRP, you selected RenderTextureScaling. The Canvas itself must be set to Screen Space - Overlay mode (or utilize a dedicated UI camera).

Q: Standard UI buttons work perfectly, but my custom mouse clicks on 3D objects are off-target.

A: Standard EventSystem events are automatically repaired by our WebScaledPhysicsRaycaster component. However, if you are executing a custom raycast via code (Camera.ScreenPointToRay()), it will miss the target due to the texture size alteration. Utilize the plugin's dedicated method: WebRaycasterUtility.TryComputeScaledRay().

Metrics and System Behavior

Q: Graphics quality dropped due to lag. Now FPS is high again, but the graphics aren't recovering!

A: The Anti Yo-Yo Penalty System has likely triggered. The plugin temporarily blocked the upgrade to prevent Quality flickering.

• If you want the graphics to recover faster, decrease the Penalty Lockout Duration parameter (e.g., to 10 seconds).
• Also, check the Increase Cooldown parameter — the wait time might be set too high.

Q: The Dashboard constantly displays a CPU Bottleneck or Unknown, even though the scene is empty.

A: Ensure you enable Frame Timing Stats in Player Settings. Additionally, verify that Application.targetFrameRate = -1. Removing the hard frame limit liberates the metrics from artificial setTimeout delays within the browser.

Q: The character or physics objects start stuttering during severe lag spikes.

A: This is a side effect of the Physics Step Scaler. It modifies Time.fixedDeltaTime to rescue the processor from overload. To ensure movement remains visually smooth, enable the Interpolate mode on your character's Rigidbody component.

Q: Shadow Scalers are enabled, but performance isn't increasing, and the shadows are still present.

A: The plugin exclusively manages dynamic (Realtime) shadows. If the lighting in your scene is Baked/Lightmaps, the Scalers will have absolutely no effect on it.

Custom Scalers

Q: My custom Scaler works perfectly in the Editor but completely disappears in the WebGL build!

A: The IL2CPP compiler stripped it during the build process as "dead code." Always apply the [UnityEngine.Scripting.Preserve] attribute above your custom Scaler class.