# Writing a character

> A character is JSON: materials, parts made of shapes, and animations. The engine shades it like a pixel artist would at every size. The playgrounds below run the real engine in your browser: edit the spec and watch.

import SpecPlayground from '../../../../components/SpecPlayground.astro';

## Parts and shapes

Coordinates are units on a 100 × 100 canvas, y down. Parts hold shapes (`circle`, `ellipse`, `rect`, `capsule`, `polygon`) and rotate around their `pivot`; a part with a `parent` moves with it.

<SpecPlayground
  title="A blob with a face"
  res={32}
  spec={`{
  "name": "Mochi",
  "materials": {
    "body": {"color": "#7fd18b"},
    "eye": {"color": "#23212c", "flat": true, "outline": false}
  },
  "parts": [
    {"id": "body", "pivot": [50, 90], "shapes": [
      {"type": "ellipse", "cx": 50, "cy": 66, "rx": 30, "ry": 24, "material": "body"}
    ]},
    {"id": "face", "parent": "body", "pivot": [50, 62], "z": 2, "shapes": [
      {"type": "circle", "cx": 40, "cy": 60, "r": 3.2, "material": "eye"},
      {"type": "circle", "cx": 60, "cy": 60, "r": 3.2, "material": "eye"}
    ]}
  ],
  "animations": {
    "idle": {"frames": 8, "fps": 8, "tracks": {
      "body": {"sy": {"wave": 0.06}, "sx": {"wave": -0.04}},
      "face": {"show": [1, 1, 1, 1, 1, 1, 0, 1]}
    }}
  }
}`}
/>

Try: change the body colour, make the ellipse wider, or set the size to 16 px to see the icon render.

## Materials and textures

Materials give colour, texture (`noise fur scales stripes checker cloth bricks spots metal`), shine, and whether a shape is outlined. Textures stick to moving parts; small sizes simplify them automatically.

<SpecPlayground
  title="Textures"
  res={48}
  spec={`{
  "name": "swatches",
  "materials": {
    "fur": {"color": "#c9773a", "texture": "fur"},
    "scales": {"color": "#4f9a6a", "texture": "scales"},
    "metal": {"color": "#9aa0ad", "texture": "metal", "shine": 0.6},
    "cloth": {"color": "#5a63a8", "texture": "cloth", "textureStrength": 0.5}
  },
  "parts": [
    {"id": "a", "shapes": [{"type": "rect", "x": 8, "y": 10, "w": 38, "h": 38, "r": 6, "material": "fur"}]},
    {"id": "b", "shapes": [{"type": "rect", "x": 54, "y": 10, "w": 38, "h": 38, "r": 6, "material": "scales"}]},
    {"id": "c", "shapes": [{"type": "circle", "cx": 27, "cy": 72, "r": 19, "material": "metal"}]},
    {"id": "d", "shapes": [{"type": "rect", "x": 54, "y": 54, "w": 38, "h": 38, "r": 6, "material": "cloth"}]}
  ]
}`}
/>

## Animating parts

Tracks animate `x`, `y`, `rot`, `sx`, `sy` and `show` per part, as keyframes, eased keys, or waves (`sin tri square bounce`).

<SpecPlayground
  title="A waving flag"
  res={48}
  spec={`{
  "name": "flag",
  "materials": {"pole": "#6b4a2f", "cloth": {"color": "#e8743b", "texture": "cloth"}},
  "parts": [
    {"id": "pole", "shapes": [{"type": "capsule", "x1": 24, "y1": 12, "x2": 24, "y2": 94, "r": 2.2, "material": "pole"}]},
    {"id": "flag1", "pivot": [25, 20], "shapes": [{"type": "rect", "x": 25, "y": 14, "w": 22, "h": 26, "material": "cloth"}]},
    {"id": "flag2", "parent": "flag1", "pivot": [47, 20], "shapes": [{"type": "rect", "x": 46, "y": 15, "w": 22, "h": 24, "material": "cloth"}]},
    {"id": "flag3", "parent": "flag2", "pivot": [68, 20], "shapes": [{"type": "polygon", "points": [[67, 16], [86, 22], [67, 38]], "material": "cloth"}]}
  ],
  "animations": {
    "wave": {"frames": 8, "fps": 10, "tracks": {
      "flag1": {"rot": {"wave": 6}},
      "flag2": {"rot": {"wave": 10, "phase": 0.2}},
      "flag3": {"rot": {"wave": 14, "phase": 0.4}}
    }}
  }
}`}
/>

## Start from a figure

For animals and people, start from a figure: a skeleton with realistic motion models. Dress its bones by id with shapes; the motions come for free. Here is a goose with a few shapes and three motions; add `"jump"`, `"climb"` or `"sit"` to the animations.

<SpecPlayground
  title="Dressing the goose figure"
  anim="walk"
  res={48}
  spec={`{
  "name": "plain goose",
  "figure": "goose",
  "materials": {
    "feather": {"color": "#ece6da", "texture": "noise", "textureStrength": 0.2},
    "beak": "#f0862a",
    "leg": "#f0862a",
    "eye": {"color": "#1d1b24", "flat": true, "outline": false}
  },
  "parts": [
    {"id": "body", "shapes": [{"type": "ellipse", "cx": 45, "cy": 66, "rx": 19, "ry": 11, "rot": -12, "material": "feather"}]},
    {"id": "tail", "shapes": [{"type": "polygon", "points": [[28, 60], [15, 56], [27, 68]], "material": "feather"}]},
    {"id": "neck", "shapes": [{"type": "capsule", "x1": 58, "y1": 58, "x2": 60, "y2": 44, "r": 4.5, "material": "feather"}]},
    {"id": "neckUp", "shapes": [{"type": "capsule", "x1": 60, "y1": 44, "x2": 62, "y2": 30, "r": 4, "material": "feather"}]},
    {"id": "head", "shapes": [
      {"type": "circle", "cx": 64, "cy": 26, "r": 6.5, "material": "feather"},
      {"type": "polygon", "points": [[69, 23], [84, 26], [69, 29]], "material": "beak"}
    ]},
    {"id": "eye", "bone": "head", "pivot": [66, 24], "z": 7, "shapes": [{"type": "circle", "cx": 66, "cy": 24, "r": 1.4, "material": "eye"}]},
    {"id": "legNear", "shapes": [{"type": "capsule", "x1": 38, "y1": 72, "x2": 36, "y2": 81, "r": 1.4, "material": "leg"}]},
    {"id": "shinNear", "shapes": [{"type": "capsule", "x1": 36, "y1": 81, "x2": 39, "y2": 89, "r": 1.3, "material": "leg"}]},
    {"id": "footNear", "shapes": [{"type": "capsule", "x1": 39, "y1": 89.5, "x2": 47, "y2": 90.5, "r": 1.3, "material": "leg"}]},
    {"id": "legFar", "shapes": [{"type": "capsule", "x1": 46, "y1": 72, "x2": 44, "y2": 81, "r": 1.4, "material": "leg"}]},
    {"id": "shinFar", "shapes": [{"type": "capsule", "x1": 44, "y1": 81, "x2": 47, "y2": 89, "r": 1.3, "material": "leg"}]},
    {"id": "footFar", "shapes": [{"type": "capsule", "x1": 47, "y1": 89.5, "x2": 55, "y2": 90.5, "r": 1.3, "material": "leg"}]}
  ],
  "animations": {
    "idle": {"motion": "idle", "tracks": {"eye": {"show": [1, 1, 1, 1, 1, 1, 0, 1]}}},
    "walk": {"motion": "walk"},
    "run": {"motion": "run"}
  }
}`}
/>

## Plug-ins: new shapes, textures and motions

A plug-in registers new building blocks; specs then use them like built-ins, with the same validation. This playground loads `examples/plugins/extras.mjs`, which adds a `star` shape, a `feathers` texture and a `float` motion.

```js
export default function setup({ registerShape, registerTexture, registerMotion }) {
  registerShape('star', { required: ['cx', 'cy', 'r'], keys: ['r2', 'tips', 'round', 'rot'], compile: (s) => ({ sdf, R, bbox }) });
  registerTexture('feathers', (x, y, scale) => brightness);
  registerMotion('float', { generate: ({ rig, params, samples }) => ({ tracks: { [rig.root]: { y: [...], rot: [...] } } }) });
}
// CLI: npx pixel preview starfish.json --plugin extras.mjs
```

<SpecPlayground
  title="A starfish made of plug-ins"
  res={48}
  plugin="/apps/packages/pixel-studio/examples/plugins/extras.mjs"
  spec={`{
  "name": "Twinkle the starfish",
  "figure": {"use": "blob"},
  "materials": {
    "star": {"color": "#ff9a5c", "texture": "spots", "textureStrength": 0.4},
    "frill": {"color": "#f4d35e", "texture": "feathers", "textureStrength": 0.6},
    "eye": {"color": "#2a1f2d", "flat": true, "outline": false}
  },
  "parts": [
    {"id": "body", "shapes": [{"type": "star", "cx": 50, "cy": 58, "r": 30, "r2": 15, "round": 2.5, "material": "star"}]},
    {"id": "top", "shapes": [{"type": "ellipse", "cx": 50, "cy": 40, "rx": 9, "ry": 6, "material": "frill"}]},
    {"id": "eyes", "bone": "body", "pivot": [50, 56], "z": 5, "shapes": [
      {"type": "circle", "cx": 44, "cy": 56, "r": 2.2, "material": "eye"},
      {"type": "circle", "cx": 56, "cy": 56, "r": 2.2, "material": "eye"}
    ]}
  ],
  "animations": {
    "float": {"motion": "float", "frames": 12, "fps": 8, "height": 5, "tilt": 8}
  }
}`}
/>

## Points, events, skins, state machines

Specs can also name attachment points, add events, define skins and carry a state machine. See [Events, points and the foot line](/docs/guide/events/) and [State machines and skins](/docs/guide/states/), and the full format in [docs/SPEC.md](/docs/reference/spec/) (which doubles as the brief for AI agents writing characters).
