ONESHOTGEMS

For game developers

Plan for the graphics context to disappear

A WebGL context can be lost when the browser or system reclaims graphics resources, a driver changes, or GPU work stalls. GPU handles that once referred to textures, buffers, and programs are no longer safe to use after loss. A robust game keeps its authoritative level and player state outside those resources, so it can rebuild the renderer instead of requiring a full game restart. Context loss is an edge case worth exercising deliberately, not an event to leave untested.

Stop rendering and show a recoverable state

Listen for webglcontextlost on the canvas, prevent the default behavior when you intend to support restoration, and stop issuing draw calls while the context is unavailable. Give the player a restrained message if recovery may take time, but retain the current game state and avoid treating this as a new level or a lost save.

Keep resource descriptions—such as source image, shader text, and buffer data—available independently of WebGL handles. On restoration, create a fresh set of GPU objects from those descriptions, reconnect attributes and uniforms, restore viewport and render state, then resume only after a small known scene draws correctly.

Simulate loss during a real interaction

Use the WEBGL_lose_context extension during development to trigger loss after the scene is loaded. Test losing context while a texture is being added, while the player is moving, and after returning to a visible tab. Confirm that the restoration path recreates every required resource and that any pending asynchronous load is either safely reapplied or discarded.

MDN documents the loss event and the testing extension. Also check isContextLost() before interpreting a failed graphics operation as an ordinary shader or asset error. Record what happened in development diagnostics so a recovery bug can be distinguished from a normal rendering failure.

Questions about WebGL context loss game

Does context restoration bring my textures back?

No. Treat the new context as needing fresh GPU resources. Preserve source data or a way to reload it, then recreate textures and other objects when the context is restored.

How can I test context loss without waiting for a real failure?

MDN's webglcontextlost documentation demonstrates the WEBGL_lose_context extension, which can deliberately trigger loss so you can exercise the recovery path.

Sources and further reading

Report a correction · How these guides are made

Follow your curiosity