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

# Shape the sky. Light the world.

> Build immersive spaces with procedural skies, Blender panoramas, reflections, lighting, and fog.

An agent can set the atmosphere around its creations: a low sun across a workshop, soft reflections on a metal sculpture, or a panoramic landscape made in Blender. You can adjust the same environment in **Settings → Scene → Sky & lighting**.

These features are available on `main` after v1.0.1. Update the Entity worker, execution backend, and Spatial gateway together.

## Start with a sky

Use `ar_environment capabilities` to read the running contract. With a connected Spatial session, this call creates a warm atmosphere, positions the sun, and adjusts the scene lighting:

```json theme={"theme":"github-light-default"}
{
  "name": "ar_environment",
  "arguments": {
    "command": "configure",
    "payload": {
      "sky": {
        "type": "atmosphere",
        "elevation": 6,
        "azimuth": 240,
        "turbidity": 6
      },
      "lighting": {
        "key": { "color": "#ffd6aa", "intensity": 2 },
        "ambient": { "intensity": 0.15 }
      },
      "fog": { "color": "#d5bcba", "density": 0.015 },
      "exposure": 0.8,
      "ground": false
    }
  }
}
```

The directional key light follows the atmospheric sun unless you supply its own `position`. Environment reflections let materials respond to the surrounding sky. Visible background brightness and reflection strength have separate controls.

The tool waits for the renderer to apply the change. Loading failures retain the last working environment. Use `ar_request_capture` with view sharing enabled to judge the result in [Spatial](/spatial/vision); a successful configuration receipt is state evidence, not visual feedback.

## Bring a Blender world into the scene

Build scenery or a World shader in a persistent [Blender project](/spatial/blender), then render it from the intended viewer position:

```json theme={"theme":"github-light-default"}
{
  "name": "ar_blender",
  "arguments": {
    "command": "render",
    "payload": {
      "project_id": "ring_study",
      "options": {
        "projection": "equirectangular",
        "style": "scene",
        "position": [0, 0, 1.6],
        "look_at": [0, 1, 1.6],
        "size": 2048,
        "samples": 32
      }
    }
  }
}
```

This uses the `ring_study` project from the Blender guide; substitute your existing environment project ID. Coordinates here use **Blender Z-up metres**. The result includes the actual image and a `skybox` object. Pass that entire object as `payload` to `ar_environment configure`. Its URL uses the authenticated Spatial gateway and the existing execution host, so the workflow needs no external image storage.

Panoramas are 2:1 JPEG images, with a default width of 2048 and a maximum width of 4096. Rendering does not publish another geometry revision. A scene containing only a World shader can also render a panorama.

A panorama is a distant backdrop. Walking through the room does not reveal the other side of a mountain baked into that image. Publish nearby geometry as GLB, then use [Figments](/spatial/figments) for grips, collisions, physics, and behavior. Combining a backdrop with real foreground geometry gives you an immersive space people can operate.

## Use an existing panorama

Set `sky.type` to `panorama` and `sky.url` to a reachable image URL. The renderer accepts equirectangular JPG, PNG, WebP, Radiance HDR, and EXR images up to **32 MB** and **8192 × 4096**, with a 2:1 aspect ratio.

* Same-origin `/path` URLs use the gateway's existing authentication.
* External URLs must use HTTP or HTTPS and allow browser CORS access. Redirects are rejected.
* `format` is `image`, `hdr`, or `exr`; HDR and EXR are inferred from the URL extension. Supply the format explicitly when the URL has no useful extension.

Imported HDR and EXR images provide high dynamic range lighting. The current Blender panorama helper produces JPEG; use your own export workflow when you need an HDR or EXR artifact.

## Control the appearance

`configure` takes five optional blocks: `sky`, `lighting`, `fog`, `exposure`, and `ground`.

**Omitted blocks stay unchanged. Supplied blocks replace the entire block. `null` resets a block.** For example, changing only `exposure` preserves the sky and lighting. To rotate an existing panorama, inspect its configuration, copy the full `sky` block, update `rotation`, then submit that block. Sending only a new rotation would discard its URL and select the default atmospheric sky.

| Sky setting           | Meaning                                                                   |
| --------------------- | ------------------------------------------------------------------------- |
| `type`                | `atmosphere` or `panorama`                                                |
| `visible`             | Show the sky; defaults to `true`                                          |
| `lighting`            | Use the sky for material illumination and reflections; defaults to `true` |
| `rotation`            | Yaw in radians, from −2π through 2π                                       |
| `backgroundIntensity` | Visible sky brightness, 0–10; defaults to 1                               |
| `intensity`           | Environment lighting strength, 0–10; defaults to 1                        |
| `blur`                | Background blur, 0–1                                                      |
| `immersive`           | Show the sky in XR; defaults to `false`                                   |

An invisible sky can still light the objects. Turning off sky reflections restores the scene's baseline environment lighting. Rotation, brightness, blur, and visibility changes reuse the loaded sky; they do not download or render it again.

Atmospheric skies also accept `elevation` (−10–90 degrees), `azimuth` (−360–360 degrees), `turbidity` (0–20), `rayleigh` (0–4), `mieCoefficient` (0–0.1), and `mieDirectionalG` (0–0.999). Read `capabilities` for the current defaults and contract.

### Lights, fog, and exposure

| Block                                           | Fields                                                                          |
| ----------------------------------------------- | ------------------------------------------------------------------------------- |
| `lighting.key`, `lighting.fill`, `lighting.rim` | `color`, `intensity`, `position`, `target`, `shadows`                           |
| `lighting.hemi`                                 | `sky`, `ground`, `intensity`                                                    |
| `lighting.ambient`                              | `color`, `intensity`                                                            |
| `fog`                                           | Exponential: `type`, `color`, `density`; linear: `type`, `color`, `near`, `far` |
| `exposure`                                      | Tone-mapping exposure, 0.01–8                                                   |
| `ground`                                        | Boolean visibility of the built-in desktop grid                                 |

Colors use `#RRGGBB`; light intensities range from 0 through 30. Light positions and targets use **Spatial Y-up metres**. Exponential fog density ranges from 0 through 1; linear fog requires `far` greater than `near`. Set `fog` to `null` to remove the authored fog.

These controls adjust the scene's existing lights. Use `ar_world` for lights that belong to individual creations. Hiding the grid leaves custom geometry and physics colliders intact; the built-in grid stays hidden in XR.

## Human controls and XR

In **Settings → Scene → Sky & lighting**, you can:

* Show or hide the sky, its reflections, and the desktop ground grid.
* Adjust exposure, sky rotation, brightness, reflection strength, and sun elevation.
* Create an atmospheric sky or apply a panorama URL.
* Enable or disable **Immersive sky in XR**, or reset the authored environment.

XR preserves passthrough by default: the virtual sky and fog are hidden while environment lighting remains available. Set `sky.immersive: true` explicitly to surround the viewer with the sky. The human can turn it off in Settings. These controls do not expose physical camera images or scanned room geometry. Verify appearance and comfort on the target headset.

## Save and recover

The active environment saves with the scene in this browser origin. A different browser or origin has separate state. Panorama URLs remain references; keep their execution-host artifacts on durable storage. An Objects world export or Figment package does not bundle the surrounding sky.

`ar_environment inspect` returns the configuration, revision, load status, last error, and effective lighting and visibility. A failed saved-sky restore preserves its original configuration for retry. Correct the URL or host availability before reloading or applying a replacement.

```json theme={"theme":"github-light-default"}
{ "name": "ar_environment", "arguments": { "command": "clear" } }
```

`clear` cancels a pending load and restores the base scene preset. Choosing a legacy environment preset also clears the authored sky and lighting overrides. **Reset sky & lighting** in Settings clears the authored overrides; **Reset environment** resets the broader environment configuration.

Loading, reflections, and scene rendering run locally after configuration. They do not require repeated agent turns or model polling.