Mc3Document — Mesh Craft Docs

Header

mc3/include/MeshCraft/Mc3/Mc3Document.hpp

Namespace

MeshCraft::Mc3

Public Fields

Field	Type	Default	Description
`version`	`string`	`"0.1"`	MC3 format version. Active format is 0.3 — the default needs updating.
`model`	`string`		Human-readable scene/model name.
`unit`	`string`	`"meter"`	World unit (`meter`, `centimeter`, `inch`).
`coordinateSystem`	`string`	`"right_handed_y_up"`	Coordinate convention.
`sourcePath`	`filesystem::path`		Directory of the XML file. Used to resolve relative texture/mesh URIs.
`environment`	`optional<Mc3Environment>`		Background color/texture and fog.
`lights`	`vector<Mc3Light>`		All scene lights (ambient, directional, point, spot).
`cameras`	`vector<Mc3Camera>`		All scene cameras.
`defaultCamera`	`string`		Name of the default camera.
`textures`	`map<string, Mc3Texture>`		Texture library. Key = texture ID.
`materials`	`map<string, Mc3Material>`		Material library. Key = material ID. Iterate with structured bindings.
`definitions`	`map<string, shared_ptr<Mc3Object>>`		Reusable object templates. Key = definition ID.
`objects`	`vector<shared_ptr<Mc3Object>>`		Root-level scene graph nodes.
`actions`	`map<string, Mc3Action>`		Animation clips. Key = action name.

Static Methods

Method	Description
`static Mc3Document loadFromFile(const filesystem::path&)`	Parses a `.mc3.xml` file using `Mc3XmlParser`. Sets `sourcePath` to the directory of the file. Throws `std::runtime_error` on parse failure.

Instance Methods

Method	Description
`void saveToFile(const filesystem::path&) const`	Serializes the document to XML using `Mc3XmlWriter`. Writes UTF-8 XML with the standard `<?xml …?>` header.

Important Usage Notes

⚠️

materials is a std::map. Always iterate with structured bindings: for (const auto& [key, mat] : doc.materials).
Mc3Material uses baseColor (a float[4]), not diffuse.
When renaming a definition key in definitions, walk all scene objects and update any Mc3Object::definition references to match.
Always call pushUndo() in MeshCraftApplication before mutating a document.
Do not change the public API without checking mc3togltf and all test XML files.

Example: Creating a Document Programmatically

MeshCraft::Mc3::Mc3Document doc;
doc.model = "MyScene";
doc.unit  = "meter";

// Add a material
MeshCraft::Mc3::Mc3Material mat;
mat.name = "red";
mat.baseColor = {1.0f, 0.2f, 0.1f, 1.0f};
doc.materials["red"] = mat;

// Add a box object
auto box = std::make_shared<MeshCraft::Mc3::Mc3Object>();
box->type = MeshCraft::Mc3::ObjectType::Box;
box->name = "Cube";
box->material = "red";
box->primitive = MeshCraft::Mc3::Mc3Primitive{};
doc.objects.push_back(box);

// Save
doc.saveToFile("scene.mc3.xml");

MeshCraftApplication Mc3Object