Three.js on mobile - the device gotchas that tank a configurator

#threejs #webgl #performance #mobile

A configurator that runs at a locked 60 on your laptop can be a stuttering mess on a customer's phone, and the profiler on your desktop will not show you why. The causes are device realities, not bugs in your render loop. Here are the four that catch people.

1. Pixel ratio will quietly 3x your work

Phones report a devicePixelRatio of 2, 3, even 4. Pass that straight to the renderer and you are rendering nine times the pixels of a ratio-1 screen, for no visible gain on a product shot. Cap it:

renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))

This single line is the most common reason a configurator goes from slideshow to smooth on mobile.

2. GPU memory is small, and textures eat it first

A mid-range phone has a fraction of the GPU memory of a laptop. Large textures are what blow the budget, decoded to raw size on the card. Keep maps at 1024 or 2048, not 4096, for mobile, and compress them with KTX2 so they stay small in VRAM. A model that loads fine on desktop can crash the tab on a phone purely on texture memory.

3. Context loss is a real state, not an edge case

Backgrounded tabs, memory pressure, the OS reclaiming the GPU: mobile loses the WebGL context far more than desktop. If you do not handle it, the user comes back to a black canvas. Listen for it:

renderer.domElement.addEventListener('webglcontextlost', (e) => {
  e.preventDefault()        // allow restore
  // pause your loop
})
renderer.domElement.addEventListener('webglcontextrestored', () => {
  // rebuild what you need, resume
})

4. Touch is not a small mouse

Pinch-zoom, two-finger orbit, and the page trying to scroll while the user rotates the model. Configure your controls for touch explicitly and stop the gesture from fighting the page. OrbitControls with damping handles most of it, but you have to tell it about touch, not assume the mouse config carries over.

The honest summary

Develop with the renderer pixel ratio capped and the browser throttled to a mid-tier device from day one. Every one of these bites at the end of a project, during client review on their actual phone, which is the worst time to find them. I now test configurators on a real mid-range Android before calling anything done. You can poke the live ones from a phone on grodev.pl; they are tuned for exactly this. More on who I am on the about page.

I am Dominik Groński / GroDev, a studio in Poznan, Poland building custom 3D configurators and Laravel back-ends for manufacturers.

DEV Community