aframe-components

aframe-connecting-line

Draws a line between points on two entities, with control over width (in pixels or world units) and dash patterns (including multi-element patterns like dash-dot), using THREE.Line2. The line position updates automatically whenever the entity at either end moves.

This package registers two A-Frame components:

• connecting-line2 — the component you should use. A THREE.Line2 stroke with width control, rich dash patterns, and an optional solid tube.
• connecting-line — a backward-compatibility wrapper that offers the previous (0.3.x) schema and maps it onto connecting-line2. Existing consumers keep working unchanged; new consumers should use connecting-line2. Its schema is in the appendix below.

Requirements

A-Frame ≥ 1.5.0. both connecting-line andconnecting-line2 render with THREE.Line2 (three/examples/jsm/lines), which needs A-Frame 1.5.0+.

For A-Frame <= 1.4.0, use 0.3.x, which uses THREE.Line.

Installation

<!-- via CDN (development build) -->
<script src="https://cdn.jsdelivr.net/npm/aframe-connecting-line@0.4.0/dist/connecting-line.js"></script>

<!-- via CDN (minified build) -->
<script src="https://cdn.jsdelivr.net/npm/aframe-connecting-line@0.4.0/dist/connecting-line.min.js"></script>

Or via npm:

npm install aframe-connecting-line

import 'aframe-connecting-line'; // registers both components

Installing v0.3.x and earlier

<!-- via CDN (development build) -->
<script src="https://cdn.jsdelivr.net/npm/aframe-connecting-line@0.3.3/connecting-line/index.js"></script>

<!-- via CDN (minified build) -->
<script src="https://cdn.jsdelivr.net/npm/aframe-connecting-line@0.3.3/connecting-line/index.min.js"></script>

Upgrading from 0.3.x to 0.4.x

If you are upgrading from 0.3.x to 0.4.x, you should note the following changes:

A-Frame Version Compatibility

0.4.X is only compatible with A-Frame 1.5.0+

Installation path changed

See “Installation” above - you will need to update the path from connecting-line/index.js to dist/connecting-line.js

Schema change

v0.4.0 delivers a new component connecting-line2 with a revised schema, and additional functionality: dash patterns, width configurable in metres or pixels, and different semantics (width = 0 now makes the line invisible; in v0.3.0 it rendered the line at 1px width).

The component connecting-line preserves the v0.3.x schema.

Changes in 0.4.0

For the full list of changes in this release, see RELEASE-NOTES.md.

connecting-line2 schema

Property	Type	Default	Description
start	selector		Entity to draw the line from.
startOffset	vec3	0 0 0	Offset of the line start, in the start entity’s local space.
end	selector		Entity to draw the line to.
endOffset	vec3	0 0 0	Offset of the line end, in the end entity’s local space.
color	color	#74BEC1	Line colour.
opacity	number	1	Line opacity.
visible	bool	true	Whether the line is visible.
lengthAdjustment	none/scale/extend/absolute	none	How to adjust the rendered length relative to the start–end distance (see below).
lengthAdjustmentValue	number	0	Value used by lengthAdjustment (meaning depends on the mode).
updateEvent	string	””	If set, per-tick() auto-update is suspended; the line only updates when this event fires on the start entity, end entity, or this entity. Useful for static or rarely-moving lines.
width	number	1	Line width, in units. Decimals allowed. 0 = invisible (no floor); sub-1px px widths render as faint antialiased hairlines.
units	px / m	px	Unit for the width. px = screen-constant; m = world units (scales with zoom).
dash	array of number	[]	Dash pattern [dashA, gapA, dashB, gapB, …] in dashUnits. Empty ⇒ solid. An odd-length array drops its trailing element ([1,1,1]→[1,1]; [5]→solid). Multi-element arrays produce dash-dot / dash-dot-dot patterns (decomposed into overlaid lines internally).
dashUnits	auto / px / m	auto	Unit for the dash pattern. auto → px only when units set to px, and camera is orthographic, otherwise m.
dashOffset	number	0	Phase offset into the pattern, in dashUnits.
tubeRadius	number	0	Optional solid cylinder radius (world units), rendered in addition to the line. 0 = no tube. Always solid; never dashes.
segments	int	4	Tube radial segments (only used when tubeRadius > 0).
shader	string	flat	Tube material shader (only used when tubeRadius > 0).

Width vs dash units

width and dash have independent units. units controls the line width; dashUnits controls the dash pattern. The default dashUnits: auto keeps the dash:width ratio constant by matching the width unit, with the one perspective-camera override noted above.

Dash patterns and overlay decomposition

A single dashed LineMaterial can express only one dash/gap pair. Patterns with more than one (dash-dot, dash-dot-dot) are decomposed into N overlaid Line2s, one per dash run, sharing one geometry. Examples (values in dashUnits):

dash	Pattern	Overlays (dashSize, gapSize, dashOffset)
[]	solid	one solid line
[4,4]	dashed	(4, 4, 0)
[1,3]	dotted*	(1, 3, 0)
[6,2,1,2]	dash-dot	(6, 5, 0), (1, 10, 3)
[6,2,1,2,1,2]	dash-dot-dot	(6, 8, 0), (1, 13, 6), (1, 13, 3)

* Dashes are butt-capped (LineMaterial has no cap option), so a “dot” renders as a small square, not a round dot.

Raycasting — world-distance, via an invisible pick proxy

Raycasting against lines uses a configurable threshold distance, so that an exact match is not required for a raycaster to register a hit against a thin line.

This is configured on the THREE raycaster’s params.Line property.

When working with A-Frame, we recommend configuring this using the raycaster-thresholds component to configure this property. The THREE.js default value of 1m is larger than is typically appropriate for A-Frame applications.

Note that even when a line is rendered wider than this threshold (either via width or tubeRadius, raycasting occurs based solely on this threshold, not the wider shape of the rendered line.

Length adjustment

lengthAdjustment (with lengthAdjustmentValue):

• none — value ignored; line spans start→end exactly.
• scale — value is a scale factor relative to the actual distance.
• extend — value is an absolute length to extend by (negative trims short).
• absolute — value is an absolute target length, ignoring the actual distance.

Examples

• connecting-line2 pattern gallery
• connecting-line2 interactive (dat-gui)
• legacy connecting-line usage

Building

npm install
npm run dist        # builds dist/connecting-line.js and dist/connecting-line.min.js
npm run dist:dev    # dev build only
npm run dist:prod   # minified build only

Code

• connecting-line2.js
• connecting-line.js (legacy wrapper)

Appendix: connecting-line schema

The connecting-line component provides back compatibility with v0.3.x

Property	Description	Default
start	selector for entity to draw line from
startOffset	offset of the start of the line in the start entity’s coordinate space	0 0 0
end	selector for entity to draw line to
endOffset	offset of the end of the line in the end entity’s coordinate space	0 0 0
color	line colour	#74BEC1
opacity	line opacity	1
visible	line visibility	true
lengthAdjustment	one of: none, scale, extend, absolute	none
lengthAdjustmentValue	value used in adjusting the line length (meaning depends on lengthAdjustment)	0
width	Optional line width. If > 0, a cylinder of radius width/2 is rendered in addition to the line, giving a more substantial appearance when inspected closely.	0
segments	Only used if width > 0. Radial segments for the cylinder. Default 4 (square cross-section).	4
shader	Cylinder material shader: “flat”, “standard”, or a custom registered shader.	flat
updateEvent	If set, auto-update each tick() is suspended; the line updates only when this event fires on the start entity, end entity, or this entity.	””

This site is open source. Improve this page.