3D Synthezier

The rectangular city at night under its single light source: four square towers with lit facades facing the light and gray shadow sides facing away. The city1.3d script places four building objects (three of them rotated with xz90) plus rows of cars parked at various heights. Each building is 32 stacked storey_square floors crowned by a randomly picked roof variant (roof, roof2 or roof3).

A close aerial view of a roof-parking variant: the flat stone slab carries buses and police cars (bus and police sub-objects) next to a tilted solar panel and pipes. Facades are assembled from window_big and window_small panels - wall_brick quads with recessed glass. On large flat surfaces like this roof the per-texel GI lightmap grid is visible up close.

A distant view of the hexagonal city at dusk: a cluster of hexagonal towers crowned with translucent domes rises from a low-poly plain under an orange sky. The city2.3d script builds this by stacking block sub-objects and placing stone ring and glass dome (dome) objects at hexagon vertex offsets - multiples of sin and cos of 30 degrees - scaled twentyfold with the x*20 z*20 size modifiers.

A closer aerial look at the hexagonal tower cluster, showing the blue-tinted glass domes sitting on their stone rings with roads threading between the towers. Each dome and ring is a separate sub-object pulled from the include directory and positioned by the use command, while materials are switched between stone (stone) and glass_transp with mtl commands before each placement.

Street-level view inside the hexagonal city: low-poly cars in blue, yellow and red dot the roads between the towers. The vehicles are the same car sub-objects reused dozens of times with different x, z and y offsets and xz rotations, illustrating how the language composes complex scenes from a handful of cached primitive objects.

Everything about the geometry commands fits into one tiny example. An object file tent.3d (reusable, so it starts with origin and has no out or end):

# A tent: floor, two roof slopes, two triangular ends.
origin

# ground rectangle
p 0 0 0
p 4 0 0
p 4 0 6
p 0 0 6

# ridge line
p 2 3 0
p 2 3 6

mtl stone
f 0 1 2 3
f 0 1 4
f 3 2 5

mtl roof
f 0 4 5 3
f 1 2 5 4

A scene file street.3d that stamps out three copies of it with different transforms (the ~ prefix loads from the program directory instead of the include path):

# Three tents in a row: same object, different transforms.
out street
use ~tent
use ~tent x+8 z+2
use ~tent x+16 y*1.5

Running crtbasic 3dparse.bas --headless --command=street (DOS: qb /RUN 3dparse.bas /CMD street) produces this exact street.obj, unedited:

mtllib result.mtl
v  0  0  0
v  4  0  0
v  4  0 -6
v  0  0 -6
v  2  3  0
v  2  3 -6
v  8  0 -2
v  12  0 -2
v  12  0 -8
v  8  0 -8
v  10  3 -2
v  10  3 -8
v  16  0  0
v  20  0  0
v  20  0 -6
v  16  0 -6
v  18 4.5  0
v  18 4.5 -6
usemtl stone
f  1 4 3 2
f  1 5 2
f  4 6 3
f  7 10 9 8
f  7 11 8
f  10 12 9
f  13 16 15 14
f  13 17 14
f  16 18 15
usemtl roof
f  1 4 6 5
f  2 5 6 3
f  7 10 12 11
f  8 11 12 9
f  13 16 18 17
f  14 17 18 15

Reading it line by line teaches most of the format:

• 18 vertices = 3 instances x 6. Instance 2 is offset by x+8 z+2, instance 3 by x+16, and its y*1.5 scale stretched the ridge from y=3 to y=4.5.
• Z is negated on output: tent z=6 becomes -6 in the OBJ. The scene language and Wavefront OBJ disagree on handedness; the parser flips Z while writing.
• Faces come out with their vertex order reversed: source f 0 1 2 3 is written as f 1 4 3 2. Flipping Z is a mirror, and reversing the face restores source-space winding (see f).
• Faces are not grouped by tent. All stone faces (floors and ends of all three tents) come first, then all roof slopes: output is grouped by material, because faces are buffered per material.
• Indices run from 1 to 18 continuously across instances - OBJ numbers vertices from 1, while f lines in the source count from the most recent origin starting at 0.
• The first line references result.mtl, the shared material library that must sit beside the .obj file.

out  file

Opens file.obj for writing and emits the mtllib result.mtl header line. Use it exactly once, as the first command of the scene file, before any geometry: every vertex and face written afterwards goes to this file. All output is buffered, so the file only grows in blocks while the scene executes (see Parser internals).

Both city scripts begin with it:

# small city block
out city1

use building xz90
...

origin

Records the number of vertices defined so far. From then on, f indices count from that point starting at 0.

This is the trick that makes objects reusable: an object file starts with origin, so its faces only ever reference its own vertices, no matter where in the scene the instance lands. The parser adds the recorded offset (and OBJ's 1-based numbering) when writing, so the same source line f 0 1 2 3 becomes f 1 4 3 2 in the first tent and f 7 10 9 8 in the second.

A scene-level file that only composes objects (like city1.3d) never needs origin - only files that define raw faces do.

Legacy spelling: here - the parser accepts both.

p  x y z

Defines one vertex. Before the coordinates are stored, every transform on the active use stack is applied to them, so a p inside an included object lands wherever the instance was moved, rotated or scaled to.

• Coordinates are numbers: integers, negatives and decimals all work (p 0.5 -0.5 -0.01 appears in window_big.3d).
• Words may be separated by spaces or tabs; several include files use tabs.
• Vertices are numbered in definition order across the whole run and stream into the OBJ as v lines in that same order, with Z negated.
• Buffer: 1000 vertices are held in memory, flushed in definition order whenever the buffer passes 900 entries. Flushing changes nothing about indices.

f  p1 p2 p3 p4

Defines one face - a triangle when p4 is omitted, a quad when it is present. Indices count from the most recent origin, starting at 0; in the OBJ they appear absolute and 1-based.

• Winding is not preserved verbatim: vertex output negates Z (a mirror), so faces are emitted in reversed order to keep the source-space orientation intact. Net effect: author faces so that the right-handed normal cross(v2-v1, v3-v1) points out of the solid, and that is what the OBJ will contain.
• Instances placed with a negative scale (e.g. x*-1) are mirrored; the parser tracks the parity of negative scales on the transform stack and flips winding back automatically. Odd count of negative scales = mirrored = winding flipped once more.
• Faces are buffered per current material (100 entries), then written as a run behind a single usemtl line. This is why OBJ output is grouped by material rather than by object.
• Indices may reach back past the current object - they are just offsets into the global vertex list. prism4.3d uses this together with if to optionally cap a prism: if 0 f 0 1 2 3.

mtl  material

Selects the material that following f faces are stored under. The first use of a name appends it to the material table (up to 50 materials); using it again later just re-selects it.

Materials are only names at this stage - their colors and textures live in the shared result.mtl library that the OBJ references on its first line. A name missing from result.mtl still ends up in the output; the renderer will complain about it, not the generator.

Real usage from city2.3d, switching between stone and glass before each placement:

mtl stone
use ring x*20 z*20 y+26
mtl glass_transp
use dome x*20 z*20 y*10 y+26

use  object xz45 xy20 x+3 y*2

Instantiates another .3d file: its lines are executed right there, as if typed in place (then the instance picks up its transforms). Legacy spelling: obj - the parser accepts both. inside the current context. Objects instantiate further objects freely - city1.3d calls building, which calls storey_square (a floor) thirty times, which calls wall_square / wall_hex (walls), which call window_big / window_small (windows).

pickmtl  material ...

Selects one of the listed materials at random - each listed name has the same chance, so repeating a name weights it (pickmtl a a b picks a two thirds of the time).

Legacy spelling: mtlrnd - the parser accepts both.

Used for variety without extra scripting. Every window block in the cities picks its glass tone per instance (window_big.3d / window_small.3d):

pickmtl glass_light glass_dark

That one line is why some windows render as light glass and others as dark glass across the towers. The dice are seeded from the clock (RANDOMIZE TIMER), so every generator run produces a slightly different city.

pick  command1 command2 ...

Executes exactly one of the alternatives, chosen uniformly at random. Because spaces separate words, a caret ^ stands in for a space inside an alternative: use^car^xz91 executes as use car xz91.

From include/wall_hex.3d - a wall randomly gets a police car, a plain car, a bus, or (most often) nothing at all, thanks to dum padding:

pick use^police^xz-92^z-6^x+1 dum dum dum dum
pick use^car^xz91^z-10^x+5 dum dum dum dum
pick use^car^xz87^z-8^x+19 dum dum dum dum
pick use^bus^xz-90^z-12^x+10 dum dum dum dum dum dum dum dum

The first three lines each give a 1/5 chance of a vehicle, the bus a mere 1/9. include/cars.3d uses the same trick at 1/2 to sometimes swap a car for a police car. Like pickmtl, the choice is seeded from the clock.

dum

Does nothing - and that is the point. Any word that matches no command is silently ignored, so an unrecognized word like dum is a legal, harmless line. Its one real use is padding the odds inside pick lists: each dum is one more chance that nothing happens. It is a convention, not a command - banana would work exactly the same.

set  variable  contents

Stores contents in variable variable. Variables are numbered 0-100 (101 slots) and hold a single word.

Variables are global: once set, every line executed afterwards - in any file, at any nesting depth - sees the value, until something overwrites it. Callers use this to parameterize the objects they instantiate; include/hexcluster.3d configures the hexagonal prism it is about to include:

set 1 stone
set 2 0
use prism6 x*20 y*5 z*20 y+21

Here variable 1 picks the body material and variable 2 tells prism6 whether to generate end caps (see ifeq and if).

anycommand %1 anything

Before a line executes, every word of the form %n is replaced textually with the contents of variable n. It works in any position of any command - material names, coordinates, transform operands:

mtl %1
use prism6 x*20 y*5 z*20 y+21

Since set values are single words, a substitution always yields exactly one word.

ifeq  flag string1 string2

Compares the two words (after % substitution) and sets condition flag flag when they are equal, clears it otherwise. There are 10 flags, numbered 0-9.

Flags are stored per nesting depth: each level of use nesting owns a fresh row of 10, so a sub-object's flags cannot clash with its caller's. Everything executing at the same depth shares that level's row.

if  flag anycommand

Executes anycommand only when condition flag flag (a single digit, 0-9) is set at the current nesting depth; otherwise the line is skipped entirely.

The complete mechanism, from include/prism4.3d - the end caps of the prism exist only when the caller set variable 2 to 1:

ifeq 0 %2 1
if 0 f 0 1 2 3
if 0 f 4 5 6 7

# whatever text

Comment. Lines whose first character is # are skipped while the file is loaded, as are blank and whitespace-only lines - they never reach the parser or count against the 500-line cache limit.

warn  message

Prints the word after warn in bright red and waits for a keypress. A debugging aid from the DOS days for flagging suspicious scenes; only the first word of the message is shown. Not used by the city scripts.

end

Flushes all buffered output (like a normal end of file), prints "terminated from file" and exits the whole program immediately.

Rarely needed: falling off the end of the scene file flushes and exits anyway. Never put end in an object file - it would kill the entire run the first time that object was instantiated, leaving a half-written city.

A few implementation facts that explain both the performance and the shape of the output.

The include files use long descriptive names (window_big.3d, hexcluster_bridges.3d, …) that exceed the DOS 8.3 filename limit, so the project is no longer DOS/QBasic compatible - and no attempt is made to keep it so.

bin

3dparse.bas

3D generator main executable

city1.3d

city with square-like buildings

city2.3d

city with hexangular buildings

result.mtl

shared material library

city1.obj, city2.obj

generated cities (versioned)

*.sh

quick launch scripts (crtbasic)

include

3D objects used to compose the scene