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.3"
     model="MyScene"
     unit="meter"
     coordinate_system="right_handed_y_up"
     rotation_units="degrees"
     euler_order="XYZ"
     default_camera="Main">
  …
</mc3>

Attribute	Values	Default	Description
`version`	string	`0.3`	Format version
`model`	string	—	Scene/model name
`unit`	`meter` \| `centimeter` \| `inch`	`meter`	World unit
`coordinate_system`	`right_handed_y_up` \| `right_handed_z_up`	`right_handed_y_up`	Coordinate convention
`rotation_units`	`degrees` \| `radians`	`degrees`	Units for all rotation attributes
`euler_order`	`XYZ` \| `XZY` \| `YXZ` \| …	`XYZ`	Euler composition order
`default_camera`	string	—	Name of the default camera

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
`role`	`cutter`	—	Marks as CSG cutter inside `<difference>`

Transform order: T(position + pivot) × R(rotation) × S(scale) × T(-pivot)

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"`

Minimal Example

<?xml version="1.0" encoding="UTF-8"?>
<mc3 version="0.3" 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>