Contents15 sections
meshfx runs on the hosted API: try it in the Playground.
Use the meshfx schema to set the source hierarchy, repair limits and LOD budgets. See the articulation guide for per-part limits and controller output.
[meta]
Names the model.
| Key | Values | Default | Meaning |
|---|---|---|---|
name | string | "" | Model name; used in every file name. Empty means the spec file's name. |
seed | 0 to 4294967295 | 0 | Seed for every random choice. |
notes | string | "" | Free text. |
[source]
The model to clean and its textures.
| Key | Values | Default | Meaning |
|---|---|---|---|
file | string | "" | The model: .glb, .gltf, .obj, .stl or .ply, beside or under the spec file. Missing is SOURCE_MISSING. |
base_colour | string | "" | An image that replaces the base colour map. Only for a model with one material. |
normal | string | "" | An image that replaces the normal map. Only for a model with one material. |
metallic | string | "" | A grey image that replaces the metal channel. Only for a model with one material. |
roughness | string | "" | A grey image that replaces the roughness channel. Only for a model with one material. |
occlusion | string | "" | A grey image that replaces the occlusion map. Only for a model with one material. |
emissive | string | "" | An image that replaces the emissive map. Only for a model with one material. |
normal_y | +y, -y | "+y" | Which way green points in the source's normal maps. -y maps are turned to +y. |
hierarchy | merge, keep, tree | "merge" | merge: the whole file becomes one object. keep: each top-level node stays a separate object. tree: every node stays, with its name, its parent and its own place (rotation included); a node that draws a mesh keeps its own part, and an empty node stays as a pivot or socket where it sits in the tree. |
kind | auto, authored, scan, generator, generated | "auto" | Source provenance for repair defaults. auto uses UVs, assigned materials and normals. generated requires units.size_m and enables cleanup and pose defaults. |
skin | keep, rest_pose, refuse | "keep" | For a skinned or animated model, choose keep to carry joint weights, skins and joint clips through every LOD, rest_pose to freeze it at rest without skin or clips, or refuse. |
clean_names | bool | true | Replaces generator names such as Object_0 with names made from meta.name. |
scene | -1 to 1000 | -1 | Which scene of a glTF file. -1 is the one the file opens on. |
split | none, components, materials | "none" | Splits each object into objects of its own by connected part or by material, each its own node. |
min_part_share | 0 to 0.5 | 0.01 | A split part smaller than this share of its object's area joins its nearest neighbour. |
[units]
Size, up axis and origin.
| Key | Values | Default | Meaning |
|---|---|---|---|
source | auto, m, cm, mm, in, ft | "auto" | The unit the file is in. auto: metres for every format read so far. |
size_m | 0 to 10000 m | 0 | Scales the model so size_axis measures this. 0 keeps the size. |
size_axis | largest, height | "largest" | What size_m measures. |
up | auto, y, z | "auto" | The source's up axis. auto: Y for every format read so far. |
pivot | bottom_centre, centre, keep, bottom_back, back_centre | "bottom_centre" | Where the origin goes. The back is the -Z face, once the model faces +Z. |
pivot_offset_m | -10000 to 10000 m | [0,0,0] | Added to the pivot after pivot is applied. |
[pose]
Geometry-only humanoid pose checks.
| Key | Values | Default | Meaning |
|---|---|---|---|
check | off, auto, on | "off" | auto checks classified humanoids; on also reports missing evidence. |
expect | a_or_t, a_pose, t_pose | "a_or_t" | Accepted arm pose. |
[repair]
Fixes to the surface (meshfx.md 5.3).
| Key | Values | Default | Meaning |
|---|---|---|---|
enabled | bool | true | Off skips repair. The faults are still counted and warned. |
weld_m | -1 to 1 m | -1 | Vertices closer than this become one. -1 preserves authored vertices and otherwise picks 0.00001 of the diagonal. 0 welds only equal positions. |
fix_winding | bool or auto | "auto" | Makes each part face outward. auto preserves authored winding. |
resolve_crossings | bool or auto | "auto" | Cuts intersecting facets. Opt-in for broken or scanned input: auto leaves crossings, unless remesh is always. |
normals | auto, keep, recompute | "auto" | auto recomputes only normals that are missing or point against their face. |
smooth_angle_deg | 0 to 180 deg | 60 | Recomputed normals are smooth across edges flatter than this. |
fill_holes | auto, none, small, all | "auto" | small fills only loops that pass the hole test; all also fills larger loops of solid parts and is opt-in. auto: none for authored input, small otherwise. |
max_hole_share | 0 to 1 | 0.02 | A small hole's patch is at most this share of its part's area. |
floaters | auto, keep, detached | "auto" | auto keeps authored components and otherwise removes specks that pass all three floater tests. |
floater_size | 0 to 0.5 | 0.02 | The speck is smaller than this share of the diagonal. |
floater_gap | 0 to 1 | 0.05 | It is farther than this share of the diagonal from everything else. |
remesh | never, auto, always | "never" | Rebuilds solid parts as one closed surface. |
remesh_voxel | 0 to 0.1 | 0 | Cell size of the rebuild, as a share of the diagonal. 0 picks 1/512 at final, 1/256 at draft. |
thicken_m | 0 to 10 m | 0 | Above 0, an open sheet is given this thickness and becomes a closed shell. |
max_error | 0 to 0.1 | 0.002 | A repair step that moves the surface farther than this share of the diagonal is undone. |
[retopo]
Stage 9 editing mesh.
| Key | Values | Default | Meaning |
|---|---|---|---|
mode | off, quads, quad_dominant | "off" | An enabled mode requests stage 9. Articulated inputs refuse retopology. |
[simplify]
Triangle reduction of LOD0 (build stage 3).
| Key | Values | Default | Meaning |
|---|---|---|---|
triangles | 0 to 10000000 | 10000 | Triangle budget of LOD0, the whole asset. 0 keeps every triangle. |
max_error | 0 to 0.5 | 0.02 | Warn when the written level exceeds this surface error (share of the diagonal). |
protect | borders, material_edges, hard_edges, uv_seams, colour_edges | ["borders","material_edges"] | Edges that must survive. |
forbid | open_edges, non_manifold_edges, crossings | ["open_edges"] | Faults a level may not add beyond the repaired model's. Others are counted in each level's metrics. |
attribute_weight | 0 to 4 | 0.5 | How much normals, UVs and colour count against position. |
[lod]
Detail levels (build stage 3).
| Key | Values | Default | Meaning |
|---|---|---|---|
count | 0 to 8 | 0 | Detail levels, LOD0 included. 0 takes the target's default. |
ratio | 0.05 to 0.9 | 0.5 | Each level's triangles as a share of the level before. |
triangles | list of integers | [] | Explicit budgets for LOD1 onward, each 4 to 10000000, falling. |
max_error | 0 to 0.5 | 0.08 | Error limit for the last level (share of the diagonal). |
pixel_error | 0.1 to 16 px | 1 | A level is used from the distance where its error is this many pixels. |
[uv]
UV sets.
| Key | Values | Default | Meaning |
|---|---|---|---|
mode | auto, keep, unwrap, repack | "auto" | keep: the source UVs. unwrap: new charts. repack: the source charts packed again. auto: keep when they pass the checks of LOD0 and no materials are merged, repack when they pass and the atlas merges materials, else unwrap. |
padding_px | 0 to 64 px | 4 | Empty texels between charts at textures.size_px. |
iterations | 1 to 8 | 2 | Chart-growing passes. |
lightmap | bool | false | Also writes a second UV set with no overlap, for baked lighting. |
time_limit_s | 1 to 3600 s | 120 | Unwrapping stops after this and the plain method is used. |
[textures]
Baked texture set.
| Key | Values | Default | Meaning |
|---|---|---|---|
size_px | 64 to 8192 px | 2048 | Edge of each baked texture at final. Draft halves it. |
atlas | auto, single, per_material | "auto" | auto keeps usable authored charts and merges materials when an unwrap is needed. single merges materials per alpha kind. |
maps | base_colour, normal, metallic_roughness, occlusion, emissive, curvature, mask | ["base_colour","normal","metallic_roughness","occlusion","emissive"] | Maps to write. A map the source lacks is left out, except normal with bake.source_detail. curvature and mask are written beside the model and named in layout.json. |
ktx2_quality | high, small | "high" | high: UASTC. small: ETC1S for colour maps. |
colour | texture, vertex, flat, none | "texture" | Where base colour goes. vertex: baked to vertex colour, no colour map. flat: one colour a material, the mean over its area. none: white. Any value but texture takes the place of bake.vertex_colour. |
mask_r | zero, one, occlusion, roughness, metallic, edge_wear, cavity | "occlusion" | What the mask map's red channel holds. edge_wear and cavity are the halves of the curvature map. |
mask_g | zero, one, occlusion, roughness, metallic, edge_wear, cavity | "roughness" | What the mask map's green channel holds. |
mask_b | zero, one, occlusion, roughness, metallic, edge_wear, cavity | "metallic" | What the mask map's blue channel holds. |
mask_a | zero, one, occlusion, roughness, metallic, edge_wear, cavity | "one" | What the mask map's alpha channel holds. |
texel_density | 0 to 4096 px/m | 0 | Above 0 it picks size_px from the surface area (at most size_px), so props of different sizes match. |
delight | off, auto, on | "off" | Takes shading painted into base colour back out. auto acts only when the colour's brightness follows the shading predicted from normals and occlusion more closely than delight_threshold. |
delight_threshold | 0 to 1 | 0.5 | The correlation delight = auto needs. |
pbr_check | off, report, fix | "report" | report measures the share of texels outside albedo_range and with metallic between 0 and 1. fix clamps colour and snaps metallic. |
albedo_range | 0 to 255 sRGB | [30,240] | The base colour range pbr_check uses. |
metallic_snap | 0 to 0.5 | 0.1 | With pbr_check = fix, metallic within this of 0 or 1 becomes 0 or 1. |
[bake]
Texture bake from the source.
| Key | Values | Default | Meaning |
|---|---|---|---|
source_detail | bool | true | The normal map carries the source's shape that reduction removed. |
max_distance | 0.0001 to 0.5 | 0.02 | How far from the new surface the source is searched (share of the diagonal). |
samples | 1 to 16 | 4 | Samples a texel at final. Draft uses 1. |
occlusion | off, source, compute | "source" | source carries the source's occlusion map; compute traces it. |
occlusion_rays | 8 to 1024 | 64 | Rays a texel for compute. |
vertex_colour | to_texture, keep, drop | "to_texture" | to_texture multiplies vertex colour into the base colour map. |
dilate_px | 0 to 64 px | 16 | How far each chart's colour is spread into the gap around it. |
[export]
Output folders, one a target.
| Key | Values | Default | Meaning |
|---|---|---|---|
targets | godot, unity, unreal, roblox, threejs | ["godot"] | One output folder each. A target whose build stage is not in this program fails with STAGE_FAILED; `targets` in the schema output says which are built. |
compression | target, none, meshopt | "target" | Mesh compression in a GLB. none: no compression and no KHR_mesh_quantization, every attribute plain floats. |
lod_layout | target, nodes, files | "target" | LODs as nodes of one file, or one file a level. |
textures_in | target, embedded, beside | "target" | Textures inside the model file or as files beside it. |
forward | target, +z, -z, +x, -x | "target" | Which way the front points in the written file. target is the target's rule. |
name_style | target, keep, lower_snake | "target" | Names of nodes, meshes and materials in the file: the target's rule, as they are, or lower_snake. |
[budget]
Limits a bake must meet; a missed one fails it with BUDGET_EXCEEDED (exit 5), files still written.
| Key | Values | Default | Meaning |
|---|---|---|---|
max_triangles | 0 to 10000000 | 0 | Most triangles in LOD0, the whole asset; LOD0 aims at it. 0 sets no limit, here and below. |
max_materials | 0 to 64 | 0 | Most materials. 1 also makes textures.atlas single and merges opaque, cut-out and blended surfaces into one material. |
max_texture_px | 0 to 8192 px | 0 | Caps textures.size_px and the edge of every texture written. |
max_bytes | integer | Largest output folder a target. Textures are halved until it fits or they reach 64 px. | |
fail_on | NON_MANIFOLD_EDGES, FLIPPED_NORMALS, OPEN_HOLES, DUPLICATE_VERTICES, ZERO_AREA_FACES, BAD_SCALE, POSE_NOT_READY, WRONG_PIVOT, UV_OVERLAP, UV_OUT_OF_RANGE, UV_STRETCH_HIGH, UV_FALLBACK, TEXEL_DENSITY_LOW, SELF_INTERSECTIONS, HIDDEN_GEOMETRY, JOINT_PART_FLOOR, JOINT_NORMAL_NEEDS_UV, FLOATERS_REMOVED, REPAIR_REJECTED, NOT_WATERTIGHT, ZERO_THICKNESS, LOD_BUDGET_MISSED, SILHOUETTE_CHANGED, PART_LOST, LOD_FAULTS_ADDED, BAKE_MISSES, BAKE_MISMATCH, BAKED_LIGHTING, ALBEDO_OUT_OF_RANGE, TEXTURE_DOWNSIZED, MATERIAL_SIMPLIFIED, ATTRIBUTE_DROPPED, ANIMATION_DROPPED, COLLISION_LOOSE, COLLISION_CAPPED, OCCLUDER_SKIPPED, STAGE_NOT_BUILT | [] | Warning codes: a bake that ends with one of them fails. |
[preview]
The preview images.
| Key | Values | Default | Meaning |
|---|---|---|---|
thumbnail_px | 64 to 1024 px | 256 | Edge of preview_thumb.png: LOD0 from the corner on a transparent background. |
Questions
How does source.hierarchy control objects in a meshfx spec?
Set merge to combine objects, keep to preserve top level nodes or tree to keep every node, parent and pivot.
What happens when source.skin is set to keep on an animated model?
meshfx carries joint weights, skins and joint clips through every level of detail instead of freezing the model at rest.
When is units.size_m required in a meshfx spec?
You must set units.size_m when source.kind is set to generated so meshfx can scale the model and run cleanup.