Mesh Craft — Documentation

ℹ️

Status

MeshCraft is under active development. ~72 of 100 planned tasks are done. Working features include all primitive shapes (Box, Sphere, Cylinder, Cone, Plane, Torus, Capsule, Disk, Grid, Ico-sphere), extrusion (5 path types, 5 cross-section types), CSG booleans, PBR materials and textures, keyframe animation timeline (with material/deform channels), named layers, first-person walk mode, proportional editing, scatter along curve, procedural LOD, fog rendering, bloom post-process pipeline, and the MCB binary format. The project builds cleanly with all CTests passing.

What is Mesh Craft?

Mesh Craft is a C++23 desktop 3D scene editor for creating and editing models in the MC3 format — a custom XML-based scene description format used by the OpenEggbert project family.

Instead of working with raw triangle meshes, Mesh Craft lets you build scenes from constructive objects: primitive shapes, extrusions, CSG booleans, reusable definitions, hierarchical groups, lights, cameras, and keyframe animations. These are stored in human-readable .mc3.xml files and can be exported to glTF 2.0 / GLB for use in game engines and real-time applications.

The project is inspired by Ray Dream Studio and Google SketchUp.

Main Features

📦

Primitive Shapes

Box, Sphere, Cylinder, Cone, Plane, Mesh, plus Torus, Capsule, Disk, Grid, and Ico-sphere — all editable with per-shape properties.

🔩

Extrude

Sweep 2D cross-sections (rect, circle, polygon, star, custom) along 5 path types: line, arc, helix, polyline, Bézier.

⚗️

CSG Booleans

Union, Difference, Intersection — evaluated using the Manifold v3 library for real boolean mesh geometry.

🎨

PBR Materials

Full PBR material editor: base color, metallic, roughness, emissive, normal scale, alpha modes, and 5 texture slots with UV mapping control.

🎞️

Keyframe Animation

Timeline editor with Step, Linear, and Cubic Bézier interpolation. Animates position, rotation, scale, material properties, and deforms. Exports to glTF animations.

🔘

Interactive Actions

State machine system for runtime interactivity: doors that open, levers that toggle, triggered sequences and parallels. Driven by on_load, interact, on_collision, on_signal, and more.

📤

glTF/GLB Export

Standalone mc3togltf converter outputs glTF 2.0 JSON or self-contained GLB, including animation tracks and embedded textures.

🧩

Definitions & Instances

Define reusable object templates and place multiple instances. Instances can override transform and material per-instance. Convert selected objects into a definition in one click.

🚶

First-Person Walk Mode

Press F5 to enter first-person exploration of your scene. WASD to move, mouse to look, Ctrl to jump. Gravity included. Press Esc or the HUD button to exit.

📦

MCB Binary Format

Compact binary runtime format (.mcb) for fast scene loading. The mc3tomcb CLI converts .mc3.xml ↔ .mcb in both directions.

🌐

Web/WASM Build

Emscripten build produces a browser-ready MeshCraft.html with IDBFS persistent storage.

🔁

Undo/Redo

20-step deep-copy snapshot stack covering all edit operations: add, delete, transform, duplicate, paste, group, ungroup.

🖱️

Transform Gizmo

Move / Rotate / Scale gizmo with Local/World space toggle, live delta overlay while dragging, vertex snapping, and angle snapping (15°/45°/90°).

📐

Editor Tools

Multi-object selection with mixed-value properties, measurement tool, alignment commands, command palette, viewport camera presets, and bounding box display.

Supported Platforms

Platform	Backend	Status
Linux	EasyGL (OpenGL ES 3.2)	Working
macOS	EasyGL or SDL_RENDERER	Planned
Windows	EasyGL / BGFX / Vulkan	Planned
Android	SDL_RENDERER	Planned
Browser (WASM)	Emscripten + WebGL 2	Working

Key Dependencies

Dependency	Role	Source
CNA	XNA-like C++ runtime: windowing, input, audio, graphics abstraction (SDL3 + OpenGL ES 3.2)	Sibling repo `../cna`
sharp-runtime	C++ System layer (math: Matrix, Vector3, …) used by CNA	Sibling repo `../sharp-runtime`
Dear ImGui v1.91.6	Immediate-mode UI for all editor panels	FetchContent from GitHub
Manifold v3	CSG boolean mesh evaluation	FetchContent from GitHub
tinyobjloader v2	OBJ mesh loading for viewport preview	FetchContent from GitHub
tinyxml2	XML parsing (bundled via sharp-runtime)	Bundled

Repository Structure at a Glance

mesh-craft/
├── src/MeshCraft/          Main editor application (C++)
├── include/MeshCraft/      Public headers
├── mc3/                    Pure-C++ MC3 format library (sublibrary)
├── mcb/                    MCB binary format library (sublibrary)
├── mc3togltf/              CLI converter: MC3 → glTF/GLB
├── mc3tomcb/               CLI converter: MC3 ↔ MCB
├── Mc3Format/              Format specification markdown docs
├── test/                   Test scenes (.mc3.xml) and smoke test
├── cmake/                  Platform-specific CMake helpers
└── CMakeLists.txt          Top-level build script

Quick Start

# Prerequisites: CMake 3.21+, GCC 13+ or Clang 16+, sibling repos cna / sharp-runtime

# Configure (first time)
cmake -S . -B cmake-build-debug

# Build everything (editor + mc3togltf + mc3tomcb)
ninja -C cmake-build-debug

# Run with a test scene
./cmake-build-debug/MeshCraft test/house.mc3.xml

For full setup instructions, see Getting Started and Build & Run.

Getting Started