## Layers, ordering, and relationships

Each entry of `layers` is one layer object. This solid fills a 640 × 360 canvas, behind every layer with a smaller `ind`:

```json
{"ty":1,"ind":4,"nm":"Background","ip":0,"op":90,"st":0,"sr":1,"bm":0,"ks":{"a":{"a":0,"k":[0,0,0]},"p":{"a":0,"k":[0,0,0]},"s":{"a":0,"k":[100,100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100}},"sw":640,"sh":360,"sc":"#101725"}
```

`ty` sets the kind of layer, and what else it needs:

| `ty` | Kind | Needs |
| --- | --- | --- |
| `0` | Precomposition | `refId` naming a precomposition asset, and positive whole-number `w` and `h`. `st`, `sr` and `tm` are optional ([precompositions](#precompositions)). |
| `1` | Solid | Positive whole-number `sw` and `sh`, and a text `sc` written `"#rrggbb"`, such as `"#17324d"`. Use `ks.s` for fractional displayed sizes. |
| `2` | Image | `refId` to an image asset the engine loads ([media](#media-and-precompositions)) |
| `3` | Null or adjustment layer | A plain null is an invisible parent. With `ef` and positive whole-number `sw` and `sh`, it is an [adjustment layer](#adjustment-layers-and-cameras). |
| `4` | Shape | `shapes`, with geometry and paint ([shapes](#shapes-and-paints)) |
| `5` | Text | A text document with copy and a declared font ([text](#text-and-fonts)) |
| `6` | Audio | Nothing: it is ignored ([audio layers](#audio-layers)) |
| `9` | Video | `refId` to a video, GIF or WebP the engine loads. A one-frame GIF or WebP shows as a still image. `st` is optional. |
| `13` | Camera | A static nonzero zoom `pe` ([cameras](#adjustment-layers-and-cameras)) |
| `16` | Native model | `refId` to a GLB asset ([native models](#native-models)) |

A layer of any other type is skipped. Layers parented to it are placed as if their parent had no transform.

### Fields every layer has

| Property | Type | Default | Notes |
| --- | --- | --- | --- |
| `ty` | whole number | Required | The layer type |
| `ind` | whole number | 0 | Unique and positive within its composition. It sets [stacking](#stacking-and-references). |
| `nm` | text | Required | A stable, non-empty name. An audio layer needs none. |
| `ks` | object | Required | The [transform](#transforms-and-coordinates) |
| `ip`, `op` | number | 0 | Visibility in frames, from `ip` up to but not including `op` ([time](#time)) |
| `parent` | whole number | None | The `ind` of a layer in the same composition. `0` means no parent. |
| `hd` | boolean | `false` | `true` hides the layer |
| `st` | number | 0 | Read only on precomposition and video layers ([time](#time)) |
| `sr` | number | 1 | Read only on precomposition layers without `tm` ([time](#time)) |
| `ao` | whole number | 0 | Auto-orient ([transforms](#transforms-and-coordinates)) |
| `bm` | whole number | 0, normal | [Blend mode](#blend-modes-and-effects) |
| `ddd` | whole number | 0 | Not read. Preserve it when present. |

### Stacking and references

- Smaller `ind` values paint in front. Array order is not paint order: moving an entry changes its pointer, not its pixels. To restack, change the `ind` values and remap the `parent` and `tp` references that depend on them.
- Each nested composition has its own index space.
- `refId` names an asset `id`, not a layer name.
- Several precomposition layers can share one asset, and editing `/assets/{index}/layers/...` changes them all. To change one instance, duplicate the asset with a new unique `id`, point only that layer's `refId` at it, then edit the duplicate.
- Keep a precomposition layer's `w` and `h` coherent with its children's local coordinates. Changing only the outer canvas does not resize the content.

### Audio layers

Audio layers (`ty:6`) are ignored and give no output audio. A render plays the version's soundtrack, which an edit sets with its `soundtrack` field ([Projects](/docs/blitframe/projects#soundtrack)). A render request can name another file in `audio`, which overrides it ([Renders](/docs/blitframe/renders)).

- Audio asset declarations use a supported audio file path and need no `w` or `h`. They cannot serve as image or video layer assets.
- The engine never opens an audio file, or any asset that is not an image, video or model. Such a file may be left out of the version (`warnings`).
- An audio layer cannot be another layer's `parent` or matte `tp`.

### Adjustment layers and cameras

An adjustment layer is `ty:3` with positive `sw` and `sh`, transforms, timing, and a non-empty `ef` list of [supported effects](#effects). It applies them to what is painted behind its rectangle, and only inside it.

- Its effects run on the rectangle's bounding box on screen, clipped to the composition. A rotation changes only what the rectangle covers: the effects stay aligned to the screen.
- Effects that spread, such as a blur, glow or shadow, get no extra room and stop at the rectangle's edges.
- It reads only the layers behind it in its own composition.
- Place it in front of the layers it affects, using `ind`, and size and place the rectangle deliberately.

A plain null has no paint and only groups transforms: leave out `ef`, `sw` and `sh`, and never add an empty `ef`. Parenting gives no group masking, clipping or composited effects.

A camera is `ty:13` with a zoom `pe`, timing and camera transforms.

- `pe:{"a":0,"k":zoom}` is a static nonzero zoom: one number, never animated, sign ignored.
- A one-node camera has no `ks.a`. On a two-node camera, `ks.a` is the point of interest, not a geometry anchor.
- An authored 3D rig uses three-component position and scale, and `rx`, `ry`, `rz` with `or`.
- The last camera layer in `layers` is used for the whole render, hidden or not, whatever its `ip` and `op`. Keep one intended camera per composition: visibility cannot cut between cameras.
- A camera moves every layer in its composition, 2D layers too, since `ddd` is not read. To keep a background or title fixed, put the camera and the layers it moves in a precomposition that does not collapse transformations. Keep the fixed layers outside it.
- Camera support does not imply lights, material shading, depth of field, motion blur or continuous rasterization.

### Edge cases

- A `ty` written other than as an unsigned whole number, such as `3.0` or `3e0`, reads as the number its low 32 bits hold (`warnings`). That is usually `0`, a precomposition, and one without a text `refId` is in `problems`.
- A missing or repeated `ind` is in `warnings`. A missing `ind` reads as 0, which no layer can name as `parent` or `tp`.
- Of layers sharing an `ind`, the engine keeps only the last in its layer tree. The others are not placed by their transforms, and children of that `ind` attach to the last. Their stacking is undefined, and a matte `tp` uses whichever draws first.
- A layer without a text `nm`, other than an audio layer: `problems`.
- A `ks`, or a value in it, that is not an object: `problems`.
- A layer whose `op` is at or before its `ip` is accepted but never appears.
- A nonzero `parent` naming no layer in the composition, or naming an audio layer: `problems`.
- Only the boolean `true` hides a layer: `hd: 1` reads as `false`.
- An entry of `layers` that is not an object: `problems`.
- The engine skips the first character of a solid's `sc` and reads the next six as hex. So `"17324d"` without `#`, or a short `"#fff"`, gives another color. Characters after the six digits, such as alpha, are ignored. A missing or non-text `sc`: `problems`.
- An image, video or 3D model layer whose `refId` names no asset of its kind that the engine loads: `problems`. So is a precomposition layer whose `refId` is not text or names no asset.
- A camera without `pe` has a zoom of 0 (`warnings`). A `pe` the engine cannot read, such as a bare whole number: `problems`.
- Effects on a `ty:3` without `sw` don't render, and the layer is a plain null (`warnings`).
- An adjustment layer whose `ef` holds no supported effect, or is empty, draws as an opaque white rectangle (`warnings`).
