Mesh Cleanup

CSG makes a lot of extra geometry, so you can try our Mesh Cleanup approach to clean up your meshes!

When Poseidon carves, it slices triangles against other triangles. That process is precise, but it leaves fingerprints: long skinny slivers, “scaffolding” cuts that only existed so the algorithm could do its job, and faces that are split into a dozen triangles where two would do. The result renders correctly, but the wireframe is messy, the triangle count is higher than it needs to be, and downstream tools (lightmappers, mesh colliders, exporters) have more data to chew on.

Mesh Cleanup is an optional post-carve pass that fixes this. After a carve finishes, it takes each flat region of the result, merges its triangles back into whole polygons, removes the vertices that no longer matter, and re-triangulates the region cleanly. A floor that came out of the carve as 40 slivers becomes the handful of triangles it always should have been. It also heals the T-intersections (hairline cracks where a vertex sits partway along a neighboring triangle’s edge) that carving can leave behind.

Experimental. Mesh Cleanup is new and opt-in. It is designed to never make your mesh wrong: when it isn’t confident about a region, it leaves that region exactly as it was. But expect it to keep improving from release to release. We think its worth using.

In our experiments Mesh Cleanup can reduce up to 95% of the triangles/vertices in really messy multi-object carves. But in real scenes with thousands of carvers building a typical level, we’ve found that turning on Mesh Cleanup reduces total triangles by 50-60% on average.

Turning It On

Mesh Cleanup is a per-object setting. On any Poseidon, open the Advanced section and enable Mesh Cleanup (Experimental). A Mode dropdown appears below it, and that mode decides how aggressively Poseidon is allowed to merge your triangles.

The Modes

The modes form a ladder. Each step up merges more and reduces more, in exchange for giving up one guarantee about your original data.

Safe (Keep Original Triangles)

Poseidon only merges fragments that came from the same original triangle of your source mesh. If the carve chopped one of your triangles into six pieces, Safe glues those six pieces back into that one triangle, and stops there.

  • What you get: every scaffolding cut inside your original triangles disappears. An uncut mesh comes back exactly as you authored it, triangle for triangle.
  • What it protects: everything. Your triangulation, your UVs, your normals. Fragments of one triangle are mathematically guaranteed to reassemble with identical surface data, so Safe cannot warp anything.
  • When to use it: precision-authored assets, meshes with carefully hand-tuned UVs, or any time you want cleanup with zero risk.

Balanced (Protect UV Seams)

Poseidon also merges across your original triangles, but only where the surface is visibly continuous. If the normals and UVs on both sides of an edge agree, the edge is considered cosmetic and can be dissolved. If they disagree (a UV seam, a hard shading edge), the edge is sacred and stays.

  • What you get: noticeably stronger reduction than Safe, because coplanar areas of your mesh merge into large polygons even when they were authored as separate triangles.
  • The trade-off: inside a merged region, UVs are re-interpolated across the new, simpler triangles. If your UVs changed rate across the region (the texture was denser on one side than the other), that variation smooths out. Your seams and hard edges are never touched; the stretching can only happen inside regions that were already visually continuous.
  • When to use it: most meshes with conventional texturing. This is the mode we expect most projects to settle on.

Aggressive (Geometry Only)

Poseidon ignores your source triangles and your surface data entirely and merges everything that is geometrically coplanar. It produces the cleanest, lightest possible mesh, and treats UVs as disposable.

  • What you get: maximum reduction. Whole floors and walls collapse to a few triangles each.
  • The trade-off: UV seams inside a merged region are destroyed: one side’s texturing wins. Only use this if your material doesn’t rely on the mesh’s UVs.
  • When to use it: triplanar shaders, world-space projected materials, or Poseidon’s own WorldSpace UV projection. Any setup where UVs are recomputed from positions anyway.

Global (Project Default)

The object doesn’t choose a mode at all: it follows the project-wide default, which you set once under Project Settings → Poseidon → Default Mesh Cleanup Mode. Use this on most objects so you can change your whole project’s policy in a single place.

What Mesh Cleanup Will Not Do

Mesh Cleanup is a cleanup pass, not a mesh repair tool. A few things worth knowing:

  • It never invents or deletes visible geometry. Every region’s rebuilt surface is validated against the original: the total area must match. If a region fails that check, Poseidon logs a console message (keeping its original triangles) and leaves that region un-reduced. Worst case is always “some areas stayed messy,” never “my mesh has a hole.”
  • It keeps vertices that matter. A vertex where two faces genuinely bend, or where a neighboring surface needs to connect, is kept, even if it looks redundant from one side. This is what prevents hairline cracks between faces.
  • It sweeps up carve dust automatically. Microscopic slivers (thinner than a tenth of a millimeter at default scale) left behind by the carve are removed outright in every mode.
  • It expects well-formed input. Mesh Cleanup assumes the carve produced a sensible closed surface. Overlapping or self-intersecting geometry is left alone rather than “fixed.”

T-Intersection Cleanup

T-intersections are the hairline cracks of CSG: a vertex from one cut sits partway along another triangle’s edge, and because the two surfaces aren’t stitched at that point, single pixels of light can bleed through the seam.

Mesh Cleanup heals these natively. While rebuilding a region, it recognizes edges that were split at mismatched points, reconnects them, and removes the leftover seam vertices, without moving anything. If T-intersections are your main reason for enabling Mesh Cleanup, Safe mode is all you need.

The Legacy Repair Pass

Earlier versions of Poseidon experimented with a standalone Repair T-Intersections pass that took a different approach: physically nudging the shared vertex off the seam and plugging the gap with a small extra triangle. It works, but it changes your geometry (vertices move slightly and triangles are added) and it has known rough edges. Mesh Cleanup supersedes it.

The legacy pass is hidden by default. If you have a specific reason to use it (for instance, you want crack repair but absolutely no re-triangulation of any kind), re-enable it by adding the scripting define POSEIDON_ENABLE_TJUNCTION_REPAIR under Project Settings → Player → Scripting Define Symbols. A “Repair T-Intersections (Legacy)” toggle then reappears in each Poseidon’s Advanced section.

Do not run both passes together: the repair pass adds geometry that Mesh Cleanup then treats as scaffolding to clean up again, and the two will fight each other.

Performance and Runtime

Mesh Cleanup runs after each carve and is compute-heavy. It’s designed for editor-time level building on a developer machine, where the payoff (a permanently lighter mesh) outlives the cost.

The pass is coarsely frame-divided: it works one face region at a time and yields to Poseidon’s frame budget in between, so the editor stays responsive during big carves. One caveat: a single enormous merged face is processed in one step, so the frame budget can be exceeded by however long your largest face takes.

At runtime the rules are conservative by default. In fact, runtime carves skip the cleanup passes entirely, even for objects that have Mesh Cleanup enabled on them. At runtime you almost always want a faster carve more than a prettier wireframe, so cleanup costs you nothing unless you ask for it. Opting in takes two steps:

  1. Enable the cleanup stages on the carve itself via CarveParameters.EnableCleanupStages. This works both for manual operations and for carves queued through the runtime service:
PoseidonRuntimeService.QueueAsyncRecarve(new CarveParameters
{
    FrameTime = 10,
    EnableCleanupStages = true, // allow Mesh Cleanup to run in this operation
});
  1. Make sure each object resolves to an actual mode. Objects with an explicit mode (Safe / Balanced / Aggressive) are ready to go. Objects set to Global, however, resolve to off in a built player (the project setting lives in an editor asset that doesn’t ship), so your game code must set the global default explicitly:
// Opt Global-mode Poseidons into Balanced cleanup at runtime.
MeshCleanup.GlobalMode = PolygonizationMode.MergeWhereAttributesMatch;

(In play mode inside the editor, Global follows your Project Settings value as usual.)

Troubleshooting

  • “MeshCleanup: island of N triangles … keeping its original triangles”: one region failed its validation and was left as-is. Harmless; that area simply didn’t get reduced. If it happens constantly on the same object, we’d love to hear about it.
  • A vertex survives that looks removable: it’s almost always load-bearing. A neighboring face bends there, or connects there. Removing it would open a crack, so Poseidon keeps it.
  • Balanced didn’t merge two areas you expected it to: check whether a UV seam or hard normal edge runs between them. Balanced treats those as boundaries on purpose; Aggressive will merge across them.
  • Mesh Cleanup isn’t running at runtime: that’s the default. See Performance and Runtime above: the operation needs EnableCleanupStages = true, and Global-mode objects need MeshCleanup.GlobalMode set in builds.