@botharness/pixel-avatar 0.2.0 → 0.4.0

package/README.md

@@ -18,5 +18,7 @@ const svg = pixelAvatarSvg(recipe); // 32×32 viewBox, crisp edges, no ids or sc
 - `AVATAR_PARTS`, `AVATAR_SWATCHES`, `AVATAR_PRESETS`, `DEFAULT_RECIPE`: everything an editor needs.
 - `isPixelAvatarRecipe`, `canonicalRecipe`: validate and normalise saved recipes.
 - `AVATAR_HAIR_PARTS`, `AVATAR_RANGES`, `detailedRecipe(recipe)`: optional finer controls. A recipe may carry `bangs`, `sideHair`, `backHair`, `spacing`, `height` and `hairLength`, all six or none; `detailedRecipe` derives them from the plain `hair` so an editor can start from what is on screen. Recipes without them render exactly as before.
+- `AVATAR_SPECIES`, `AVATAR_SPECIES_SWATCHES`, `AVATAR_PIECE_COLORS`, `withSpecies(recipe, species)`: Avatar Species (`human`, `goblin`) on the same rig, as asset version 2. `withSpecies` keeps every choice, splits side hair into `sideHair` (left) and `rightSideHair`, and accepts optional `leftSideHairColor`/`rightSideHairColor`, where left and right are as seen on screen. Consumers built before version 2 reject these recipes with `isPixelAvatarRecipe` and can show a saved snapshot instead.
+- `AVATAR_PARTS_V2`, `AVATAR_EXTRA_PARTS`, `hiddenChoices(recipe)`: version 2 adds elf, dwarf, orc and flower species, armor/robe/tunic/cloak outfits, helmet/hood headwear, an optional `beard`, and a flower's `petals` and `flowerBase`. `hiddenChoices` names saved choices the current species or headwear keeps but does not draw, so an editor can say so instead of discarding them.
 - `faceCells`, `pixelSymbolCells`, `symbolArtCells`: pixels for [`@botharness/pixel-morph`](../morph).
 - `pixelAvatarSvg(recipe, { turns, classPrefix })`: optional pre-rendered head turns, and rig layer classes (`<prefix>-body`, `-head`, `-face`, `-gaze`, `-blink`) for CSS animation.

package/dist/index.d.ts

@@ -30,15 +30,76 @@ type AvatarRange = keyof typeof AVATAR_RANGES;
 type AvatarPart = keyof typeof AVATAR_PARTS;
 declare const AVATAR_COLORS: readonly ["skinColor", "hairColor", "eyeColor", "shirtColor"];
 type AvatarColor = (typeof AVATAR_COLORS)[number];
-type PixelAvatarRecipe = {
+/**
+ * Avatar Species: a base on the pixel bust rig. Species share motion and anchors; each sets its
+ * own ears, face details and suggested body colors. A recipe with a species is asset version 2.
+ */
+declare const AVATAR_SPECIES: readonly ["human", "goblin", "elf", "dwarf", "orc", "flower"];
+type AvatarSpecies = (typeof AVATAR_SPECIES)[number];
+/** Optional per-piece hair colors (asset version 2); an absent piece uses `hairColor`. */
+declare const AVATAR_PIECE_COLORS: readonly ["leftSideHairColor", "rightSideHairColor"];
+type AvatarPieceColor = (typeof AVATAR_PIECE_COLORS)[number];
+/** Part choices that exist only in asset version 2, added after every version 1 choice. */
+declare const AVATAR_PARTS_V2: {
+  readonly outfit: readonly ["tee", "shirttie", "hoodie", "turtleneck", "sailor", "blazer", "overalls", "dress", "kimono", "cardigan", "maid", "jacket", "armor", "robe", "tunic", "cloak"];
+  readonly accessory: readonly ["none", "beanie", "cap", "headphones", "flower", "bow", "earring", "crown", "halo", "catears", "hairclip", "horns", "beret", "ribbon", "headband", "bunnyears", "horseears", "flowercrown", "witch", "pins", "helmet", "hood"];
+  readonly head: readonly ["round", "oval", "square", "long", "heart", "vchin", "chubby", "diamond"];
+  readonly pose: readonly ["front", "left", "right"];
+  readonly hair: readonly ["crop", "sweep", "spiky", "buzz", "curly", "mohawk", "bob", "long", "bun", "pigtails", "afro", "twintails", "drills", "ponytail", "sidetail", "hime", "odango", "messy", "wavy", "braids", "wolf", "ahoge", "none"];
+  readonly eyes: readonly ["round", "dot", "sparkle", "lashes", "sleepy", "happy", "wink", "sharp"];
+  readonly brows: readonly ["soft", "thick", "raised", "angry", "worried", "none"];
+  readonly nose: readonly ["button", "dot", "line", "none"];
+  readonly mouth: readonly ["smile", "grin", "open", "flat", "smirk", "cat", "tongue", "o"];
+  readonly cheeks: readonly ["blush", "freckles", "none"];
+  readonly glasses: readonly ["none", "round", "square", "shades", "monocle"];
+  readonly backdrop: readonly ["sparkles", "hearts", "stars", "dots", "none"];
+};
+/** Optional asset version 2 parts; an absent part is not drawn (or uses the first choice). */
+declare const AVATAR_EXTRA_PARTS: {
+  readonly beard: readonly ["short", "full", "braided"];
+  readonly petals: readonly ["trumpet", "daisy", "sunflower", "tulip", "sakura"];
+  readonly flowerBase: readonly ["leaves", "pot"];
+};
+type AvatarExtraPart = keyof typeof AVATAR_EXTRA_PARTS;
+type Meta = {
   schemaVersion: 1;
   family: 'illustrated';
-  assetVersion: 1;
   rigVersion: 1;
-} & { [P in AvatarPart]: (typeof AVATAR_PARTS)[P][number] } & Record<AvatarColor, string> & { [P in AvatarHairPart]?: (typeof AVATAR_PARTS)['hair'][number] } & { [P in AvatarRange]?: number };
-declare const DEFAULT_RECIPE: PixelAvatarRecipe;
+} & Record<AvatarColor, string>;
+/** Asset version 1: optional split hair and geometry, all six or none. */
+type PixelAvatarRecipeV1 = Meta & {
+  assetVersion: 1;
+} & { [P in AvatarPart]: (typeof AVATAR_PARTS)[P][number] } & { [P in AvatarHairPart]?: (typeof AVATAR_PARTS)['hair'][number] } & { [P in AvatarRange]?: number } & {
+  species?: never;
+  rightSideHair?: never;
+} & { [P in AvatarPieceColor | AvatarExtraPart]?: never };
+/**
+ * Asset version 2: a species, the full split hair and geometry, a separate right side hair
+ * (`sideHair` is then the left side) and optional per-side hair colors.
+ */
+type PixelAvatarRecipeV2 = Meta & {
+  assetVersion: 2;
+} & { [P in AvatarPart]: (typeof AVATAR_PARTS_V2)[P][number] } & { [P in AvatarHairPart]: (typeof AVATAR_PARTS)['hair'][number] } & { [P in AvatarRange]: number } & {
+  species: AvatarSpecies;
+  rightSideHair: (typeof AVATAR_HAIR_PARTS)['sideHair'][number];
+} & { [P in AvatarPieceColor]?: string } & { [P in AvatarExtraPart]?: (typeof AVATAR_EXTRA_PARTS)[P][number] };
+type PixelAvatarRecipe = PixelAvatarRecipeV1 | PixelAvatarRecipeV2;
+declare const DEFAULT_RECIPE: PixelAvatarRecipeV1;
 declare function isPixelAvatarRecipe(value: unknown): value is PixelAvatarRecipe;
 declare function canonicalRecipe(recipe: PixelAvatarRecipe): PixelAvatarRecipe;
+/**
+ * Saved choices the recipe keeps but does not draw: a flower shows petals and a stem instead of
+ * hair, outfit, beard and headwear, and a helmet or hood covers the hair. The choices return when
+ * the species or headwear changes back.
+ */
+declare function hiddenChoices(recipe: PixelAvatarRecipe): readonly string[];
+/**
+ * Returns the recipe as asset version 2 with the given species, keeping every other choice.
+ * Side hair splits into left (`sideHair`) and right (`rightSideHair`) pieces that start equal.
+ * When the skin color is one of the previous species' suggested colors, it moves to the new
+ * species' first suggestion; a custom color is kept.
+ */
+declare function withSpecies(recipe: PixelAvatarRecipe, species: AvatarSpecies): PixelAvatarRecipeV2;
 declare function detailedRecipe(recipe: PixelAvatarRecipe): PixelAvatarRecipe;
 declare const AVATAR_SWATCHES: Record<AvatarColor, readonly string[]>;
 /**
@@ -46,8 +107,19 @@ declare const AVATAR_SWATCHES: Record<AvatarColor, readonly string[]>;
  * name; the factory takes the name only, so it is safe to pass straight to `Array.map`.
  */
 declare function createSeededRecipe(namespace: string): (seed: string) => PixelAvatarRecipe;
+/**
+ * A version 2 name-seeded recipe factory over every species. Species are equally likely; a
+ * person may get a beard or a version 2 outfit, and a flower gets petals and a base. Version 1
+ * factories (`createSeededRecipe`) keep their faces, so a consumer chooses per identity which
+ * seed version it was created with.
+ */
+declare function createSeededRecipeV2(namespace: string): (seed: string) => PixelAvatarRecipeV2;
+/** Version 2 counterpart of `seededRecipe` (BotHarness's namespace). */
+declare const seededRecipeV2: (seed: string) => PixelAvatarRecipeV2;
 /** The same name always gives the same face (BotHarness's namespace). */
 declare const seededRecipe: (seed: string) => PixelAvatarRecipe;
+/** Suggested body colors per species; any color remains allowed. */
+declare const AVATAR_SPECIES_SWATCHES: Record<AvatarSpecies, readonly string[]>;
 declare const AVATAR_PRESETS: readonly PixelAvatarRecipe[];
 //#endregion
 //#region src/figure.d.ts
@@ -115,5 +187,5 @@ declare function pixelSymbolCells(symbol: PixelSymbol, color: string): PixelCell
  */
 declare function symbolArtCells(rows: readonly string[], color: string): PixelCell$1[];
 //#endregion
-export { AVATAR_COLORS, AVATAR_HAIR_PARTS, AVATAR_PARTS, AVATAR_PRESETS, AVATAR_RANGES, AVATAR_SWATCHES, AVATAR_TURNS, type AvatarColor, type AvatarHairPart, type AvatarPart, type AvatarRange, DEFAULT_RECIPE, PIXEL_SYMBOLS, type PixelAvatarRecipe, type PixelAvatarSvgOptions, type PixelCell, type PixelFigureOptions, type PixelGrid, type PixelMouthState, type PixelSymbol, canonicalRecipe, createSeededRecipe, detailedRecipe, faceCells, isPixelAvatarRecipe, pixelAvatarSvg, pixelFigure, pixelSymbolCells, pixelTileColor, seededRandom, seededRecipe, symbolArtCells };
+export { AVATAR_COLORS, AVATAR_EXTRA_PARTS, AVATAR_HAIR_PARTS, AVATAR_PARTS, AVATAR_PARTS_V2, AVATAR_PIECE_COLORS, AVATAR_PRESETS, AVATAR_RANGES, AVATAR_SPECIES, AVATAR_SPECIES_SWATCHES, AVATAR_SWATCHES, AVATAR_TURNS, type AvatarColor, type AvatarExtraPart, type AvatarHairPart, type AvatarPart, type AvatarPieceColor, type AvatarRange, type AvatarSpecies, DEFAULT_RECIPE, PIXEL_SYMBOLS, type PixelAvatarRecipe, type PixelAvatarRecipeV1, type PixelAvatarRecipeV2, type PixelAvatarSvgOptions, type PixelCell, type PixelFigureOptions, type PixelGrid, type PixelMouthState, type PixelSymbol, canonicalRecipe, createSeededRecipe, createSeededRecipeV2, detailedRecipe, faceCells, hiddenChoices, isPixelAvatarRecipe, pixelAvatarSvg, pixelFigure, pixelSymbolCells, pixelTileColor, seededRandom, seededRecipe, seededRecipeV2, symbolArtCells, withSpecies };
 //# sourceMappingURL=index.d.ts.map