Planes

What is a Plane3D?

A Plane3D renders as a bounded rectangular surface in 3D space, defined by a center point and a normal vector. Planes are useful for:

Visualizing geometric planes and cross-sections
Drawing walls, floors, and other flat surfaces
Showing tangent planes to curves or surfaces
Representing mirror/reflection planes in symmetry

Basic Usage

const plane = scene.create("plane3d", {
  point: vec3(0, 0, 0),
  normal: vec3(0, 1, 0),
  width: 4,
  height: 4,
  color: "dodgerblue",
});

Styling Planes

Color

Any CSS color string works:

scene.create("plane3d", { point: vec3(0, 0, 0), color: "red" });
scene.create("plane3d", { point: vec3(3, 0, 0), color: "#4ecdc4" });
scene.create("plane3d", { point: vec3(6, 0, 0), color: "hsl(280, 80%, 60%)" });

Opacity

Planes default to 0.5 opacity. Set opacity from 0 (fully transparent) to 1 (fully opaque):

scene.create("plane3d", {
  point: vec3(0, 0, 0),
  normal: vec3(0, 1, 0),
  color: "cyan",
  opacity: 0.3, // Semi-transparent
});

Multiple transparent items that overlap can cause rendering artifacts where one hides the other. If you need overlapping items, keep at most one of them transparent.

Size

The width and height properties set the plane's dimensions in world units:

scene.create("plane3d", { point: vec3(0, 0, 0), width: 2, height: 2 }); // Small
scene.create("plane3d", { point: vec3(4, 0, 0), width: 4, height: 4 }); // Medium
scene.create("plane3d", { point: vec3(8, 0, 0), width: 8, height: 4 }); // Wide

Edges

By default, planes render with visible edge lines. Toggle them with showEdges:

scene.create("plane3d", {
  point: vec3(0, 0, 0),
  normal: vec3(0, 1, 0),
  color: "gold",
  showEdges: false, // No border
});

Orientation

The normal vector controls which direction the plane faces. The plane surface is perpendicular to this vector:

// Horizontal plane (facing up)
scene.create("plane3d", { normal: vec3(0, 1, 0), color: "red" });

// Vertical plane (facing forward)
scene.create("plane3d", { point: vec3(3, 1, 0), normal: vec3(0, 0, 1), color: "green" });

// Vertical plane (facing right)
scene.create("plane3d", { point: vec3(6, 1, 0), normal: vec3(1, 0, 0), color: "blue" });

The normal does not need to be a unit vector, it will be normalized internally.

Examples

Normal Defined by a Vector

Use a draggable vector to control the plane's orientation:

const normal = scene.create("vector3d", {
  origin: vec3(0, 0, 0),
  vector: vec3(0, 2, 1),
  color: "tomato",
});

scene.create("plane3d", {
  point: vec3(0, 0, 0),
  normal: normal.vector,
  width: 4,
  height: 4,
  color: "gold",
  opacity: 0.5,
});

Drag the vector tip to tilt the plane.

Plane Through a Draggable Point

A plane that moves with a point but keeps a fixed orientation:

const anchor = scene.create("point3d", {
  coords: vec3(0, 2, 0),
  color: "dodgerblue",
  draggable: "y",
});

scene.create("plane3d", {
  point: anchor.coords,
  normal: vec3(0, 1, 0),
  width: 4,
  height: 4,
  color: "dodgerblue",
  opacity: 0.4,
});

The point is constrained to the y-axis, so dragging it slides the horizontal plane up and down.

Updating Properties

const plane = scene.create("plane3d", {
  point: vec3(0, 0, 0),
  normal: vec3(0, 1, 0),
  color: "white",
});

// Update properties
plane.point.set(vec3(2, 2, 2));
plane.normal.set(vec3(1, 0, 0));
plane.width.set(6);
plane.height.set(4);
plane.color.set("purple");
plane.opacity.set(0.3);
plane.showEdges.set(false);

API Reference

Options

Property	Type	Default	Description
`point`	`Vec3`	`{ x: 0, y: 0, z: 0 }`	Center position of the plane
`normal`	`Vec3`	`{ x: 0, y: 1, z: 0 }`	Normal vector defining plane orientation
`width`	`number`	`2`	Plane width in world units
`height`	`number`	`2`	Plane height in world units
`color`	`string`	`"white"`	CSS color string
`opacity`	`number`	`0.5`	Opacity (0 to 1)
`showEdges`	`boolean`	`true`	Whether to render edge lines
`visible`	`boolean`	`true`	Whether the plane is shown
`pointerEvents`	`"auto" \| "none"`	`"auto"`	Whether the plane receives pointer events
`tags`	`string[]`	`[]`	Custom tags for grouping

Returned Item

Field	Type	Description
`id`	`string`	Unique identifier
`point`	`BoundAtom<Vec3>`	Center position atom
`normal`	`BoundAtom<Vec3>`	Normal vector atom
`width`	`BoundAtom<number>`	Width atom
`height`	`BoundAtom<number>`	Height atom
`color`	`BoundAtom<string>`	Color atom
`opacity`	`BoundAtom<number>`	Opacity atom
`showEdges`	`BoundAtom<boolean>`	Show edges atom
`visible`	`BoundAtom<boolean>`	Visibility atom
`pointerEvents`	`BoundAtom<string>`	Pointer events atom
`tags`	`BoundAtom<string[]>`	Tags atom

On this page