@gnsx/three 0.185.16 → 0.186.0

package/examples/jsm/generators/CityGenerator.js

@@ -1,13 +1,26 @@
 import {
+	BoxGeometry,
 	Group,
-	Matrix4
+	InstancedMesh,
+	Matrix4,
+	Quaternion,
+	Vector3
 } from '@gnsx/three';
 
 import { MeshStandardNodeMaterial } from '@gnsx/three/webgpu';
-import { cameraPosition, color, float, floor, Fn, fract, fwidth, hash, If, mix, mod, mx_fractal_noise_float, mx_noise_float, normalView, positionView, positionWorld, smoothstep, step, uint, varying, vec4 } from '@gnsx/three/tsl';
+import { cameraPosition, color, float, floor, Fn, fract, fwidth, hash, If, mix, mod, mx_fractal_noise_float, mx_noise_float, positionWorld, smoothstep, step, uint, uniform, varying, vec4 } from '@gnsx/three/tsl';
 
 import { SkyscraperGenerator, createSkyscraperMaterial, buildingPalette } from './city/SkyscraperGenerator.js';
 import { SidewalkGenerator } from './city/SidewalkGenerator.js';
+import { StreetlightGenerator } from './city/StreetlightGenerator.js';
+import { TrafficlightGenerator } from './city/TrafficlightGenerator.js';
+import { TrashcanGenerator } from './city/TrashcanGenerator.js';
+import { BenchGenerator } from './city/BenchGenerator.js';
+import { HydrantGenerator } from './city/HydrantGenerator.js';
+import { StreetTreeGenerator } from './city/StreetTreeGenerator.js';
+import { CarGenerator } from './city/CarGenerator.js';
+import { PersonGenerator } from './city/PersonGenerator.js';
+import { bumpNormal } from './city/CityGeneratorUtils.js';
 
 /**
  * Lays out a grid of city blocks and fills each lot with a {@link SkyscraperGenerator}
@@ -31,30 +44,69 @@ class CityGenerator {
 		this.parameters = Object.assign( {}, CityGenerator.defaults, parameters );
 		this.layout = cityLayout( this.parameters );
 
+		/**
+		 * The city seed shared by building and proxy materials. Pass this to
+		 * {@link createBuildingMaterial} to update the palette when rebuilding.
+		 *
+		 * @type {UniformNode<uint>}
+		 */
+		this.seedNode = uniform( this.parameters.seed, 'uint' );
+
 		this.generators = [];
+
+		// per-tower box specs recorded during build(), consumed by buildProxy()
+		this.towers = [];
+
 		this.sidewalk = new SidewalkGenerator( {
 			width: this.layout.blockW,
 			depth: this.layout.blockD,
 			height: this.parameters.curbHeight,
 			radius: this.parameters.curbRadius
 		} );
+
+		// the street-furniture generators, each instanced across placements the
+		// layout hands them ( see buildFurniture )
+		this.furniture = {
+			streetlight: new StreetlightGenerator(),
+			trafficlight: new TrafficlightGenerator(),
+			trashcan: new TrashcanGenerator(),
+			bench: new BenchGenerator(),
+			hydrant: new HydrantGenerator(),
+			tree: new StreetTreeGenerator(),
+			car: new CarGenerator(),
+			person: new PersonGenerator()
+		};
+
 		this.group = null;
 
 	}
 
 	build( materials = {} ) {
 
-		this.dispose();
+		this.seedNode.value = this.parameters.seed;
+
+		for ( const generator of this.generators ) generator.dispose();
+		this.generators.length = 0;
+
+		if ( this.group ) {
+
+			this.group.clear();
+			this.group.dispose();
+
+		}
 
 		const group = new Group();
 		group.name = 'City';
 
+		this.towers = [];
+
 		const L = this.layout;
 		const random = createRandom( this.parameters.seed );
 
 		// raise the lots onto rounded sidewalk slabs ( curbs ) when curbHeight > 0
 
 		const curb = this.parameters.curbHeight;
+		const sw = this.parameters.sidewalkWidth;
 		const slabs = [];
 
 		for ( let bx = 0; bx < L.blocksX; bx ++ ) {
@@ -70,6 +122,11 @@ class CityGenerator {
 
 				}
 
+				// the lots sit in an inner zone set back from the block edge by the
+				// sidewalk width, so a real walking strip is left between the street
+				// wall and the curb. buildings front onto that building line.
+				const zoneX = blockX + sw, zoneZ = blockZ + sw;
+
 				for ( let lx = 0; lx < L.lotsX; lx ++ ) {
 
 					for ( let lz = 0; lz < L.lotsZ; lz ++ ) {
@@ -83,10 +140,17 @@ class CityGenerator {
 
 						const tall = random();
 
+						// nearly fill the lot so neighbours abut into a continuous street
+						// wall; the small slack goes to the interior side ( a light well )
+						const fw = L.innerLotX - ( 0.4 + random() * 1 );
+						const fd = L.innerLotZ - ( 0.4 + random() * 1 );
+
+						const totalHeight = 38 + tall * tall * 114; // a few tall towers, mostly mid-rise
+
 						const generator = new SkyscraperGenerator( {
 							seed: Math.floor( random() * 100000 ),
-							totalHeight: 38 + tall * tall * 114, // a few tall towers, mostly mid-rise
-							footprint: { width: L.lot - 1 - random() * 4, depth: L.lot - 1 - random() * 4 }, // nearly fill the lot so neighbours sit close; width and depth vary independently
+							totalHeight,
+							footprint: { width: fw, depth: fd },
 							floorHeight: 3.4 + random() * 1.8,
 							bayWidth: 1.9 + random() * 2.1,
 							pierWidth: 0.4 + random() * 0.5,
@@ -99,12 +163,21 @@ class CityGenerator {
 						}, materials.building );
 
 						const building = generator.build();
-						building.position.set( blockX + ( lx + 0.5 ) * L.lot, curb, blockZ + ( lz + 0.5 ) * L.lot );
+
+						// place within the lot, fronted toward the streets it borders so its
+						// outer faces land on the building line; interior columns stay centred
+						const lotLeft = zoneX + lx * L.innerLotX, lotNear = zoneZ + lz * L.innerLotZ;
+						const cx = cornerX === - 1 ? lotLeft + fw / 2 : ( cornerX === 1 ? lotLeft + L.innerLotX - fw / 2 : lotLeft + L.innerLotX / 2 );
+						const cz = cornerZ === - 1 ? lotNear + fd / 2 : ( cornerZ === 1 ? lotNear + L.innerLotZ - fd / 2 : lotNear + L.innerLotZ / 2 );
+						building.position.set( cx, curb, cz );
 						building.castShadow = building.receiveShadow = true;
 
 						group.add( building );
 						this.generators.push( generator );
 
+						// record a plain box matching this tower for the GI proxy
+						this.towers.push( { x: cx, y: curb + totalHeight / 2, z: cz, w: fw, h: totalHeight, d: fd } );
+
 					}
 
 				}
@@ -113,7 +186,9 @@ class CityGenerator {
 
 		}
 
-		if ( slabs.length > 0 ) group.add( this.sidewalk.build( slabs ) );
+		group.add( this.sidewalk.build( slabs ) );
+
+		group.add( this.buildFurniture( random ) );
 
 		this.group = group;
 
@@ -121,6 +196,181 @@ class CityGenerator {
 
 	}
 
+	/**
+	 * Builds a lightweight stand-in for the city: one instanced box per tower,
+	 * sized to match, in a single draw call. Intended for cheap global-illumination
+	 * bakes, where the detailed facades and street furniture are unnecessary and the
+	 * boxes still cast the same street shadows and bounce the same warm fill.
+	 *
+	 * Call after {@link CityGenerator#build}, which records the tower boxes.
+	 *
+	 * @return {InstancedMesh} The proxy mesh.
+	 */
+	buildProxy() {
+
+		const towers = this.towers;
+
+		// each box takes its tower's own masonry colour ( same node, keyed off world
+		// position ), so the GI bleeds the real per-building tints. mid roughness / metalness
+		// give the boxes a soft, part-glazed sky reflection.
+		const material = new MeshStandardNodeMaterial( { roughness: 0.4, metalness: 0.4 } );
+		material.colorNode = buildingColorNode( this.layout, this.seedNode );
+		const mesh = new InstancedMesh( new BoxGeometry( 1, 1, 1 ), material, towers.length );
+		mesh.name = 'CityProxy';
+
+		const matrix = new Matrix4();
+
+		for ( let i = 0; i < towers.length; i ++ ) {
+
+			const t = towers[ i ];
+			matrix.makeScale( t.w, t.h, t.d );
+			matrix.setPosition( t.x, t.y, t.z );
+			mesh.setMatrixAt( i, matrix );
+
+		}
+
+		mesh.castShadow = true;
+		mesh.receiveShadow = true;
+
+		return mesh;
+
+	}
+
+	// dresses the sidewalks and roadway with instanced street furniture, walking the
+	// curb edge of every block so poles, baskets, trees, pedestrians and parked cars
+	// all align to the same grid the buildings and road markings use
+	buildFurniture( random ) {
+
+		const L = this.layout;
+		const top = this.parameters.curbHeight; // sidewalk surface the furniture stands on
+		const sw = this.parameters.sidewalkWidth;
+		const group = new Group();
+		group.name = 'StreetFurniture';
+
+		const lights = [], signals = [], cans = [], benches = [], hydrants = [], trees = [], people = [], cars = [];
+
+		// the kerbside mix of a New York street: yellow cabs over an almost
+		// entirely grayscale fleet ( black livery cars, whites, silvers,
+		// graphites ), with a dark navy, a burgundy or a bronze only here and
+		// there. cumulative weights, so common colours repeat like they do kerb
+		// to kerb
+		const carColor = () => {
+
+			const r = random();
+			for ( const [ threshold, color ] of CAR_COLORS ) if ( r < threshold ) return color;
+			return CAR_COLORS[ CAR_COLORS.length - 1 ][ 1 ];
+
+		};
+
+		for ( let bx = 0; bx < L.blocksX; bx ++ ) {
+
+			for ( let bz = 0; bz < L.blocksZ; bz ++ ) {
+
+				const blockX = - L.cityW / 2 + bx * ( L.blockW + L.street );
+				const blockZ = - L.cityD / 2 + bz * ( L.blockD + L.street );
+				const edges = blockEdges( blockX, blockZ, L.blockW, L.blockD );
+
+				for ( const e of edges ) {
+
+					const len = e.length;
+
+					// cars on opposite kerbs of a street face opposite ways ( with the
+					// traffic on their side ), keyed off which way the kerb faces
+					const fdir = Math.sign( e.nx + e.nz ) || 1;
+
+					// a point on the sidewalk, `lateral` metres in from the curb
+					const onWalk = ( t, lateral ) => place( e.x0 + e.dx * t - e.nx * lateral, top, e.z0 + e.dz * t - e.nz * lateral, e.nx, e.nz );
+
+					// streetlights spaced along the curb, facing the road so the arm reaches over it
+					const lc = Math.max( 1, Math.round( len / 30 ) );
+					for ( let i = 0; i < lc; i ++ ) lights.push( onWalk( len * ( i + 0.5 ) / lc, 0.8 ) );
+
+					// street trees in curbside pits, offset from the lights, clear of the corners
+					const tc = Math.max( 1, Math.round( len / 16 ) );
+					for ( let i = 0; i < tc; i ++ ) {
+
+						const t = len * ( i + 0.5 ) / tc + 5;
+						if ( t > 7 && t < len - 7 && random() < 0.85 ) {
+
+							// random yaw and height so no two street trees read as copies
+							trees.push( placeYawScale( e.x0 + e.dx * t - e.nx * 1.5, top, e.z0 + e.dz * t - e.nz * 1.5, random() * Math.PI * 2, 0.8 + random() * 0.5 ) );
+
+						}
+
+					}
+
+					// a single hydrant on the kerb, its no-parking zone honoured below
+					const hydT = len * ( 0.25 + random() * 0.5 );
+					hydrants.push( onWalk( hydT, 0.7 ) );
+
+					// a bench facing the street on some edges
+					if ( random() < 0.4 ) benches.push( onWalk( len * ( 0.3 + random() * 0.4 ), 1.7 ) );
+
+					// pedestrians scattered across the walking strip, facing any way
+					const pc = Math.max( 2, Math.round( len / 9 ) );
+					for ( let i = 0; i < pc; i ++ ) {
+
+						if ( random() < 0.7 ) {
+
+							const t = len * ( i + random() ) / pc;
+							const lateral = 0.9 + random() * ( sw - 2 );
+							people.push( placeYawScale( e.x0 + e.dx * t - e.nx * lateral, top, e.z0 + e.dz * t - e.nz * lateral, random() * Math.PI * 2, 0.92 + random() * 0.16 ) );
+
+						}
+
+					}
+
+					// parked cars in the kerb lane, nose-to-tail with gaps, clear of the
+					// corners ( daylighting ) and the hydrant
+					for ( let t = 9; t < len - 9; t += 5.8 ) {
+
+						if ( Math.abs( t - hydT ) > 3 && random() < 0.72 ) {
+
+							cars.push( { matrix: place( e.x0 + e.dx * t + e.nx * 1.5, 0, e.z0 + e.dz * t + e.nz * 1.5, e.dx * fdir, e.dz * fdir ), color: carColor() } );
+
+						}
+
+					}
+
+					// the occasional vehicle out in a travel lane
+					for ( let t = 14; t < len - 14; t += 13 ) {
+
+						if ( random() < 0.4 ) cars.push( { matrix: place( e.x0 + e.dx * t + e.nx * 5.5, 0, e.z0 + e.dz * t + e.nz * 5.5, e.dx * fdir, e.dz * fdir ), color: carColor() } );
+
+					}
+
+				}
+
+				// at two opposite corners: a mast-arm signal reaching over the crossing,
+				// and a litter basket on every corner just along the kerb
+				const corners = [[ 0, 0 ], [ 1, 0 ], [ 0, 1 ], [ 1, 1 ]];
+				for ( const [ cx, cz ] of corners ) {
+
+					const x = blockX + cx * L.blockW, z = blockZ + cz * L.blockD;
+					const ix = cx ? - 1 : 1, iz = cz ? - 1 : 1; // inward, toward the block centre
+
+					if ( cx === cz ) signals.push( place( x + ix * 1.4, top, z + iz * 1.4, - ix, - iz ) );
+					cans.push( place( x + ix * 2.2, top, z + iz * 2.2, ix, iz ) );
+
+				}
+
+			}
+
+		}
+
+		group.add( this.furniture.streetlight.build( lights ) );
+		group.add( this.furniture.trafficlight.build( signals ) );
+		group.add( this.furniture.trashcan.build( cans ) );
+		group.add( this.furniture.bench.build( benches ) );
+		group.add( this.furniture.hydrant.build( hydrants ) );
+		group.add( this.furniture.tree.build( trees ) );
+		group.add( this.furniture.person.build( people ) );
+		group.add( this.furniture.car.build( cars ) );
+
+		return group;
+
+	}
+
 	dispose() {
 
 		for ( const generator of this.generators ) generator.dispose();
@@ -128,6 +378,10 @@ class CityGenerator {
 
 		this.sidewalk.dispose();
 
+		for ( const key in this.furniture ) this.furniture[ key ].dispose();
+
+		if ( this.group ) this.group.dispose();
+
 		this.group = null;
 
 	}
@@ -143,19 +397,39 @@ CityGenerator.defaults = {
 	blocksX: 2,
 	blocksZ: 2,
 	curbHeight: 0.15, // ~6 in standard curb reveal / sidewalk height above the road
-	curbRadius: 5
+	curbRadius: 5,
+	sidewalkWidth: 5 // walkable strip between the street wall and the curb ( NYC ~15 ft )
 };
 
+// kerbside paint mix sampled from Manhattan street photos: cumulative
+// probability thresholds and the paint they select
+const CAR_COLORS = [
+	[ 0.22, 0xf5c518 ], // yellow cab
+	[ 0.42, 0x111216 ], // black ( livery sedans and SUVs )
+	[ 0.59, 0xe9e8e3 ], // white
+	[ 0.72, 0xb2b5b8 ], // silver
+	[ 0.84, 0x3e4247 ], // graphite
+	[ 0.90, 0x74787c ], // mid grey
+	[ 0.95, 0x1c2a3f ], // dark navy
+	[ 0.98, 0x571f1f ], // burgundy
+	[ 1.01, 0x5c4834 ] // bronze
+];
+
 // derives the block / street dimensions from the parameters
 function cityLayout( parameters ) {
 
-	const { street, lot, lotsX, lotsZ, blocksX, blocksZ } = parameters;
+	const { street, lot, lotsX, lotsZ, blocksX, blocksZ, sidewalkWidth } = parameters;
 
 	const blockW = lotsX * lot;
 	const blockD = lotsZ * lot;
 
+	// the lots tile the inner zone left after the sidewalk strip is taken from
+	// every edge; buildings front onto its perimeter ( the building line )
+	const innerLotX = ( blockW - 2 * sidewalkWidth ) / lotsX;
+	const innerLotZ = ( blockD - 2 * sidewalkWidth ) / lotsZ;
+
 	return {
-		street, lot, lotsX, lotsZ, blocksX, blocksZ, blockW, blockD,
+		street, lot, lotsX, lotsZ, blocksX, blocksZ, blockW, blockD, sidewalkWidth, innerLotX, innerLotZ,
 		cityW: blocksX * blockW + ( blocksX - 1 ) * street,
 		cityD: blocksZ * blockD + ( blocksZ - 1 ) * street
 	};
@@ -178,25 +452,51 @@ function createRandom( seed ) {
 
 }
 
-// --- road material -------------------------------------------------------
+// --- furniture placement -------------------------------------------------
+
+// the four curb edges of a block: each carries a start corner, a unit direction
+// along the edge, the outward normal ( toward the road ) and a length. furniture
+// walks these, insetting against the normal to sit on the sidewalk.
+function blockEdges( x, z, w, d ) {
+
+	return [
+		{ x0: x, z0: z, dx: 1, dz: 0, nx: 0, nz: - 1, length: w },
+		{ x0: x, z0: z + d, dx: 1, dz: 0, nx: 0, nz: 1, length: w },
+		{ x0: x, z0: z, dx: 0, dz: 1, nx: - 1, nz: 0, length: d },
+		{ x0: x + w, z0: z, dx: 0, dz: 1, nx: 1, nz: 0, length: d }
+	];
+
+}
 
-// derivative-based bump for a procedural, world-space height field. the built-in bumpMap
-// offsets the UV to read its height, so it returns a zero gradient for a height keyed off
-// world position; this feeds the hardware screen-space derivatives of the height into
-// Mikkelsen's surface-gradient method so the relief actually perturbs the normal.
-function bumpNormal( height ) {
+const _f = /*@__PURE__*/ new Vector3();
+const _r = /*@__PURE__*/ new Vector3();
+const _up = /*@__PURE__*/ new Vector3( 0, 1, 0 );
 
-	const dpdx = positionView.dFdx();
-	const dpdy = positionView.dFdy();
-	const r1 = dpdy.cross( normalView );
-	const r2 = normalView.cross( dpdx );
-	const det = dpdx.dot( r1 );
-	const grad = det.sign().mul( height.dFdx().mul( r1 ).add( height.dFdy().mul( r2 ) ) );
+// a placement matrix at ( x, y, z ) whose local +Z faces ( faceX, faceZ ) in the
+// XZ plane, so a canonical model authored facing +Z turns to face that way
+function place( x, y, z, faceX, faceZ ) {
 
-	return det.abs().mul( normalView ).sub( grad ).normalize();
+	_f.set( faceX, 0, faceZ ).normalize();
+	_r.crossVectors( _up, _f ).normalize();
+	return new Matrix4().makeBasis( _r, _up, _f ).setPosition( x, y, z );
 
 }
 
+const _q = /*@__PURE__*/ new Quaternion();
+const _pos = /*@__PURE__*/ new Vector3();
+const _sca = /*@__PURE__*/ new Vector3();
+
+// a placement with a free yaw and a uniform scale, so repeated instances ( trees,
+// pedestrians ) read as individuals rather than copies
+function placeYawScale( x, y, z, yaw, scale ) {
+
+	_q.setFromAxisAngle( _up, yaw );
+	return new Matrix4().compose( _pos.set( x, y, z ), _q, _sca.set( scale, scale, scale ) );
+
+}
+
+// --- road material -------------------------------------------------------
+
 // antialiased filled band: 1 where |coord| < halfWidth, edge sized to the
 // pixel footprint ( fwidth ) so thin road paint stays crisp and doesn't shimmer
 function lineAA( coord, halfWidth ) {
@@ -218,13 +518,19 @@ function gridLine( coord, period, halfWidth ) {
 }
 
 /**
- * The shared material every tower in a {@link CityGenerator} is dressed with: one flat
- * masonry colour per lot, picked from a palette by hashing the lot's grid cell.
+ * The per-tower flat masonry colour: one palette entry per lot, picked by hashing the
+ * lot's grid cell from world position. Keyed off `positionWorld`, so it colours anything
+ * standing on the city grid identically, the towers and their {@link CityGenerator#buildProxy}
+ * boxes alike.
+ *
+ * @param {Object} layout - The city layout.
+ * @param {number|Node<uint>} [seed=0] - The city seed or a shared seed node.
+ * @return {Node<vec3>} The tower colour.
  */
-function createBuildingMaterial( layout, seed = 0 ) {
+function buildingColorNode( layout, seed = 0 ) {
 
-	// every tower takes one flat colour, picked by hashing its lot — one shared material
-	// dresses the whole skyline; common tones repeat so the equal-probability pick feels real
+	// every tower takes one flat colour, picked by hashing its lot; common tones repeat
+	// so the equal-probability pick feels real
 	const palette = buildingPalette.map( hex => color( hex ) );
 
 	const periodX = layout.blockW + layout.street;
@@ -233,9 +539,14 @@ function createBuildingMaterial( layout, seed = 0 ) {
 	const gz = positionWorld.z.add( layout.cityD / 2 );
 	const blockIX = floor( gx.div( periodX ) );
 	const blockIZ = floor( gz.div( periodZ ) );
-	const cellX = blockIX.mul( layout.lotsX ).add( floor( gx.sub( blockIX.mul( periodX ) ).div( layout.lot ) ) );
-	const cellZ = blockIZ.mul( layout.lotsZ ).add( floor( gz.sub( blockIZ.mul( periodZ ) ).div( layout.lot ) ) );
-	const cellKey = uint( cellX.add( 4096 ) ).mul( uint( 73856093 ) ).bitXor( uint( cellZ.add( 4096 ) ).mul( uint( 19349663 ) ) ).bitXor( uint( ( seed * 2654435761 ) >>> 0 ) ).toVar();
+	// cells align to the inner-lot grid each tower sits in, so an inset, fronted
+	// tower maps wholly to its own cell and reads as one flat colour
+	const lotIX = floor( gx.sub( blockIX.mul( periodX ) ).sub( layout.sidewalkWidth ).div( layout.innerLotX ) ).clamp( 0, layout.lotsX - 1 );
+	const lotIZ = floor( gz.sub( blockIZ.mul( periodZ ) ).sub( layout.sidewalkWidth ).div( layout.innerLotZ ) ).clamp( 0, layout.lotsZ - 1 );
+	const cellX = blockIX.mul( layout.lotsX ).add( lotIX );
+	const cellZ = blockIZ.mul( layout.lotsZ ).add( lotIZ );
+	const seedHash = typeof seed === 'number' ? uint( ( seed * 2654435761 ) >>> 0 ) : uint( seed ).toVar().mul( uint( 2654435761 ) );
+	const cellKey = uint( cellX.add( 4096 ) ).mul( uint( 73856093 ) ).bitXor( uint( cellZ.add( 4096 ) ).mul( uint( 19349663 ) ) ).bitXor( seedHash ).toVar();
 	const cellHash = ( a, b ) => hash( cellKey.add( uint( Math.round( ( a + b * 7 ) * 100 ) ) ) );
 
 	const pick = cellHash( 127.1, 311.7 );
@@ -243,8 +554,22 @@ function createBuildingMaterial( layout, seed = 0 ) {
 	for ( let i = 1; i < palette.length; i ++ ) buildingBase = mix( buildingBase, palette[ i ], step( i / palette.length, pick ) );
 	buildingBase = buildingBase.mul( cellHash( 269.5, 183.3 ).mul( 0.12 ).add( 0.94 ) ); // subtle per-building brightness
 
+	return buildingBase;
+
+}
+
+/**
+ * The shared material every tower in a {@link CityGenerator} is dressed with: the per-lot
+ * {@link buildingColorNode} resolved once per vertex on a skyscraper material.
+ *
+ * @param {Object} layout - The city layout.
+ * @param {number|Node<uint>} [seed=0] - A fixed seed, or {@link CityGenerator#seedNode} for a changing city.
+ * @return {MeshStandardNodeMaterial} The building material.
+ */
+function createBuildingMaterial( layout, seed = 0 ) {
+
 	// the pick is constant across a tower, so resolve it once per vertex ( varying )
-	return createSkyscraperMaterial( varying( buildingBase ) );
+	return createSkyscraperMaterial( varying( buildingColorNode( layout, seed ) ) );
 
 }
 
@@ -255,41 +580,48 @@ function createBuildingMaterial( layout, seed = 0 ) {
 function createRoadMaterial( layout ) {
 
 	// wet asphalt: a warm-grey base in patchwork pours, two-scale aggregate
-	// grit, oily wear stains, hairline cracks and low-frequency wet patches
-	// that turn glossy and mirror the sky. detail fades in as the camera nears.
+	// grit, oily wear stains and low-frequency wet patches that turn glossy and
+	// mirror the sky. detail fades in as the camera nears.
 
 	const p = positionWorld;
-	const detail = smoothstep( 240, 25, p.distance( cameraPosition ) );
+	const dist = p.distance( cameraPosition );
+	const detail = smoothstep( 240, 25, dist );
+	const microFade = smoothstep( 22, 4, dist ); // the finest grit only resolves right under the camera, so fade it out fast to avoid shimmer
 
 	const blotch = mx_fractal_noise_float( p.mul( 0.2 ), 3 ).mul( 0.5 ).add( 0.5 );
 
-	// close-range detail — aggregate grit, oily wear pools, hairline cracks and worn
-	// paint — only resolves near the camera, so its noise is sampled ( inside the branch )
-	// only where detail is non-zero and skipped across the far majority of the road
+	// close-range detail — aggregate grit, oily wear pools and worn paint — only
+	// resolves near the camera, so its noise is sampled ( inside the branch ) only
+	// where detail is non-zero and skipped across the far majority of the road
 	const near = Fn( () => {
 
 		const grit = float( 0 ).toVar(); // two scales of aggregate, -1..1
 		const stain = float( 0 ).toVar(); // oily wear pools
-		const crack = float( 0 ).toVar();
 		const worn = float( 1 ).toVar(); // paint rubbed thin and patchy, more so where tyres cross it
+		const micro = float( 0 ).toVar(); // fine, high-frequency grain for the close-up bump
 
 		If( detail.greaterThan( 0 ), () => {
 
 			grit.assign( mx_noise_float( p.mul( 7 ) ).add( mx_noise_float( p.mul( 23 ) ) ).mul( 0.5 ) );
 			stain.assign( smoothstep( 0.5, 0.85, mx_fractal_noise_float( p.mul( 0.45 ), 3 ).mul( 0.5 ).add( 0.5 ) ) );
-			crack.assign( smoothstep( 0.88, 1, mx_fractal_noise_float( p.mul( 1.1 ), 4 ).abs().oneMinus() ).mul( detail ) );
 			worn.assign( smoothstep( 0.25, 0.7, mx_fractal_noise_float( p.mul( 0.7 ), 3 ).mul( 0.5 ).add( 0.5 ) ).mul( 0.55 ).add( 0.35 ) );
 
 		} );
 
-		return vec4( grit, stain, crack, worn );
+		If( microFade.greaterThan( 0 ), () => {
+
+			micro.assign( mx_noise_float( p.mul( 45 ) ).mul( 0.6 ).add( mx_noise_float( p.mul( 80 ) ).mul( 0.4 ) ) );
+
+		} );
+
+		return vec4( grit, stain, worn, micro );
 
 	} )();
 
 	const grit = near.x;
 	const stain = near.y;
-	const crack = near.z;
-	const worn = near.w;
+	const worn = near.z;
+	const micro = near.w;
 
 	const base = mix( color( 0x24262b ), color( 0x3b3f46 ), blotch );
 	const gritty = base.mul( grit.mul( 0.22 ).mul( detail ).add( 1 ) );
@@ -334,10 +666,10 @@ function createRoadMaterial( layout ) {
 	const paint = laneV.max( laneH ).max( crossV ).max( crossH ).mul( detail ).mul( worn );
 
 	const material = new MeshStandardNodeMaterial();
-	const surface = mix( asphalt, asphalt.mul( 0.6 ), wet ).mul( crack.mul( 0.5 ).oneMinus() );
+	const surface = mix( asphalt, asphalt.mul( 0.6 ), wet );
 	material.colorNode = mix( surface, color( 0xd0ccc0 ), paint ); // worn white paint
 	material.roughnessNode = mix( float( 0.95 ).sub( paint.mul( 0.2 ) ), float( 0.32 ), wet );
-	material.normalNode = bumpNormal( grit.mul( 0.003 ).sub( crack.mul( 0.01 ) ).mul( detail ) ); // world units: ~3 mm aggregate, ~10 mm cracks
+	material.normalNode = bumpNormal( grit.mul( 0.003 ).mul( detail ).add( micro.mul( 0.0016 ).mul( microFade ) ) ); // world units: ~3 mm aggregate, ~1.6 mm fine grain up close
 
 	return material;
 

package/examples/jsm/generators/ForestGenerator.js

@@ -15,18 +15,12 @@ import { ImprovedNoise } from '../math/ImprovedNoise.js';
 import { mergeVertices } from '../utils/BufferGeometryUtils.js';
 
 /**
- * Carpets a {@link TerrainGenerator} ( or anything exposing `sampleHeight`,
- * `sampleSlope`, `minY`, `maxY` and `parameters.size` ) with a forest of hundreds
- * of thousands of trees in a single draw call.
+ * Carpets a {@link TerrainGenerator} with trees in a single instanced draw call.
+ * Each tree is a distorted icosphere with a baked crown gradient. Altitude, slope
+ * and a density mask control placement; rotation and scale vary between trees.
  *
- * Each tree is the cheapest thing that still reads as a tree: a ~20-face icosphere
- * squashed into a tapered teardrop and lumped with a little noise, carrying a baked
- * dark-base / bright-top gradient. Tens of triangles each, so a single
- * {@link THREE.InstancedMesh} of half a million of them costs one draw call. Trees
- * are placed by rejection sampling against ecological rules — a min/max altitude
- * band ( above the mist floor, below the snowline ), a slope limit ( none on
- * cliffs ) and a low-frequency density mask that opens clearings — then jittered in
- * yaw, lean and ( squared-biased ) scale so the stand never reads as copies.
+ * Compatible terrain objects expose `sampleHeight`, `sampleSlope`, `minY`, `maxY`
+ * and `parameters.size`.
  *
  * ```js
  * const forest = new ForestGenerator( { count: 500000 } );
@@ -154,7 +148,13 @@ class ForestGenerator {
 
 	dispose() {
 
-		if ( this.mesh ) this.mesh.geometry.dispose();
+		if ( this.mesh ) {
+
+			this.mesh.dispose();
+			this.mesh.geometry.dispose();
+
+		}
+
 		this.mesh = null;
 		this.group = null;