Compose objects

Docs / Objects

A person, a loaf of bread and a plane use the same assembly format. Their names don't choose a renderer recipe. You choose primitives, connect them and declare a body independently of their appearance.

The gallery frames each asset independently to show its construction. The shared-scale lineup shows their relative dimensions.

Five complete furniture constructions show how the same vocabulary makes a slatted bench, supported table, stacked fruit, hollow clay pot and market stall. Their parts still belong to explicit break groups; changing appearance does not create a new interaction rule.

Parts and materials

part has a shape, material, local position and full bounding dimensions. A sphere with size=[10,10,10] is ten units across, not a radius-ten sphere. Rotation is Euler XYZ in degrees.

Cylinders, cones and capsules point along local Y; a torus hole points along local Z. A rotated primitive keeps its own motion axes. beam takes from and to endpoints and builds a connected box, cylinder or capsule between them.

Box bevels follow the smallest physical dimension, so a long plank keeps crisp ends. Rings use a slimmer profile for tyres, rims and handles while keeping their declared outer dimensions. The asset library shows how the current world uses these shapes for window frames, pedals, bark, food and detachable building details.

Materials are engine-owned styles, each with two hex colors. deform(seed=...,amount=...) adds bounded, deterministic variation to supported parts.

Use faceted=true on an undeformed icosphere, cone or cylinder when the polygonal faces belong to the design. Cylinder beams accept it too. The engine retains flat faces in ordinary rendering and exact cut-cell contours in voxel worlds, instead of reconstructing a curved surface. This makes small fruit and layered crowns readable without increasing grid resolution. Other shapes and positive deformation reject the field; false or omission keeps the existing curved reconstruction. Part, grid, contact and fracture budgets stay unchanged. Complete faceted fir.

A rooted prism profile can form leaves along a fern rib or foxglove stem, with another profile for rounded petals. Joined panels form open flowers and pot rims. Keep the connection at the component origin, then orient use on the supporting stem. The complete plant library contains four checked live constructions using the existing vocabulary.

material fired_clay(style=brick,colors=[#a96f55,#bcb1a0]);
material oak(style=wood,colors=[#98724e,#62452f]);
material limestone(style=stone,colors=[#b3b3a5,#8c9489]);

Compile the complete wall and bench. Brick courses share the assembly's local frame across adjacent parts; wood keeps each member's grain direction. Surface coordinates survive rigid merging, instances and newly exposed voxel fracture faces. Physical scale follows the rendered transform, so enlarging a building doesn't enlarge its bricks. Fine patterns blend toward their average below a pixel to reduce shimmer at a distance. Relief changes lighting, not silhouettes or collision. No material adds per-brick geometry, downloads, model-written shaders or extra physics bodies.

grain remains the original paper-grain finish. cloth supplies flag wind, not garment physics. The new presets do not change the voxel grid, material URLs remain unsupported, and roughness/relief are engine-owned rather than arbitrary Dream shader parameters.

Grow a connected branch

A cylinder can narrow continuously with taper, a tip-to-base diameter ratio from .1 to 1. It defaults to 1. For a beam, the base is from and the tip is to; for a part, the tip is local +Y. The declared dimensions still cover the full base. Start a fork inside its trunk so the surfaces overlap at the join.

This complete snag uses one tapered trunk and one branch, with a smaller cut face at the top:

dream 2;
material bark(style=toon,colors=[#76583d,#503b2b]);
material cut(style=toon,colors=[#bc9668,#97754f]);
object snag(label="Woodland snag"){
  measure(kind=tree,axis=y,meters=6);
  body(interaction=solid,radius=9,height=42);
  beam trunk(shape=cylinder,material=bark,from=[0,0,0],to=[1,41,0],width=7,depth=6,taper=.38);
  beam branch(shape=cylinder,material=bark,from=[.5,20,0],to=[-12,33,2],width=2.8,depth=2.5,taper=.4);
  beam cut_top(shape=cylinder,material=cut,from=[1,40.8,0],to=[1,41.3,0],width=2.1,depth=1.9);
}

Shape a panel instead of stacking boxes

A prism extrudes a small XY outline through the full Z dimension. Coordinates run from 0 to 1 across the declared width and height, and the engine centers the result at at. The outline must reach both extrema on X and Y. It has 3–24 vertices, area at least .01, and no holes, repeated closing point, crossed edges or self-touching. Either winding works. Concave lower edges can leave real wheel openings through both sides of a body.

Inside an object, with a declared glass material:

part cabin(shape=prism,material=glass,at=[0,12,0],size=[20,8,14],outline=[[0,0],[1,0],[.75,1],[.2,1]]);

The complete city car combines a shaped shell, sloped glazing, roof and pillars with connected axles. Visual openings do not change its collision cylinder. The profile is bounded data, triangulated once by the engine, with the same batching, materials, measured size and terrain support as other parts.

Give it a physical size

Inside an object:

measure(kind=person,axis=y,meters=1.75);

The compiler measures the assembled rest pose and resolves a uniform factor. Ten world units represent a metre. Your local modeling dimensions stay bounded; geometry, grounding, physical contacts, foundations, seats and debris all use the resolved scale.

The proportion profiles specify the measured axis and permitted range for cars, trees, planes, people, furniture and other common categories. place(...,scale=1.1) adds variation after measurement and must stay inside the profile. A measured car player also establishes relative rules: tree height and plane wingspan exceed its length, while bikes and boards stay shorter.

Use kind=custom with an explicit axis and dimension for unusual inventions or deliberate fantasy sizes. Omitting measure preserves legacy local-unit sizing. The detailed sizing contract explains compiled data and bounds.

Reuse a shape without copying it

component accepts numeric and material parameters. use expands it at a named site. The same geometry can become oak furniture, painted furniture or four people in different uniforms without copying the assembly. repeat supplies an index for bounded variation.

component leg(params=[h],materials=[finish]){
  beam post(shape=box,material=finish,from=[0,0,0],to=[0,h,0],width=4,depth=4);
}

Inside an object or another component, pass numbers and material IDs in their separate lists:

use support(component=leg,args=[24],materials=[timber],at=[-22,0,-12]);

Two complete tables reuse a table component and pass its finish to the nested leg component. Both lists have exact arity, in declaration order. There are at most eight unique parameter names combined. Numeric and material parameters cannot share a name; material parameters cannot shadow global numeric constants. They may shadow global materials. Bindings resolve in the caller, and the callee receives globals plus its own explicit bindings. Caller locals do not leak into nested components. Existing numeric-only components keep their meaning.

Parameters work with part, beam and voxels, including geometry inside groups, joints and fragments. Expansion still counts every part and joint; reuse makes the source smaller, not the resulting world's budgets larger. The breakable bench uses repeats to place its slats and frames.

A group applies a rigid position, rotation and uniform scale to its contents. Use joint when parts need a connected coordinate frame. Joint transforms don't inherit primitive dimension scaling, so a hand doesn't stretch when an upper arm gets longer. Local constants resolve in order. Components see globals and their parameters, not the caller's local bindings.

mount adds a component in a previously declared humanoid bone's frame. It is useful for coats, hair, hats and carried objects, without introducing another joint. People and connected clothing includes the complete live character library and the bone, scope and placement-clearance rules.

Animate a connection

Parts support spin, distance-driven roll and rigid sway. Joints support roll, distance-driven stride, oscillating swing or a proximity-driven open. Arguments use named fields: spin(axis=x,deg_s=90) or swing(axis=z,deg=20,hz=.25,phase_deg=0).

A rolling joint turns its whole child assembly around one bearing by traveled distance divided by its resolved radius. Tires, hubs and a shaft can share one axle frame; a chainring, crank arms and pedals can share another. All children retain their distances from the bearing. Orient the local axis to match forward wheel travel. Reduced motion rests the mechanism, and prop furnishings bake its rest pose without allocating live joints. Controllable furnishings retain the mechanism for their single occupied fleet rig and instance its unoccupied pose. Stride, swinging or proximity-operated templates remain ineligible for furnishings. The complete bicycle uses a rolling crank with paired forks and stays.

Use joint(...,bone=left_knee) and the complete twelve-bone humanoid contract for people who walk, run and swim. The engine chooses the movement cycle; the model supplies connected anatomy. Rig, source and close-up motion. Ordinary machinery keeps roll, stride, swing and open.

Scattered fragments require a static rest pose so their release frames are deterministic. A whole-object topple may retain part sway on a pooled static prop with world(...,damage_pool=true). Its crown keeps the same wind phase while the assembly falls, including its shadow and material finishes. Spin, roll, cloth and animated joints remain incompatible. Compile a complete planting world. Full shape, position, motion and expansion bounds are in the reference.

Next: world layout · Behavior and destruction

Voxel geometry

Dream 2 now supports bounded filled/carved voxel parts, greedy surface meshing and optional fracture chunks. The city uses voxel building shells, bench boards and carved park walls; the library bakehouse adds chunked masonry; measured proportions and explicit contacts remain unchanged. See the voxel guide for syntax, limits, a complete example and current boundaries.

Finer construction

Object DSL v2 accepts visual dimensions from .1 to 128 local units. V1 retains .5 as its minimum, and beams still need at least .5 endpoint length. The minimum is local: use measure to resolve physical scale before choosing pipe, frame or railing thickness. Parts remain visual; body, compound contacts and all geometry budgets are independent.

The construction guide follows complete live house, bus and launch sources. They combine carved voxel frames with shaped profiles rather than increasing the part cap.

Enterable assemblies

A static measured building can declare an interior with named portal openings. It needs explicit rectangle floor/ceiling contacts, an actual doorway and shell parts tagged with cutaway. The original cylinder contact form remains compatible. Read interiors and the complete market assembly; a painted door creates no passage.

Background ground cover reuses grass and flower components in separate objects and one combined inspection form. Keep leaf roots on their stalk and grass tips below petals. The engine uses these same small prototypes; its scatter density and palette remain engine-owned.

Pace a joint by travel

stride is joint-only. length is 1–128 local units per cycle; deg is a 0–1.4-radian amplitude expressed in degrees, and phase_deg stays within ±180. Nested uniform scales resolve the length before object scale is applied. Time alone does not advance the joint. It uses a rigid sinusoidal rotation, without a foot-contact solver. Reduced motion and parked roll-only updates rest it. Humanoid walking continues to use its separate complete bone contract.

This complete example is identical to joint-stride.dream:

dream 2;
material coat(style=toon,colors=[#b78352,#8f6847]);
material foot(style=toon,colors=[#3c413a,#3c413a]);
object stride_limb(label="Distance-driven limb"){
 measure(kind=custom,axis=y,meters=.7);
 body(interaction=decor,radius=4,height=28);
 part body(shape=icosphere,material=coat,at=[0,22,0],size=[8,8,6],faceted=true);
 joint hip(at=[0,20,0],motion=stride(axis=z,deg=24,length=20,phase_deg=0)){
  beam thigh(shape=cylinder,material=coat,from=[0,0,0],to=[0,-10,0],width=2,depth=2,faceted=true);
  joint knee(at=[0,-10,0],motion=stride(axis=z,deg=9.6,length=20,phase_deg=0)){
   beam shin(shape=cylinder,material=coat,from=[0,0,0],to=[0,-9,0],width=1.5,depth=1.5,faceted=true);
   part paw(shape=box,material=foot,at=[1,-9,0],size=[5,2,3]);
  }
 }
 joint glance(at=[0,24,0],motion=swing(axis=y,deg=5,hz=.2,phase_deg=0)){
  part head(shape=icosphere,material=coat,at=[0,2,0],size=[4,4,4],faceted=true);
 }
}

All nine animal constructions reuse this mechanism. Ambient animals share GPU geometry and color/shadow transforms; new motion vocabulary does not raise their population or joint limits.