Convex Hull has more than 255 Polygons! – How to fix Unity Convex Colliders

[Physics.PhysX] ConvexHullBuilder: convex hull has more than 255 polygons! – What is this error?

Unity logs the convex hull has more than 255 polygons error when trying to generate a convex mesh (a version of the mesh with no holes or entrances; imagine wrapping your mesh with wrapping paper) but fails due to the complexity of the mesh as Unity will not generate a convex mesh with more than 255 polygons.

Convex meshes are mainly generated by mesh colliders with the convex property enabled. You may also have scripts in your project trying to generate a convex mesh too. In these cases you should be able to double click the error and you’ll be taken to the script causing the error allowing you to debug further.

However most of the time the error will be created by a mesh collider and is logged to the console every time the object is interacted with, either by movement, activation or simply just when entering a scene containing the object.

Solution #1 – Inflate the mesh within Unity

Luckily the solution is usually pretty easy to fix as most of the time enabling inflation will fix the issue completely. In Unity 2017.3 and later you can mark the convex mesh to be inflated from the “Cooking Options” dropdown making sure “Inflate Convex Mesh” is enabled. In older versions of Unity there’s simply a tickbox to “Inflate Mesh” on mesh colliders.

Unity Mesh Collider Inflate Convex Mesh

If inflating the convex mesh still isn’t working you can increase the skin width which as the name suggests inflates or bloats the size of the convex mesh smoothing it out and reducing polygons. Just be aware that the higher the skin width the less accurate collisions will be to the actual mesh.

Convex Mesh Skin Width Changing

Solution #2 – Use primitive colliders instead

Simply using multiple box colliders and sphere colliders to create the shape of your model actually gives you a lot of extra benefits, however the setup process of placing the colliders is a bit more work compared to simply attaching a mesh collider component to your mesh!

Benefits of using multiple primitive colliders rather than a convex mesh collider:

  • Better performance when processing collisions.
  • Allows you to create more accurate collision meshes than you can achive with a convex mesh.
  • Provides more stability in cases where the object will be carrying other objects. (such as the flatbed of a pickup truck model)
Unity Mesh Primitive Colliders

Solution #3 – Create an alternative simplified version of the mesh

Sometimes you may find that Unity refuses to generate a convex version of the mesh unless you set the inflation extremely high and you mesh may be way too complicated to use primitive colliders.

In these cases then making an alternative mesh for your collider might be the best option! Just remember that you’ll still need to mark the new mesh as convex too for it to be used as a physical object in dynamic collisions. You’ll need to keep your new mesh simple and smooth or you’ll be given the same convex hull has more than 255 polygons error again!

Unity Simplified Mesh Collider

This is the mesh being used as the collider in the screenshot above, it’s a very simple example of how an alternative collider can be used.

Unity Very Simple Custom Collider

Have any questions about anything explained in this guide? Have you ran into the convex hull has more than 255 polygons error, did this guide help? Leave a comment at the bottom of the page and I’ll try help as best I can!