three-roads

three-roads is a TypeScript toolkit for authoring road networks and turning them into renderer-neutral, typed-array meshes. It is designed for browser and Node.js tooling, with a Three.js demo included in this repository.

Packages

Package	Purpose
@three-roads/core	Authoring documents, road-network compilation, geometry, lanes, validation, SVG output, and scenario fixtures.
@three-roads/mesher	Road-surface, marking, junction, and infrastructure mesh generation.
@three-roads/dressing	Streetscape presets and roadside placement plans.
@three-roads/editor-bridge	Stateful editor-facing commands and previews.
@three-roads/cdt	Constrained Delaunay triangulation used by the mesher.

Install

npm install @three-roads/core @three-roads/mesher

@three-roads/dressing and @three-roads/editor-bridge are optional additions. All packages are ESM-only and support Node.js 20 or newer.

Basic workflow

import {
  addRoadTemplate,
  createRoadAuthoringDocument,
  compileRoadNetwork,
  addRoadStroke,
  germanRoadPreset,
  makeLineSegment,
} from '@three-roads/core'
import { buildRoadSurfaceModel, meshRoadSurfaceChunks } from '@three-roads/mesher'

const preset = germanRoadPreset('de-urban-two-way')
let document = createRoadAuthoringDocument({ id: 'main-street' })
document = addRoadTemplate(document, preset.template)
document = addRoadStroke(document, {
  id: 'main-street',
  geometry: [makeLineSegment(0, 0, 0, 0, 100)],
  templateSpans: [{ templateId: preset.template.id, s: 0 }],
})

const compilation = compileRoadNetwork(document)
if (!compilation.ok || !compilation.network || !compilation.physicalTopology) {
  throw new Error('Road network did not compile')
}
const surface = buildRoadSurfaceModel(compilation.network, compilation.physicalTopology)
const meshChunks = meshRoadSurfaceChunks(surface)

The mesh package returns simple positions, normals, UVs, indices, and material groups. Adapt those buffers to Three.js, React Three Fiber, Babylon.js, a file exporter, or your own renderer without a renderer dependency in the package.

Demos

bun install
bun run dev:3d   # interactive Three.js road mesher
bun run dev:svg  # SVG scenario gallery

The 3D demo is in apps/mesher-preview. The gallery is in demos/svg-gallery, with a curated collection of source SVG cases in demos/svg-gallery/public/cases.

GitHub Pages

Pushing to main deploys the 3D demo to vibe-stack.github.io/three-roads. The first deployment may require selecting GitHub Actions under Settings → Pages → Build and deployment in GitHub.

Development

bun install
bun run check
bun run build

Each publishable package has a prepack script that generates JavaScript and declaration files into dist. Before releasing, inspect the exact tarball:

npm pack --dry-run --workspace @three-roads/core
npm pack --dry-run --workspace @three-roads/mesher

Publish public scoped packages with npm authentication configured for the @three-roads scope:

npm publish --workspace @three-roads/core --access public

Documentation

• Build a road network — progressive guide from a first road to junctions, roundabouts, interchanges, and diagnostics.
• Architecture
• Contributing
• @three-roads/cdt API

License

MIT © 2026 @alightinastorm. See LICENSE. The triangulation package retains a third-party attribution in its NOTICE.