'Optimization' section in the documentation 🤩

Hi there,

I find it quite tedious to find information about Three.js project optimization. The only way to get information about this subject is to roam the forum, the GitHub page, StackOverflow, and scattered blogs and youtube videos…

A centralised ‘Optimization’ section in the documentation would be awesomely useful

As I am still learning to master Three.js, I don’t feel confident doing it myself, but I wanted to open the discussion, to see if somebody would be up to do it, and share ideas about what can constitute this page. Of course I can help in the limit of my modest abilities. I jot down some ideas, feel free to add/debate/critisize :

Scene optimization :

  • Occlusion culling
  • LOD
  • BufferGeometry
  • Octree ?
  • What else ?

Assets optimization :

  • Number of vertices
  • Merging geometries
  • GLTF + Draco
  • Texture compression
  • What else ?

Bad practices :

  • Creating objects in the loop
  • Creating identical file loaders (common with beginners)
  • Adding too much lights into a scene
  • Too big camera frustum
  • Using non power of two textures
  • Removing objects without disposing
  • What else?

Optimization process

  • How to know if GPU-bound/CPU-bound
  • How to know draw calls
  • How to profile
  • What else ?

What do you think about this ?


I keep a list of tips here:

I’m sure there’s plenty more the could be added, so if you have any suggestions, let me know.

Check out the links at the bottom of the page to unreal and unity’s optimization pages as well, they have lots of generic graphics tips that are relevant to three.js.

See this guide as well:


@looeee your page of tips is amazing, I’ve learned a lot from it, and go back to it from time to time. I just thought it could be nice to have something in the doc, even if it’s only an index of pages such as yours.

1 Like

I think it’s important that the documentation focuses on two things:

  • The technical documentation of the engine’s API
  • Basic guides that support beginners in different topics like loading 3D models, WebVR, dev-tools etc.

The documentation is not the right place to explain concepts like spatial indices (e.g. Octrees) or culling techniques. There is a lot of existing literature that already does this. You can find resources to all topics listed in @felixmariotto first post. Most of this stuff is not even specific to WebGL but computer graphics in general.

I think it might be worth having a page that discusses three.js specific gotchas or things to look out for. Things like how to handle matrix updates, the variable caching pattern, raycasting performance, etc. I agree that the docs shouldn’t encompass a lesson in computer graphics but there are some things we might take for granted in other engines that three.js does not do.

1 Like

This topic should be already covered by: How to update things and Matrix transformations.

However, it might make sense to enhance the FAQ page with new entries (e.g. “Why is my raycasting performance so bad?”):


Regarding this line under the materials section:

  1. Materials used with morph targets, morph normals, or skinning can’t be shared. You’ll need to create a unique material for each skinned or morphed mesh ( material.clone() is your friend here).

I haven’t found this to be true in my case. I have several SkinnedMesh objects that share a cached material if they are the same type of “enemy” in my game. I haven’t had any problems. Am I misunderstanding this suggestion?