# Sandy avatar editor and runtime (sandy-avatar.html)

One self-contained HTML file. Open it in a browser and it is a wardrobe for Sandy: hair,
skin, nails, face, build, base clothes, outfit pieces with a tint each, flip-flops or
boots, and a weapon. The same file carries the runtime (`window.SandyKit`) that builds a
dressed Sandy from a small JSON config, so other projects can use her as the player or
as any number of NPCs. Nothing is loaded from the network.

## Where things are in this file

Search for these markers. Everything between them is plain text you can copy out. This read-me quotes the markers as well, so take the last match of each runtime marker.

| Marker | What it is |
| --- | --- |
| `<textarea id="sandy-readme"` | This read-me (Markdown) |
| `SANDY RUNTIME: BEGIN` / `SANDY RUNTIME: END` | Everything a project needs: three.js r149, GLTFLoader, the body model, hair, outfits, weapons, the rig (`makeN3`) and `SandyKit` |
| `<script id="sandy-kit">` | The `SandyKit` API itself (the last script inside the runtime) |
| `SANDY EDITOR: BEGIN` / `SANDY EDITOR: END` | The wardrobe page, in two parts: its styles and markup (before the runtime) and its script (after it). Drop both when you only need the runtime |

To split the runtime into its own file (for example from a shell, or from a Claude session):

```python
s = open('sandy-avatar.html', encoding='utf-8').read()
a = s.rindex('<!-- ===== SANDY RUNTIME: BEGIN ===== -->')   # rindex: this read-me quotes the markers too
b = s.rindex('<!-- ===== SANDY RUNTIME: END ===== -->') + len('<!-- ===== SANDY RUNTIME: END ===== -->')
open('sandy-runtime.html', 'w', encoding='utf-8').write(s[a:b])   # paste these script tags into your page
readme = s[s.index('<textarea id="sandy-readme" hidden readonly'):]
readme = readme[readme.index('>') + 1:readme.index('</' + 'textarea>')]
```

## Three ways to use her in a project

### 1. As an iframe (any page, any framework, nothing to merge)

Put the file next to your page and embed it in viewer mode (no wardrobe, just her):

```html
<iframe id="npc1" src="sandy-avatar.html?mode=viewer&bg=transparent&seed=guard-1"
        width="320" height="480" style="border:0" title="Sandy"></iframe>
```

URL options:

- `mode=viewer`: hide the wardrobe. Leave it out to show the full editor.
- `bg=transparent`: no backdrop (viewer mode only).
- `config=<code>`: a look, from the editor's "Copy link" / "Copy embed code" or `SandyKit.encode(config)`.
- `seed=<any text>`: a random look that is the same every time for the same seed (good for NPC crowds).
- `view=body|face|feet`, `spin=1`: camera framing and a slow turntable.

Talk to it with `postMessage`. Every reply echoes the `id` you sent.

```js
const f = document.getElementById('npc1').contentWindow;
f.postMessage({ sandy: 'apply', config: { skin: '#8a5a3c', top: { part: 'Female_Ranger_Body', colour: '#3fc1ff' } }, id: 1 }, '*');
f.postMessage({ sandy: 'apply', config: fullConfig, replace: true }, '*'); // replace the whole look
f.postMessage({ sandy: 'get', id: 2 }, '*');          // -> { sandy: 'config', config, id: 2 }
f.postMessage({ sandy: 'random', seed: 'bob' }, '*'); // a random look
f.postMessage({ sandy: 'snapshot', id: 3 }, '*');     // -> { sandy: 'png', dataURL, id: 3 }
f.postMessage({ sandy: 'view', view: 'face', spin: true }, '*');
f.postMessage({ sandy: 'catalog', id: 4 }, '*');      // -> everything a config can name
addEventListener('message', e => { if (e.data && e.data.sandy === 'change') save(e.data.config); });
// the frame also sends { sandy: 'ready', config } once she has loaded
```

A game can open the full editor in an iframe (no `mode=viewer`) as its character
creator, listen for `change`, and store the config.

### 2. Inside a three.js scene (the player or NPCs in your own 3D world)

Copy the runtime block (see above) into your page before your own code. It defines
`window.THREE` (r149) and `THREE.GLTFLoader`; build your scene with that same `THREE`.

```js
const sandy = await SandyKit.create({ hair: { style: 5, colour: '#d6ae58' }, feet: { type: 'flipflops', sole: '#ffffff', strap: '#ff5c8a' } });
scene.add(sandy.object3d);             // a THREE.Group: stands on y = 0, faces +z, units are centimetres (about 205 to the top of her hair)
sandy.object3d.position.set(0, 0, 0);
sandy.object3d.scale.setScalar(0.01);  // if your world is in metres
// every frame:
sandy.update(dt);                      // dt in seconds (or leave it out and she times herself)
// later:
sandy.apply({ expression: 'surprised' });
sandy.lookAt(camera.position);         // head and eyes follow a world point; lookAt(null) to stop
const cfg = sandy.getConfig();         // save it, send it, put it in a level file
sandy.dispose();
```

NPC crowds: `SandyKit.create(SandyKit.randomConfig('npc-' + i))` for each one. Each
Sandy takes a moment to build (she is a full skinned model), so create them during a
loading screen or one per frame.

Lighting: she uses `MeshStandardMaterial`, so give your scene a light or two
(a `HemisphereLight` plus a `DirectionalLight` with shadows looks right). Set
`renderer.outputEncoding = THREE.sRGBEncoding`.

If your project already uses a different three.js version, either load this r149 copy
in its own page and use the iframe route, or keep the runtime's copy as the only
`THREE` on the page. The rig and loader are written for r149.

### 3. As the whole page

Open `sandy-avatar.html` and use it as is: dress her, then "Save" gives you the JSON,
a link that reopens this exact look, an embed code and a PNG picture.

## The config

Every field is optional; anything left out comes from `SandyKit.DEFAULT`.
`apply()` takes a partial config and changes only what you pass.

```json
{
  "hair": { "style": 12, "colour": "#2a1a12" },
  "skin": "#d9a67e",
  "nails": "#d9a67e",
  "expression": "smug",
  "outfit": { "shirt": "#2b3350", "shorts": "#2a2a2a", "belt": "#141414" },
  "top":       { "part": "mh_toigo_keyhole_tank_top", "texture": "mh_toigo_keyhole_tank_top", "colour": "#ffffff" },
  "legs":      { "part": "Female_Peasant_Legs", "texture": "peasant2", "colour": "#ffffff" },
  "shoulderL": null,
  "shoulderR": null,
  "feet": { "type": "flipflops", "sole": "#f2efe6", "strap": "#e3101c" },
  "weapon": { "name": "Sword", "variant": "Iron", "colour": "#ffffff" },
  "build": { "height": 1, "footLength": 1, "toeLength": 1, "upperTorso": 1, "lowerTorso": 1, "neck": 1,
             "shoulders": 1, "hips": 1, "upperArm": 1, "forearm": 1, "thigh": 1, "shin": 1 }
}
```

- `body`: `"female"` or `"male"` (`SandyKit.CATALOG.bodies`). Both bodies are Quaternius Universal Base Characters
  (Superhero, CC0) wearing her own head, sphere hands and feet; every outfit piece fits both. Changing `body` rebuilds
  her rig in place; `await sandy.ready` if you need to know when it's done.
- `decal`: a chest print on her top: `image` (`"star"`, `"heart"`, `"bolt"`, `"smile"`, `"peace"`, `"print:<name>"` for a ready-made print in assets/prints/ (fire, crown, rocket, gamepad, pearl, gem, rainbow, flower, paw, duck), `"pack:<id>"` for any of the 1,176 icon-pack prints in assets/prints/pack/ (ids in its index.json), an image data URL, or null), `size`, `up` and `side` (cm).
- `hat`: `type` (`"none"` or one of `SandyKit.CATALOG.hats`: beanie, beret, bucketHat, cap, cowboyHat, sunHat, topHat, witchHat),
  `colour`, `size`, `up` and `forward` (cm), `tilt` (radians). Her hair is never changed by a hat. Hats: Chibi Hats by PaperPluto
  (itch.io; free for commercial use, not to be redistributed on their own).
- `earrings`: `type` `"none"`, `"pearls"` or `"hoops"`; `size`, `colour` (null = pearl white / gold), `drop` and `forward` (cm), `angle` (radians, hoops).
- `ears`: `size` (0 hides them), `thickness`, `up`, `forward`, `out` (cm), `twist` and `flare` (radians); all 0 / 1 by default.
- `faceShape`: `jaw` and `cheeks` (widths), `chin` (length below the mouth) and `depth` (how far the lower face comes forward), multipliers around 1.
- `faceScale`: the size of the face drawing (eyes, brows, mouth), 0.7 by default (0.3 to 1 in the editor); `faceY` moves it up or down.
- `build.headSize`, `build.headWidth`, `build.handSize` (the hand balls) and `hair.size`: multipliers around 1; `hair.up` and `hair.forward` nudge the hair (cm).
- `build.cranium`: the size of her cranium above the brow (her hair grows with it), 1 by default; for cartoonish big-brained looks.
- `build`: `height`, `footLength`, `toeLength`, and the proportions `upperTorso`, `lowerTorso`, `neck`, `shoulders`
  (width), `hips` (width), `upperArm`, `forearm`, `thigh`, `shin`: each a length multiplier, 1 = as modelled.
- `hair.style`: 0 to `SandyKit.CATALOG.hairStyles.length - 1` (5 styles from the Universal Base Characters pack:
  long, buns, pixie, parted, buzzed; `hair.colour` tints any of them).
- `skin`, `nails`, `hair.colour`, the `outfit` colours and every `colour`: any `#rrggbb`.
  Skin is a tint over her painted skin (`#ffffff` = as painted).
- `outfit`: her shirt, shorts and belt, shown where no `top` / `legs` piece is worn.
- `top`, `legs`, `shoulderL`, `shoulderR`: `null` for nothing, or a `part` from
  `SandyKit.CATALOG.parts[slot]`, a `texture` from `SandyKit.CATALOG.textures`
  (`ranger`, `ranger3`, `peasant`, `peasant2`) and a `colour` tint (`#ffffff` keeps the
  original colours).
- Checked clothing only: every part in `SandyKit.CATALOG.parts` passed an automated check on both bodies. Each part is worn
  alone and rendered from 20 angles in 5 poses (idle, two walk frames, wave, jump), counting two things: skin that was hidden
  but can be seen (a see-through hole, such as a missing neck), and skin poking out through cloth. Parts over the limits
  (idle ≤ 90 px, walk ≤ 120, wave / jump ≤ 400, no single view over 120, at 400×600) were left out, plus two shoes that
  passed but looked wrong close up. The kit pieces left out are still in the data, so old configs naming them still load.
- Clothes: the parts whose id starts with `mh_` are MakeHuman community garments (dresses, suits, tops, trousers,
  skirts, shoes, boots and socks) fitted to both bodies, in plain colours (no textures; `#ffffff` keeps the garment's
  own colour, any other `colour` replaces it). Each has one "texture" entry, its own id
  (`SandyKit.texturesFor(p.set)` lists the textures a catalogue part `p` can take), and `colour` tints it. In the catalogue
  they carry `clothes: true`, `licence` (`CC0`, or `check`: read that asset's MakeHuman page before you ship it)
  and `full: true` for a dress, suit or robe: those go in `top` and cover her legs too, so wearing one clears
  `legs` and picking a `legs` piece takes it off. Skin a garment covers is hidden rather than pushed out.
- Boots take `height` (0 = cut just above the ankle, like a shoe; 1 = as made) and `auto` (default true: at ankle height whenever
  trousers, a long skirt or a long dress reach below the knee).
- T-shirt and Long-sleeve tee (`gen_tshirt`, `gen_longsleeve`) are grown from the body itself, so they fit both bodies exactly.
- Every garment starts white (textured kit pieces in greyscale), so `colour` sets its colour directly.
- `SandyKit.randomConfig(seed, {body})` keeps that body and only picks what that body wears (each catalogue part has
  `wearer`: `"f"`, `"m"` or `"u"` for both). The editor's Randomize keeps the body you have selected.
- `feet.type`: `"barefoot"`, `"flipflops"` (with `sole` and `strap` colours) or
  `"boots"` (with `part`, `texture` and `colour`, like the other pieces).
- `weapon`: always `null` (weapons were removed; her hands stay empty).
- `build`: multipliers around 1 (height 0.85 to 1.15, foot length 0.8 to 1.25, toe
  length 0.8 to 1.3).
- The male body has his own face drawing, shown whatever `expression` says (the expressions are drawn for her face).
- `expression`: one of `SandyKit.CATALOG.expressions` (neutral, smug, happy, laugh,
  surprised, scared, annoyed, pout, curious, blush, relaxed, sleepy, wince, dizzy, dead,
  pleading, gasp).

Animations: `sandy.play(name)` with a name from `SandyKit.CATALOG.animations` (`idle`, `walk`, `wave`, `jump`,
`dance`) loops it on top of her idle pose; `sandy.animation` says which is playing. Call `sandy.update(dt)` every frame.

In the editor's stage: drag to turn her, right-drag or Shift-drag to pan, scroll to zoom; **Free cam** flies the camera
with W A S D (Q / E down and up, Shift for speed) while dragging looks around. The buttons at the bottom left preview the
animations.

### Character files

The Save tab's **Save character (.json)** writes the whole character (with its name) to one small file; **Open character…**,
or dropping a .json on the page, loads one back. The file is a config plus `"name"` (and a `"sandyCharacter": 1` marker),
so it also works anywhere a config does. In a game:

```js
const rosa = await SandyKit.loadCharacter('characters/rosa.json');   // or a parsed object
scene.add(rosa.object3d);  // rosa.name === 'Shopkeeper Rosa'
```

Served over http, `sandy-avatar.html?character=characters/rosa.json` opens the editor on that file.

Configs are small, so they fit in save files, URLs and level data.
`SandyKit.encode(config)` turns one into a URL-safe string and `SandyKit.decode(text)`
turns it back.

## SandyKit API

- `SandyKit.create(config) -> Promise<Sandy>`: build a new Sandy.
- `SandyKit.randomConfig(seed?)`: a random look; the same seed always gives the same look.
- `SandyKit.DEFAULT`: the look used for anything a config leaves out.
- `SandyKit.CATALOG`: `hairStyles`, `skinTones`, `nailColours`, `expressions`,
  `textures`, `parts` (by slot), `weapons`, `slots` (slot labels).
- `SandyKit.merge(a, b)`, `SandyKit.encode(config)`, `SandyKit.decode(text)`.
- `SandyKit.readme()`: this text.
- A `Sandy` has `object3d` (add it to your scene), `apply(patch)`, `getConfig()`,
  `setExpression(name)`, `lookAt(vector3 | null)`, `update(dt)` and `dispose()`.
  `sandy.n3` is the underlying rig (`n3.bones` by name, `n3.pose` for the idle pose)
  for anyone who wants to animate her further.

## What is not included

This is her look and an idle stance. Walking, fighting, ragdolls, voices and the
dungeon live in Splash Dungeon and are not part of this file.

## Credits and licences

- Body rig: "Natalie" by Andrew Silke (create3dcharacters.com), licensed for
  non-commercial, educational use only. Check that licence before shipping anything
  commercial with her.
- Outfits: Quaternius "Modular Character Outfits - Fantasy" (CC0), refitted to her rig.
- Weapons: FantasyWeaponsPack models.
- three.js r149 (MIT).

Your avatar

Drag to turn her, right-drag or Shift-drag to pan, scroll to zoom, double-click to reset. Free cam: WASD, Q/E, drag to look.Drag to turn her, two fingers to pan and zoom.

Getting dressed…

Wardrobe

Body

Face

Face size

Jaw width

Cheek width

Chin length

Face depth

Face height

Ears

Size

Thickness

Up / down

Forward / back

Out / in

Twist

Flare

Hat

Size

Up / down

Forward / back

Tilt

Earrings

Size

Drop

Forward

Hoop angle

Skin

Hair

Hair size

Hair up / down

Hair forward / back

Nails

Painted on her toes too.

Build

Height

Foot length

Toe length

Head size

Head width

Hand size

Cranium

Proportions

Upper torso

Lower torso

Neck

Shoulder width

Hip width

Upper arm

Forearm

Thigh

Shin

Character file

Name

Saves everything about this character in one small file. Open one here (or drop it on the page) to keep editing; load it in a game with SandyKit.loadCharacter('rosa.json').

This Sandy

Edit the JSON and apply it, or paste one saved earlier.

Share and embed

The link and embed code carry her whole look. The embed shows her alone, with no wardrobe.

Using her in a project

The read-me (the ? button) explains how to drop Sandy into another page, as the player or as NPCs.