Mesh Topology

Home › Guides

To find a caster's silhouette edges, the feature needs to know which triangles share each edge: the mesh's topology. It is built once per mesh and reused.

Mesh requirements

Supported geometry

Any triangle mesh casts a closed shadow volume, including:

• open surfaces, such as Plane and Quad, which cast from their light-facing side
• edges shared by three or more triangles (non-manifold edges)
• triangles wound differently from their neighbors

A triangle wound backward casts as if it faced the other way, which can leave a hole in its shadow. Degenerate (zero-area) triangles are skipped.

Vertex formats

Static meshes can use any vertex format. Skinned and GPU-deformed meshes have extra requirements. See Shadow Casters.

Seam welding

Vertices split for UVs, normals, or hard edges are welded back together by position, so the mesh reads as closed. Topology Weld Tolerance (default 0.0001) is the distance within which positions are joined. Raise it only if a mesh's seams are not exactly coincident.

In skinned meshes, vertices with different bone weights are never welded, since they can move apart.

Readable and non-readable meshes

• Readable meshes (Read/Write enabled) are read directly, in the Editor and in players.
• Non-readable meshes are read in the Editor. Player builds need their topology in the topology cache.

The topology cache

Player builds use a cache at Generated/Resources/StencilShadowTopologyCache.asset, updated automatically before each build. It stores the meshes used by:

• scenes enabled in Build Profiles
• assets in Resources folders
• assets labeled StencilShadowTopology (non-readable meshes only)

Each mesh is stored for every weld tolerance your renderer features use. In the Editor, reimporting a mesh updates its entry.

Addressables and runtime-loaded content

Meshes loaded only at runtime, such as from Addressables or AssetBundles, are not found automatically. Add the Unity asset label StencilShadowTopology to the prefab, model, or mesh. Its dependencies are included too. This is a Unity asset label, not an Addressables label.

The cache stores these meshes' topology without the meshes themselves, so they don't add to the player's size. A runtime-loaded copy of a mesh is matched to its entry by its name, vertex and index counts, and bounds. If two labeled meshes of different shape share all of these, the build logs a warning and their non-readable copies cast no shadow: rename one or enable Read/Write on them.

Procedural and runtime meshes

Readable procedural meshes need no setup. A non-readable mesh created at runtime must register its source data before it casts:

ShadowVolumeTopologyRegistration.Register(mesh, positions, triangleIndices);

Pass the feature's weld tolerance as the fourth argument if you changed it from the default. Call ShadowVolumeTopologyRegistration.Unregister(mesh) when the data is no longer valid. See Scripting API.

Meshes edited at runtime

Topology is built once per mesh. After a script changes a mesh's vertices or triangles in place, call ShadowVolumeTopologyRegistration.Refresh(mesh) so its shadow follows. Only that mesh's casters rebuild their volumes. The mesh must be readable in players. Skinned and GPU-deformed meshes need no call, and a mesh deformed every frame is cheaper as a GPU-deformed mesh.

Malformed-mesh diagnostics

With Diagnostics on, meshes with degenerate triangles or split skinned seams are reported once each. A mesh with no available topology is skipped with a diagnostic. One bad mesh never stops other casters from rendering.