API Reference

Makio MeshLine is built around three creative-coding requirements: performance, customization, and simplicity.

The regular MeshLine API uses TSL and requires Three.js WebGPURenderer; it works with both its WebGPU and WebGL2 backends on Three.js r186+. The root MeshLineCompute export requires WebGPU compute support. The optional gpu-culling and gpu-path entry points also require native WebGPU. Existing v1 users should review Migrating from v1 to V2 before upgrading.

MeshLine

High-level façade – the class you will use 99 % of the time. It can build either a camera-facing screen stroke or a camera-independent world-space surface.

new MeshLine(options?: MeshLineConfigureOptions)

For convenience, use the fluent API below:

new MeshLine().color(0xff0000).gradientColor(0xff00ff) // etc.

Use .surface( options ) when the path represents a road, track, or lit ribbon. See World-Space Surfaces.

MeshLineCompute

Experimental WebGPU-only curve engine. It stores autonomous curve points in GPU storage buffers, updates them with motion and arc-length compute passes, and renders the result through MeshLine's ribbon material.

new MeshLineCompute(options?: MeshLineComputeOptions)

Call step(renderer, deltaSeconds) once per frame to dispatch the motion and cumulative arc-length compute passes. Use the regular MeshLine API when a WebGL2-compatible path is required.

MeshLineGeometry

Low-level geometry builder – it's created internally by MeshLine; reach for it when you need to update or add extra buffer attributes.

new MeshLineGeometry(options?: MeshLineGeometryOptions)

MeshLineNodeMaterial

Specialised NodeMaterial that understands the vertex attributes generated by MeshLineGeometry and renders them with:

• Constant CSS-pixel thickness or scene-space projected thickness, plus optional analytic edge antialiasing (.antialias(true))
• Optional gradients, textures, dashes, and shadow casting + 3D cylindrical shadow receiving (.shadow(true, true) / .setReceiveShadow(true))
• Bounded miter, bevel, or round joins with 3D projected fold protection (join.fold: 'geometry' | 'exact' | false, miterLimit tunes the cap) — optional sharp-bend subdivision is available for static paths
• Optional TSL hooks and the normalized lineCoord stroke-silhouette node to customize the vertex & fragment easily

new MeshLineNodeMaterial(options?: MeshLineMaterialOptions)

MeshLineSurfaceGeometry and MeshLineSurfaceNodeMaterial

World-space geometry and PBR material used by new MeshLine().surface(). The geometry creates camera-independent frames, distance-based UVs, normals, tangents, true bevel/round joins, caps, and explicit reversal splits for roads and ribbons.

new MeshLine()
  .lines( roadPoints )
  .lineWidth( 4 )
  .surface( { frame: 'transport', uvMode: 'distance', uvScale: 5 } )
  .join( { type: 'round', segments: 8 } )
  .cap( { type: 'round', segments: 8 } )
  .build()

Prefer the MeshLine façade unless you specifically need to compose the low-level surface geometry and material yourself.

MeshLineCullingSystem

Optional native-WebGPU chunk culling for very large opaque packed lines and road surfaces. Import it from makio-meshline/gpu-culling so the regular WebGPU/WebGL2 entry point never loads the WebGPU indirect APIs.

const culling = MeshLineCullingSystem.attach(renderer, scene, { mode: 'auto', cullCamera: null })
culling.add(line)

The system compacts visible indices into one indirect draw (with optional detached cullCamera inspection) and fails open for unsupported backends, passes, materials, or bounds.

MeshLineGPUPath

Experimental native-WebGPU point-centric renderer for one very large static open screen line. Import it from makio-meshline/gpu-path. It stores source points once, optionally applies a guaranteed discrete local-space dyadic tolerance, and renders one non-indexed indirect draw. Advanced mode emits true bevel/round joins, square/round caps, explicit reversal splits, and width-padded homogeneous clipping.

Pass { variableTopology: true } as the second constructor argument to opt the otherwise-fast miter + butt signature into shared miter triangles and a true over-limit bevel. Adapter storage limits are validated before staging; oversized topology fails back instead of producing a WebGPU validation error.

The wrapper always retains a complete CPU MeshLine and selects it for unsupported backends, multi-line/closed/surface/shadow/XR profiles, or failures. The fallback preserves full source detail but uses the regular fixed-strip miter/butt visuals. Advanced GPU topology remains full detail because local-space LOD cannot safely remove camera-dependent projected cusps.

MeshLinePicker & MeshLinePickerHelper

GPU pixel-picker that identifies which line / instance is under the cursor — works with GPU-positioned, instanced, animated, and hook-driven lines because it reads what was rendered, not a CPU proxy.

new MeshLinePicker(renderer, scene, camera, options?: MeshLinePickerOptions)

MeshLinePickerHelper is a Three.js-style visual helper (in the spirit of BoxHelper / SkeletonHelper) that overlays the picker's wide hit-zones on your scene, painted with a distinct hue per instance — useful for verifying coverage and debugging missed hits.

const helper = new MeshLinePickerHelper(picker, { opacity: 0.45 })
scene.add(helper)
// in your render loop:
helper.update()

See the dedicated picking page for the full API.

Implementation Notes

• Only the uniforms / attributes needed are created & uploaded to the GPU.
• Many hooks are available for customizing line behavior and rendering.
• Instancing and GPU positions support large repeated or procedural line scenes.
• MeshLineCompute keeps animated curve point state and cumulative arc length on the GPU for experimental WebGPU-only simulation workflows.
• Batching is available for CPU-controlled animation or static lines.
• The surface profile uses ordinary world-space mesh geometry for roads, tracks, and lit ribbons.
• Optional native-WebGPU chunk culling is available for large opaque packed paths.
• There are no runtime dependencies beyond three.