MC3 Format Reference

Overview

MC3 (Mesh Craft 3D) is a human-readable XML format for 3D scenes. It describes scenes as constructive objects — primitives, extrusions, CSG booleans, groups, instances — rather than raw triangle meshes. The recommended pipeline:

.mc3.xml  →  mc3togltf  →  .glb / .gltf  →  game engine / browser

Root Element

<mc3 version="0.1"
     model="MyScene"
     unit="meter"
     coordinate_system="right_handed_y_up">
  …
</mc3>

Attribute	Values	Default	Description
`version`	string	`0.1`	Format version
`model`	string	`"unnamed"`	Scene/model name
`unit`	`meter` \| `centimeter` \| `inch`	`meter`	World unit
`coordinate_system`	`right_handed_y_up`	`right_handed_y_up`	Coordinate convention (Y-up, right-handed)

Top-Level Structure

<mc3 …>
  <environment>…</environment>   <!-- background, fog -->
  <lights>…</lights>               <!-- ambient, directional, point, spot -->
  <cameras>…</cameras>             <!-- perspective, orthographic -->
  <textures>…</textures>           <!-- texture library -->
  <materials>…</materials>         <!-- PBR material library -->
  <definitions>…</definitions>     <!-- reusable prefabs -->
  <objects>…</objects>             <!-- scene graph -->
  <actions>…</actions>             <!-- keyframe animations -->
</mc3>

All sections are optional and may appear in any order.

Environment

<environment>
  <background color="0.5 0.7 1.0" texture="sky"/>
  <fog mode="linear" color="0.5 0.7 1.0" start="50" end="200" density="0.01"/>
</environment>

Lights

<lights>
  <ambient     color="0.3 0.3 0.4" brightness="0.5"/>
  <directional name="Sun" color="1 0.95 0.8" brightness="2"
               direction="-0.5 -1 -0.5" cast_shadows="true"/>
  <point       name="Lamp" color="1 0.6 0.2" brightness="5"
               position="0 3 0" range="10"/>
  <spot        name="Torch" position="0 5 0" direction="0 -1 0"
               angle="30" falloff="45" range="20"/>
</lights>

Cameras

<cameras default="Main">
  <camera name="Main" type="perspective"
          position="8 5 12" target="0 1 0"
          fov="60" near="0.1" far="500"/>
  <camera name="Ortho" type="orthographic"
          position="0 10 0" target="0 0 0" size="20"/>
</cameras>

Common Object Attributes

All object types support these attributes:

Attribute	Type	Default	Description
`name`	string	—	Object name (used by animation `target`)
`position`	vec3	`0 0 0`	World position
`rotation`	vec3	`0 0 0`	Euler angles (units/order set by root attributes)
`scale`	vec3	`1 1 1`	Scale per axis
`pivot`	vec3	`0 0 0`	Rotation/scale pivot offset (local space)
`material`	IDREF	—	Reference to a material `id`
`visible`	boolean	`true`	Visibility
`collision`	string	`none`	Collision shape hint
`tags`	string	—	Space-separated tag list
`layer`	string	—	Named layer for visibility grouping (empty = default layer)
`role`	`cutter`	—	Marks as CSG cutter inside `<difference>`

Transform order: T(position + pivot) × R(rotation) × S(scale) × T(-pivot). All rotation angles are in degrees, applied XYZ Euler order.

Value Formats

Type	Format	Example
vec2	`"W H"`	`"50 50"`
vec3	`"X Y Z"`	`"0 2 -5"`
vec4	`"R G B A"`	`"0.8 0.2 0.1 1.0"`
boolean	`"true"` or `"false"`	`"true"`
float	decimal	`"0.5"`
int	positive integer	`"24"`
ID	XML ID (unique)	`"brick"`
IDREF	XML IDREF (must match an existing ID)	`"brick"`

Coordinates and Units

MC3 uses a right-handed, Y-up coordinate system by default — the same convention as glTF 2.0. All lengths are in the unit declared by the unit root attribute (default: meter).

Axis	Direction
+X	Right
+Y	Up
+Z	Towards viewer (out of screen)

Rotation angles default to degrees and use XYZ Euler order unless overridden by the rotation_units / euler_order root attributes. The transform matrix per object is:

M = T(position + pivot) × Rx × Ry × Rz × S(scale) × T(-pivot)

When exporting to glTF the coordinate system is automatically converted to the glTF convention (right-handed, Y-up) and Euler angles are converted to quaternions.

Best Practices

💡

Keep scenes human-readable

Give every object a meaningful name. Animation target attributes and interactive action object references use the name to resolve objects.
Give every material and texture a short, stable id. Renaming IDs requires updating all object material attributes that reference them.
Prefer <definition> + <instance> over duplicating geometry. Multiple instances share one definition and produce leaner export files.
Keep CSG trees shallow. Deep union/difference/intersection chains re-evaluate every ancestor; flatten where possible using exported mesh objects.
Use tags (tags="door interactive") to group objects semantically — MeshCraft's hierarchy filter and interactive action resolver both support tag queries.
Set collision="none" explicitly for purely decorative objects. The default is none but making it explicit documents intent.
Prefer relative texture URIs (textures/brick.png) over absolute paths so scenes are portable across machines.

Minimal Example

<?xml version="1.0" encoding="UTF-8"?>
<mc3 version="0.1" model="Minimal">

  <environment>
    <background color="0.4 0.6 0.9"/>
  </environment>

  <lights>
    <ambient     color="0.3 0.3 0.4" brightness="0.4"/>
    <directional name="Sun" color="1 0.95 0.8"
                 brightness="2.5" direction="-0.5 -1 -0.3"/>
  </lights>

  <materials>
    <material id="grey">
      <base_color>0.7 0.7 0.7 1.0</base_color>
    </material>
  </materials>

  <objects>
    <plane name="Ground" size="20 20" axis="y" material="grey"/>
    <box   name="Cube"   size="1 1 1" position="0 0.5 0" material="grey"/>
  </objects>

</mc3>