Object Types
All MC3 object elements with their attributes. Common attributes apply to every type.
Common Object Attributes
Every object element supports these attributes:
| Attribute | Type | Default | Description |
|---|---|---|---|
name | string | — | Object name. Required for animation targets and interactive action references. |
position | vec3 | 0 0 0 | World position (X Y Z). |
rotation | vec3 | 0 0 0 | Euler rotation in degrees, applied XYZ order. |
scale | vec3 | 1 1 1 | Scale per axis. |
pivot | vec3 | 0 0 0 | Rotation/scale pivot offset in local space. Essential for doors, lids, and levers. |
material | IDREF | — | Reference to a material id declared in <materials>. |
visible | boolean | true | Whether the object is rendered. |
collision | string | none | Physics collision type: none, static, dynamic, kinematic, trigger. |
tags | string | — | Space-separated tag list (e.g., "door interactive wood"). |
role | string | — | cutter — marks this object as a subtractor inside a <difference> CSG node. |
layer | string | — | Named layer for visibility grouping. Empty means the default layer. |
state | string | — | Initial active state name (must match an id in the object's <states> block). |
Transform order: T(position + pivot) × R(rotation) × S(scale) × T(−pivot)
Object Child Elements (all types)
The following optional child elements may appear inside any object element, in this order:
<states> — named configurations
Declares named configurations that override the object's base attributes at runtime.
<box name="Door" state="closed">
<states>
<state id="closed" rotation="0 0 0"/>
<state id="open" rotation="0 90 0"/>
</states>
</box>See Interactive Actions & States for the full reference.
<deform> — geometry-level scale
Applied before the object transform. Useful for non-uniform stretching of a primitive without affecting its children's transforms.
<sphere name="Egg" radius="0.5">
<deform scale="1.0 1.5 1.0"/>
</sphere>The deform.x/y/z components are also animatable via keyframe channels (see Animation Reference).
<uv_mapping> — texture coordinate control
Controls how the texture is tiled and positioned on the object surface.
<box name="Wall" size="10 3 0.3" material="brick">
<uv_mapping scale="2.5 1.5" offset="0 0" rotation="0"/>
</box>| Attribute | Type | Default | Description |
|---|---|---|---|
scale | vec2 | 1 1 | U and V scale (tiling factor). |
offset | vec2 | 0 0 | U and V offset. |
rotation | float | 0 | Rotation in degrees. |
<metadata> — import source data
Opaque key-value store preserved during round-trip serialization. Intended for tool-specific import/export hints that should not affect rendering.
<box name="ImportedWall">
<metadata>
<property name="rd4_original_type" value="SweepObject"/>
<property name="rd4_source_line" value="142"/>
</metadata>
</box>Primitive Objects
<box> / <cube>
Rectangular box centered at the local origin. <cube size="n"> is equivalent to <box size="n n n">.
<box name="Wall" size="10 4 0.3" position="0 2 -5" material="brick"/>
<cube name="Crate" size="1" material="wood"/>| Attribute | Type | Default | Description |
|---|---|---|---|
size | vec3 | 1 1 1 | Width × Height × Depth. For <cube>, a single number is expanded to W H D. |
segments | int | 1 | Subdivisions per axis. |
<sphere>
<sphere name="Ball" radius="0.5" segments="24" position="0 1 0"/>| Attribute | Type | Default | Description |
|---|---|---|---|
radius | float | 0.5 | Sphere radius. |
segments | int | 16 | Latitude/longitude subdivisions. |
<cylinder>
<cylinder name="Pillar" radius="0.3" height="4" segments="16" axis="y"/>| Attribute | Type | Default | Description |
|---|---|---|---|
radius | float | 0.5 | Base radius. |
height | float | 1.0 | Total height. |
segments | int | 16 | Circumference subdivisions. |
axis | x|y|z | y | Height axis. Controls how the mesh is generated; does not apply a rotation transform. |
<cone>
<cone name="Cap" radius="0.5" height="1.5" segments="16"/>| Attribute | Type | Default |
|---|---|---|
radius | float | 0.5 |
height | float | 1.0 |
segments | int | 16 |
<plane>
Flat surface with no thickness. Useful for floors, ground planes, and walls with one-sided rendering.
<plane name="Ground" size="50 50" axis="y" material="grass"/>| Attribute | Type | Default | Description |
|---|---|---|---|
size | vec2 | 1 1 | Width and height. |
axis | x|y|z | y | Normal axis. |
segments | int | 1 | Subdivisions. |
<torus>
Donut-shaped surface. Useful for rings, wheels, and loop shapes.
<torus name="Ring" major_radius="1.0" minor_radius="0.25" segments="32"/>| Attribute | Type | Default | Description |
|---|---|---|---|
major_radius | float | 1.0 | Distance from the center of the tube to the center of the torus. |
minor_radius | float | 0.25 | Radius of the tube. |
segments | int | 32 | Ring subdivisions (both major and minor). |
<capsule>
Cylinder with hemispherical end caps. Commonly used as a character or physics body shape.
<capsule name="Body" radius="0.4" height="1.8" segments="16"/>| Attribute | Type | Default | Description |
|---|---|---|---|
radius | float | 0.5 | Radius of the cylinder and the end caps. |
height | float | 1.0 | Total height including both caps. |
segments | int | 16 | Circumference subdivisions. |
<disk>
Circular disc (or annulus when inner_radius > 0). Use for coin shapes, rings, and washers.
<disk name="Coin" radius="0.4" segments="32"/>
<disk name="Washer" radius="0.5" inner_radius="0.2" segments="24"/>| Attribute | Type | Default | Description |
|---|---|---|---|
radius | float | 0.5 | Outer radius. |
inner_radius | float | 0 | Inner hole radius. 0 = solid disc. |
segments | int | 24 | Circumference subdivisions. |
<grid>
Flat subdivided plane (N×M quads) useful as a ground or reference surface. Unlike <plane>, a grid has configurable subdivision for deformation or displacement.
<grid name="Ground" size="10 10" subdivisions_x="10" subdivisions_z="10"/>| Attribute | Type | Default | Description |
|---|---|---|---|
size | vec2 | 1 1 | Width × depth (X × Z). |
subdivisions_x | int | 1 | Number of columns. |
subdivisions_z | int | 1 | Number of rows. |
<icosphere>
Sphere with uniformly distributed triangles (no pole singularity). Higher subdivision gives a rounder result with fewer shading artifacts than a UV sphere at the same polygon count.
<icosphere name="Ball" radius="0.5" subdivisions="3"/>| Attribute | Type | Default | Description |
|---|---|---|---|
radius | float | 0.5 | Sphere radius. |
subdivisions | int | 3 | Refinement iterations. Each step ×4 triangles: 0=20, 1=80, 2=320, 3=1280 faces. |
<mesh>
External polygon mesh loaded from a file. Supports OBJ and GLB/glTF sources.
<mesh name="Chair" src="assets/chair.obj" material="wood"/>| Attribute | Description |
|---|---|
src | Path to the mesh file, relative to the .mc3.xml file. OBJ files are previewed in the editor viewport (up to ~300k triangles); GLB/glTF references are parsed at export time. |
<extrude>
Sweeps a 2D cross-section along a 3D path, producing a solid mesh with optional end caps and twist.
Contains exactly two child elements: <cross_section> and <path>.
<extrude name="Arch" material="stone"
segments="24" caps="true" smooth="true">
<cross_section type="rect" width="0.3" height="0.2"/>
<path type="arc" radius="2.0" angle="180"/>
</extrude>Extrude attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
segments | int | 32 | Subdivisions along the path. |
twist | float | 0.0 | Total rotation in degrees applied from start to end of path. |
smooth | bool | true | Smooth (averaged) normals between segments vs. flat face normals. |
caps | bool | true | Close both ends of the swept tube with filled polygons. |
Cross-section types
| type | Attributes | Description |
|---|---|---|
rect | width, height | Rectangle. |
circle | radius, inner_radius (optional), segments | Circle or hollow pipe. inner_radius > 0 → annular cross-section. |
polygon | radius (circumradius), sides | Regular N-gon. sides=3→triangle, sides=6→hexagon. |
custom | child <point x="…" y="…"/> elements (CCW winding) | Arbitrary closed 2D polygon. |
Path types
| type | Attributes | Description |
|---|---|---|
line | length, axis (x|y|z) | Straight extrusion along a world axis. |
arc | radius, angle (degrees) | Circular arc in the XZ plane. Good for arches and curved rails. |
helix | radius, height, turns | Helical coil. Good for springs and screws. |
polyline | child <point x y z/> | Piecewise-linear 3D path. |
bezier | child <point x y z cx cy cz/> | Cubic Bézier spline; cx/cy/cz is the in-tangent control point. |
Examples
<!-- Arch -->
<extrude name="Arch" segments="24">
<cross_section type="rect" width="0.3" height="0.2"/>
<path type="arc" radius="2.0" angle="180"/>
</extrude>
<!-- Spring -->
<extrude name="Spring" segments="64">
<cross_section type="circle" radius="0.08" inner_radius="0.04"/>
<path type="helix" radius="0.5" height="2.0" turns="6"/>
</extrude>
<!-- Hex bolt -->
<extrude name="HexBeam" segments="1">
<cross_section type="polygon" radius="0.15" sides="6"/>
<path type="line" length="3.0" axis="y"/>
</extrude>
<!-- Twisted ribbon -->
<extrude name="Ribbon" segments="32" twist="180">
<cross_section type="rect" width="0.5" height="0.05"/>
<path type="bezier">
<point x="0" y="0" z="0" cx="1" cy="1" cz="0"/>
<point x="3" y="2" z="1" cx="1" cy="0" cz="0"/>
<point x="6" y="0" z="0"/>
</path>
</extrude><group>
Container that applies a shared transform to its children. Children can be any type including nested groups.
<group name="Table" position="3 0 1">
<box name="Top" size="2 0.1 1" position="0 1 0" material="wood"/>
<box name="Leg1" size="0.08 1 0.08" position="-0.9 0.5 -0.4" material="wood"/>
<box name="Leg2" size="0.08 1 0.08" position=" 0.9 0.5 -0.4" material="wood"/>
<box name="Leg3" size="0.08 1 0.08" position="-0.9 0.5 0.4" material="wood"/>
<box name="Leg4" size="0.08 1 0.08" position=" 0.9 0.5 0.4" material="wood"/>
</group>Transform hierarchy: world_transform = parent_transform × local_transform
<instance>
Places a copy of a <definition> in the scene. Shares the definition's geometry but supports per-instance overrides.
<instance name="Tree1" definition="tree" position="-5 0 3"/>
<instance name="Tree2" definition="tree" position=" 5 0 1" material="autumn_leaves"
scale="1.2 1.2 1.2"/>Overridable attributes on <instance>: position, rotation, scale, material, visible, collision, state. Tags are merged with definition tags.
<union> / <difference> / <intersection>
CSG Boolean operations. See CSG Tutorial for detailed examples.
<!-- Difference: box with spherical cavity -->
<difference name="HollowBox" material="stone">
<box name="body" size="2 2 2"/>
<sphere name="cavity" radius="0.9" role="cutter"/>
</difference>
<!-- Union: merge two shapes -->
<union name="TwoSpheres" material="glass">
<sphere radius="0.6" position="-0.4 0 0"/>
<sphere radius="0.6" position=" 0.4 0 0"/>
</union>
<!-- Intersection: only the overlapping volume -->
<intersection name="RoundBlock" material="metal">
<box size="1.5 1.5 1.5"/>
<sphere radius="0.9"/>
</intersection>CSG children can themselves be CSG operations (recursive). The role="cutter" attribute applies only inside <difference>; all children of <union> and <intersection> participate equally.
CSG evaluation uses the Manifold v3 library and requires non-degenerate, watertight meshes. Results are cached per object and invalidated on every edit.
<area>
An invisible logical volume for trigger zones, checkpoints, and pathfinding hints. No visual geometry is generated.
<area name="CheckpointZone"
size="5 3 5"
position="0 1.5 10"
tags="trigger checkpoint"/>| Attribute | Type | Default | Description |
|---|---|---|---|
size | vec3 | 1 1 1 | Box extent of the area volume. |
tags | string | — | Use tags to classify areas (e.g., "trigger", "checkpoint", "navmesh"). |
Areas are typically paired with on_enter_area triggers in interactive actions. See Interactive Actions.
Pivots and Rotation Centers
The pivot attribute shifts the rotation and scale center away from the object's local origin.
This is essential for doors (pivot on the hinge edge), lids (pivot at the back edge), levers, and wheels.
<!-- Door that rotates around its left edge -->
<box name="Door"
size="1 2.1 0.08"
position="0 1.05 0"
pivot="-0.5 0 0"
material="wood"/>Transform order with pivot: T(position + pivot) × R(rotation) × S(scale) × T(−pivot)
The pivot is in local object coordinates, specified before any transform is applied.