Each Meshmatic profile contains a “tools” array — a list of processing operations applied by the Meshmatic Engine in a strict top-to-bottom sequence.
The order is not random: each tool depends on the previous step’s cleanup, ensuring the mesh is optimized correctly without losing fidelity.
This article explains why the sequence of tools matters, and what each stage contributes to the final conversion.
Why Tool Order Matters
Meshmatic’s toolchain works like a layered pipeline:
-
Geometry preparation (merge, reorient, optimize)
-
Structural simplification (decimate, roll up, hierarchy fix)
-
Surface refinement (normals, materials, naming)
-
Scene cleanup and finalization
Changing the order can lead to:
-
Broken hierarchies
-
Shading artifacts
-
Incomplete cleanup
-
Inefficient meshes (duplicate nodes or invalid normals)
Each profile sorts tools to balance quality, performance, and file size for its target platform.
General Tool Priority Order
| Stage | Typical Tools | Purpose |
|---|---|---|
| 1. Merge & Optimize Geometry | AT_MERGE_CLOSE_VERTICES, AT_OPTIMIZE_FACES, AT_OPTIMIZE_VERTICES |
Combine nearby vertices and clean redundant topology. These always appear early to reduce complexity before decimation. |
| 2. Face Orientation & Decimation | AT_REORIENT_FACES_COHERENTLY, AT_DECIMATE_HIGH_QUALITY_MESHES_LOW |
Ensure correct face normals and reduce triangle count while preserving shape. |
| 3. Hierarchy Operations | AT_REMOVE_EMPTY_NODES, AT_ROLLING_UP_HIERARCHY, AT_HIERARCHY_UNIQUIZER |
Flatten and simplify the node structure. Applied after geometry cleanup to avoid reintroducing duplicates. |
| 4. Surface & Material Refinement | AT_GEN_SMOOTH_NORMALS, AT_REMOVE_DUPLICATE_MATERIAL, AT_INSTANTIATE_MESHES_Q0_2 |
Regenerate shading normals and unify materials for rendering consistency. |
| 5. Naming & Final Cleanup | AT_OUTLINER_NAME_CLEANUP, AT_CLEANING_UP_SCENE |
Standardize node names, purge leftovers, and ensure export readiness. |
Examples by Profile Category
Rendering Profiles
-
Rendering1, 2, 3 prioritize surface fidelity → tools like
AT_INSTANTIATE_MESHES_Q0_2andAT_GEN_SMOOTH_NORMALSappear late, after all topology work. -
Early tools (
AT_OPTIMIZE_FACES,AT_OPTIMIZE_VERTICES) prepare for tight tessellation (low tolerance values). -
Hierarchy cleanup (
AT_ROLLING_UP_HIERARCHY,AT_HIERARCHY_UNIQUIZER) ensures renderer-friendly, merged scenes.
Rule of thumb: Rendering profiles finish with normals + cleanup to guarantee visually perfect surfaces.
VR Profiles
-
VR1, VR2 start with geometry merges (
AT_MERGE_CLOSE_VERTICES) before decimation to maintain watertight geometry under aggressive reduction. -
VR3 includes hierarchy roll-ups and uniquizers because desktop VR handles larger files but benefits from a flatter scene tree.
Rule of thumb: Merge and optimize come first; hierarchy and normals come last for smooth performance in headsets.
WebGL Profiles
-
Web1 and Web2 are designed for maximum FPS → they repeat optimization passes before normals generation to minimize polycount and ensure clean edges.
-
Web3 adds hierarchy tools (
AT_ROLLING_UP_HIERARCHY,AT_HIERARCHY_UNIQUIZER) since configurators require unique part references.
Rule of thumb: Web profiles double up geometry passes early; cleanup and material merge always finish the chain.
Typical Sequence Explained
Below is a condensed view of why this order works universally:
| Step | Example Tool | Why It’s Early or Late |
|---|---|---|
| 1️⃣ Merge vertices | AT_MERGE_CLOSE_VERTICES |
Must occur before face optimization or decimation. |
| 2️⃣ Optimize faces/verts | AT_OPTIMIZE_FACES, AT_OPTIMIZE_VERTICES |
Reduces geometry noise before LOD or tessellation. |
| 3️⃣ Reorient faces | AT_REORIENT_FACES_COHERENTLY |
Prevents flipped normals before smoothing. |
| 4️⃣ Decimate | AT_DECIMATE_HIGH_QUALITY_MESHES_LOW |
Simplifies mesh now that geometry is stable. |
| 5️⃣ Remove empties | AT_REMOVE_EMPTY_NODES |
Cleans up hierarchy after mesh edits. |
| 6️⃣ Roll-up hierarchy | AT_ROLLING_UP_HIERARCHY |
Consolidates structure; should not happen before merges. |
| 7️⃣ Generate normals | AT_GEN_SMOOTH_NORMALS |
Must come after decimation to reflect final topology. |
| 8️⃣ Cleanup | AT_OUTLINER_NAME_CLEANUP, AT_REMOVE_DUPLICATE_MATERIAL, AT_CLEANING_UP_SCENE |
Always last for a valid export state. |
Best Practices
-
Always preserve the existing order when editing or creating profiles.
Each tool’s result feeds the next stage. -
If adding custom tools, insert them after geometry cleanup but before normals generation unless specified otherwise.
-
Avoid placing decimation or normals earlier — it can cause shading errors or broken meshes.
-
Profiles can repeat certain tools (like
AT_OPTIMIZE_FACES) intentionally to perform incremental cleanup after major topology changes.
Summary
The order of tools defines the recipe for conversion.
Think of it as a structured build pipeline:
“Mesh preparation → Hierarchy simplification → Surface refinement → Final export.”
By maintaining this sequence, Meshmatic ensures:
-
Optimal triangle count
-
Correct orientation and shading
-
Clean hierarchies
-
Error-free outputs across all export formats (GLB, USD, FBX, etc.)
