Tutorial: Export to glTF/GLB
Convert an .mc3.xml scene to a glTF 2.0 JSON or self-contained GLB binary for use in Godot, Unity, Blender, and other engines.
What is mc3togltf?
mc3togltf is a standalone command-line tool included in the MeshCraft repository. It reads an .mc3.xml file and writes a standard glTF 2.0 file (.gltf JSON + separate .bin) or a self-contained GLB binary (.glb).
The tool does not require the editor to be running — it can be used in automated pipelines and CI.
Step 1 — Build mc3togltf
The converter is built alongside the main editor when you use the default CMake target. You can also build only the converter:
cmake -B cmake-build-debug -DCMAKE_BUILD_TYPE=Debug .
cmake --build cmake-build-debug --target mc3togltfThe binary is placed at cmake-build-debug/mc3togltf/mc3togltf.
Step 2 — Run the Conversion
Export as glTF JSON
./cmake-build-debug/mc3togltf/mc3togltf scene.mc3.xml scene.gltfThis produces scene.gltf (JSON) and scene.bin (binary mesh data) in the same directory.
Export as GLB (single file)
./cmake-build-debug/mc3togltf/mc3togltf scene.mc3.xml scene.glbThe output format is determined from the file extension: .gltf → JSON+BIN, .glb → binary container.
Export the test house scene
./cmake-build-debug/mc3togltf/mc3togltf test/house.mc3.xml /tmp/house.glbWhat Gets Exported
| MC3 feature | glTF equivalent | Status |
|---|---|---|
| Box, Sphere, Cylinder, Cone, Plane primitives | mesh with TRIANGLES primitive | Exported |
| Extrude objects | mesh (tessellated geometry) | Exported |
| Group (hierarchy) | node with children | Exported |
| Instance (reference to definition) | Separate node with copied mesh | Exported |
| Transform (position, rotation, scale) | node.translation/rotation/scale | Exported |
| Pivot offset | Baked into node transform | Exported |
| PBR materials (baseColor, roughness, metallic) | material.pbrMetallicRoughness | Exported |
| Texture references | texture + image entries | Exported |
| Position/rotation/scale animation channels | animation samplers + channels | Exported |
| Directional and ambient lights | Not in base glTF — skipped | Skipped |
| CSG objects (union/difference/intersection) | Individual child meshes (not merged) | Partial |
| visible / deform / material.* animation | No glTF equivalent — skipped | Skipped |
Verifying the Export
Open the exported file in any of these free tools:
- Khronos glTF Sample Viewer — browser-based, drag-and-drop
- Blender — File → Import → glTF 2.0
- Godot 4 — import directly into the project assets folder
- VS Code + glTF Tools extension — preview and validate the JSON
Animation Export Notes
Keyframe animations in the <actions> section are exported as glTF animations[]. Some caveats apply:
- Each MC3 action becomes one glTF animation clip.
- Per-component channels (e.g.,
position.yalone) are merged into VEC3 samplers; the other two components default to the object's static transform value. - Cubic Bézier channels are sampled at 30 fps and exported as
LINEARglTF samplers (glTF has no native Bézier interpolation). visible,deform.*, andmaterial.*channels have no glTF equivalent and are silently dropped.
Running the Test Suite
The mc3togltf module has its own CTest suite with 38 assertions that verify round-trip correctness:
cd cmake-build-debug
ctest -R mc3togltf --output-on-failureDuplication note: mc3togltf contains its own local copy of the MC3 XML parser (mc3togltf/src/Mc3XmlParser.cpp) rather than linking against the mc3/ library. This is an architectural decision for standalone deployment. If you extend the MC3 format, you must update both parsers to keep them in sync.
Common Problems
| Problem | Likely Cause | Fix |
|---|---|---|
| Output glTF has no meshes | The scene only contains groups, instances, or unsupported types | Ensure there are primitive or extrude objects in the scene |
| Textures not found in Blender | Texture paths in MC3 are relative to the .mc3.xml file | Keep texture files next to the MC3 file, or use GLB which embeds nothing — embed textures separately |
mc3togltf segfaults on load | Malformed XML or missing required attributes | Validate the MC3 file first by opening it in the editor |
| CSG geometry looks like individual pieces | CSG is not resolved by mc3togltf | Boolean evaluation is planned; workaround: export individual children and merge in Blender |