@botharness/pixel-avatar 0.1.0 → 0.3.0

package/README.md

@@ -18,5 +18,6 @@ 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.
 - `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,48 @@ 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"];
+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];
+type BaseRecipe = {
   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;
+} & { [P in AvatarPart]: (typeof AVATAR_PARTS)[P][number] } & Record<AvatarColor, string>;
+/** Asset version 1: optional split hair and geometry, all six or none. */
+type PixelAvatarRecipeV1 = BaseRecipe & {
+  assetVersion: 1;
+} & { [P in AvatarHairPart]?: (typeof AVATAR_PARTS)['hair'][number] } & { [P in AvatarRange]?: number } & {
+  species?: never;
+  rightSideHair?: never;
+} & { [P in AvatarPieceColor]?: 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 = BaseRecipe & {
+  assetVersion: 2;
+} & { [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 };
+type PixelAvatarRecipe = PixelAvatarRecipeV1 | PixelAvatarRecipeV2;
+declare const DEFAULT_RECIPE: PixelAvatarRecipeV1;
 declare function isPixelAvatarRecipe(value: unknown): value is PixelAvatarRecipe;
 declare function canonicalRecipe(recipe: PixelAvatarRecipe): PixelAvatarRecipe;
+/**
+ * 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[]>;
 /**
@@ -48,15 +81,21 @@ declare const AVATAR_SWATCHES: Record<AvatarColor, readonly string[]>;
 declare function createSeededRecipe(namespace: string): (seed: string) => PixelAvatarRecipe;
 /** 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
 type Cell = string | undefined;
 type Grid = Cell[][];
 type PixelGrid = Grid;
+type PixelMouthState = 'saved' | 'closed' | 'half-open' | 'open';
+interface PixelFigureOptions {
+  mouthLayers?: boolean;
+}
 type Recipe = PixelAvatarRecipe;
 declare function pixelTileColor(hair: string): string;
-declare function pixelFigure(recipe: Recipe, yawDeg: number): {
+declare function pixelFigure(recipe: Recipe, yawDeg: number, options?: PixelFigureOptions): {
   tile: string;
   body: string;
   head: string;
@@ -70,6 +109,7 @@ declare function seededRandom(seed: string): () => number;
 /** Head-turn offsets (degrees) the thinking animation cycles through. */
 declare const AVATAR_TURNS: readonly [-14, -7, 7, 14];
 interface PixelAvatarSvgOptions {
+  mouthLayers?: boolean;
   /** Extra yaw offsets to pre-render as hidden `[data-avatar-turn]` layers. */
   turns?: readonly number[];
   /** Class prefix for the rig layers (`-body`, `-head`, `-face`, `-gaze`, `-blink`). */
@@ -110,5 +150,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 PixelGrid, type PixelSymbol, canonicalRecipe, createSeededRecipe, detailedRecipe, faceCells, isPixelAvatarRecipe, pixelAvatarSvg, pixelFigure, pixelSymbolCells, pixelTileColor, seededRandom, seededRecipe, symbolArtCells };
+export { AVATAR_COLORS, AVATAR_HAIR_PARTS, AVATAR_PARTS, AVATAR_PIECE_COLORS, AVATAR_PRESETS, AVATAR_RANGES, AVATAR_SPECIES, AVATAR_SPECIES_SWATCHES, AVATAR_SWATCHES, AVATAR_TURNS, type AvatarColor, 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, detailedRecipe, faceCells, isPixelAvatarRecipe, pixelAvatarSvg, pixelFigure, pixelSymbolCells, pixelTileColor, seededRandom, seededRecipe, symbolArtCells, withSpecies };
 //# sourceMappingURL=index.d.ts.map