Getting Started
From zero to a running MeshCraft editor in minutes.
Prerequisites
Compiler
MeshCraft requires a C++23-capable compiler:
| Compiler | Minimum Version |
|---|---|
| GCC | 13+ |
| Clang | 16+ |
| MSVC | 2022 (17.6+) |
Build Tools
- CMake 3.21 or newer
- Ninja (recommended) or GNU Make
- Git (for cloning sibling repositories)
- Python 3 (for running the glTF test suite — optional)
System Libraries (Linux)
sudo apt install libgles2-mesa-dev libgl-dev libsdl3-devThe exact packages depend on how CNA resolves SDL3 and OpenGL. SDL3 may also be fetched and built by CNA's own CMakeLists.txt.
Cloning the Repositories
MeshCraft depends on three sibling repositories that must exist next to the mesh-craft directory:
mkdir openeggbert && cd openeggbert
git clone https://github.com/openeggbert/cna
git clone https://github.com/openeggbert/sharp-runtime
git clone https://github.com/openeggbert/nova-3d
git clone https://github.com/openeggbert/mesh-craft
ls
# cna sharp-runtime nova-3d mesh-craftCMakeLists.txt uses add_subdirectory(../cna CNA_dep). If the sibling repos are not at the expected relative paths, the build will fail immediately with a CMake error.
Configuring and Building
cd mesh-craft
# Configure with the default EasyGL backend (Linux desktop)
cmake -S . -B cmake-build-debug \
-DCMAKE_BUILD_TYPE=Debug \
-DMESH_CRAFT_GRAPHICS_BACKEND=EASYGL
# Build (all CPU cores)
cmake --build cmake-build-debug --target MeshCraft -- -j$(nproc)The first build downloads ImGui, Manifold, and tinyobjloader via CMake's FetchContent. This requires internet access. Subsequent builds use the cached downloads.
Running the Editor
# Open an empty new scene
./cmake-build-debug/MeshCraft
# Open an existing test scene
./cmake-build-debug/MeshCraft test/house.mc3.xml
# Auto-screenshot mode (exits after ~2 s — useful for CI)
./cmake-build-debug/MeshCraft test/house.mc3.xml --screenshot /tmp/editor.ppmKeyboard Shortcuts
| Shortcut | Action |
|---|---|
Ctrl+N | New scene |
Ctrl+O | Open file (in-editor dialog) |
Ctrl+S | Save |
Ctrl+Shift+S | Save As |
Ctrl+E | Export to GLB (via mc3togltf) |
Ctrl+Z | Undo |
Ctrl+Y | Redo |
Ctrl+D | Duplicate selection |
Ctrl+A | Select all objects (if nothing selected) / select all children in group |
Ctrl+G | Group selected objects |
Ctrl+Shift+G | Ungroup selected group |
Ctrl+X / C / V | Cut / Copy / Paste |
Delete | Delete selected objects |
Q | Select tool (no gizmo) |
G | Move (Translate) gizmo |
R | Rotate gizmo |
S | Scale gizmo |
F | Focus camera on selection (or reset view if nothing selected) |
F1 | Add Box |
F2 | Add Sphere |
F3 | Add Cylinder |
F4 | Add Cone |
F5 | Add Plane |
F11 | Save screenshot to screenshot.ppm |
Ctrl+T | Toggle timeline panel |
Space | Play/pause animation (when timeline is open) |
Alt+W | Toggle edge wireframe overlay |
Arrow keys | Nudge selected object ±0.1 units on X/Y axis |
Page Up / Page Down | Nudge selected object ±0.1 units on Z axis |
Camera Controls
| Input | Action |
|---|---|
| Middle-mouse drag | Orbit |
| Right-mouse drag | Pan |
| Scroll wheel | Zoom in/out |
F | Focus on selection (reset view if nothing selected) |
| Numpad 1 | Front view (yaw=0°, pitch=0°) |
| Numpad 3 | Right view (yaw=90°, pitch=0°) |
| Numpad 5 | Back view (yaw=180°, pitch=0°) |
| Numpad 7 | Top view (yaw=0°, pitch≈84°) |
| Numpad 9 | Bottom view (yaw=0°, pitch≈−84°) |
Building the mc3togltf Converter
The mc3togltf converter is a standalone binary required for File → Export GLB. It has its own CMake build:
cmake -S mc3togltf -B mc3togltf/build -DCMAKE_BUILD_TYPE=Release
cmake --build mc3togltf/build --parallel
# Test conversion
./mc3togltf/build/mc3togltf test/house.mc3.xml test/house.glbRunning the Tests
ctest --test-dir cmake-build-debug -VThis runs two test suites:
- smoke_test — launches the editor with
test/house.mc3.xml, takes a screenshot, and verifies the file is ≥ 1 MB. - mc3_roundtrip — 114 XML round-trip checks covering all MC3 field types and animation data.
If the smoke test fails with a display error, set DISPLAY=:0 or use a virtual framebuffer (Xvfb) for headless CI environments.