super-three 0.181.0 → 0.185.0

package/examples/jsm/generators/TreeGenerator.js

@@ -0,0 +1,377 @@
+import {
+	BufferAttribute,
+	BufferGeometry,
+	Mesh,
+	Vector3
+} from 'three';
+
+import { MeshStandardNodeMaterial } from 'three/webgpu';
+import { color, float, mx_fractal_noise_float, positionLocal, vec3 } from 'three/tsl';
+
+// the golden angle ( 137.5° ): rolling each sibling branch by this much around the
+// parent axis spreads them like a real stem, so they never line up
+const GOLDEN_ANGLE = Math.PI * ( 3 - Math.sqrt( 5 ) );
+const DEG2RAD = Math.PI / 180;
+const TAU = Math.PI * 2;
+
+const UP = /*@__PURE__*/ new Vector3( 0, 1, 0 );
+const _axis = /*@__PURE__*/ new Vector3();
+
+// reusable scratch for one tube's ring vertices ( grows to the largest tube seen )
+let _ring = new Float32Array( 0 );
+
+/**
+ * Grows a procedural tree skeleton — trunk, branches and twigs, each swept as a tapered
+ * tube — and bakes it into one non-indexed {@link BufferGeometry} (position and normal
+ * only), ready to instance into a forest. It produces *branches only*; add foliage as a
+ * separate layer.
+ *
+ * The branching is deterministic for a given `seed`: a recursive sweep lays down gently
+ * curved tubes with a parallel-transport frame (so they never twist), forking by the
+ * pipe model (each child much thinner than its parent), spreading children along the
+ * upper part of each branch with a golden-angle roll, and pulling them back up toward
+ * the light. A flared root, non-linear taper and gravity droop fill in the character.
+ *
+ * Parameters are set with a fluent builder: a `set<Param>()` exists for every default
+ * ( `setSeed`, `setLevels`, `setChildren`, … ), each returning `this` for chaining.
+ *
+ * Each `build()` returns a fresh, independent mesh that the caller owns, so one
+ * generator can be re-parametrized and built repeatedly to grow a varied stand:
+ *
+ * ```js
+ * const generator = new TreeGenerator( material );
+ * const oak = generator.setSeed( 1 ).setLevels( 4 ).build();
+ * const pine = generator.setSeed( 2 ).setLevels( 5 ).build();
+ * ```
+ */
+class TreeGenerator {
+
+	constructor( material = null ) {
+
+		this.material = material;
+		this.parameters = {}; // overrides; defaults fill the rest at build time
+
+	}
+
+	build() {
+
+		const p = Object.assign( {}, TreeGenerator.defaults, this.parameters );
+		const random = createRandom( p.seed );
+
+		// grow the skeleton into a flat list of tubes, then size and fill the geometry in
+		// one pass — no per-vertex objects, no array growth
+
+		const tubes = [];
+		growBranch( tubes, new Vector3(), UP, p.trunkLength, p.trunkRadius, 0, p, random );
+
+		let vertexCount = 0;
+		for ( const tube of tubes ) vertexCount += ( tube.rings.length - 1 ) * tube.radial * 6;
+
+		const positions = new Float32Array( vertexCount * 3 );
+		const normals = new Float32Array( vertexCount * 3 );
+
+		let offset = 0;
+		for ( const tube of tubes ) offset = emitTube( positions, normals, offset, tube.rings, tube.radial );
+
+		const geometry = new BufferGeometry();
+		geometry.setAttribute( 'position', new BufferAttribute( positions, 3 ) );
+		geometry.setAttribute( 'normal', new BufferAttribute( normals, 3 ) );
+		geometry.computeBoundingSphere();
+
+		const mesh = new Mesh( geometry, this.material || createTreeMaterial() );
+		mesh.name = 'Tree';
+
+		return mesh;
+
+	}
+
+}
+
+TreeGenerator.defaults = {
+	seed: 1,
+	levels: 4, // recursion depth: trunk, branch, twig, sub-twig
+	children: [ 3, 12, 8 ], // sub-branches per level; density comes from many children spread along each parent, not depth
+	branchAngle: [ 38, 50, 58 ], // degrees a child tilts off its parent axis, per level
+	angleVariance: 14, // degrees of random jitter on the branch angle, breaks fractal regularity
+	lengthRatio: 0.62, // child length / parent length
+	trunkLength: 9, // trunk length in world units; sets the tree's height
+	trunkRadius: 0.42, // base radius of the trunk
+	taper: 0.55, // a branch thins to ( 1 - taper ) of its base radius along its own length
+	taperCurve: 0.7, // < 1 keeps the bole full then tapers ( real trees ), 1 = straight cone
+	rootFlare: 0.6, // how much the trunk swells at the very base
+	flareFrac: 0.18, // fraction of the trunk over which the flare acts
+	radiusExponent: 2.3, // pipe model ( da Vinci ): childBase = parentBase × ( 1 / children )^( 1 / radiusExponent )
+	minRadius: 0.05, // hair-thin floor so twigs don't taper to a sliver
+	minLength: 0.6, // branches shorter than this stop recursing
+	droop: 0.05, // gravity sag per branch ( ≈ droop × length ); the trunk stays upright
+	upPull: 0.3, // phototropism: 0 = a bare spread cone ( many branches aim down ), 1 = straight up
+	gnarl: [ 0.05, 0.16, 0.26, 0.32 ], // per-level random wobble on each tube segment
+	radialSegments: 6, // ring vertices around a tube ( drops by one per level for thin twigs )
+	sectionLength: 1.3, // world units per tube segment, so a tall trunk stays smooth
+	childStart: 0.12, // fraction up a sub-branch before children appear
+	trunkClear: 0.25 // fraction of the trunk kept bare before the crown ( raise for a tall clean bole )
+};
+
+// a fluent setter for every default — setSeed(), setLevels(), setChildren(), … — each
+// storing its value and returning `this`, so the API stays in sync with the parameters
+for ( const key of Object.keys( TreeGenerator.defaults ) ) {
+
+	TreeGenerator.prototype[ 'set' + key[ 0 ].toUpperCase() + key.slice( 1 ) ] = function ( value ) {
+
+		this.parameters[ key ] = value;
+		return this;
+
+	};
+
+}
+
+// --- skeleton ------------------------------------------------------------
+
+// Grows one branch as a gently curved, tapered tube and recurses, collecting the tube
+// into `tubes`. The tube is swept with a parallel-transport frame ( rotated by the same
+// rotation that bends the tangent each step ) so it never twists, unlike a naive Frenet
+// frame. Children fork off the upper part of the branch by the pipe model.
+function growBranch( tubes, base, dir, length, baseRadius, level, p, random ) {
+
+	const sections = Math.max( 3, Math.min( 24, Math.round( length / p.sectionLength ) ) ); // ring count tracks length
+	const radial = Math.max( 3, p.radialSegments - level );
+	const step = length / sections;
+	const gnarl = p.gnarl[ Math.min( level, p.gnarl.length - 1 ) ];
+	const start = level === 0 ? p.trunkClear : p.childStart; // the trunk carries a clean bole below its crown
+
+	let tangent = dir.clone().normalize();
+	const normal = perpendicular( tangent );
+
+	const rings = [];
+	const pos = base.clone();
+
+	for ( let s = 0; s <= sections; s ++ ) {
+
+		const t = s / sections;
+
+		// non-linear taper down to ( 1 - taper ) of the base, with a flared root on the trunk
+		let radius = baseRadius * ( ( 1 - p.taper ) + p.taper * Math.pow( 1 - t, p.taperCurve ) );
+		if ( level === 0 && p.rootFlare > 0 ) {
+
+			const flare = Math.max( 0, ( p.flareFrac - t ) / p.flareFrac );
+			radius *= 1 + p.rootFlare * flare * flare * flare; // sharp knee, confined to the base
+
+		}
+
+		rings.push( {
+			pos: pos.clone(),
+			tangent: tangent.clone(),
+			normal: normal.clone(),
+			binormal: new Vector3().crossVectors( tangent, normal ),
+			radius
+		} );
+
+		if ( s < sections ) {
+
+			const next = tangent.clone();
+			next.x += ( random() * 2 - 1 ) * gnarl;
+			next.y += ( random() * 2 - 1 ) * gnarl;
+			next.z += ( random() * 2 - 1 ) * gnarl;
+			if ( level > 0 ) next.y -= p.droop * step; // branches sag; the trunk stays vertical
+			next.normalize();
+
+			transport( tangent, next, normal ); // keep the frame torsion-free
+			pos.addScaledVector( next, step );
+			tangent = next;
+
+		}
+
+	}
+
+	tubes.push( { rings, radial } );
+
+	if ( level >= p.levels - 1 || length < p.minLength ) return;
+
+	// fork: children spread along the upper branch, each tilted off the local tangent,
+	// rolled by the golden angle, and much thinner than the parent ( pipe model )
+
+	const n = p.children[ Math.min( level, p.children.length - 1 ) ];
+	const angle = p.branchAngle[ Math.min( level, p.branchAngle.length - 1 ) ];
+	const pipeDrop = Math.pow( 1 / n, 1 / p.radiusExponent );
+
+	for ( let i = 0; i < n; i ++ ) {
+
+		const t = start + ( i + 0.5 + ( random() - 0.5 ) * 0.6 ) / n * ( 1 - start );
+		const ring = ringAt( rings, t );
+
+		const tilt = ( angle + ( random() * 2 - 1 ) * p.angleVariance ) * DEG2RAD;
+		const roll = i * GOLDEN_ANGLE + ( random() * 2 - 1 ) * 0.4;
+
+		// tilt off a perpendicular axis FIRST, then roll about the parent axis, then pull
+		// back toward the light ( else the roll sends half the children downward )
+		const childDir = ring.tangent.clone()
+			.applyAxisAngle( ring.normal, tilt )
+			.applyAxisAngle( ring.tangent, roll );
+		if ( p.upPull > 0 ) childDir.lerp( UP, p.upPull ).normalize();
+
+		// the pipe-model drop, but never fatter than the wood it leaves nor below the floor
+		const childBase = Math.max( p.minRadius, Math.min( baseRadius * pipeDrop, ring.radius ) );
+
+		growBranch( tubes, ring.pos, childDir, length * p.lengthRatio, childBase, level + 1, p, random );
+
+	}
+
+}
+
+// a unit vector perpendicular to v ( cross with the least-aligned axis )
+function perpendicular( v ) {
+
+	const a = Math.abs( v.x ) < 0.9 ? _axis.set( 1, 0, 0 ) : _axis.set( 0, 1, 0 );
+	return new Vector3().crossVectors( v, a ).normalize();
+
+}
+
+// rotate frame vector n by the rotation that maps tangent t0 onto t1
+function transport( t0, t1, n ) {
+
+	_axis.crossVectors( t0, t1 );
+	const sin = _axis.length();
+	if ( sin < 1e-6 ) return; // already parallel
+	_axis.divideScalar( sin );
+	n.applyAxisAngle( _axis, Math.atan2( sin, t0.dot( t1 ) ) );
+
+}
+
+// sample the branch frame at fraction t ( 0..1 ) for spawning a child
+function ringAt( rings, t ) {
+
+	const f = Math.max( 0, Math.min( 0.999, t ) ) * ( rings.length - 1 );
+	const i = Math.floor( f );
+	const frac = f - i;
+	const a = rings[ i ];
+	const b = rings[ Math.min( i + 1, rings.length - 1 ) ];
+
+	return {
+		pos: a.pos.clone().lerp( b.pos, frac ),
+		tangent: a.tangent.clone().lerp( b.tangent, frac ).normalize(),
+		normal: a.normal.clone().lerp( b.normal, frac ).normalize(),
+		radius: a.radius + ( b.radius - a.radius ) * frac
+	};
+
+}
+
+// --- geometry ------------------------------------------------------------
+
+// Sweeps a tube through the rings: each ring is a loop of `radial` vertices in its
+// ( normal, binormal ) plane, the outward radial direction being the vertex normal.
+// Ring vertices are computed once into a reused scratch, then stitched straight into the
+// preallocated geometry arrays — no per-vertex objects.
+function emitTube( positions, normals, offset, rings, radial ) {
+
+	const stride = ( radial + 1 ) * 6; // one ring loop: ( position, normal ) per vertex
+	const needed = rings.length * stride;
+	if ( _ring.length < needed ) _ring = new Float32Array( needed );
+
+	const ring = _ring;
+
+	for ( let r = 0; r < rings.length; r ++ ) {
+
+		const { pos, normal, binormal, radius } = rings[ r ];
+		let o = r * stride;
+
+		for ( let j = 0; j <= radial; j ++ ) {
+
+			const a = j / radial * TAU;
+			const c = Math.cos( a );
+			const s = Math.sin( a );
+			const nx = c * normal.x + s * binormal.x;
+			const ny = c * normal.y + s * binormal.y;
+			const nz = c * normal.z + s * binormal.z;
+
+			ring[ o ++ ] = pos.x + nx * radius;
+			ring[ o ++ ] = pos.y + ny * radius;
+			ring[ o ++ ] = pos.z + nz * radius;
+			ring[ o ++ ] = nx;
+			ring[ o ++ ] = ny;
+			ring[ o ++ ] = nz;
+
+		}
+
+	}
+
+	// stitch consecutive rings into quads ( two triangles ), wound so normals face out
+
+	for ( let r = 0; r < rings.length - 1; r ++ ) {
+
+		const a = r * stride;
+		const b = ( r + 1 ) * stride;
+
+		for ( let j = 0; j < radial; j ++ ) {
+
+			const aL = a + j * 6, aR = a + ( j + 1 ) * 6;
+			const bL = b + j * 6, bR = b + ( j + 1 ) * 6;
+
+			offset = copyVertex( positions, normals, offset, ring, aL );
+			offset = copyVertex( positions, normals, offset, ring, bR );
+			offset = copyVertex( positions, normals, offset, ring, bL );
+
+			offset = copyVertex( positions, normals, offset, ring, aL );
+			offset = copyVertex( positions, normals, offset, ring, aR );
+			offset = copyVertex( positions, normals, offset, ring, bR );
+
+		}
+
+	}
+
+	return offset;
+
+}
+
+// copies one ( position, normal ) vertex from the ring scratch into the geometry arrays
+function copyVertex( positions, normals, offset, ring, i ) {
+
+	const o = offset * 3;
+	positions[ o ] = ring[ i ]; positions[ o + 1 ] = ring[ i + 1 ]; positions[ o + 2 ] = ring[ i + 2 ];
+	normals[ o ] = ring[ i + 3 ]; normals[ o + 1 ] = ring[ i + 4 ]; normals[ o + 2 ] = ring[ i + 5 ];
+
+	return offset + 1;
+
+}
+
+// --- deterministic PRNG ( mulberry32 ) -----------------------------------
+
+function createRandom( seed ) {
+
+	let s = ( seed >>> 0 ) || 1;
+
+	return function () {
+
+		s = ( s + 0x6D2B79F5 ) | 0;
+		let t = Math.imul( s ^ ( s >>> 15 ), 1 | s );
+		t = ( t + Math.imul( t ^ ( t >>> 7 ), 61 | t ) ) ^ t;
+		return ( ( t ^ ( t >>> 14 ) ) >>> 0 ) / 4294967296;
+
+	};
+
+}
+
+// --- material ------------------------------------------------------------
+
+/**
+ * A simple bark material for a {@link TreeGenerator} mesh: a low-saturation brown with a
+ * faint, vertically-stretched grain, so trunks read near-black against bright fog.
+ *
+ * @param {Object} [parameters] - `barkColor` ( a hex, THREE.Color or TSL node ).
+ * @return {MeshStandardNodeMaterial}
+ */
+function createTreeMaterial( parameters = {} ) {
+
+	const c = parameters.barkColor;
+	const barkColor = c === undefined ? color( 0x4b3a2b ) : ( c.isColor || typeof c === 'number' ? color( c ) : c );
+
+	const material = new MeshStandardNodeMaterial();
+	const grain = mx_fractal_noise_float( positionLocal.mul( vec3( 2.5, 0.4, 2.5 ) ), 3 ).mul( 0.18 );
+	material.colorNode = barkColor.mul( grain.add( 0.9 ) );
+	material.roughnessNode = float( 0.95 );
+	material.metalnessNode = float( 0 );
+
+	return material;
+
+}
+
+export { TreeGenerator, createTreeMaterial };

package/examples/jsm/generators/city/SidewalkGenerator.js

@@ -0,0 +1,253 @@
+import {
+	ExtrudeGeometry,
+	Group,
+	InstancedMesh,
+	MeshStandardNodeMaterial,
+	Shape
+} from 'three/webgpu';
+
+import { cameraPosition, color, float, floor, Fn, fract, fwidth, If, mix, mx_noise_float, normalView, normalWorldGeometry, positionView, positionWorld, sin, smoothstep } from 'three/tsl';
+
+/**
+ * Generates the raised sidewalk for a city's blocks: per block, a rounded-corner concrete
+ * slab rimmed by a distinct granite kerbstone that stands proud of the walking surface and
+ * drops to the road. Instanced across a list of placements and dressed with its own
+ * procedural material ( poured concrete flags, scored expansion joints, granite curb ).
+ * Returns a `THREE.Group` of two instanced meshes — the walking slab and the curb.
+ *
+ * Unlike the building generator, this one owns its materials: the slab and curb
+ * geometry and the TSL that shades them live together here.
+ *
+ * ```js
+ * const sidewalk = new SidewalkGenerator( { width: 90, depth: 60, height: 0.5 } );
+ * scene.add( sidewalk.build( placements ) ); // placements: Matrix4[]
+ * ```
+ */
+class SidewalkGenerator {
+
+	constructor( parameters = {} ) {
+
+		this.parameters = Object.assign( {}, SidewalkGenerator.defaults, parameters );
+
+		this.material = null; // the procedural concrete, built once and reused across rebuilds
+		this.curbMaterial = null; // the procedural granite curb, likewise
+		this.mesh = null;
+
+	}
+
+	build( placements ) {
+
+		this.dispose();
+
+		const { width, depth, height, radius, curbWidth, curbLip } = this.parameters;
+
+		if ( this.material === null ) this.material = createSidewalkMaterial();
+		if ( this.curbMaterial === null ) this.curbMaterial = createCurbMaterial();
+
+		// the walking slab and the curb are separate meshes so each carries its own material
+		const slab = new InstancedMesh( slabGeometry( width, depth, height, radius, curbWidth ), this.material, placements.length );
+		const curb = new InstancedMesh( curbGeometry( width, depth, height, radius, curbWidth, curbLip ), this.curbMaterial, placements.length );
+
+		for ( let i = 0; i < placements.length; i ++ ) {
+
+			slab.setMatrixAt( i, placements[ i ] );
+			curb.setMatrixAt( i, placements[ i ] );
+
+		}
+
+		slab.computeBoundingSphere();
+		curb.computeBoundingSphere();
+		slab.receiveShadow = curb.receiveShadow = true;
+
+		const group = new Group();
+		group.name = 'Sidewalk';
+		group.add( slab, curb );
+
+		this.mesh = group;
+
+		return group;
+
+	}
+
+	dispose() {
+
+		if ( this.mesh === null ) return;
+
+		this.mesh.traverse( ( o ) => o.geometry && o.geometry.dispose() );
+		this.mesh = null;
+
+	}
+
+}
+
+SidewalkGenerator.defaults = {
+	width: 90, // the block footprint each slab covers
+	depth: 60,
+	height: 0.5, // walking-surface height above the road
+	radius: 5, // corner radius, so the sidewalk turns each intersection instead of a hard 90°
+	curbWidth: 0.13, // top width of the granite kerbstone rimming the block ( ~5 in )
+	curbLip: 0.01 // how far the curb stands proud of the walking surface ( near-flush )
+};
+
+// --- geometry ------------------------------------------------------------
+
+// the block footprint as a rounded-corner rectangle ( centred at the origin ), so the
+// sidewalk turns each intersection instead of meeting the kerb at a hard 90°
+function roundedRect( width, depth, radius ) {
+
+	const w = width / 2;
+	const d = depth / 2;
+	const r = Math.min( radius, w, d );
+
+	const shape = new Shape();
+	shape.moveTo( - w + r, - d );
+	shape.lineTo( w - r, - d );
+	shape.quadraticCurveTo( w, - d, w, - d + r );
+	shape.lineTo( w, d - r );
+	shape.quadraticCurveTo( w, d, w - r, d );
+	shape.lineTo( - w + r, d );
+	shape.quadraticCurveTo( - w, d, - w, d - r );
+	shape.lineTo( - w, - d + r );
+	shape.quadraticCurveTo( - w, - d, - w + r, - d );
+
+	return shape;
+
+}
+
+// extrude a footprint outline up by `height` ( the extrusion runs +Z; stand it up so height is +Y )
+function extrudeUp( shape, height ) {
+
+	const geometry = new ExtrudeGeometry( shape, { depth: height, bevelEnabled: false, curveSegments: 6 } );
+	geometry.rotateX( - Math.PI / 2 );
+
+	return geometry;
+
+}
+
+// the walking slab: the inner concrete surface, inset to sit inside the curb and overlapping
+// it slightly so the seam is buried. base at y = 0, walking surface at `height`.
+function slabGeometry( width, depth, height, radius, curbWidth ) {
+
+	const innerRadius = Math.max( 0.5, radius - curbWidth );
+	return extrudeUp( roundedRect( width - 2 * curbWidth + 0.06, depth - 2 * curbWidth + 0.06, innerRadius ), height );
+
+}
+
+// the curb: a distinct full-height kerbstone band rimming the block ( the outline with an
+// inset hole ), standing proud of the walking slab by `curbLip` and dropping to the road.
+function curbGeometry( width, depth, height, radius, curbWidth, curbLip ) {
+
+	const innerRadius = Math.max( 0.5, radius - curbWidth );
+	const shape = roundedRect( width, depth, radius );
+	shape.holes.push( roundedRect( width - 2 * curbWidth, depth - 2 * curbWidth, innerRadius ) );
+	return extrudeUp( shape, height + curbLip );
+
+}
+
+// --- material ------------------------------------------------------------
+
+// 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 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 ) ) );
+
+	return det.abs().mul( normalView ).sub( grad ).normalize();
+
+}
+
+// an antialiased line repeated at every multiple of `period` ( the scored joints )
+function gridLine( coord, period, halfWidth ) {
+
+	const g = coord.div( period );
+	const d = float( 0.5 ).sub( fract( g ).sub( 0.5 ).abs() ); // distance to nearest line, in periods
+	const aa = fwidth( g ).max( 0.0001 );
+	const hw = halfWidth / period;
+	return smoothstep( float( hw ).add( aa ), float( hw ).sub( aa ), d );
+
+}
+
+// a noise term that only resolves up close: sampled inside a detail branch ( and kept in its
+// own single-output Fn, so it is evaluated only in the output flow that consumes it )
+function detailNoise( p, detail, scale, amp ) {
+
+	return Fn( () => {
+
+		const n = float( 0 ).toVar();
+
+		If( detail.greaterThan( 0 ), () => {
+
+			n.assign( mx_noise_float( p.mul( scale ) ).mul( amp ) );
+
+		} );
+
+		return n;
+
+	} )();
+
+}
+
+function createSidewalkMaterial() {
+
+	// concrete flags: each poured slab a slightly different tone, fine aggregate speckle
+	// and expansion joints scored on a grid both ways
+
+	const p = positionWorld;
+	const detail = smoothstep( 200, 18, p.distance( cameraPosition ) );
+
+	const panel = 1.5; // flag size ( ~5 ft NYC sidewalk flags )
+	const panelHash = fract( sin( floor( p.x.div( panel ) ).mul( 127.1 ).add( floor( p.z.div( panel ) ).mul( 311.7 ) ) ).mul( 43758.5453 ) );
+
+	const tone = mx_noise_float( p.mul( 0.5 ) ).mul( 0.5 ).add( 0.5 );
+
+	// fine aggregate speckle ( grit, tinting the colour ) and grain relief ( driving the normal )
+	const grit = detailNoise( p, detail, 14, 0.07 ).mul( detail );
+	const grain = detailNoise( p, detail, 3, 0.003 );
+
+	const base = mix( color( 0x6f6f68 ), color( 0x8c8c82 ), tone ).mul( panelHash.sub( 0.5 ).mul( 0.16 ).add( 1 ) ); // per-flag tone
+	const concrete = base.add( grit );
+
+	const joints = gridLine( p.x, panel, 0.045 ).max( gridLine( p.z, panel, 0.045 ) ).mul( detail );
+
+	const material = new MeshStandardNodeMaterial();
+	material.colorNode = concrete.mul( joints.mul( 0.45 ).oneMinus() );
+	material.roughnessNode = float( 0.92 ).sub( panelHash.mul( 0.05 ) );
+	material.normalNode = bumpNormal( grain.sub( joints.mul( 0.012 ) ).mul( detail ) ); // world units: ~3 mm grain, ~12 mm scored joints
+
+	return material;
+
+}
+
+function createCurbMaterial() {
+
+	// granite kerbstone: a dense, cool grey stone — darker and smoother than the concrete
+	// flags — with a fine speckle, segment joints every ~1.5 m and a grimier road-facing face
+
+	const p = positionWorld;
+	const detail = smoothstep( 200, 18, p.distance( cameraPosition ) );
+
+	const tone = mx_noise_float( p.mul( 0.6 ) ).mul( 0.5 ).add( 0.5 );
+	const stone = mix( color( 0x46463f ), color( 0x5c5c54 ), tone ).add( detailNoise( p, detail, 18, 0.05 ).mul( detail ) ); // dark cool granite, fine speckle
+
+	const seg = 1.5; // kerbstone segment length
+	const joints = gridLine( p.x, seg, 0.04 ).max( gridLine( p.z, seg, 0.04 ) ).mul( detail );
+	const top = smoothstep( 0.5, 0.85, normalWorldGeometry.y ); // 1 on the curb top, 0 on its walls
+	const dressed = mix( stone.mul( 0.7 ), stone, top ).mul( joints.mul( 0.4 ).oneMinus() ); // grimier on the road-facing face
+
+	const material = new MeshStandardNodeMaterial();
+	material.colorNode = dressed;
+	material.roughnessNode = float( 0.7 ).add( tone.mul( 0.1 ) ); // flamed granite: matte, a touch smoother than the concrete sidewalk
+	material.normalNode = bumpNormal( detailNoise( p, detail, 4, 0.002 ).mul( detail ) ); // fine granite grain
+
+	return material;
+
+}
+
+export { SidewalkGenerator };