Getting Started
From zero to a running MeshCraft editor in minutes.
Prerequisites
Sibling Repositories
These two repos must exist next to mesh-craft/:
- cna — XNA-like C++ runtime (SDL3 + OpenGL ES 3.2)
- sharp-runtime — C++ math and system layer
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 two 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/mesh-craft
ls
# cna sharp-runtime 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
cmake -S . -B cmake-build-debug
# Build everything: editor + mc3togltf + mc3tomcb (all CPU cores)
ninja -C cmake-build-debugThe first build downloads ImGui, Manifold, and tinyobjloader via CMake's FetchContent. This requires internet access. Subsequent builds use the cached downloads.
If you add new .cpp files after the initial configure, run cmake -S . -B cmake-build-debug -DFETCHCONTENT_UPDATES_DISCONNECTED=ON to re-scan the source tree.
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
File Operations
| 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) |
F11 | Save screenshot to screenshot.ppm |
Edit Operations
| Shortcut | Action |
|---|---|
Ctrl+Z | Undo (up to 20 steps) |
Ctrl+Y | Redo |
Ctrl+D | Duplicate selection |
Ctrl+A | Select all objects (or 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 |
Ctrl+Up / Down | Reorder selected object among its siblings in hierarchy |
Ctrl+Shift+P | Copy properties from active object to all selected |
P | Select parent of currently selected object |
Transform Tools
| Shortcut | Action |
|---|---|
Q | Select tool (no gizmo) |
G | Move (Translate) gizmo |
R | Rotate gizmo |
S | Scale gizmo |
Shift (hold while dragging) | Vertex snap — snap position to nearest vertex of another object |
Ctrl (hold during rotate) | Angle snap — lock rotation to 15°/45°/90° increments |
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 |
Viewport
| Shortcut | Action |
|---|---|
F | Focus camera on selection (reset view if nothing selected) |
Alt+W | Toggle full-scene wireframe overlay |
B | Toggle bounding box display around selected objects |
| Viewport overlay buttons | Click Front / Top / Right / Perspective icons to snap to preset camera views |
| Ortho/Persp button (toolbar) | Toggle orthographic ↔ perspective projection |
| World/Local button (toolbar) | Toggle gizmo between world-space and local-space axes |
Add Primitives
| Shortcut | Action |
|---|---|
F1 | Add Box |
F2 | Add Sphere |
F3 | Add Cylinder |
F4 | Add Cone |
F5 | Add Plane |
| Menu: Add → Primitive | Torus, Capsule, Disk, Grid, Ico-sphere, Extrude, CSG Union/Difference/Intersection |
Animation & Tools
| Shortcut | Action |
|---|---|
Ctrl+T | Toggle timeline panel |
Space | Play / pause animation |
K | Insert keyframe for selected object at current time |
Ctrl+P | Open Command Palette (search objects and commands) |
M | Activate Measurement Tool (click two points to show distance) |
F5 | Enter / exit first-person Walk Mode |
Walk Mode Controls (while active)
| Input | Action |
|---|---|
W / A / S / D or Arrow keys | Move forward / left / back / right |
| Mouse move | Look around (yaw + pitch) |
Ctrl | Jump |
Esc or "Exit Walk Mode" HUD button | Return to editor |
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°) |
CLI Tools
Both converter tools are built as part of the top-level build (ninja -C cmake-build-debug) and land in cmake-build-debug/:
mc3togltf — Export to glTF/GLB
# Export scene to GLB
./cmake-build-debug/mc3togltf/mc3togltf test/house.mc3.xml /tmp/house.glb
# Export with approximate CSG (children exported as separate meshes)
./cmake-build-debug/mc3togltf/mc3togltf --allow-approximate-csg scene.mc3.xml out.glbBy default, any scene containing CSG nodes (<union>, <difference>, <intersection>) causes mc3togltf to exit with an error. Pass --allow-approximate-csg to export children as separate meshes instead (geometrically incorrect but useful for review).
mc3tomcb — Convert to/from MCB Binary
MCB is a compact binary format (.mcb) for fast runtime loading. The converter works in both directions:
# XML → MCB (for runtime use)
./cmake-build-debug/mc3tomcb/mc3tomcb scene.mc3.xml scene.mcb
# MCB → XML (to inspect or edit a binary scene)
./cmake-build-debug/mc3tomcb/mc3tomcb scene.mcb scene.mc3.xmlRunning 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.