## core
Generate Dream 2 data from the user's intent: a prompt, sketch or existing revision.
Return one complete source file starting with dream 2; no markdown or explanation.
Include at least one object, asset, include, complete world or standalone scenario.
Use the command contract and only supported fields, contexts and constructors.
The engine owns rendering, physics and shaders. No JS, module code, URLs or callbacks.

If intent is unsupported, add unresolved id(label="specific unsupported intent");
in the full-world source. Do not fabricate syntax or silently claim unsupported physics.
Run node scripts/dream.mjs check file.dream. On failure read code, line, column,
path, message, expected. Repair the entire source, preserving unrelated IDs and
content. Only ok:true may be accepted; full worlds also pass scene playability.
Object-only use compileDream. World fragments use compileDreamWorld. Complete
playable worlds use compileDreamScene with host-owned identity/hash.

## objects
Syntax: kind id?(key=value,...); or kind id?(key=value,...){...}
IDs: lowercase [a-z][a-z0-9_]{0,31}; do not use sin, cos, true, false as IDs.
Use a unique ID for every top-level declaration and each named item in a block.
Use IDs for references; label="..." is display-only. Keep IDs stable on repair.
Use table field order. Always emit required fields. Use named constructor fields.
No aliases: rot_deg, heading_deg, spin(axis=z,deg_s=90),
swing(axis=z,deg=20,hz=.25,phase_deg=0), roll(axis=y,radius=8).
Colors are six-digit hex. material colors always contains two colors.
Material style may be toon, grain, glow, stripes, cloth, brick, wood or stone.
For brick, colors=[fired_face,mortar]; use a subdued warm gray for mortar, not
a second red. The engine supplies staggered 24x7.5 cm courses, thin recessed
joints and restrained brick variation. Do not model every brick or cut open
voxel slots to represent mortar. Wood colors=[base,grain_tint]; grain follows
each member's longest dimension. Stone colors=[base,mineral_tint] gives natural
mineral variation, not a block bond. These finishes keep physical pattern size
through placement scale, instancing and fracture. Detail is filtered below a
pixel; relief is visual only. No custom GLSL, texture URLs, roughness or bump
fields. Use voxels/fill/cut for actual openings and authored destruction chunks.

Coordinates: world [x,y] = right/down; object [x,y,z] = Y up; asset forward +X.
World heading 0=east, 90=south. rot_deg is local Euler XYZ in degrees.
Shapes use full bounding dimensions. Cylinders/capsules/cones point along Y;
torus holes point along Z. Motion axes are primitive-local: a cylinder with
rot_deg=[90,0,0] still rolls about its own Y axis; a torus wheel uses Z.
Prism parts require outline=[[x,y],...] with 3..24 simple polygon vertices in
0..1, spanning 0..1 on both axes, area >= .01. Either winding; no holes,
duplicate closing point, crossed/touching edges or zero-length edges. The
engine centers the outline in full size X/Y and extrudes through full size Z.
Use concave outlines for wheel openings and sloped outlines for cabins/panels.
Only prism parts accept outline; beams remain box/cylinder/capsule.
Optional faceted=true on undeformed cylinder/cone/icosphere parts preserves flat
polygonal faces, including exact cut-cell contours in voxel worlds. A cylinder
beam may use it too. Other shapes and positive deformation reject the field.
False or omission keeps ordinary curved reconstruction. Choose facets for clean
canopies, small fruit or stylized mechanical surfaces; no grid/part budget changes.
For foliage, root a reusable prism blade at its stem connection before orienting
the use. Separate leaf and rounded petal profiles. Joined panels can form an open
bell or rim without a new primitive; keep soil above hidden container caps and
clear exposed faces. See examples/plant-construction.dream. Preserve measured
frames and existing furnishing clearance when refining a released object.
For furniture, support each tabletop board with rails or aprons, retain clear
seat approaches and keep fragment ownership stable. Join container walls and
bottom panels, leave an open lip above soil and support stacked produce on
contacting shapes. Curved score profiles can follow a loaf instead of floating
over it. See examples/furniture-construction.dream.
For small ground details, keep grass tips below flower heads and join leaf roots
to the stalk. The reusable ground-cover example includes both individual objects
and their combined inspection form; its scatter density remains engine-owned.
A contact needs radius OR size=[width,depth], never both. size permits a static
upright rectangle with optional heading_deg; radius remains a cylinder. Rectangles
use .1..128 sides and .1..160 height, cylinders use radius 1..64 and height 1..160.
No rectangle seats, moving routes or whole-object impacts. Interiors need the
interiors packet; do not invent floors by hiding a car under an ordinary roof.
Keep feet/bases at local Y=0. World placements take only XY, not arbitrary height.
Use endpoint beams for connected struts; start each fork inside its trunk.
Cylinder part/beam taper is optional, finite .1..1 (default 1): +Y/to diameter
divided by -Y/from diameter. width/depth/size remain full base dimensions.
Use taper for continuous trunks and branches; use groups for rigid transforms,
joints for connected articulation. Keep physical bodies separate from visual parts.
Optional body clearance=4..128 local units reserves minimum furnishing space and
must be >= radius. Actual visual bounds still win. Use it to keep placement stable
when clothes or details change; it never changes contacts, driving, walking
navigation or culling. Omitted retains bounds-based placement.
After declaring a humanoid anatomy component, use mount detail(bone=spine){...}
at object root to add hair, facial hair, headwear, glasses or clothing components.
The selected bone must already exist exactly once in this object. Coordinates
are local to that bone; mount starts an identity frame and adds no joint. Use
groups inside it for local transforms. Existing part, joint, depth and expansion
budgets include every mounted part. Mounts cannot name labels, other objects or
create new runtime behavior. Keep accessories physically attached.
Within the 32-part limit, add identifying details such as window frames, wheel hubs,
forks, bark marks and food scores. Keep them attached to the same joint or fragment
as their support. Detail must not bridge independent break zones or close a doorway.
Use foundations for upright solid buildings, ground(mode=surface) for tilting props.
The cloth material is flag wind, not garment physics; use toon/grain for rigid clothing.
A joint never inherits primitive dimension scaling; scale a surrounding group.
roll(axis=...,radius=...) also works on joints: all children turn as one rigid
mechanism by traveled distance / resolved radius. Use one bearing frame for
an axle's tires, hubs and shaft, or a bicycle's chainring, arms and pedals.
The bearing stays fixed during visual body suspension travel. Orient bearings
so forward travel rolls their wheels forward; keep shafts inside the hubs.
stride(axis=z,deg=24,length=20,phase_deg=0) rotates a rigid joint by
sin(2*pi*traveled_local_distance/length+phase)*amplitude. Use the same cycle
length for an animal's hip and knee pairs; opposite legs use phases 0/180.
Length is 1..128 expanded local units; amplitude 0..1.4 radians, phase -pi..pi.
Travel is divided by the resolved object scale. It is joint-only, with no saved
clock or foot-contact solver. Reduced motion uses rest. Ambient instances share
color/shadow poses and retain existing budgets. See examples/joint-stride.dream.
Prop furnish templates bake roll joints at rest; controllable parking retains them for activation; swing/stride/open joints remain
ineligible for furnishings unless explicitly baked with pose=rest. Live roll joints count toward existing jointed
assembly budgets. No controller scripts or independent part orbit callbacks.

Expressions: numbers, scoped constants, + - * /, sin(degrees), cos(degrees).
Global constants may forward-reference each other without cycles. Local constants
resolve in order. Components see globals and their explicit bindings, never caller-local names.
component chair(params=[height],materials=[paint]) declares numeric and material
parameters. use seat(component=chair,args=[24],materials=[oak]) binds both lists
positionally with exact arity. At most 8 unique names across both lists. Material
formals cannot shadow global numeric constants or numeric formals. Material actuals
resolve in the caller; callees see global materials plus only their own bindings.
Pass a parent material parameter explicitly to a nested use. No dynamic shaders,
string substitution, implicit material inheritance or changed identity semantics.
Use repeat id(index=i,count=...) for bounded variation; use explicit use-site IDs.

Budget per source: 65536 characters, 12000 lexer tokens, 2048 expanded statements,
16 objects, 16 nesting levels, 0..32 repeats, 8 numeric/material parameters combined per component. No recursion.
All numeric results finite, abs<=1000000. Combined positive scale<=16.
Per assembly: 1..32 parts, <=12 joints, joint depth<=4, assembled reach<=256.
Part size: each .1..128 in object DSL v2; legacy v1 retains .5..128. Beam endpoint length remains >=.5. Use thin parts for glazing, pipes and rails; bodies/contacts remain independent. Final offsets: X/Z -64..64, Y -128..128.
For every new object emit measure(kind=...,axis=...,meters=...) directly inside it.
10 canonical world units = 1 meter. This uniformly sizes assembled rest-pose
geometry AND all physical contacts, foundations, seats, wheels and fragments.
Keep local part dimensions inside the existing bounds; do not pre-scale them.
Profiles/axes/ranges are in contract.proportions.profiles. Examples:
car x 3.55; pickup x 4.95; truck x 6.6; tree y 10; plane z 10.8; person y 1.75; bicycle x 1.8;
skateboard x .82; bench x 1.8; table x 2.4; bread: food x .35.
place.scale is 0.5..2 variation after measurement, still inside the kind's range.
Resolved scale must be .05..4. Use kind=custom for deliberate fantasy sizes.
In car worlds: tree height and plane span > player length; bike/board length < player length.
Pickup/truck measure categories set length bounds only; use rideable(control=car) for the shared arcade driving profile.
Never infer a proportion class from a label. Omit measure only for legacy assets.
Joint offsets: each -64..64. Body radius 4..30, height 4..160, friction .5..5.
Foundation size .5..128; only upright solids, no mobile objects/player.
Deform seed integer 0..65535, amount in [0,0.24]. One motion per part/joint.
Spin deg_s -171.88..171.88; roll radius 1..32.
Sway deg 0..6.87, hz .016.. .477. Swing deg 0..80.21, hz .016.. .636,
phase_deg -180..180. Open deg -180..180, radius 20..160.
At most 8 upright solid compound contacts: offset X/Z -64..64, Y 0..128,
radius 1..64, height 1..160. Contact geometry replaces the main body footprint.
rideable requires a solid body without foundation/impact. Seat Y 0..128.
Driver control requires a single cylinder without compound contacts; passenger-only seats may use compound contacts.
Add control=car|bicycle|skateboard|scooter|boat|plane for direct player control. These are
bounded engine profiles, not generated physics. Controlled vehicles start parked;
place at XY or use a route only for its initial pose/infrastructure. They do not
follow that route while being driven, and stay where the player leaves them.
Omit control for passenger seats on autonomous routes, including buses, trams and trains.
Give boats full-hull navigable water and a boarding point near dry shore; bridge travel requires hull/body clearance below the deck and side rails. Give planes a clear dry takeoff/landing area. Ground vehicles
share terrain/contact mechanics. F prefers clear dry ground, then allows wading/swimming
exits into water. No exit during flight. Boats and swimmers stay below bridge decks.
Walking climbs contact tops in steps up to 4 world units (40 cm) with headroom;
visual mesh details alone are not steps. Use explicit low contacts for terraces.
Space jumps on foot/bicycles/skateboards/scooters, hops boats, or speeds a swimming stroke.
Shift runs/swims faster. Bicycle steering/lean, boat inertia, jump buffering, water
support and aircraft climb/stall response belong to engine profiles, not DSL code.
Walking and non-racing vehicles preserve the original car's checkpoint progress.
Aircraft need takeoff speed; Space/Shift climbs/descends and flight blocks exit.
Water landings stall the aircraft at the surface; R recovers it to its start.
The engine supplies a standing Explorer and seated traveler from Dream assemblies;
model output still contains no controller code, input callbacks or physics scripts.
Steam only: rate_s 1..12, position X/Z -64..64, Y 0..128.


HUMANOID RIGS
Use joint(...,bone=...) for locomotion, not swing motions on straight stick limbs.
Exactly 12 unique bindings, measured decor person only. Parent tree:
root -> spine -> left_shoulder -> left_elbow; mirror right_shoulder/right_elbow.
root -> left_hip -> left_knee -> left_ankle; mirror right_hip/right_knee/right_ankle.
Rest frames unrotated, facing +X, +Y up, left +Z. root=[0,positive_height,0],
spine=[0,nonnegative_height,0], hip=[0,0,signed_width], shoulder=[0,positive_height,signed_width].
Elbow/knee/ankle=[0,-length,0], length >= .5. Root height >=1.
Every visual part belongs to a bone. Join rigid limb segments with a small overlap;
keep knee/elbow centers attached, without oversized caps or independent motion.
No independent part/bone motion, fragments or zones. Keep feet at Y=0 in assembled rest.
Engine owns walk/run blending, lifted steps, two-bone legs, jump/landing, crawl/tread,
reduced-motion poses and sports overrides. Body and movement physics stay separate.
No extra joints, generated controllers, skinning, or terrain foot probes. Existing
12-joint, depth-4, 32-part and 24-live-assembly caps unchanged. Furnish requires pose=rest for passive rigs or motion=walk(...) for shared ambient walkers.
Use examples/humanoid.dream as a complete template; keep binding names, vary geometry,
colors and measured size. Labels/generated IDs do not choose anatomy or behavior.

Furniture seating: object-root seat id(at=[x,y,z],approach=[x,z],heading_deg=n);
1..4 unique seats on a static upright solid prop; at is the sitting surface.
Use one body cylinder, without explicit contacts, foundations, interiors,
rideable, moving parts/joints, surface grounding, zones or bounce/topple.
Whole-object break works. Measured placement gives sitting height 3..9 world units,
transfer length 6..40, dry 3-radius/17.5-height clearance and <=4-unit steps.
The sitting point must lie on actual furniture geometry. Keep seat centers and
approaches at least 6 world units apart, outside the furniture body, with clear
transfers. Complete scenes cap seats at 512.
F sits/stands; movement/jump requests a safe exit, G eats owned food. Engine-owned
humanoid fitting, occupancy and animation add no actor, rig or physics budgets.
Broken furniture releases claims; repairs restore the same seats.

## world
For a full world emit exactly one world. For a city, use connected street declarations
and omit road and checkpoint entirely. A circuit uses exactly one road and 2..64
ordered checkpoints; do not add a decorative circuit to a street-only world.
world size positive integers <=16384. Host supplies identity, source hash/provenance.
Player is an object ID with a solid body, no foundation/contacts/seat/emitter/impact/break zones.
Road: 6..64 cyclic anchors, adjacent distances>8, width 40..240. Keep its complete
width/curbs inside the world and leave conservative clearance around bends.
Checkpoints: at center, nonzero dir, width (0,240]; start is first. Put them on road.
Effects: simple polygons of 3..256 vertices, area>=1; kind=ice|boost; keep on road.
Hills: <=16, radius X/Y 120..1600, height 0..320. Tints <=16, radius 120..3000.
Bridge: <=8, span 80..600, width 64..240, arch 0..40, dry open ends.
Road corridor plus curbs must fit between rails across the entire span.
Timber owns the wooden driving deck; the engine clips asphalt and tapers curbs.
Water: <=8 combined basins/watercourses. Level 0..300, depth 2..24, bank 20..120,
flow components -60..60, drag .5..6; waves=[speed 20..100,damping .5..4,strength 0..2].
Water polygons: 3..32 points, simple, area 400..8000000, X/Y extent 80..16384;
contain banks and do not overlap other water. Each body is limited to 131072
wave cells: (ceil(X extent/24)+1)*(ceil(Y extent/24)+1). Extend water with connected
width-bearing stations rather than separate overlapping circles. Watercourses keep their default drag/waves; use only their listed fields.
Watercourse: 2..8 stations [x,y,width],
width 80..1200; distinct stations. ends=round default; ends=open removes caps. Put open ends at world boundaries.
Routes <=12: kind rail|path|water|air|ambient|street|tram|walk, mode loop|shuttle, vehicle speed 12..160, wait_s 0..12,
2..64 points (loop>=3), segments>=8, total length<=12000. Air requires altitude
60..300. Ambient optionally accepts altitude 60..300; omit it for ground movement.
Ambient speed .5..160. Use ambient for decor-only wildlife: no roads, rails, runway,
grass clearing, vehicle control, impacts, foundations or physical contacts.
It follows terrain + optional constant altitude, including the loop seam.
Ground habitat footprints must stay dry and clear of solids. Compose wings/legs with
existing bounded swing joints; use slower ground speed to match their gait.
Use custom measurements for animal length/wingspan; do not infer size from a label.
Path-only width 16..120 is the full corridor width. Use surface=trail|cycle|paved
only with an explicit width. New dedicated paths should declare both. Reserve their
full width plus at least 8 units from racing-road curbs, water, physical props,
other ground routes and runways; validation adds conservative sampling clearance.
Do not cover a path with road, or place trees/benches on its surface. Place boarding
stops beside approachable dry ground. Use generous route extents for world activities;
keep objects at their measured sizes. Omit width/surface only for legacy shared paths.
Widen bends to keep the inside ribbon from folding; avoid turns sharper than 120 degrees.
The engine does not invent crossings or reroute invalid layouts.
Place uses exactly one of at or route; offset 0..2048 only with route;
scale .5..2; heading_deg -360..360 only for at placements (routes own heading). <=64 placements; scene <=24 resident mobile actors including controllable vehicles,
<=24 live joint assemblies including the standing engine character; reserve one slot,
so source objects plus the player vehicle may use at most 23. <=24 resident impact objects, <=128 resident potential fragments; see interactions for pooled static destruction,
<=16 steam emitters. Vehicle route actors need solid bodies without foundation/impact; compound contacts are allowed only on street/tram/rail NPCs;
ambient route actors require decor bodies instead.
One driving height per XY. No stacked roads or ground driving under bridges. Boats use the water bed,
and may pass under a deck only with full hull/body clearance. Boat exits require
real dry shore; never place a boarding point underneath a deck.
Hollow buildings/tunnels use separated contacts and overhead clearance.

## modules
PROJECT MODULES
asset local_id(module=library_id,object=exported_object_id); imports only an object.
Optional control=car|bicycle|skateboard|scooter|boat|plane adapts a COPY with an existing rideable seat to a validated driver profile. The exported template and other imports retain their original passenger capability. It cannot add a missing seat or bypass driver validation.
include district_id(module=module_id); includes that module's world declarations.
Use the asset alias for local place/object and world/player references.
Example: asset ball(module=props,object=festival_ball);
place courtyard_ball(object=ball,at=[300,400]);
The host supplies a closed map of module IDs to Dream 2 text. No file paths, URLs,
JS imports, fetches or generated execution. Only reference module IDs supplied
by the host; otherwise author a self-contained file. Object/material/constants
are local to a file. Asset imports do not add the library's example placements,
routes or terrain. Include adds placements/routes/water/layout, never symbols.
A file may import an asset and include the same library once; shared asset
libraries compile once. Cycles, duplicate included world IDs and multiple layouts
fail atomically. Diagnostics add module when the error originates in a module.
Per-file limits above still apply: at most 16 local objects + asset aliases and
16 includes, 64 placements, 12 routes, 8 watercourses. Split larger worlds into
district files. Across reachable files, including entry: <=32 files, depth <=8,
<=524288 UTF-16 characters, <=128 object definitions, <=4096 placements,
<=12 routes and <=8 water bodies. Legacy scenes cap 24 impact objects and 128 potential fragments. Pooled worlds
use the separate data/cache/active limits in interactions. Animated assemblies remain at 24. The whole project needs
exactly one world-owning layout for compileDreamScene; never split checkpoints or
terrain across district files. Final merged geometry must pass playability.

## interactions
DESTRUCTION EXTENSIONS
Bounce: knockable body; restitution in [0.1,0.9], lift in [0.05,0.8].
Break: solid body; speed 40..400, scatter 0..160, lift 0..180, spin 0..8,
lifetime 2..8. <=8 static fragments; fragment blocks cannot nest.
Whole-object impacts cannot have foundations, compound/offset contacts, seats or emitters.
One contact at [0,0,0] is allowed for break/topple; use it for a narrow pole while preserving body radius >=4. Topple uses that root body radius as its hinge envelope; it must clear the visual foot.
Prefer flat ground for scattering props; foundations cannot fill their downhill gaps.
Topple uses terrain-aware support and can fall on hills.

break(...,pattern=scatter|splinter|crumble) optionally chooses release motion.
Absent pattern preserves original scatter. Splinter throws wood parts forward;
crumble drops masonry near the contact with low lift, spin and rebound.
impact(mode=topple(speed=110,duration=1.1,lifetime=8)); topples the entire static
solid as one rigid fragment about the far edge of its body, away from impact.
If no part has fragment metadata, Dream 2 compiles all parts into one stable rigid fragment.
With explicit fragment blocks, all parts must belong to one group. duration .25..2; lifetime 2..8 and >=
duration+.8. Other whole-object impact restrictions still apply.
Whole topple may retain engine-owned part sway on a pooled static prop with
world(...,damage_pool=true). The same GPU phase, pivots, finishes and colour/shadow
motion survive release. Spin, roll, cloth, animated joints, break-zone motion and
animated scatter fragments remain invalid. No live rig or per-cell body is added.
Complete world and finite replanting example: examples/city-tree-replanting.dream.
zone facade(at=[42,0,0],radius=16,height=39,mode=break(speed=135,scatter=55,
lift=45,spin=3,lifetime=7,pattern=crumble)){ visual statements }
Zone at is an object-local cylinder base; visual coordinates inside are relative
to it. radius 1..64, height 1..160, offsets X/Z +/-64 and Y 0..128. Only break
mode is allowed. A zone may use fragments/groups/components/static joints;
fragments cannot cross zones. Up to 4 zones and 8 total released fragments per
assembly; keep the 32-part, reach and scene budgets. Zone blocks belong directly
inside an object. They cannot nest or appear in visual components, but use sites
inside them can compose visual components. Every zone owns at least one part;
retain structural geometry outside all zones. The object must be an upright
solid without whole-object impact, a seat, emitter or animated geometry. Core
contacts and foundations are allowed and survive section damage. Author core
contacts separately so an intact root cylinder does not block the intended
opening after a zone breaks. Terrain foundations stay intact.

SHARED INTERACTION RULES
rule wooden_tables(kind=table,mode=break(speed=90,scatter=62,lift=100,spin=4,lifetime=6,pattern=splinter)); declares an authoritative interaction for every object whose measure.kind matches. At most 16 rules, exactly one owner per category, in the entry file only. Loaded modules cannot declare rules. Apply across local/imported templates, placements and furnishing before object validation. A rule replaces local impact settings. A break rule replaces every existing break-zone impact when zones exist; retained core/foundations remain. Bodies, animation and fragment grouping must be compatible; incompatible assets fail compilation, never silently lose construction. Each placement has independent damage. Scene v1 interactionRules is optional for legacy data, defaults to []; serialized placements must match. Legacy scenes retain 24 reactive placements and 128 potential fragments; all templates retain <=8 fragments. Pooled worlds use the limits below; rules never bypass bounds. Select by measure.kind, never labels/position/randomness. custom is one catchall category, not separate bread/rock/ball types. Current live policies cover tables, benches, street lamps and trees; other categories keep authored defaults. Existing break/topple/bounce constructors only, no scripts or structural/material simulation. Complete example: examples/interaction-rules.dream.

POOLED STATIC DESTRUCTION
world(...,damage_pool=true) enables instanced static break/topple props across
linked placements and furnish. Intact geometry streams as ordinary scenery.
Keep existing source/project/4096-placement bounds; at most 128 distinct pooled
template records (not preallocated meshes), plus 24 resident impact objects and
128 resident potential fragments. Bounce props and partial building zones remain
resident. Active destruction is capped at 24 object assemblies and 128 pieces;
oldest cosmetic pieces yield when full but all damage remains persistent.
Mesh caches hold <=24 templates and <=128 fragment meshes, share geometry between
instances and evict unused data after ten simulation seconds or to make room.
No generated code, per-cell bodies, automatic damage or free repair.
Lamps can be pooled static props; their surface light pools turn off while broken
and return after repair. Use measure(kind=lamp,axis=y,meters=3.8); range 1..15 m.
The live 413 lamps share the entry's lamp rule and connected repair coverage.
All 345 trees share the tree rule; 106 have declared finite-sapling replanting,
including all 93 furnished street trees. The other 239 stay broken. Keep
actor/rig limits unchanged. Whole pooled static topplers allow only part sway;
their falling crown retains its original wind phase, material finish and shadow.
Omit damage_pool (or false) for the original strict budgets. Rest poses, ambient
motion and controllable parking cannot disable or acquire destruction implicitly.
See examples/streetlight-repairs.dream. Save format 10, simulation rules 15 preserve
registered r50 progress through a checked projection; unknown worlds stay separate.

## city
Urban layouts: street id(width=100,sidewalk=20,points=[[x,y],...],cycle_width=20);
Streets use open polylines in any direction, turns <=120 degrees: 2..16 anchors, segments >=80, width 60..180,
sidewalk 0..40 per side. Optional cycle_width 16..40 adds one lane per side outside
the carriageway, each with a 6-unit separator; sidewalks move outward. Use this for
connected city bicycle lanes, not isolated path loops. Intersections join the tracks
with painted crossings. All street components must reach the circuit or the street-only world spawn with full car clearance.
Reserve the entire riding width from solids and ground finishes. Water crossings
need explicit aligned bridges carrying carriageway, both lanes, separators and
sidewalks between rails. Street endpoints must extend 20 units beyond both bridge
ends. Streets do not create bridges, actor routes or traffic rules.
Scene limits: <=32 streets, <=120000 total street length. These are separate from
road's cyclic racing spline and route's moving actors/dedicated paths.
Painted surface id(color=#rrggbb,points=[[x,y],...]); fills a simple 3..64 point polygon.
Surface area <=1000000, extent <=2000. Split larger grounds. Never cover street carriageways.
Local surfaces precede included modules; includes follow include order. Later linked painted surfaces overlay earlier paint. Grounds follow existing terrain; they do not
flatten it or change physics. Use for courtyards, driveways, turf, courts and sand.
Explicit pedestrian paths: surface id(color=#bcb6a4,points=[[x,y],...],walkable=true);
Optional walkable defaults false. True requires a convex, clear path piece joined
at full width to existing sidewalks, crossings, entrances or interior pavement.
Join convex strips into bends and loops. No point-only joins, unsupported water,
rail/runway overlaps or bridge side entries; fit the full path between bridge rails.
Place benches, lamps and parking beside the path. It adds accepted pavement for
ambient walkers and existing work journeys, never road grip, flattening or actors.
Terrain finish can also be walkable, with no painted mesh. Existing surface and
navigation budgets still apply. Same-colored standard paving merges with entrances.
See examples/park-paths.dream. Ordinary paint alone is not pedestrian pavement.
marking id(color=#rrggbb,width=1,closed=true){point(at=[x,y]);...}
Marking blocks accept point/let/repeat; generate circles with sin/cos. 2..64 points,
closed needs >=3, width .5..12. Never repeat the first point at the end. No zero edges.
Scene limits: <=64 surfaces, <=128 markings, <=40000 total marking length.
Include district modules to merge streets/surfaces/markings as well as placements.
Keep all ground features inside world bounds. The full scene acceptance boundary
checks them after linking. The model still writes only bounded data.

CONNECTED CITY DATA
In street-only worlds, nearby junctions share an intersection area: crossing expansion
omits their short internal links and keeps zebras on the outer arms. Do not add
extra mid-junction zebras; overlapping parallel paint shares one stripe phase.
At junction=true, existing cycle_width ribbons continue across connected roads.
Ending cycle streets join the other cycle street's riding edge, or end on their
approach if no cycle facility continues. Engine-owned paint stays within existing
riding footprints and crossing-arm bounds. Do not add overlapping surface/marking
patches to imitate these connections. Centerlines, separators and stop bars clear
the cycle surface; zebra stripes overlay it. No traffic-priority rule is implied.
See examples/cycle-junctions.dream. Physical pavement and navigation are unchanged.
At a declared junction, a street returning exactly to its first point joins its cycle-paint corner inside
the existing riding footprint; no closed field is added to street.
junction id(at=[x,y]); binds one file-local point; <=128 per source. road and street
require exactly one of points=[[x,y],...] or via=[junction_id,...]. world.spawn and
bridge.from/to accept either an XY pair or junction ID. Includes never export symbols.
Keep the main road/street network in one file and reuse junctions for exact joins.
Street interiors use bounded miter joins; only the two ends have square caps.
Crossing paint clears centerlines, cycle glyphs and neighboring stop lines.
City sidewalks, cycle tracks and separators yield to the circuit carriageway.
Existing sidewalk strips across it become painted, walkable crossings with open
curbs and no center paint. Cycle symbols require their entire envelope to fit
inside a lane and outside crossing clearance; crowded symbols are omitted whole.
road.style=racing default; street makes neutral curbs and removes start paint.
site id(object=placement_id,kind=home|market|school|hospital|work|civic|park|station|airport|stop,
entry=[local_x,local_z],street=street_id,width=16,points=[[world_x,world_y],...],label="Garden park");
Optional label is 1..80 nonblank plain-text characters, independent of the object
template name. It names a destination without generating any activity or behavior.
Entry follows the owner's placement heading and resolved measured scale; points are
world XY and the engine prepends that entrance. 1..16 points; path width 12..40;
length <=800. End the full path width inside its named sidewalk. Keep the entire
path dry and free of other solid bodies. Every static measured building in a
site-authored city needs a site. <=256 sites. Stops alone may declare serves=[ids],
max 8 destination sites, all reachable on sidewalks/paths/crossings.
airport classifies a terminal destination for navigation. Author its buildings,
runway/apron surfaces, service access, aircraft and transit explicitly; the kind
does not generate them. Keep public walking paths and boarding clear of the runway.
crossing id(street=street_id,at=[x,y],width=24,junction=true);
At lies on the named centerline. Omit junction for a single crossing; true creates
crossings on all arms of the shared junction. <=64 declarations. Use junction
crossings to connect the pedestrian network. Short overlapping street ends fail;
use a shared junction instead of ending a branch a few units short of centerline.
route kind=street uses existing carriageways without paving; tram lays rails in
existing carriageways; walk uses the authored pedestrian network without paving.
street/tram validate the complete vehicle contacts on roads. Walk validates full
body clearance on sidewalks, paths and crossings. walk speed .5..160.
rail/tram optional gauge 10..24. No traffic avoidance, automatic pathfinding or
traffic-light solver. Use clear routes. Long bus/tram/train NPCs can use up to
8 explicit object-root contact declarations; contact cannot appear in repeat.
Inside route only: stop id(at=[x,y],wait_s=4,site=platform_site_id);
A stop is an anchor; <=16 stops among <=64 route anchors. wait_s .1..30. Site must
be within 120 units. street/tram/rail stops require stop or station sites; walk may
visit a destination. Shuttle returns visit stops in reverse order. Put the person's
full body inside the walking network when waiting; stop a few units before a path's
open endpoint. Keep paths attached to entrances and leave boarding/waiting space.
measure profiles also include bus x 6..18 m and tram x 10..35 m.
Compose buildings using shared wall/roof dimensions: roof base = wall top, glass
embedded in its wall, canopy touching wall and supported by posts that reach a
porch slab. Keep all architectural parts attached. Reserve schoolyards, market
squares, service aprons and entrance paths before placing surrounding housing.

Surface finish: surface area(points=[[...]],finish=terrain); defines bounded
work/activity coverage on the existing terrain, without a paint mesh or map
fill. Omit color for terrain finish. Ordinary surfaces default to finish=paint
and require color; explicit finish=paint is also valid. Natural coverage retains
cosmetic grass/flowers; furniture, habitats, physical support, road/water bounds,
clearance and pedestrian connections remain checked as before. It creates no
shortcut, flattened ground, collider or extra growth clock. It adds pedestrian
pavement only with explicit walkable=true, under the city path rules. Prefer terrain
finish for orchards and natural work grounds; paint real courts, squares and
paths. Existing surface bounds apply. See examples/orchard-replanting.dream.

## interiors
Request this feature for enterable buildings. Author one static ground-floor
interior per object: interior(at=[x,floor_y,z],size=[width,clear_height,depth]){
portal entrance(side=front,offset=0,width=4,height=6); }. Values are local units.
front=-Z, back=+Z, left=-X, right=+X. Offset follows X on front/back, Z on sides.
Keep a solid foundation, a matching rectangle floor contact whose top equals
floor_y, a matching ceiling contact starting at floor_y + clear_height, attached
visible floor/walls/roof and actual openings between contacts.
Tag shell parts with cutaway=roof|front|back|left|right. Leave contents and floor
untagged. No joints, seats or whole-building impact. At most 32 placed interiors,
4 portals each, using the existing 8 contacts and 32 parts per assembly.
Full scenes prove a clear 9-unit doorway, 20-unit headroom and approach steps <=4.
The same contacts govern walking, driving, props, NPC paths and sight for trade
and conversation. Narrow doors can block cars. A room owner may have a lamp;
its always-on pool fits only the floor, without wall lighting/object occlusion.
Repair/delivery grounds can name the placed building ID instead of another
painted surface. This does not add work, stock, staff or markets implicitly.
One supported ground floor only. Do not claim multiple floors, stairs or lifts.

## npcs
ACTOR OWNERSHIP AND NPC PROGRAMS
For every new general actor placement emit role=controllable or role=npc explicitly.
Use role=ambient only with the bounded population motion contract below.
role=prop is passive scenery; no route or behavior. Mechanical motion/destruction remain possible.
Template rideable.control is capability; place.role chooses ownership. controllable needs
that capability and starts parked, accepting player input after boarding. npc is engine-owned;
a driver-capable NPC cannot be boarded. Passenger-only NPC train seats remain usable.
Legacy omitted role infers control capability -> controllable, else route -> npc, else prop.
world.player remains the original car; no humanoid possession or generated input profiles.
behavior attentive_walk(start=walking){
 state walking(action=patrol){on notice(event=near_player,to=watching,radius=65);}
 state watching(action=idle,face=player){on leave(event=far_player,to=walking,radius=95);}
}
place neighbor(object=person,route=promenade,role=npc,behavior=attentive_walk);
Behavior IDs/references are file-local; state IDs and transition targets are behavior-local.
All states must be reachable from start. Transition IDs unique per state. Includes merge
program data; asset imports only object capabilities. <=16 programs and <=32 NPCs per scene.
1..8 states/program; <=4 transitions/state. action=idle rests joints; perform animates in
place; both hold route clock. patrol requires placement.route and resumes its clock without
teleporting. It animates only while moving. face=none default; face=player stationary only,
turning <=2.5 rad/s. Asset forward is +X. No arbitrary poses, scripts or callbacks.
on event=after requires only seconds (.1..300); near_player/far_player requires only radius
(10..240 units), using 3D distance <= / >=. Use separated near/far radii for hysteresis.
For player conversations use on talk(event=interact,to=reply,radius=55). interact requires
radius, 10..80 units; optional requires uses a personal economy milestone (request commerce context).
Optional interact-only shared_meals checks completed meals with this social NPC; request commerce context for its capability, consent, bounds and ownership.
Use requires only at the task receiving market actor: work/repair.market or delivery.to.
It checks the player account, never another NPC or the shared total. One grounded on-foot talk press selects one nearest eligible
NPC by 3D distance, with stable ID ties. Optional familiar=false matches a first meeting;
familiar=true matches a known person. familiar is only valid for interact. A successful
interaction marks that NPC known; this persists on R, render unloads and local save/load,
and resets on Start over. It is familiarity with the one player, not friendship or dating.
The renderer exposes T and a contextual button.
state reply(action=idle,face=player,say="Hello."){on finish(event=after,to=waiting,seconds=6);}
Optional say is 1..240 nonblank plain-text characters, idle/perform only. It is shown only
after interaction, within 80 units, for at most eight simulation seconds. Author the return
transition; repeated interactions may advance to another reply. No voice generation,
HTML, scripts, purchases, quests, money or relationship changes are implied by a line.
One transition/fixed tick, first matching declaration wins; state elapsed resets on entry.
Use perform -> idle -> perform with after transitions for timed routines. Existing joints
supply the motion; this does not generate sports rules, pathfinding or obstacle avoidance.
Explicit NPCs need version 2 decor/solid bodies, without foundations,
knockable bodies or destruction. Ambient routes remain decor-only; boat/plane NPCs need
routes in their domain. Stationary NPC footprints must be dry and clear. Preserve <=24 resident route
actors/controllable vehicles and <=24 live jointed assemblies including the player.
Runtime clocks are per instance outside Scene; pause freezes them; R preserves them and
Start over resets them. No model calls during simulation.

## population
CONTEXTUAL POPULATIONS
furnish id(objects=[object_ref,...],streets=[street_ref,...],spacing=340,setback=2,seed=41,facing=street);
furnish id(objects=[bicycle],sites=[site_ref,...],spacing=26,setback=4,count=6,seed=82,paving=#aaa99f);
Exactly one streets/sites array, 1..32 unique targets. 1..8 object refs, file-local or asset imports.
Street spacing 80..800, side=left|right|both (default both), relative to path direction.
Sites require count 1..12, spacing 12..800; follow entrance side, preserving access.
setback 0..120 beyond the pavement and full visual radius. facing=along|street|varied (along default; varied is seeded heading).
jitter 0...3 (default 0) varies longitudinal street or site-row spacing; seed integer 0..65535. No arbitrary scale jitter.
grounds=[surface_ids] explicitly permits those visual grounds; other authored grounds excluded.
Site-only paving=color adds parking aprons joined to pavement, within 64 scene surfaces.
Expansion runs after linking; complete visual footprints reserve roads, crossings, entrances,
bridges, water, ground infrastructure and existing objects. Skip blocked candidates.
Static templates unless bounded ambient motion is declared below: no proximity joints, knockables or emitters. Static break/topple props are allowed with world.damage_pool; rest, ambient and controllable modes still reject damage.
pose=rest explicitly bakes bone bindings and part/joint animation at authored rest transforms;
full geometry, material, measure, body and joint parenting survive. It never disables damage,
knockables, emitters or proximity interactions. The original template remains live.
place(...,at=[x,y],role=prop,pose=rest) also supports a single passive resting instance;
explicit prop required, no route or behavior. Resting props consume no NPC/live-rig slot.
on=verge (default) stays outside the sidewalk. on=sidewalk requires decor, setback=0,
no paving; full radius fits the outer sidewalk, leaving at least 8 units inside for walking.
Generated objects default to role=prop; motion creates role=ambient. furnish(...,role=controllable) requires rideable(control=...) on every template and emits parked=true.
For an explicit dormant ride use place(...,at=[x,y],role=controllable,parked=true). No route, behavior, pose=rest or ambient motion; no foundations, damage, emitters, lamps, humanoid or proximity joints. Furnish controllable parking cannot use on=sidewalk.
Dormant parking supports car/bicycle/skateboard/scooter. Boats and planes keep ordinary resident controllable placements with their existing water/air support.
At most 256 dormant vehicles, separate from the 24 resident route/controllable cap. Reserve ONE extra slot inside the existing 24 live-assembly cap for the occupied fleet rig; never instantiate all parked rigs. Original seeds and moved local poses stay instanced. Physics/ownership/moved poses remain in simulation and format 7 saves; R preserves parked poses, Start over resets them. No autonomous parking movement or damage. examples/parked-vehicles.dream is runnable.
<=32 rules, <=2048 candidates/rule, <=128 emitted/rule, <=1024 generated overall, also <=4096
scene objects. Output has no minimum guarantee; inspect compiled rule/district coverage.
AMBIENT GROUND MOTION (separate from general NPC programs)
furnish neighbors(objects=[person],streets=[avenue],spacing=160,setback=0,seed=31,on=sidewalk,motion=walk(speed=14,wait_s=1));
place hare_one(object=hare,at=[1200,1500],role=ambient,motion=roam(radius=90,speed=5,alert=70,flee_speed=30,recover_s=2,gait=hop));
place motion requires explicit role=ambient, fixed at, no pose, route or behavior.
Furnish motion creates ambient ownership; walk requires on=sidewalk. Cannot combine pose and motion.
walk needs a complete measured humanoid rig; speed 4..24, wait_s 0..5 default 1.
Engine caches portals from accepted sidewalk/crossing/entrance polygons; no paths invented across roads.
Full rest footprints stay on pavement, wait for approaching swept vehicles and locally space ambient walkers.
Engine-owned bounded passing/slowing/backing uses stable ID yielding; old overlaps separate without teleport.
Narrow bottlenecks may wait/back away. This does not add pushing or avoidance of decor NPC people.
roam stays within authored radius 20..180, speed 2..16; alert 20..180 uses 3D player distance.
flee_speed 8..60 and >= speed; recover_s .5..10 default 2 after separation; gait walk default or hop.
Animals avoid road/ground reservations, solids, water and world bounds. Blocked movement rests in alert.
Decor only; no seats, contacts, foundations, damage, emitters, lamps, part clocks, proximity or roll joints.
Validated humanoid bindings or swing joints animate rigid complete geometry in shared GPU instances.
<=192 ambient members, deterministic 20 Hz simulation with render interpolation; <=8192 cached walk nodes.
All populations remain resident; existing 32 NPC/24 route+control/24 CPU live-rig caps do not increase.
Pause freezes state, R preserves it, Start over resets it. Reduced motion rests limb/hop poses.
No generated scripts, general crowd physics, general NPC programs, signals or ecological simulation.
flock id(object=bird_ref,at=[x,y],radius=[rx,ry],count=16,altitude=65,speed=32,seed=101,flap_hz=3.2,flap_deg=18);
Passive decor only: no seat, contact, foundation, impact or emitter; measured horizontal radius <=20.
Radius axes 40..1200; count 1..32; altitude 60..300; speed 5..80; seed integer 0..65535;
flap_hz 0..6 default 2, flap_deg 0..25 default 12. Full habitat must fit world bounds.
Flight clears terrain/roofs; joints bake at rest; bounded local-Z flex animates wings.
<=16 flocks, <=256 decorative birds overall. Instanced GPU motion, no NPC/physics ownership,
no reactions or programs. Reduced motion freezes pose; complete populations stay resident.
place optional phase_s=0..3600 requires route and shifts the entire route clock, including waits.
offset stays distance along the route. No traffic avoidance or signal solver is added.
rideable(control=scooter) uses direct ground controls, standing rider and buffered Space jump.
Driver controls still need one solid cylinder without foundation/compound contacts/impact.
Passenger-only rideable(at=[x,y,z]) may use compound contacts on a solid transit assembly;
F boards without taking control. NPC route clocks keep ownership. No underground transit layer yet.

## lighting
DAY AND NIGHT
Optional once, beside world/road in the world-owning file:
daylight(cycle_s=600,start_hour=10);
cycle_s finite 120..3600 seconds per complete 24-hour cycle. start_hour finite 0<=h<24;
fractions allowed. Omit for legacy static daytime. Paused visual clock across all control
modes; pause/reduced motion freeze it, R preserves it, Start over resets to start_hour.
material glass(style=toon,colors=[#6c929d,#42616f],night=#f2bf7e);
Optional night=color adds dusk-to-dawn emission; daytime base paint remains. It follows
geometry through batching, instancing and fragments. No scripts, collider or point light.
Object-root only, one per assembly:
lamp(at=[0,38,0],radius=30,color=#ffd18a);
Position X/Z -64..64, Y 0..128. Radius 8..80 local units, scaled with measured placement.
Projects a soft unshadowed pool below source XZ onto terrain/deck surfaces; source height
is metadata, not optical falloff. It does not illuminate walls or calculate object occlusion.
<=512 placed pools per scene. Static props only; no route/NPC/control ownership, knockables
or player lamp. Whole-object break/topple is allowed with world.damage_pool; the pool
turns off while broken and returns after repair. Flocks cannot carry lamps. Use material.night for glowing windows.
One shared 2048 directional shadow map serves sun/moon; no per-lamp shadow maps.
NPC routines and transit continue; market hours use simulation time, even when reduced motion freezes the sky. No weather or astronomical calendar.

## scenarios
LOGICAL TASK SCENARIOS
An optional scenario block describes a logical graph environment, separate from 3D
movement/NPC clocks. Do not claim physical navigation, clinical or learning outcomes.
scenario morning(seed=7,max_steps=80){ ... }
Block-local commands, IDs unique across kinds, no callbacks or generated scripts:
item bread(label="Bread");
location shop(label="Shop",at=[100,200]);
link walk(from=shop,to=school,steps=3);
stock shelf(at=shop,item=bread,mode=source,quantity=8,price=2);
stock delivered(at=school,item=bread,mode=sink,quantity=0);
service session(at=school,consumes=material,produces=receipt,duration=4,capacity=1,fee=1);
agent courier(at=shop,budget=16,capacity=4);
objective breakfast(agent=courier,kind=deliver,at=school,item=bread,quantity=2);
All references need typed declarations in the same block. Links are bidirectional;
all locations connected. Steps/durations are integer ticks including the start tick.
Sources sell finite stock; sinks start empty/price=0 and never resell. Services
consume/produce exactly one unit, reserve capacity and charge at start, finish
later. Credits transfer to location treasuries; no negative inventory or free money.
Goals are deliver or produce and advance only on real transfers/completions by
that agent at that location; each unit is allocated once. Each completed goal
rewards one. Success terminates; reaching max_steps first truncates. Seed rotates
ASCII agent contention priority. Blocked capacity races are separate from violations.
One scenario/project, <=32 locations/items/services/objectives, <=64 links/stocks,
<=8 agents, max_steps 1..1000, seed 0..2147483647, coordinates 0..14000.
Stock quantity 0..1000, objective quantity 1..1000, price/fee/budget 0..100000,
agent capacity 1..100, service capacity 1..8, link steps/duration 1..100; integers.
Every agent needs a goal; delivery goals need a matching sink and production goals
need a matching service. An item needs finite initial stock or a production chain.
No guarantee of affordability/solvability. The current lab requires a standalone
scenario; it cannot yet apply logical actions to the rendered city's actors.
Keep unsupported user intent explicit instead of inventing vocabulary.

## voxels
VOXEL CONSTRUCTION
Use voxels id(material=mat,at=[x,y,z],size=[sx,sy,sz],grid=[nx,ny,nz],chunks=[cx,cy,cz]?){fill solid(from=[0,0,0],to=[nx,ny,nz]);cut opening(from=[...],to=[...]);}. Each voxels declaration is one rigid part. The block permits fill/cut, let and bounded repeat. shape=box is default; ellipsoid tests cell centers inside the from/to bounds. Operations run in order. Coordinates are integer half-open cell indices, 0 <= from < to <= grid; each axis 1..32, at most 32768 cells, 64 expanded operations, 8192 greedy surface quads. Assembly limits: 65536 cells, 1048576 fill/cut cell visits, existing 32 parts. Linked project: 1048576 cells across assembly definitions. Use equal size/grid ratios for cubic cells. Use separate volumes for materials. No raw voxel arrays, shaders, scripts or remote meshes.
Optional chunks must divide grid axes exactly into at most 8 nonempty pieces. Requires impact break or a break zone, no fragment wrapper. All pieces count toward existing 8 fragments per assembly, 24 reactive placements and 128 scene fragments. Unchunked volumes can use normal fragment groups/topple. Voxel parts disallow deform, cloth and part motion; use rigid joints for animation. Explicit body/contact cylinders remain the physics geometry: carved holes do not create traversable openings, editable terrain or tunnels. The live city uses the optional world construction policy below.

Construction: silhouette and measure first. Doors/window heights follow usable floors; glazing must remain visible through carved frames. Roofs meet walls, porch posts meet base/canopy, gutters meet leaders. Rolling tires/hubs stay coaxial, bogies support their shell, and rideable seats must fit an independently measured rider. Check transformed multi-angle renders, not only schemas. Checked live constructions: examples/terraced-house.dream, examples/city-bus.dream, examples/cabin-launch.dream.

WHOLE-WORLD VOXELS
For a complete world, put voxel_world(object_cell=1,ground_cell=8,height_step=1); beside world/road in the owner file. Exactly one declaration; object_cell .25..4 local units, ground_cell exactly 4 or 8, height_step .5..1. The compiler applies it to all linked templates, furnishings, player and flocks. Continue writing part/beam as compact shape stamps; the engine constructs their occupied cells, fits the authored envelope, and retains material/joint/fragment ownership. Undeformed prism/pyramid stamps and explicit faceted cylinder/cone/icosphere stamps retain exact planar boundary contours, including thin roof shells; curved/deformed stamps use sampled continuous contours. Explicit voxels/fill/cut remain exact and keep existing budgets. Ground and infrastructure use resident column tiles; paint keeps fine cells/layer separation and water keeps rigid column wave anchors. Fixed construction resolution, no camera LOD. Physics remains explicit contacts plus the smooth driving heightfield. No editable terrain, automatic destructibility or per-cell physics. Do not output voxelSize/voxelWorld compiler metadata in source.

## sports
SPORTS PRACTICE
sport id(kind=football|basketball,surface=surface_id,ball=placement_id,targets=[first,second],target_at=[x,y,z],target_size=[width,height]); connects existing world data after linking. At most 8 grounds, each with its own non-overlapping dry surface and distinct bounce ball. Ball is a static prop with a round knockable body: world radius .5..3, height twice radius. Use measure(kind=custom,axis=x,meters=.22/.24) to resolve real ball size from a local body(radius=4,height=8); do not lower legacy body bounds. Targets are two static upright assemblies at least 64 units apart; target_at and target_size use their local units and follow placement heading/scale. Football target is a grounded opening 6..120 wide and 4..50 high, local +Z points out of the field, opposing target normals. Basketball target is a clear X/Z ring diameter 2.5..12, fitting the ball, at height 16..50; local +Z points into the court. Target anchor must lie in the actual assembly bounds and within 32 of the surface. Surface sampled height variation <=3, no water. Existing object/reactive budgets still apply. Engine owns walk-up dribbling, charged shots, scoring, recovery and camera; no generated controller code. Optional bounded team matches are described below; fouls and bank-shot backboard physics remain unimplemented. Complete source: examples/sports-practice.dream.

Optional sport block: exactly team home(...) and team away(...), each role=npc with exactly one object=ref or objects=[1..4 refs]. Team templates must be complete upright measured person decor humanoids, world radius 2..8, height 12..28, all 12 explicit bones, no foundation, contacts, seats, rideable, lamps, emitters, damage or other motion. sport.team_size=2..6 (default 6) includes the player on home; duration_s=30..900 (default 180), score_to=1..21 (default 5). Team style=balanced|press|counter and skill=.3..1 are bounded deterministic tactics data, not scripts or model policies. Optional members=[stationary NPC placement refs] reuses their identities with the team template; no routes, commerce or conversation. Home can name at most team_size-1 NPCs, away team_size. The member ID player is reserved for the active player. Remaining identities derive from court/roster ID, side and index. Keep all existing and generated identities inside the shared 32 NPC cap. Optional roster=stable_id shares one physical squad across grounds with identical team sizes/member lists. Only the latest joined venue displays that squad; venue assembly is an arcade transition, not pedestrian travel.

Football keeper=0..5 selects one NPC index on that side, default 0; keeper_object=complete_humanoid supplies an optional distinct kit. Basketball rejects keeper fields. Optional football net_depth=6..64 is target-local Z extent: author matching triangular side/back net from top mouth to ground behind it. Engine contains full ball spheres against the side and sloping back planes, leaving the mouth open. No per-thread contacts. Match courts require a rectangle >=108 by 70 world units aligned with the targets. N joins/rests/resumes or starts a new round; J charges/releases shots; K passes, calls or tackles based on current ownership, distance, facing and a .6s tackle recovery. Both sides chase, pass, intercept and shoot with one ball owner; keepers defend near their own goal and distribute catches. Tactics run at 20 Hz, ball/movement remain fixed step. Leaving the court rests match time/poses; pause freezes all time; R preserves results; Start over resets. Only one match can play. Match records/possession/poses/results survive saves. GPU athlete instances use the complete authored rigs in color/shadow passes without raising existing CPU joint, route or ambient caps. Full source: examples/team-sports.dream. No fouls, offside, general crowd physics or competition rulebook.

## commerce

Business ownership: market(...,owner=account_id,sale=15){lot(...);}
owner references an existing personal account, separately from the counter actor.
sale is an optional integer 1..1000000, requiring a non-player initial owner.
The quote is sale + current available company cash. A free standing, dry, grounded
buyer in reach/sight purchases once while the counter is open and staffed; pay
the seller account, never the acquired treasury. Stock, workers and commitments
stay in place. No resale. Only the current owner may deposit/withdraw positive
whole credits locally, even when closed; protect market refund/invoice and account
pending wage headroom. No minted income, generated callbacks, role changes or
new actor/rig slots. R, pause, streaming and saves retain ownership and capital;
Start over restores the initial owner. Format 15/simulation 23 validates r65
before adding only its zero-funded seller and initial depot owner; keep old slots.
See examples/business-ownership.dream. Hiring, price policy, loans, property deeds
and starting a new business remain separate.

Shared social meals: social id(good=food,seats=[bench],on=ground,grounds=[extra],eat_s=8,cooldown_s=600,max_fullness=80,markets=[counter]);
account(...,social=id). At most 8 plans; 1..4 unique furniture placement IDs,
each with >=2 slots. Positive food, eat_s 1..12, cooldown_s 30..86400 (default 600),
max_fullness 0..100 (default 80). Only stationary complete humanoid decor NPC
programs with world body radius <=8 and height <=32; actual body-sized paths
reuse accepted pavement and bounded convex grounds (4096 local samples,
8192 nodes, 32768 links, 128 waypoints). No new NPC, body or rig slots.
The seated player presses Y, after meeting the person with T, within 80 units
and clear sight. Busy, too-full, unknown, cooling-down or soon-due staff decline.
Reserve two owned food units, their refund capacity and an adjacent slot.
The person walks over. Consume once after both spend eat_s together; update both
fullness values and this NPC's completed-meal history. Leaving, F, R, end meal,
broken furniture or a due shift refunds both portions once and returns the person
home before their routine resumes. No completion credit for an interrupted meal.
Pause, streaming and saves retain the activity and history; Start over resets.
Optional on.shared_meals is an integer 1..1000000000 on event=interact only;
it gates dialogue on completed player meals with that particular social NPC.
No authored affection counters, dating, generated callbacks, free food or offline
progression. Registered save upgrades retain prior resources and history.
Complete example: examples/shared-meal.dream. Guide: dream/social.md.

NPC HOSTING
Optional social.markets=[counter,...] uses 1..4 unique priced-food counters; at
least one must be within reach of the NPC's authored work placement. No new
shopping route is implied. A known host can buy two real portions with its own
credits while an existing counter is open/staffed; capacity >=2, whole-purchase
funds/stock/headroom and ordinary sight/range apply. No money or food is created.
At an eligible paired seat, an off-duty host can offer a 30-second invitation to
the seated player. Y accepts, X declines. One pending offer globally; it reserves
a seat while food remains in the NPC bag. Acceptance escrows both portions from
that host. Interruption refunds that donor once. Decline/expiry keeps purchases
and releases the seat. cooldown_s also bounds repeated offers, remembered per
account. Consent, shift-return margin, fullness, first meeting and shared history
use the existing social rules. Pause freezes offer time; R ends it but retains
its cooldown/history; save/streaming preserve it; Start over resets it. No NPC
invites another NPC. Omitting markets retains player-funded sharing.

Optional market hours=[6,22] means daily [open,close); hours=[22,6] spans midnight.
Use two finite different endpoints: 0 <= open < 24, 0 <= close <= 24. Omit hours
for all-day service. Requires world daylight(cycle_s,start_hour). Economic service
uses simulation time, independent of the paused/reduced-motion visual sky clock.
Player and NPC buy/sell, new work, supplier pickup and destination handoff share
the counter check. Committed work finishes after closing; owned food, refunds and
local repair services remain usable. Couriers already traveling wait at closed
counters, retaining real cargo/escrow and retrying after opening. Meal customers
skip closed shops and return empty-handed if closing occurs before purchase.
Hours alone do not add staff travel. Add an explicit shift plan below; no idle wages or offline catch-up.
See examples/market-hours.dream. Format 12/simulation 19 registers r61 by removing
only market hours; retain all saved fields, clocks, seats, meals and resources.

Use shift id(market=counter,rest=[x,y],on=rest_ground,grounds=[extra_ground],lead_s=15);
and account(...,shift=id) for physical daily staff attendance. At most 8 plans,
one NPC per plan. The market needs explicit hours; lead_s is 0..120 and strictly
shorter than its closed interval. Rest is at least 16 world units from work.
The actor is a stationary measured-person decor NPC with a program, no route,
meal, repair or delivery policy. shop and matching production may coexist;
operated counter and every assigned job must use shift.market. The work placement
must be in counter reach. Paths use the actual body, rounded upward to .1 units,
with radius <=8 and height <=32. on plus 0..7 unique convex grounds share 4096
local samples; existing pedestrian nodes, links, waypoints and actor budgets stay.
Finish committed production before leaving. Walk to rest after closing and start
returning lead_s before reopening. Reversing a journey preserves physical position.
A counter owner must reach the original work anchor before service resumes, even
if its scheduled opening has passed. Player/NPC trade, new production and cargo
pickup/handoff share this rule. Couriers wait with their escrow. At rest, staff can
talk and remember meetings through existing NPC programs; walking pauses those
clocks. No idle wages, employment contracts, homes or weekly calendar are implied.
Persist out/rest/in pose, path, speed, distance and retry time. R and streaming
retain them; Start over resets. Format 13/simulation 20 validates the registered
r62 world before retaining every saved field/clock; it splits the existing school
path without changing its footprint and centers the teacher on the entrance.
See examples/staff-shifts.dream.

One optional economy() block owns goods, accounts, markets and work in the playable
3D world. This is independent of logical scenario/stock/service declarations.
Use good(label,food=0); account(actor,credits,capacity,satiety,drain_s,shop=false,shift?,work?,works?,repair?);
market(label,actor,credits,radius,hours?,owner?,sale?){lot(good,quantity,limit,price?);} and
work id(label,market,input,take,output,make,seconds,pay,effort,capacity,target);
For multiple inputs omit input/take and use a work block:
work id(label,market,output,make,seconds,pay,effort,capacity,target){
 ingredient(good=first_good,take=1); ingredient(good=second_good,take=2);
}
Use exactly one form. A block has 1..4 unique ingredient goods, no IDs, no empty
block, and no input equal to output. Each positive integer take fits an existing
lot at that market. All ingredients and all refund space reserve atomically;
a shortage changes nothing, cancellation returns every input, completion consumes
once. The same rules apply to food recipes and manufactured repair supplies.
Use examples/multi-input-work.dream. Existing scalar input/take work stays readable.
Labels must contain nonblank text. Every declaration except economy and ingredient needs a stable ID. Scope IDs are unique; good IDs
and lot goods must agree. One economy per linked project, with exactly one player
account. Other account actors are existing role=npc placements. Markets and production
workers must be stationary NPCs. NPC shop=true buys and eats food at satiety <=40;
NPC work refills output up to target. Alternatively works=[advanced,basic] is an
ordered list of 1..4 unique work IDs, exclusive with work, repairs and deliveries.
Try the first eligible job below target; no extra actors, commitments or free stock.
Player accounts never act automatically.
NPC meal trips use meal id(good=food_id,markets=[first_shop,second_shop],on=home_ground,grounds=[extra_ground],eat_s=4,seats=[bench_placement]); and account.meal=meal_id.
Optional seats lists 1..4 unique static furniture placement IDs. Seated customers
require complete humanoid bones. After purchase, reserve a reachable free slot,
walk to its approach, sit and eat; release before returning home. Shared claims
include the player and customers walking to seats. Full/broken furniture falls
back to standing, retaining the purchased food. No queues or table service.
At most 8 plans, 1..4 unique ordered markets, a positive-food good with a priced
lot in every market, and eat_s=1..12 seconds. on plus 0..7 unique extra convex
work grounds share the 4096 local-sample budget and accepted pedestrian network.
A meal account is a measured person decor NPC with a program, optional walk route,
no counter operator role, and no shop/work/repair/delivery policy. Hungry at <=40, it
eats carried food first; otherwise it walks to the first stocked affordable shop
with a clear outbound/return path. No reservation before arrival. The shared buy
transaction rechecks stock, funds, bag and treasury. Failure returns empty-handed,
without refund or pay. Success waits eat_s, consumes its owned unit once, restores
fullness, then returns to the captured routine position. Program clocks pause
through travel/eating/return; moving transit/player contacts can cause waits and
bounded replans. Save paths, timers and ownership outside Scene. No item bodies,
new rigs, queues, generated navigation or offline catch-up. See
examples/meal-trips.dream. Compose works=[pack_lunch,bake], account.deliveries
and meal for a finite staffed business; see examples/market-production.dream.
Courier/meal scenes prepare pedestrian routing independently of repairs or ambient
walkers. Format 11/simulation 17 preserves registered previous worlds, all personal
records and active tasks, without new money/stock or live-city graph rebasing.

Use milestone id(label="Bake bread batches",kind=work,task=bake,count=3); inside economy.
At most 16; kind=work|delivery|repair references an existing matching task, count
integer 1..1000000000. Optional work.requires=milestone_id checks the acting account.
Work prerequisite cycles fail. Only actual paid completion, delivery handoff or
successful repair increments personal history; starting, cancelling, collecting,
NPC completions and shared totals never qualify the player. Optional on.requires
is interact-only and checks the player; after linking every using placement must
be the receiving market actor of that task (work/repair.market or delivery.to).
Milestones award no goods/pay and execute no code. Existing bounds stay fixed.
Personal counters plus unassigned history equal global counts. Save format 10,
simulation 15 preserves old totals unassigned and starts personal records at zero;
old active work earns its owner credit only on completion. Start over resets all.
See examples/work-progression.dream. This is task recognition and earned work,
not a friendship score, qualifications in the real world or generated dialogue.
Prices/pay/quantities/capacities are bounded integers. No price means an ingredient
that cannot be bought or sold. Trade is one unit at the listed price in either direction, with stock, carrying and treasury checks. Work reserves input, wage and output room atomically; leave
range or cancel to refund without output/pay. Completion spends effort and moves
reserved wage to the worker. Food restores bounded satiety; drain_s is simulation
time only. Limits and ranges are in contract.commerce; preserve finite stock,
conserved money/material, one job per account, shared capacity and saved clocks.
No scripts, free restocking, offline catch-up or claims of nutritional realism.

Use delivery id(label=...,from=source_market,to=destination_market,good=...,
quantity=2,pay=5,price=3,capacity=1); inside economy(). At most 16 contracts; quantity
integer 1..32, pay integer 1..1000000, capacity integer 1..4. Markets must have
non-overlapping interaction areas and both must stock the named good with enough
capacity. Optional price is a per-unit supplier payment, integer 0..10000 (omitted means 0).
Quantity*price+pay must fit 1000000. Collection reserves source goods, destination
invoice plus wage, supplier treasury headroom and both shelf capacities.
Completion pays the source business its invoice and the courier its wage; cancellation
returns the invoice as well as cargo/pay. No player purchase is required. Cargo is separate from owned inventory but counts toward carry limits.
One work/delivery/repair commitment per account; sealed cargo cannot be sold or eaten.
The player may travel in vehicles and must hand over on foot at the destination.
Completion transfers goods/pay once; cancellation anywhere returns reservations.
No deadline, offline travel or free supply. NPC walking resupply uses the explicit contract below.
NPC customers can buy/eat delivered food through the same market transactions.
Owned food can be eaten on foot during a delivery; sealed cargo is never food inventory.

Use repair id(label=...,market=supply_market,on=work_surface,kind=table,
input=kit,take=1,seconds=8,pay=4,effort=5,dispatch_s=12); inside economy.
At most 8 services. on is an existing convex ground surface. Optional
grounds=[park_seating,station_seating] adds 1..7 unique convex surfaces, excluding
on. All grounds together are capped at 4096 local samples at 12-unit spacing.
With grounds, the engine joins them using accepted sidewalks, crossings and
entrance paving; bridges require supported sidewalks. Complete-world acceptance
checks every eligible target from every worker home. No connection means rejection.
Routing has at most 8192 nodes, 32768 directed links and 128 saved waypoints.
Request context features commerce,city when authoring the grounds/infrastructure.
Without grounds or streets, the original on-only local behavior remains unchanged. Supply vendor and stationary worker home must lie in
it; home must be within market reach. Choose exactly one of kind=table or
kinds=[table,custom], a nonempty unique list from measure kinds. Both select
measure.kind, never labels. The same service applies to every eligible category.
Eligible ground-accessible break/topple targets and zones retain their original
geometry/contacts after repair. Input must fit an existing lot; take integer
1..32; seconds 1..120, pay positive integer <=1000000, effort 1..50, optional
dispatch_s 0..120 default 12. NPC account.repair=service excludes account.work,
route/ambient motion and market ownership. Player accounts never automate.
The engine owns bounded walking paths (128 saved points), notices, one claimant
per target, supply/wage reservations, work progress, obstruction waiting,
consumption counters and return home. Player takes the same job at the market,
stands beside the damage to work, or cancels/refunds. Pause freezes; R and saves
preserve; Start over resets. No scripts, arbitrary off-network dispatch, ladders, free kits,
implicit plant growth or destruction. See examples/market-repair.dream, examples/market-maintenance.dream and
examples/neighborhood-repairs.dream. Worker topology is derived/prepared by the
engine worker, never model-authored or saved graph data. Journeys advance in
resident simulation time; walking across a city may take several minutes.

Repair street coverage: add streets=[avenue,high_street] and optional verge=24 to
repair(...). Streets are 1..32 unique existing IDs with sidewalks >=8 units wide.
The service selects its existing measured kind/kinds near those sidewalks, plus
its existing on/grounds targets. Verge is 0..128 world units, default 24, and needs
streets. The engine derives short dry approaches only near matching damage
contacts; it never creates roads or paving. Keep all riding surfaces, circuit and
water clear, and supply real crossings at street intersections. Approaches join
the public network with full-cylinder inset portals. At most 512 street targets
and 2048 access pieces per service; 4096 local samples, 8192 derived graph nodes,
32768 directed links and 128 saved waypoints remain. Complete-world acceptance
rejects any unreachable target. Source/saves never supply graph edges. Existing
workers, kits, wages, ownership and per-target claim rules apply. Use
examples/street-verge-repairs.dream and request context features commerce,city.


Tree recovery: repair(...,kind=tree,regrow_s=180,seed_scale=.15) plants a young
replacement after paid work rather than restoring the mature tree immediately.
regrow_s is 30..86400 simulation seconds; seed_scale is 0.1..0.5, default .15, and
requires regrow_s. Planting requires kind=tree and whole toppling prop targets
with a centered base body, without foundations, zones, seats, emitters or lamps.
Use an explicit finite sapling good and a real supply-market lot. The same player
and NPC jobs reserve inputs/pay, wait for space, consume once and return home.
At most 32 growing plants plus committed planting jobs; each job reserves one slot.
Growth runs at the resident commerce cadence, scales full visuals and contacts,
waits for obstacles and survives R, render eviction and saves. Hitting a growing
tree breaks its current size and loses that sapling; consumed supplies are not
refunded. Mature completion frees its growth slot. No offline growth or biology claim.

NPC account(...,repairs=[furniture,trees]) chooses from 1..4 unique service IDs in
priority order, skipping unavailable work. It excludes repair= and work=; the
legacy single repair= remains readable. One active commitment per worker. Homes
must be inside each service's on surface and within its supply market's reach.
Notices identify the selected service as well as the target. Touching work grounds
join through full-cylinder portals; keep real gaps, roads and water impassable.
Use examples/orchard-replanting.dream; request context features commerce,city.


NPC resupply: account(...,deliveries=[kits_run,saplings_run]) accepts 1..4 unique
ordered delivery refs, exclusive with automatic work and player accounts, compatible
with repair/repairs. A courier is a stationary non-vendor NPC with home in the
receiving market reach and delivery on ground. Add delivery(...,on=work_ground,
grounds=[depot_yard]); grounds optional, 1..7 unique convex surfaces excluding on.
The supplier may already be on accepted pedestrian pavement, needing no extra
ground. All declared grounds together retain 4096 local samples. They add no paving.
compileDreamScene checks pickup, handoff and return paths from every assigned home.
Use accepted sidewalks/crossings/bridge pavement, never road or water shortcuts.
Food choices and available repairs precede deliveries; a whole shipment must fit.
Pickup intent reserves one shared contract slot but no stock, funds or shelf room.
Recheck collection on arrival through the player transaction; if unavailable,
return empty-handed without refund or wage. Cargo uses the same sealed reservation,
invoice and pay. Handoff settles once, then walk home. One commitment owns pose and
pauses the NPC program. Live contacts may block the route; wait/retry without teleport.
Pickup/carry/return state survives R, streaming and saves, with no offline travel.
Identical ordered delivery grounds share one prepared graph; retain 8192 nodes,
32768 links, 128 saved waypoints and existing actor/rig caps. No courier vehicle AI,
item bodies or upstream production. See examples/courier-resupply.dream.

Pickup/handoff approaches must be less than 4 world units above/below their vendor. Author a level connected approach; steep unsupported counters are rejected.