Docs/Modules/MC3 Library

MC3 Library (mc3/)

Pure-C++ scene data model, XML parser, XML writer, and animation system. No graphics dependency.

Purpose

The mc3/ directory builds as a static library (libMc3.a) that is shared between the MeshCraft editor and the mc3togltf converter. It has no dependency on CNA, OpenGL, SDL, or ImGui — it is a pure data + I/O library.

Key Files

FileRole
include/MeshCraft/Mc3/Mc3Document.hppTop-level scene container. Holds all objects, materials, textures, lights, cameras, definitions, and actions.
include/MeshCraft/Mc3/Mc3Object.hppSingle scene graph node. Has ObjectType enum and optional primitive/extrude/CSG data + children.
include/MeshCraft/Mc3/Mc3Transform.hppPosition / rotation (XYZ Euler, degrees) / scale / pivot.
include/MeshCraft/Mc3/Mc3Primitive.hppShape parameters for box, sphere, cylinder, cone, plane.
include/MeshCraft/Mc3/Mc3Extrude.hppCross-section and path types for extrude objects.
include/MeshCraft/Mc3/Mc3Material.hppPBR material: baseColor, roughness, metallic, emissive, texture slots.
include/MeshCraft/Mc3/Mc3Texture.hppTexture definition: uri, wrap modes, filter, color space.
include/MeshCraft/Mc3/Mc3Light.hppAmbient / Directional / Point / Spot light types.
include/MeshCraft/Mc3/Mc3Camera.hppPerspective / orthographic camera with position, target, FOV.
include/MeshCraft/Mc3/Mc3Animation.hppAction / Channel / Keyframe types, interpolation modes, evaluateChannel().
src/Mc3XmlParser.hpp/.cppReads .mc3.xml into the data model using tinyxml2.
src/Mc3XmlWriter.hpp/.cppSerializes the data model back to XML (used by Save/Save As).
src/MathUtils.hppInline helpers: degree/radian conversion, vector normalization.
mc3.xsdXML Schema Definition for the MC3 format v0.3.
MC3_FORMAT.mdAuthoritative format specification (version 0.3).
test/roundtrip_test.cpp114 assertions that verify every field round-trips through XML without loss.

Data Model Hierarchy

Mc3Document
├── version: string  (e.g. "0.3")
├── model: string    (scene name)
├── unit: string     (e.g. "meter")
├── sourcePath: filesystem::path
│
├── environment: optional<Mc3Environment>
│   └── background (color, texture), fog (mode, color, start, end, density)
│
├── lights: vector<Mc3Light>
│   └── type (Ambient/Directional/Point/Spot), name, color, brightness, ...
│
├── cameras: vector<Mc3Camera>
│   └── type, name, position, target, fov, near, far, ...
│
├── textures: map<string, Mc3Texture>
│   └── uri, wrapU, wrapV, filter, colorSpace, mipMaps
│
├── materials: map<string, Mc3Material>
│   └── baseColor[4], roughness, metallic, emissive[3], texture slots, alphaMode
│
├── definitions: map<string, shared_ptr<Mc3Object>>
│
├── objects: vector<shared_ptr<Mc3Object>>
│   └── (scene graph roots)
│
└── actions: map<string, Mc3Action>
    └── duration, loop, channels (target + property + keyframes)

Mc3Object
├── type: ObjectType   (Box, Sphere, Cylinder, Cone, Plane, Mesh,
│                       Extrude, Group, Instance, Union,
│                       Difference, Intersection, Area)
├── name, id, material (IDREF)
├── transform: Mc3Transform  (position, rotation[XYZ Euler °], scale, pivot)
├── deform: optional<Mc3Deform>
├── primitive: optional<Mc3Primitive>
├── extrude:   optional<Mc3Extrude>
├── csgOperation: optional<Mc3CsgOperation>
├── isCutter: bool
├── definition: string  (type == Instance)
├── meshSource: string  (type == Mesh)
├── visible, collision, tags
└── children: vector<shared_ptr<Mc3Object>>

XML Parsing

Mc3XmlParser uses tinyxml2. It parses the document top-down:

  1. Reads root <mc3> attributes (version, model, unit, rotation_units, euler_order)
  2. Reads each top-level section: <environment>, <lights>, <cameras>, <textures>, <materials>, <definitions>, <objects>, <actions>
  3. Each object element is parsed recursively, building the child tree
  4. Sets Mc3Document.sourcePath to the directory of the XML file (used for resolving relative texture/mesh paths)
ℹ️

The mc3togltf/ converter has its own copy of the XML parser (mc3togltf/src/Mc3XmlParser.*) rather than linking the mc3/ library. This keeps the converter self-contained. If you change the MC3 format, update both parsers.

Animation System

Defined in Mc3Animation.hpp:

See Animation API Reference for the full list of animatable properties.

Known Limitations

📋
Areas still needing work
  • UV mapping (<uv_mapping>) is parsed but not yet fully wired into the editor UI (noted as TODO in Mc3Object.hpp).
  • Object states (<states>) are defined in the format spec but not yet in the C++ data model.
  • Action triggers (<triggers>) are spec'd but not implemented.
  • The Mc3Document::version field defaults to "0.1" even though the active format is v0.3 — needs updating.

Related Pages