## Shapes and paints

Shape layers (`ty:4`) hold their items in `shapes`. A group lists its paths, then the paints that draw them, then its transform. This group draws a rounded blue plate:

```json
{"ty":"gr","nm":"Plate","it":[
  {"ty":"rc","nm":"Plate path","d":1,"p":{"a":0,"k":[0,0]},"s":{"a":0,"k":[280,100]},"r":{"a":0,"k":16}},
  {"ty":"fl","nm":"Plate fill","c":{"a":0,"k":[0.1,0.3,0.8,1]},"o":{"a":0,"k":100},"r":1},
  {"ty":"tr","p":{"a":0,"k":[0,0]},"a":{"a":0,"k":[0,0]},"s":{"a":0,"k":[100,100]},"r":{"a":0,"k":0},"o":{"a":0,"k":100},"sk":{"a":0,"k":0},"sa":{"a":0,"k":0}}
]}
```

### Shape structure

- Supported items: `sh`, `rc`, `el`, `sr`, `fl`, `st`, `gf`, `gs`, `tm`, and top-level `gr` groups ending in a `tr` transform. Loose top-level items work too, and every top-level group renders.
- Every item, in `shapes` or a group's `it` list, is an object with a text `ty`. Every animatable value is a property object, such as `"c":{"a":0,"k":[1,0,0]}`.
- A fill or stroke paints the paths before it in its own group only. A paint before every path is ignored, and paths after every paint are dropped.
- A shape layer needs a path followed by a fill or stroke that draws, or the engine stops and the render fails (`problems`). A stroke the engine drops ([strokes](#strokes)) does not count.
- A group draws at most 10 paths and 8 paints. The rest are skipped, each in `warnings` with its layer and group. The limits apply to each sibling group, and to the loose items, separately: spread more filled shapes that share motion over sibling groups.
- Nested `gr` groups don't render: flatten them.
- Group transforms animate independently in one layer. Split shapes into layers only when masks, effects, matte roles, visibility or compositing need it.

### Paint order

- Top-level groups are stored front to back: an earlier `gr` paints over a later one, so put foreground details first.
- Loose top-level items form one more untransformed group in front of every `gr`, wherever they sit. Wrap them in a `gr` to place them in the stack.
- Each paint applies to all the paths before it in its group. Paints draw in reverse order, so an earlier fill can cover a later fill's details.
- Give independently colored elements their own sibling groups, each with geometry then paints, such as a colored symbol before its white panel. Share a group only to share paint on purpose.
- A fill (`fl` or `gf`) paints all the paths before it together, holes included. Keep a compound contour's winding and shared fill in one group: splitting the outer contour from its holes changes the result.

### Shape items

| Item | Property | Type | Default | Notes |
| --- | --- | --- | --- | --- |
| `rc` rectangle | `p`, `s` | property: `[x,y]` | Required | Center and `[width,height]`. Animatable. |
| | `r` | property: number | Required | Corner radius, which needs no rounded-corner modifier. Animatable. |
| | `d` | whole number | 1 | Direction ([codes](#plain-codes)) |
| `el` ellipse | `p`, `s` | property: `[x,y]` | Required | Center and size. Animatable. |
| | `d` | whole number | 1 | Direction, which sets the winding |
| `sr` star or polygon | `sy` | whole number | Polygon | Star or polygon ([codes](#plain-codes)) |
| | `pt` | property: whole number | Required | Point count, 3 to 300. Static. |
| | `p` | property: `[x,y]` | Required | Center. Animatable. |
| | `r` | property: number | 0 | Rotation in degrees. Animatable. |
| | `or`, `ir` | property: number | 0 | Outer and inner radius. A polygon ignores `ir`. Animatable. |
| `sh` path | `ks` | property: path `{c,i,o,v}` | Required | The vertices ([paths](#paths)). Animatable. |
| `fl` fill | `c` | property: RGB, 0–1 | White | A fourth component is ignored: use `o` for transparency. Animatable. |
| | `o` | property: number | 100 | Opacity, 0–100. Animatable. |
| | `r` | whole number | 1 | Fill rule |
| `st` stroke | `c`, `o` | as `fl` | White, 100 | Color and opacity. Animatable. |
| | `w` | property: number | Required | Width, never animated ([strokes](#strokes)) |
| | `lc`, `lj` | whole number | 1, 1 | Cap and join |
| | `ml` | number | 4 | Miter limit |
| `gf` gradient fill, `gs` gradient stroke | `t`, `s`, `e`, `o`, `g` | | | [Gradients](#gradients). `gf` also has a fill rule `r`, and `gs` the `w`, `lc`, `lj` and `ml` of `st`. |
| `tm` trim | `s`, `e`, `o` | property: number | Required | Start, end and offset ([trim paths](#trim-paths)). Animatable. |
| `tr` group transform | `p`, `a`, `s`, `r`, `o`, `sk`, `sa` | property | No transform | Position, anchor, scale, rotation, opacity, skew and skew axis. Animatable. Group opacity fades solid fills and strokes, not gradients. |

Stroke width, star point count and gradients are static: `a:1` does not make every property animatable. Star roundness `is` and `os` is ignored, so edges are straight.

#### Plain codes

Plain codes are whole numbers, not property objects:

| Code | Values | Default |
| --- | --- | --- |
| `d` direction | `1` normal; any other value reverses the path | Normal |
| `sy` star type | `1` star; any other value polygon | Polygon |
| `r` fill rule | `1` nonzero, `2` even-odd | Nonzero |
| `t` gradient type | `2` radial; any other value linear | Linear |
| `lc` cap | `1` butt, `2` round, `3` square | Butt |
| `lj` join | `1` miter, `2` round, `3` bevel | Miter |

### Strokes

Solid and gradient stroke widths are a fixed positive number with an explicit static marker `"a": 0` (or `false` or `null`), such as `"w":{"a":0,"k":5}`. A width of 0 or less draws nothing.

### Paths

Bezier paths live in the `sh` item's `ks.k`, never beside `ty`:

```json
{"ty":"sh","nm":"Triangle","ks":{"a":0,"k":{"c":true,"v":[[0,-50],[50,50],[-50,50]],"i":[[0,0],[0,0],[0,0]],"o":[[0,0],[0,0],[0,0]]}}}
```

- `v` holds local vertices. `i` and `o` are incoming and outgoing offsets relative to each vertex, not absolute control points. Supply lists of equal length. Zero offsets make straight segments.
- `c` closes the path when it is `true` or a nonzero whole number.
- For compound holes, keep the winding and fill rule across the paths that share a fill.

### Gradients

```json
{"ty":"gf","nm":"Blue gradient","t":1,"r":1,"s":{"a":0,"k":[-140,0]},"e":{"a":0,"k":[140,0]},"o":{"a":0,"k":100},"g":{"p":2,"k":{"a":0,"k":[0,0.1,0.3,0.8,1,0.5,0.8,1,0,1,1,1]}}}
```

| Property | Type | Default | Notes |
| --- | --- | --- | --- |
| `t` | whole number | Linear | `2` radial, any other value linear |
| `s`, `e` | property: `[x,y]` | Required | Start and end in local pixels: a fixed list of two numbers, or a first keyframe `s` holding one |
| `o` | property: number | 0, transparent (`warnings`) | Paint opacity, 0–100: a plain number such as `k:100`, or when animated a one-element first keyframe `s:[100]` |
| `g` | object | White (`warnings`) | `p` is the color stop count, at most 16. `k` is a property object holding four numbers per color stop, then at most 16 opacity stops of two. |
| `r` | whole number | Nonzero | `gf` only: the fill rule |

- `g.k` holds four numbers per color stop (position, R, G, B), then optional opacity stops as position/alpha pairs with their own positions. Keep `g.p` equal to the number of color stops.
- Keep stops ordered from 0 to 1. The engine holds the first stop's color before its position and the last one's after, and blends the first pair around each point.
- Geometry is in local pixels. Color, stop position and stop alpha are 0–1, and paint `o` is 0–100. To recolor, change only the RGB entries.
- Gradients are static: `s`, `e`, `o` and the stops are read once, for the whole render. They come from the first frame, or the first keyframe's `s` when `a` is 1. To change one over time, fade between two layers with different static gradients using layer opacity.
- Group opacity `o` does not fade gradients.
- Radial gradients are always centered: highlight length `h` and angle `a` are ignored.
- The `ADBE Ramp` effect is separate ([effects](#effects)).

### Trim paths

- `s` and `e` are 0–100 percent of the path's length, and `o` is an offset in degrees. All three can animate.
- A trim is skipped when more than one path (`sh`, `rc`, `el` or `sr`) is listed before it in its group (`warnings`). So `m` (trim multiple shapes) has no effect.
- Put the trim right after its single path in the same group. For several Trim Paths reveals, give each trimmed path its own sibling group, with its paint and `tm`. A single loose top-level path, paint and trim needs no group.
- A stroke trim draws the span from start to end. A fill trim rebuilds the contour.
- A fill trim on a rectangle with rounded corners fills the whole path and ignores the trim (`warnings`). The engine cannot measure any roundness `r` other than a static 0. Set `r` to `{"a":0,"k":0}`, or draw it as a path `sh`.

### Shape features that do not render

| Feature | What the engine does |
| --- | --- |
| Repeater `rp`, merge paths `mm`, rounded corners `rd`, offset paths `op`, pucker and bloat `pb`, zig zag `zz`, twist `tw`, any other unsupported item | Draws the shape as if it were not there |
| Stroke dashes (`d` on `st` or `gs`) | Draws a solid line |
| A fill's or stroke's blend mode `bm` | Paints it normally |
| `hd` on a shape item | Ignores it: a hidden item still draws, and a hidden trim still trims |

Each is listed in `warnings`. Express the required geometry as supported paths, using sibling groups where transforms or paints differ. Preserve unsupported source data during unrelated edits, rather than silently deleting it.

### Edge cases

| Written as | Result |
| --- | --- |
| An item `5` or without `ty`; `"it":5`; `"c":5`; `"w":4`; a rectangle without `s` | Unreadable, and the render fails (`problems`) |
| A marker that does not match the value ([static values and keyframes](#static-values-and-keyframes)) | The render fails (`problems`) |
| No `a`, with a `k` that is neither the value nor keyframes, such as `"c":{"k":"#ff0000"}` or `"c":{"k":[1]}` | The render fails (`problems`) |
| An `it` of `{}`, `0`, `false` or `""` | An empty group (`warnings`) |
| An animatable value written `0`, `true`, `false`, or a number such as `4.0` | Missing: the default is used, and named in `warnings` |
| A nested `gr` | Skipped with everything in it (`warnings`) |
| A plain code with a decimal point or exponent, such as `2.0` | Reads as 0 (`warnings`): a reversed path, a polygon, nonzero winding or a linear gradient. A join reads as no corner joins. A cap reads as the cap of another stroke on the same paths, or butt when there is none. |
| A cap or join above 255 | The engine reads its lowest 8 bits, so 257 is 1. A cap or join it does not read as 1, 2 or 3 is in `warnings`. |
| A miter limit `ml` that is not a number | An unpredictable limit (`warnings`) |
| A star point count with a fraction, such as `5.7` | The fraction is dropped: 5 points |
| A star point count that is animated or outside 3 to 300 | The star or polygon is skipped (`warnings`) |
| Nonzero star roundness `is` or `os` | Straight edges (`warnings`) |
| A path `c` of `1.0` or a text | Reads as false: the path draws open (`warnings`) |
| A group whose paths all reach past 1,000,000 units in its own coordinates, before its transform, where misread geometry usually lands | Not drawn. On a layer with effects or layer styles, it still draws. |
| A fill trim whose span reaches past three lengths of its path (`s` and `e` far outside 0–100) | Fills the whole path and ignores the trim. Keep `s` and `e` within 0–100. |

A stroke width `w`:

| `w` written as | Result |
| --- | --- |
| `{"a":0,"k":5}` | Draws at that width |
| Animated, or without `a` | Draws at no width (`warnings`) |
| Missing, or a static `w` that is not a single number | The stroke is dropped (`warnings`) |
| A value that reads as empty, such as `0`, `4.0`, `true` or `false` | Draws at no width (`warnings`) |
| A bare number, such as `"w": 4` | The render fails: `problems` |

A gradient:

| Written as | Result |
| --- | --- |
| `s` or `e` missing | The render fails (`problems`) |
| `o` as a list, such as `k:[100]` | Misread |
| `g.p` as `2.0` | 0 color stops, so white (`warnings`) |
| Non-numeric stops | Unpredictable colors or positions (`warnings`) |
| Over 16 color or opacity stops, or fewer than four numbers per color stop in `g.k` (`"p":2` with 7 numbers, or a negative `p`) | The render fails (`problems`) |
| Stops out of order | A different ramp (`warnings`) |
| Animated | The first frame's values for the whole render (`warnings`) |
| A group opacity `o` that would fade it | The gradient does not fade (`warnings`) |
| A nonzero radial highlight | Ignored (`warnings`) |
