> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grounds.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Client panorama backgrounds

> Provide version-specific cube faces and configure client-owned background motion independently of MOTD data.

The library can show a moving cubemap behind a server-list preview. It is
framework independent and does not require Grounds or a Portal connection.
Panorama sources stay in the host's preview context; they are not added to
`ServerListDocument` or exported to the Minecraft status response.

## Supply host-owned faces

Provide six square images in the same order as the Java client resources
`panorama_0` through `panorama_5`: front, right, back, left, top and bottom.
All faces must have the same dimensions, from 1 through 2048 pixels. Each face
may be a same-origin URL, data URL, blob URL, or a cross-origin URL that allows
anonymous CORS image access (`Access-Control-Allow-Origin`). Cross-origin faces
are requested without credentials. A blocked image retains the static fallback.

```ts theme={null}
import type { ClientAssetProvider, PanoramaBackground } from "@groundsgg/motd";

const background: PanoramaBackground = {
  panorama: {
    faces: [front, right, back, left, top, bottom],
    fallbackImageUrl: staticImage,
    overlayImageUrl: optionalOverlay,
  },
  motion: { initialYaw: 0, speed: 1, paused: false },
  blur: 5,
  dimming: 1 / 3,
};

const assetProvider: ClientAssetProvider = (profile) => {
  if (profile.id === "java-26.3") return { background };
  return undefined;
};

const context = {
  ...previewContext,
  background: "auto",
  assetProvider,
  animations: true,
};
```

An explicit `context.background` takes precedence over `assetProvider(profile)`.
Return per-profile sources from the provider when the client versions use
different scenes. Replacing a provider or returning equivalent new arrays does
not reload unchanged face URLs.

## Motion and appearance

At speed `1`, the audited Java 26.3 camera turns at 2 degrees per second, with
an 85-degree vertical field of view and a 10-degree downward pitch. `initialYaw`
sets the starting heading. `speed` accepts finite values from -10 to 10; zero
stops motion and negative values reverse it. Speed and pause changes preserve
the current phase. `panoramaPose(elapsedMs, initialYaw?)` returns the DOM-free
camera pose for integrations that need the same timing model.

The optional blur radius is 0–32 CSS pixels and defaults to 5; dimming is a
black opacity from 0 to 1 and defaults to 1/3. A host-owned overlay image can
add custom artwork above the faces. These CSS effects approximate native
post-processing. They do not claim pixel equality with Minecraft's blur shader
or its original panorama images.

The renderer keeps a static fallback while faces load and after an image, size,
or GPU error. Faces must be square, equally sized and no larger than 2048 pixels.
WebGL projects the cubemap without a runtime dependency. Previews in one document
share a GPU context and identical textures, with independent output canvases and
animation clocks. Iframes use their own document's resources. The last destroyed
preview releases the GPU resources. WebGL being disabled or losing its context
restores the static fallback. Late image callbacks cannot replace a newer source
or restore a destroyed preview.

Full server-list and row presentations both rotate. Motion pauses when
`motion.paused` is true, `context.animations` is false, the
document is hidden, or the operating
system requests reduced motion. Destroying the preview cancels animation frames
and listeners. The decorative backdrop does not accept pointer or keyboard
input and is hidden from assistive technology.

## Rights and demo art

Hosts are responsible for image rights and availability. The library does not
ship extracted Minecraft textures or original release panoramas. Its example
faces are original CC0-1.0 illustrations, generated by
`tools/build-panorama-demo.mjs` and checked against
`assets/ui/panorama-demo/manifest.json`. The DOM and React examples map separate
original scenes to the 26.3 and 1.21.1 profiles.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.