# POST /environment

> Talos 0.6 · Since 0.6

A partial sky merged onto the live one.

Goes through the simulation like the other mutating routes, because uploading a panorama and rebuilding the environment cube touch the renderer, which belongs to the sim thread.

## Request

#### Request body: `EnvironmentRequest`

`POST /environment` request: a partial sky, merged onto the live one.

| Field | Type | Required | Description |
|---|---|---|---|
| `sky` | `SkyPatch` | no | The sky fields to change. Absent leaves the sky alone. |
| `ambient` | `number` | no | The flat ambient fill. Absent leaves it alone. |

#### Request body: `SkyPatch`

The sky fields a swap may set. Absent means "leave this one as it is".

| Field | Type | Required | Description |
|---|---|---|---|
| `kind` | `string` | no | `"procedural"`, `"hdr"`, `"color"` or `"atmosphere"` (an atmosphere sky's own settings are written in the scene file). |
| `preset` | `string` | no | A named procedural sky: `clear-noon`, `golden-hour`, `overcast`, `dusk`, `night`. Setting a preset with no `kind` switches to `procedural`, because that is the only thing a preset can mean. |
| `asset` | `string` | no | The `envmap` asset id for an `hdr` sky. It must already be in `scene.assets`: this endpoint swaps skies, it does not add assets to a scene. |
| `intensity` | `number` | no | Scalar on the whole environment. Free to change: no rebuild. |
| `rotation` | `number` | no | Yaw applied to the whole sky, radians. Free to change: no rebuild. |
| `sun_from_sky` | `boolean` | no | Whether the scene's directional light should follow the sky's sun. |
| `sun_elevation` | `number` | no | Sun elevation above the horizon for a procedural sky, radians. Negative is below it. |
| `sun_azimuth` | `number` | no | Sun azimuth for a procedural sky, radians. Setting either angle sets both, so a request giving only one keeps the other from the live sky. |
| `turbidity` | `number` | no | Atmospheric haze for a procedural sky, within `TURBIDITY_MIN`..=`TURBIDITY_MAX`. |

## Response

#### Response: `EnvironmentResponse`

`POST /environment` response: the environment after the swap, and where it went.

| Field | Type | Present | Description |
|---|---|---|---|
| `kind` | `string` | always | `"procedural"`, `"hdr"` or `"color"`. |
| `preset` | `string` | sometimes | The preset name, for a procedural sky. |
| `asset` | `string` | sometimes | The asset id behind an `hdr` sky that loaded. |
| `asset_path` | `string` | sometimes | The file that asset resolved to, as the engine opened it. |
| `intensity` | `number` | always | Scalar on the whole environment. |
| `rotation` | `number` | always | Yaw applied to the sky, radians. |
| `sun_direction` | `number[3]` | sometimes | Travel direction of the sun the sky casts (sun -> scene), when it has one. A `color` sky has none. |
| `sun_color` | `number[3]` | sometimes | Linear RGB of that sun. |
| `sun_intensity` | `number` | sometimes | Its scene-referred irradiance. 0 when the sun is below the horizon. |
| `sun_from_sky` | `boolean` | always | Whether the scene's directional light is following that sun. |
| `ambient` | `number` | sometimes | The flat fill added on top of the image-based diffuse, when the scene has no `sky` field and `ambient` therefore still means what it meant before this change. |
| `findings` | `string[]` | sometimes | Why this is not what the scene asked for: a missing panorama, an undecodable file. Empty when the sky is exactly what was written. |
| `persisted` | `boolean` | always | Always false: this endpoint reports the live sky, and a live sky is never on disk until someone edits the scene file. Present so a client does not have to infer it. |
| `frame` | `integer` | always | The frame the new sky is first drawn on. |
| `changed` | `string[]` | sometimes | What was actually changed, so a caller sees that a field it sent was a no-op. |

## Example

```sh
curl -X POST "http://127.0.0.1:7700/environment" --json @body.json
```

Start a server with `argus run --serve`; the port is `--port` (7700 by default). The request and response fields are in the query API guide.