Docs/Internals

Developer Internals

Deep-dive reference for contributors: how data flows, how rendering works, and how subsystems are implemented.

ℹ️

This section targets contributors and developers who need to modify MeshCraft internals. End users and format consumers should start with Tutorials or the Format Reference.

What This Section Covers

🔄
Data Flow
How a user action moves from UI input through the scene model to disk and back. The lifecycle of an Mc3Document.
🎨
Rendering Pipeline
How SceneRenderer traverses the scene graph, builds GPU meshes, applies transforms, and composites the final viewport image.
⚙️
CSG Engine
How Manifold v3 is integrated, how the mesh cache works, and how the fallback rendering path handles failed boolean evaluations.
↩️
Undo/Redo System
The 20-step deep-copy snapshot stack: what gets copied, when, and the trade-offs of full-document snapshots vs. command patterns.

Key Design Principles

Understanding these principles will make the codebase easier to navigate:

Single source of truth: Mc3Document

All scene state lives in a single Mc3Document instance owned by MeshCraftApplication. There is no secondary "editor model" — the UI panels read directly from and write directly to Mc3Document. The renderer reads the same document every frame. This eliminates synchronisation bugs at the cost of requiring defensive coding around mutations.

Immediate mode UI (Dear ImGui)

All UI panels are rebuilt from scratch every frame by ImGui. There is no retained widget tree. Panel state (expanded nodes, selected tab, etc.) is stored in plain C++ member variables of MeshCraftApplication, not in the document.

Undo = full document snapshot

Rather than a command/inverse-command pattern, every mutation pushes a deep copy of the entire Mc3Document onto the undo stack before making changes. This is simple to implement correctly but has an O(scene size) cost per edit. See Undo/Redo for details.

Caching is per-object-pointer

SceneRenderer caches GPU meshes and CSG results in std::unordered_map keyed by Mc3Object* pointer. The cache is invalidated globally on each undo push (since a new deep-copy creates new pointers). This is safe but means large scenes with many CSG nodes will re-evaluate all CSG on every edit.

CNA game loop

MeshCraftApplication inherits from the CNA framework's Application class. CNA provides the SDL3 window, OpenGL ES 3.2 context (via EasyGL), and the fixed game loop: LoadContent → [BeginDraw → Update → Draw → EndDraw] × ∞. MeshCraft overrides each of these virtual methods.

Important Invariants

⚠️
  • Push to the undo stack before every mutation, never after.
  • Never hold raw pointers to Mc3Object across undo/redo boundaries — the pointer will dangle.
  • All MC3 object names must be unique within a document (required for animation target lookup).
  • The CSG cache is keyed by Mc3Object*. If you copy an object, the copy gets a new address and starts with an empty cache entry.
  • Mc3Document.version defaults to "0.1" in code even though the active format is v0.3. This is a known inconsistency — do not rely on the version string for feature detection.