mc3togltf — Mesh Craft Docs

Purpose

mc3togltf is a standalone command-line binary — separate from the editor — that takes an MC3 XML scene as input and writes a glTF 2.0 file (JSON + external .bin) or a GLB (self-contained binary). It is required for the editor's File → Export GLB command (Ctrl+E).

Usage

# Export to GLB (binary, self-contained)
./mc3togltf/build/mc3togltf test/house.mc3.xml test/house.glb

# Export to glTF JSON (+ external .bin)
./mc3togltf/build/mc3togltf test/house.mc3.xml test/house.gltf

# Omit output path → same name as input, .gltf extension
./mc3togltf/build/mc3togltf test/house.mc3.xml

Building

cmake -S mc3togltf -B mc3togltf/build -DCMAKE_BUILD_TYPE=Release
cmake --build mc3togltf/build --parallel

The converter has no dependency on CNA, ImGui, Manifold, or any graphics library. It only requires a C++17 compiler and tinyxml2 (bundled via the mc3 include path).

Key Source Files

File	Role
`src/main.cpp`	CLI entry point: parse args, call `Mc3XmlParser`, call `GltfExporter`, write output.
`src/Mc3XmlParser.hpp/.cpp`	Local copy of the MC3 XML parser. Converts XML → in-memory MC3 document struct.
`src/GltfExporter.hpp/.cpp`	Converts an MC3 document to glTF JSON or GLB. Handles geometry, materials, textures, and animations.
`src/MeshBuilder.hpp/.cpp`	Tessellates MC3 objects (primitives, extrusions, groups) into triangle meshes for glTF accessors.
`src/MathUtils.hpp`	Inline math: Euler → quaternion, matrix operations.
`test/gltf_test.py`	Python test suite: 38 assertions on the output glTF/GLB JSON.

Export Pipeline

.mc3.xml
  │
  ▼ Mc3XmlParser::parse()
MC3 Document (in-memory)
  │
  ▼ GltfExporter::exportDocument()
  │
  ├── For each object: MeshBuilder → triangulated geometry
  │     → glTF mesh / primitive / accessor / bufferView
  │
  ├── For each material → glTF material (PBR metallic-roughness)
  │
  ├── For each texture → glTF image + sampler + texture
  │
  ├── For each Mc3Action → glTF animation
  │     channels: position (VEC3), rotation (VEC4 quaternion), scale (VEC3)
  │     cubic bezier → sampled at 30 fps → LINEAR glTF interpolation
  │
  └── Write JSON header + binary buffer
        .gltf → JSON file + separate .bin
        .glb  → single binary envelope (JSON chunk + BIN chunk)

Animation Export Notes

Position, rotation, and scale channels are exported as glTF animations[].
Individual per-component MC3 channels (e.g., position.y only) are merged into VEC3/VEC4 at export time; non-animated components fall back to the object's base transform value.
Cubic Bézier channels are densely sampled at 30 fps and exported as LINEAR glTF interpolation (glTF has no native cubic Bézier).
The visible, deform.*, and material.* properties have no glTF equivalent and are silently skipped during export.

Test Suite

mc3togltf/test/gltf_test.py contains 38 Python assertions. Registered as a CTest test when both Python 3 and the mc3togltf binary are available:

# Run via CTest (from the main cmake-build-debug)
ctest --test-dir cmake-build-debug -V -R mc3togltf_gltf

# Run directly
python3 mc3togltf/test/gltf_test.py \
    mc3togltf/build/mc3togltf \
    test/animation_test.mc3.xml \
    test/house.mc3.xml

Limitations

📋

CSG boolean geometry is not evaluated during export — the individual child primitives are exported as separate meshes. True CSG export would require linking Manifold.
External OBJ meshes (<mesh src="…">) are not included in the glTF output — only the MC3 primitive/extrude geometry.
UV mapping overrides from <uv_mapping> are not yet applied during mesh tessellation.

MC3 Library Editor