cluster_lod

The public cluster-LOD API — draw an entity with virtualized cluster geometry. Its registry (entity id → the cluster blob to draw) is read every frame by the @builtin::renderFeatures.cluster_lod render feature, which uploads each blob's pools to GPU buffers once and draws the entity's clusters at its world transform. The feature is ensured live on first use, so clusterLod.show(entity, bytes) is all a caller needs.

The blob is the output of renderer.mesh.buildClusters(meshGuid) (a meshlet-clustered, multi-level LOD hierarchy). Building, decode, GPU upload and draw all run on every target, so a mesh bakes its clusters wherever it is loaded and a blob built once renders anywhere.

Each cluster is self-contained: it carries its own local→global vertex map, and its triangles name positions inside that map one byte at a time. Reaching a cluster's geometry is therefore one contiguous run of vertex-map entries plus three bytes per triangle.

clusterLod.placement(entity) answers the matrix the feature last cut and drew that entity's clusters at — 16 column-major numbers, translation in elements 13, 14, 15. It is the entity's composed object-to-world placement, so the cut agrees with the draw wherever the entity sits in a hierarchy.

local clusterLod = require("modules.cluster_lod")
clusterLod.show(entity, renderer.mesh.buildClusters(meshGuid))
clusterLod.setThreshold(entity, 0.5)
local m = clusterLod.placement(entity)
clusterLod.hide(entity)