@fabiplay/avatars
v0.9.3
Published
39 child-friendly avatars: Fabi the fox in every age band, 12 per band, a T-rex and a fairy, drawn from a body pose, on canvas or as SVG portraits for the pickers.
Maintainers
Readme
@fabiplay/avatars
Thirty-nine original, child-friendly avatars, drawn from a body pose: 12 for each age band, the T-rex and the fairy, and Fabi the fox (the fox of the app icon, the mascot). Fabi is the host, not a player: no band offers it to the children, but the TV and games draw it like any other avatar. The lion, the T-rex and the fairy are offered to both 3–5 and 6–8. The TV shows them in place of the plain silhouette when the phone's video is not on screen. Each child picks one on the phone, among the avatars of their age band. The phone stores only the avatar's id; any valid id is accepted everywhere, whatever the band.
All characters are original. None is an existing character or a real person. The people of 9–12 have generic faces, varied skin tones and gender-neutral looks, and are told apart by their gear.
| Band | Style | id · en · it (the first four are the slot defaults) |
| --- | --- | --- |
| all | the app icon's fox, the host: in no band's list (pickers don't offer it), special: true, drawn with the 6–8 proportions; never a slot default; a child saved with it keeps it | mascot Fabi · Fabi |
| 3–5 | cuddly baby animals: big round heads, chubby limbs, soft colours, a soft brown outline | bunny Bunny · Coniglietto, bear Bear · Orsetto, panda Panda · Panda, penguin Penguin · Pinguino, koala Koala · Koala, frog Frog · Ranocchio, cat Cat · Gattino, owl Owl · Gufetto, chick Chick · Pulcino, puppy Puppy · Cucciolo, lamb Lamb · Agnellino, duckling Duckling · Anatroccolo; then, also offered here (home 6–8): lion, trex, fairy |
| 6–8 | animals and adventure | fox Fox · Volpe, lion Lion · Leoncino, dragon Little Dragon · Draghetto, unicorn Unicorn · Unicorno, tiger Tiger · Tigrotto, monkey Monkey · Scimmietta, dinosaur Dinosaur · Dinosauro, trex T-Rex · T-Rex, octopus Octopus · Polpetto, ghost Friendly Ghost · Fantasmino, shark Shark · Squalo, wolf Wolf · Lupo, parrot Parrot · Pappagallo, fairy Fairy · Fatina |
| 9–12 | older kids: smaller heads, slimmer longer limbs, gear, cooler colours, no blush, a cool outline | robot Robot · Robot, astronaut Astronaut · Astronauta, ninja Ninja · Ninja, skater Skater · Skater, alien Alien · Alieno, explorer Explorer · Giramondo, wizard Wizard · Mago, knight Knight · Cavaliere, racer Racer · Pilota, pirate Pirate · Pirata, diver Diver · Sub, hero Hero · Supereroe |
Install
npm install @fabiplay/avatarsESM only, types included; depends on @fabiplay/protocol. Games get the avatars from @fabiplay/sdk
(play.drawAvatar) and need not install this package.
API
import { drawAvatar, drawAvatarIcon, avatarIconSvg, AVATARS, avatarById, isAvatarId } from '@fabiplay/avatars'
// On the TV or in a game, every frame (box: where player space 0–1 lands, e.g. cameraBox(...)):
drawAvatar(ctx, body, player.avatar ?? 'fox', box, { alpha: 0.9 })
// A picker on a canvas:
drawAvatarIcon(ctx, 'panda', x, y, 96)
// A picker on the phone, without a canvas:
el.innerHTML = avatarIconSvg('panda', 96) // web DOM
<SvgXml xml={avatarIconSvg('panda', 96)} /> // React Native, react-native-svg
<img src={avatarIconDataUri('panda', 96)} /> // data URIAVATARS: readonly AvatarDef[](all 39),AVATAR_IDS,DEFAULT_AVATAR(the fox),avatarById(id),isAvatarId(x).AVATAR_BANDS: Record<AgeRange, readonly AvatarId[]>(picker order: the band's own 12, whose first four are the slot defaults, seedefaultAvatarFor(slot, ageRange?)in@fabiplay/protocol, then the avatars also offered there; the lists are not all the same length: 15, 14, 12). The mascot (MASCOT_ID) is in none: Fabi is the host, not a player. It stays inAVATARS,isAvatarId('mascot')is true anddrawAvatardraws it,avatarsFor(ageRange)(the definitions, in that order),bandOf(id)(the home band:'all'for the mascot, 6–8 for an unknown id),bandsOf(id)(every band whose list offers it: none for the mascot). Every definition has itsband(AvatarBand: an age range or'all') and, if it is offered elsewhere too,alsoIn(see "Avatars of two bands" below);special: truemarks the mascot.bodyBand(def, shown?)gives the proportions it is drawn with (6–8 for'all').drawAvatar(ctx, body, def | id, box, { alpha?, mirrored?, band? }). Unknown ids draw the default avatar.band: the child's age band, when the caller knows it (see "Avatars of two bands"). Passmirroredwhen the body is in camera space rather than player space. It draws nothing when the shoulders are not seen (it returns whether it drew), and it never throws on missing or broken points.drawAvatarIcon(ctx, def | id, x, y, size, { band? }): a head-and-shoulders portrait in a neutral pose, clipped to its square. A picker passes the band it shows.avatarIconSvg(def | id, size, { background?, radius?, band? }): the same portrait as an SVG document string. Its clip-path id is unique per call (avatar, size and a counter), so many portraits can sit inline in one page.avatarIconDataUrireturns the same as a data URI.smoothBody(prev, next, amount = 0.5): optional per-player smoothing. Points ease towards the new frame. A point that was seen stays visible until its visibility drops below 0.3, so limbs don't blink. Keep the result per player.new BodyInterpolator(options?): bodies at the display's rate, drawn one interval between bodies behind the newest (lag, default 1) so network jitter is absorbed, going on past the newest by at most half an interval (extrapolate, default 0.5) andmaxExtrapolateMs(25) when the next one is late.- Bodies from a camera on the same device (a phone or a tablet playing alone, no network in between):
smoothBody(prev, next, LOCAL_SMOOTHING)(0.8) andnew BodyInterpolator(LOCAL_INTERPOLATION)(lag0.5,extrapolate0.75, at most 50 ms). At 15 bodies a second an arm wave lags about 49 ms instead of 131 ms (SDK's 0.5) or 109 ms (0.6); arrival jitter up to a quarter of an interval still moves smoothly, more makes the drawing wait and catch up (test/latency.test.ts,FABI_LATENCY_TABLE=1prints the tables). - Poses for previews and tests:
neutralPose(),armsUpPose(),starJumpPose(),squatPose(),wavePose(),TEST_POSES,poseBody(spec). - Lower level:
avatarShapes(body, def, box, { mirrored?, portrait?, band? })returns the shape list,iconShapes(def, size, band?)the portrait's,drawShapes(ctx, shapes)draws it on a canvas, andshapesToSvg(shapes)turns it into SVG.frameOf(body, box)gives the rig's torso frame.
Avatars of two bands
An avatar can be offered in more than one band: its band is its home, and alsoIn lists the others (today the
lion, the T-rex and the fairy: home 6–8, also in 3–5). It is listed in each of those bands' AVATAR_BANDS, after
the band's own, so the slot defaults never change.
- Proportions follow the band shown. Pass the band (
drawAvatar/avatarShapesoptionband, the third argument oficonShapes, thebandoption ofdrawAvatarIcon/avatarIconSvg): an avatar offered in that band takes its proportions (bodyBand(def, band)), so the lion in a 3–5 picker or game has the toddler build. The band is the child's (Player.ageRangeon the phone and the TV) or the picker's. - Without a band, or with a band it is not offered in, it keeps its home band's proportions: exactly what it drew
before. Avatars of one band, and the mascot (always 6–8), ignore
bandentirely, so passing it is always safe. - Its style stays its home band's (outline colour, palette): one look, whatever the band.
bandOf(id)still returns the home band (one value, as before);bandsOf(id)returns them all. - The SDK's and the engine's
drawAvatardon't pass a band yet: in games these avatars are drawn with their home band's proportions, as are their name tags.
How it is drawn
One source of truth: the rig and the portrait build a small shape list (circle, ellipse, rect, path,
line, group with translate/rotate/scale). Two small backends read it: a canvas backend and an SVG backend.
Because both read the same list, canvas and SVG pictures match. Paths use only absolute M L Q C Z, so the canvas
backend does not need Path2D. The rig builds them as number arrays (PathData: a PATH command code, then its
coordinates, rounded to 2 decimals as the SVG prints them), so nothing is turned into a string and parsed back every
frame; pathToString prints one. A head depends only on the avatar and the outline width, so it is built once and
shared across frames (treat shape lists as read-only). test/snapshot.json holds a hash of every avatar's pictures:
a change that alters them by accident fails the tests (UPDATE_SNAPSHOT=1 after one meant to).
Rig rules (src/rig.ts)
Unit U: the torso length (shoulder midpoint to hip midpoint). It is at least 1.15 × the shoulder width, so bending forward does not shrink the avatar. Every size is a multiple of U, so avatars scale with distance.
Torso: a smooth rounded shape along the torso axis (square to the shoulder line when shoulders to hips is under 0.25 × the shoulder width: a child bent towards the camera). It runs from just above the shoulders to just below the hips, and is at least 0.68 U wide at the shoulders and 0.8 U wide at the hips. A belly patch sits on top.
Limbs: thick round strokes from shoulder to elbow to wrist (0.22 U) and from hip to knee to ankle (0.28 U), each with an outline. Arms start just below the shoulder. Legs start inside the torso, so nothing looks detached. Hands are round caps. Feet are ovals, flippers or boots.
Proportions by band (
BAND_BODY): the joints are always the child's, only sizes change. An avatar of no band ('all', the mascot) takes the 6–8 row. An avatar of two bands takes the row of the band shown (above).| band | head radius | head centre above the shoulders | arm / leg thickness | hand radius | torso below the hips | torso min half width (shoulders / hips) | | --- | --- | --- | --- | --- | --- | --- | | 3–5 | 0.75 U | 0.74 head radii | 0.30 / 0.36 U | 0.19 U | 0.26 U | 0.40 / 0.50 U, rounder tummy | | 6–8 | 0.6 U | 0.78 | 0.22 / 0.28 U | 0.15 U | 0.14 U | 0.34 / 0.40 U | | 9–12 | 0.5 U | 0.92 | 0.17 / 0.21 U | 0.125 U | 0.10 U | 0.36 / 0.32 U, slimmer hips |
In 3–5 an arm raised well above the shoulders is drawn over the big head, which would hide it.
Head: radius by band (above), centred above the shoulder midpoint along the torso axis. It follows the nose a little (at most 0.35 radii) and tilts with the ear line, or the eye line if the ears are missing. The tilt is clamped to ±0.5 rad from the torso, and a swapped pair is treated as a child facing away. The
snout-longhead (the T-rex) is turned three-quarters, its snout on the left, away from the tail; its portrait is centred on the head's width, snout included.Tail, wings, backpack, tentacles: these hang off the hips or the back, in torso coordinates, and are drawn behind the body. The tail goes on the child's right. Portraits leave it out.
Held things: the fairy's
wandis in the hand on the right, following it (up and out from the body, leaning with the forearm), under the hand; no wrist, no wand. Portraits leave it out.tiny-armsonly makes the arms slimmer, with small clawed hands: they still reach the child's hands.Draw order: back extras, legs, torso, arms, head, then (3–5 only) raised arms.
Degrading: a point counts as seen at visibility ≥ 0.5. If the elbow or knee is missing, that limb is hidden. If the wrist or ankle is missing, the limb ends at the elbow or knee. If the hips are missing, the torso is one U long and the legs are hidden. If either shoulder is missing, nothing is drawn.
Adding an avatar
- Add an entry to
AVATARSinsrc/defs.tsand its id to its band inAVATAR_BANDS(src/index.ts) (an avatar of band'all'goes in no band (only the mascot, the host, is one); one offered in another band too lists it inalsoInand goes in that band's list as well, after the band's own). Choose a new kebab-caseidand never rename it later, because phones store it. Fill inname.en,name.itandband. Pick apalettewithbody,limbs,belly,accentandoutline, plus optionalhands,feetandears. Then choose aheadshape,ears, theface(eyes, mouth, muzzle, nose, cheeks), atail,headExtrasandbodyExtras.extraColorscovers stripes, spots, manes and lights. - Make it different from the others by its silhouette (ears, head, tail, extras) and its body colour. Use a body colour that reads on both the night background (#1f1813) and a light one. Keep the dark outline.
- If a part does not exist yet, add a kind to the union in
src/types.tsand draw it insrc/head.ts(head units: radius 1, y down) or insrc/rig.ts(torso units of U). Don't write per-id special cases. - Run
pnpm -F @fabiplay/avatars preview <dir> --detailsand look at the PNGs (an avatar of two bands is shown in each, with that band's proportions): the portrait, every pose, and both backgrounds. Then runpnpm -F @fabiplay/avatars test.
Scripts
pnpm -F @fabiplay/avatars typecheck/testpnpm -F @fabiplay/avatars preview [out-dir] [--details]writescontact-sheet.html, grouped by age band. If Chrome is installed, it also renderscontact-sheet.png: every portrait (SVG and canvas side by side), and every avatar in three poses on night and light backgrounds.--detailsaddsicons.pngand largedetail-<band>-<n>.pngpages with six poses each, including one with missing points (detail-all-1.png: the mascot, next to the 6–8 fox). The default output ispackages/avatars/preview/, which git ignores.
License
Fabi Play Kit License: free to use, for making games and tools for Fabi Play only. The avatars and the mascot Fabi are part of the Kit: see LICENSE, section 2e.
