geometry

The geometry component provides a basic shape for an entity. The primitive property defines the general shape. Geometric primitives, in computer graphics, are irreducible basic shapes. A material component is commonly defined to provide a appearance alongside the shape to create a complete mesh.

Table of Contents

Base Properties

Every geometry type will have these properties:

PropertyDescriptionDefault Value
bufferTransform geometry into a BufferGeometry to reduce memory usage at the cost of being harder to manipulate.true
mergeToA selector to an entity to merge the entity’s geometry to.None
primitiveName of a geometry (e.g., one of the geometries listed below). Determines the geometry type and what other properties are available.box
skipCacheDisable retrieving the shared geometry object from the cache.false

mergeTo

Merging geometries reduces the number of draw calls, greatly improving performance under certain circumstances. Merged geometries will inherit the material of the target geometry. Thus, it’s useful when we have entities that share the same material.

Once merged, we can no longer manipulate the individual geometry independently.

For geometry merging to be able to work, we will have to turn off buffer and turn on skipCache.

<a-entity id="target" geometry="primitive: box; buffer: false; skipCache: true" material="color: red"></a-entity>
<a-entity geometry="primitive: box; buffer: false; skipCache: true; mergeTo: #target"
material="color: red" position="1 2 3"></a-entity>

Built-in Geometries

box

The box geometry defines boxes (i.e., any quadilateral, not just cubes).

<a-entity geometry="primitive: box; width: 1; height: 1; depth: 1"></a-entity>
PropertyDescriptionDefault Value
widthWidth (in meters) of the sides on the X axis.1
heightHeight (in meters) of the sides on the Y axis.1
depthDepth (in meters) of the sides on the Z axis.1

circle

The circle geometry creates flat two-dimensional circles. These can be complete circles or partial circles (like Pac-Man). Note that because circles are flat, A-Frame will only render a single face of the circle if we don’t specify side: double on the material component.

<a-entity geometry="primitive: circle; radius: 1" material="side: double"></a-entity>
PropertyDescriptionDefault Value
radiusRadius (in meters) of the circle.1
segmentsNumber of triangles to construct the circle, like pizza slices. A higher number of segments means the circle will be more round.32
thetaStartStart angle for first segment. Can be used to define a partial circle.0
thetaLengthThe central angle (in degrees). Defaults to 360, which makes for a complete circle.360

thetaLength and thetaStart Properties

In degrees, thetaStart defines where to start a circle or arc and thetaLength defines where a circle or arc ends. If we wanted to make a ( shape, we would start the circle halfway through and define the length as half of a circle. We can do this with thetaStart: 180; thetaLength: 180. Or if we wanted to make a ) shape, we can do thetaStart: 0; thetaLength: 180.

Useful cases might be to animating thetaStart to create a spinner effect or animating thetaLength on a fuse-based cursor for visual feedback.

cone

The cone geometry is a cylinder geometry that have different top and bottom radii.

<a-entity geometry="primitive: cone; radiusBottom: 1; radiusTop: 0.1"></a-entity>
PropertyDescriptionDefault Value
heightHeight of the cone.2
openEndedWhether the ends of the cone are open (true) or capped (false).false
radiusBottomRadius of the bottom end of the cone.1
radiusTopRadius of the top end of the cone.1
segmentsRadialNumber of segmented faces around the circumference of the cone.36
segmentsHeightNumber of rows of faces along the height of the cone.18
thetaStartStarting angle in degrees.0
thetaLengthCentral angle in degrees.360

cylinder

The cylinder geometry creates cylinders in the traditional sense like a Coca-Cola™ can, but it can also define shapes such as tubes and curved surfaces.

We can create a basic cylinder using height and radius:

<a-entity geometry="primitive: cylinder; height: 3; radius: 2"></a-entity>

We can create a tube by making the cylinder open-ended, which removes the top and bottom surfaces of the cylinder such that the inside is visible. Then we need a double-sided material to render properly:

<!-- Tube -->
<a-entity geometry="primitive: cylinder; openEnded: true" material="side: double"></a-entity>

We can create a cured surfaces by specifying the arc via thetaLength such that the cylinder doesn’t curve all the way around, making the cylinder open-ended, and then making the material double-sided:

<!-- Curved surface -->
<a-entity geometry="primitive: cylinder; openEnded: true; thetaLength: 180"
material="side: double"></a-entity>
PropertyDescriptionDefault Value
radiusRadius of the cylinder.1
heightHeight of the cylinder.2
segmentsRadialNumber of segmented faces around the circumference of the cylinder.36
segmentsHeightNumber of rows of faces along the height of the cylinder.18
openEndedWhether the ends of the cylinder are open (true) or capped (false).false
thetaStartStarting angle in degrees.0
thetaLengthCentral angle in degrees.360

We can create prisms by changing the number of radial segments (i.e., sides). For example, to make a hexagonal prism:

<!-- Hexagonal prism -->
<a-entity geometry="primitive: cylinder; segmentsRadial: 6"></a-entity>

dodecahedron

The dodecahedron geometry creates a polygon with twelve equally-sized faces.

<a-entity geometry="primitive: dodecahedron; radius: 2"></a-entity>
PropertyDescriptionDefault Value
radiusRadius (in meters) of the dodecahedron.1

octahedron

The octahedron geometry creates a polygon with eight equilateral triangular faces.

<a-entity geometry="primitive: octahedron"></a-entity>
PropertyDescriptionDefault Value
radiusRadius (in meters) of the tetrahedron.1

plane

The plane geometry creates a flat surface. Because planes are flat, A-Frame will render only a single face of the plane unless we specify side: double on the material component.

<a-entity geometry="primitive: plane; height: 10; width: 10" material="side: double"></a-entity>
PropertyDescriptionDefault Value
widthWidth along the X axis.1
heightHeight along the Y axis.1

ring

The ring geometry creates a flat ring, like a CD. Because the ring is flat, A-Frame will only render a single face of the ring we specify side: double the material component.

<a-entity geometry="primitive: ring; radiusInner: 0.5; radiusOuter: 1"
material="side: double"></a-entity>
PropertyDescriptionDefault Value
radiusInnerRadius of the inner hole of the ring.1
radiusOuterRadius of the outer edge of the ring.1
segmentsThetaNumber of segments. A higher number means the ring will be more round.32
segmentsPhiNumber of triangles within each face defined by segmentsTheta.8
thetaStartStarting angle in degrees.0
thetaLengthCentral angle in degrees.360

sphere

The sphere geometry creates spheres (e.g., balls). We can create a basic sphere:

<a-entity geometry="primitive: sphere; radius: 2"></a-entity>

We can create polyhedrons and abstract shapes by specifying the number of horizontal angles and faces:

<a-entity geometry="primitive: sphere; segmentsWidth: 2; segmentsHeight: 8"></a-entity>
PropertyDescriptionDefault Value
radiusRadius of the sphere.1
segmentsWidthNumber of horizontal segments.18
segmentsHeightNumber of vertical segments.36
phiStartHorizontal starting angle.0
phiLengthHorizontal sweep angle size.360
thetaStartVertical starting angle.0
thetaLengthVertical sweep angle size.360

tetrahedron

The tetrahedron geometry creates a polygon with four triangular faces.

<a-entity geometry="primitive: tetrahedron; radius: 2"></a-entity>
PropertyDescriptionDefault Value
radiusRadius (in meters) of the tetrahedron.1

torus

The torus geometry creates a donut or curved tube shape:

<!-- Half donut -->
<a-entity geometry="primitive: torus; radius: 2; radiusTubular: 0.5; arc: 180"></a-entity>
PropertyDescriptionDefault Value
radiusRadius of the outer edge of the torus.1
radiusTubularRadius of the tube.0.2
segmentsRadialNumber of segments along the circumference of the tube ends. A higher number means the tube will be more round.36
segmentsTubularNumber of segments along the circumference of the tube face. A higher number means the tube will be more round.32
arcCentral angle.360

torusKnot

The torus knot geometry creates a pretzel shape. A pair of coprime integers, p and q, defines the particular shape of the pretzel. If p and q are not coprime the result will be a torus link:

<a-entity geometry="primitive: torusKnot; p: 3; q:7"></a-entity>
PropertyDescriptionDefault Value
radiusRadius that contains the torus knot.1
radiusTubularRadius of the tubes of the torus knot.0.2
segmentsRadialNumber of segments along the circumference of the tube ends. A higher number means the tube will be more round.36
segmentsTubularNumber of segments along the circumference of the tube face. A higher number means the tube will be more round.32
pHow many times the geometry winds around its axis of rotational symmetry.2
qHow many times the geometry winds around a circle in the interior of the torus.3

Register a Custom Geometry

We can register our own geometries using AFRAME.registerGeometry and creating an object that is an instance of THREE.Geometry. A-Frame registers all built-in geometries using this API. Here is how A-Frame registers the box geometry:

AFRAME.registerGeometry('box', {
schema: {
depth: {default: 1, min: 0},
height: {default: 1, min: 0},
width: {default: 1, min: 0},
segmentsHeight: {default: 1, min: 1, max: 20, type: 'int'},
segmentsWidth: {default: 1, min: 1, max: 20, type: 'int'},
segmentsDepth: {default: 1, min: 1, max: 20, type: 'int'}
},
init: function (data) {
this.geometry = new THREE.BoxGeometry(data.width, data.height, data.depth);
}
});

Like with registering components, we provide a name, a schema that will expose the properties of the geometry, and lifecycle methods. Then we need to create the geometry and set on this.geometry through the init and update lifecycle methods.

When a geometry component sets its primitive property to the custom geometry name, we can set the properties of the custom geometry on the geometry component. Say we registered a custom geometry:

AFRAME.registerGeometry('example', {
schema: {
vertices: {
default: ['-10 10 0', '-10 -10 0', '10 -10 0'],
}
},
init: function (data) {
var geometry = new THREE.Geometry();
geometry.vertices.push.call(
geometry.vertices,
data.vertices.map(function (vertex) {
var points = vertex.split(' ').map(parseInt);
return new THREE.Vector3(points[0], points[1], points[2]);
});
);
geometry.faces.push(new THREE.Face3(0, 1, 2));
this.geometry = geometry;
}
});

We can then use that custom geometry in HTML:

<a-entity geometry="primitive: example; vertices: 1 1 1, 2 2 2, 3 3 3"></a-entity>