Spheres

What is a Sphere3D?

A Sphere3D renders as a sphere with a given center and radius. Spheres are useful for:

Representing volumes or regions in space
Visualizing bounding spheres
Drawing planets, atoms, or other round objects
Creating semi-transparent enclosures around other objects

Basic Usage

const sphere = scene.create("sphere3d", {
  center: vec3(0, 2, 0),
  radius: 1.5,
  color: "dodgerblue",
});

Styling Spheres

Color

Any CSS color string works:

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

Opacity

Spheres support transparency via the opacity property (0 = fully transparent, 1 = fully opaque):

scene.create("sphere3d", {
  center: vec3(0, 0, 0),
  radius: 2,
  color: "cyan",
  opacity: 0.3, // Semi-transparent
});

This is great for showing a region without hiding the objects inside it.

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 radius property sets the sphere's size in world units:

scene.create("sphere3d", { center: vec3(0, 0, 0), radius: 0.5 }); // Small
scene.create("sphere3d", { center: vec3(3, 0, 0), radius: 1 });   // Medium
scene.create("sphere3d", { center: vec3(6, 0, 0), radius: 2 });   // Large

Interactive Spheres

Click to Change Color

Toggle the sphere's color each time it's clicked:

const colors = ["tomato", "dodgerblue", "gold", "mediumseagreen"];
let index = 0;

const sphere = scene.create("sphere3d", {
  center: vec3(0, 1, 0),
  radius: 1.5,
  color: colors[0],
});

sphere.on("click", () => {
  index = (index + 1) % colors.length;
  sphere.color.set(colors[index]);
});

Hover to Highlight

Change the sphere's opacity when the pointer enters and leaves:

const sphere = scene.create("sphere3d", {
  center: vec3(0, 1, 0),
  radius: 1.5,
  color: "dodgerblue",
  opacity: 0.4,
});

sphere.on("hover", (event) => {
  if (event.phase === "enter") {
    sphere.opacity.set(0.8);
  } else if (event.phase === "leave") {
    sphere.opacity.set(0.4);
  }
});

Updating Properties

const sphere = scene.create("sphere3d", {
  center: vec3(0, 0, 0),
  radius: 1,
  color: "white",
});

// Update properties
sphere.center.set(vec3(2, 2, 2));
sphere.radius.set(3);
sphere.color.set("purple");
sphere.opacity.set(0.5);

API Reference

Options

Property	Type	Default	Description
`center`	`Vec3`	`{ x: 0, y: 0, z: 0 }`	Center position in 3D space
`radius`	`number`	`1`	Sphere radius in world units
`color`	`string`	`"white"`	CSS color string
`opacity`	`number`	`1`	Opacity (0 to 1)
`visible`	`boolean`	`true`	Whether the sphere is shown
`pointerEvents`	`"auto" \| "none"`	`"auto"`	Whether the sphere receives pointer events
`tags`	`string[]`	`[]`	Custom tags for grouping

Returned Item

Field	Type	Description
`id`	`string`	Unique identifier
`center`	`BoundAtom<Vec3>`	Center position atom
`radius`	`BoundAtom<number>`	Radius atom
`color`	`BoundAtom<string>`	Color atom
`opacity`	`BoundAtom<number>`	Opacity atom
`visible`	`BoundAtom<boolean>`	Visibility atom
`pointerEvents`	`BoundAtom<string>`	Pointer events atom
`tags`	`BoundAtom<string[]>`	Tags atom

On this page