@botharness/pixel-avatar 0.8.0 → 0.10.0

package/README.md

@@ -25,5 +25,7 @@ const svg = pixelAvatarSvg(recipe); // 32×32 viewBox, crisp edges, no ids or sc
 - `REPLACE_PART_SLOTS`, `replacePartStart(recipe, slot)`: drawn `outfit`, `accessory`, `beard`, `glasses`, `nose`, `cheeks`, `petals` and `flowerBase` parts (front layer only). A drawn part replaces the built-in part pixel for pixel in the layer that part paints into, while the built-in choice stays saved underneath. `replacePartStart` flattens the worn built-in part for this recipe: pixels that are exactly an appearance color at a tone become that color slot, and the rest become fixed colors, so an unchanged copy renders identically. Drawn face parts never cover the speaking mouth, and drawn parts are hidden wherever the species or headwear hides the built-in part. A drawn accessory replacing a helmet or hood no longer hides the hair.
 - `emptyPartLayer`, `paintPartLayer`, `fillPartLayer`, `mirrorPartX`, `partLayer`, `partCells`, `createCustomPart`: drawing on dense layers, with pencil and eraser strokes, 4-connected flood fill and mirroring across the Avatar centerline.
 - `partLinePoints`, `partRectPoints`, `gradientPartLayer`, `ditherThreshold`, `noisePartLayer`, `shadePartLayer`: line (with 0°/45°/90° snap), rectangle (with square), tone gradient with 4×4 or 2×2 ordered dithering inside the start region, seeded ±1 tone noise, and a shade stroke that moves each colored cell one tone. All mirror, and all produce ordinary cells: the seed and the tool are not part of the part.
+- `AVATAR_PIECE_COLORS_V4`, `AVATAR_STRANDS`, `AVATAR_HEADPIECES`, `withPieces`, `withBuiltInHeadpiece`, `builtInHeadpiece`, `headpieceStart`: asset version 4. Bangs, back hair and a single `strand` each take an optional color (`bangsColor`, `backHairColor`, `strandColor`) that defaults to `hairColor`, like the side hair colors. The headpiece slot holds a built-in headpiece (ears, horns, halo or small head wings) or a Custom Part, worn together with any accessory. The base sits behind the hair and the rest in front, and the far side hides when the head turns. `withPieces` upgrades a recipe when the Human edits and moves an accessory that is now a headpiece into the empty headpiece slot. Saved recipes are never migrated on their own, so they keep rendering as before. `headpieceStart` flattens the worn headpiece into a Custom Part to start drawing from.
+- `AVATAR_ANIMAL_SPECIES`, `AVATAR_PATTERNS`, `isAnimalSpecies`: animal species in asset version 4. Each has a muzzle, an animal nose and its own ears, uses the skin color as fur, and takes an optional fur `pattern` drawn in fur tones. A drawn `pattern` Custom Part replaces the built-in one. Ear headpieces and ear accessories are kept but hidden on an animal.
 - `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

@@ -36,9 +36,36 @@ type AvatarColor = (typeof AVATAR_COLORS)[number];
  */
 declare const AVATAR_SPECIES: readonly ["human", "goblin", "elf", "dwarf", "orc", "flower"];
 type AvatarSpecies = (typeof AVATAR_SPECIES)[number];
+/**
+ * Anthropomorphic animal species (asset version 4): a muzzle, animal ears and fur colors. The
+ * skin color is the fur color, and an optional `pattern` is drawn in its tones.
+ */
+declare const AVATAR_ANIMAL_SPECIES: readonly ["cat", "dog", "fox", "rabbit", "bear"];
+type AvatarAnimalSpecies = (typeof AVATAR_ANIMAL_SPECIES)[number];
+type AvatarSpeciesV4 = AvatarSpecies | AvatarAnimalSpecies;
+declare const isAnimalSpecies: (species: unknown) => species is AvatarAnimalSpecies;
+/** Fur patterns for animal species, drawn in skin-color tones so they survive recoloring. */
+declare const AVATAR_PATTERNS: readonly ["solid", "tabby", "spots", "patches", "colorpoint"];
+type AvatarPattern = (typeof AVATAR_PATTERNS)[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];
+/**
+ * Asset version 4 adds a color for every other hair piece; an absent piece uses `hairColor`.
+ * `strandColor` colors the single strand (`strand`).
+ */
+declare const AVATAR_PIECE_COLORS_V4: readonly ["bangsColor", "backHairColor", "strandColor"];
+type AvatarPieceColorV4 = (typeof AVATAR_PIECE_COLORS_V4)[number];
+/** A single strand of hair standing up from the crown (asset version 4). */
+declare const AVATAR_STRANDS: readonly ["ahoge", "curl", "double"];
+type AvatarStrand = (typeof AVATAR_STRANDS)[number];
+/**
+ * Built-in headpieces (asset version 4), worn in the headpiece slot alongside an accessory and
+ * drawn partly behind the hair. The first five were accessories in earlier versions.
+ */
+declare const AVATAR_HEADPIECES: readonly ["catears", "bunnyears", "horseears", "horns", "halo", "wings"];
+type AvatarHeadpiece = (typeof AVATAR_HEADPIECES)[number];
+type V4Key = AvatarPieceColorV4 | 'strand' | 'pattern';
 /** 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"];
@@ -72,7 +99,7 @@ type PixelAvatarRecipeV1 = Meta & {
 } & { [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 } & { [P in CustomPartKey]?: never };
+} & { [P in AvatarPieceColor | AvatarExtraPart]?: never } & { [P in CustomPartKey]?: never } & { [P in V4Key]?: 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.
@@ -82,7 +109,7 @@ type PixelAvatarRecipeV2 = Meta & {
 } & { [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] } & { [P in CustomPartKey]?: never };
+} & { [P in AvatarPieceColor]?: string } & { [P in AvatarExtraPart]?: (typeof AVATAR_EXTRA_PARTS)[P][number] } & { [P in CustomPartKey]?: never } & { [P in V4Key]?: never };
 /** The recipe key that embeds the Custom Part worn in each slot. */
 declare const CUSTOM_PART_KEYS: {
   readonly headpiece: "headpiece";
@@ -98,6 +125,7 @@ declare const CUSTOM_PART_KEYS: {
   readonly cheeks: "cheeksPart";
   readonly petals: "petalsPart";
   readonly flowerBase: "flowerBasePart";
+  readonly pattern: "patternPart";
 };
 type CustomPartKey = (typeof CUSTOM_PART_KEYS)[PartSlot];
 /**
@@ -106,8 +134,23 @@ type CustomPartKey = (typeof CUSTOM_PART_KEYS)[PartSlot];
  */
 type PixelAvatarRecipeV3 = Omit<PixelAvatarRecipeV2, 'assetVersion' | CustomPartKey> & {
   assetVersion: 3;
-} & { [P in CustomPartKey]?: PixelCustomPart };
-type PixelAvatarRecipe = PixelAvatarRecipeV1 | PixelAvatarRecipeV2 | PixelAvatarRecipeV3;
+} & { [P in Exclude<CustomPartKey, 'patternPart'>]?: PixelCustomPart } & {
+  patternPart?: never;
+};
+/**
+ * Asset version 4: version 2 with a color for every hair piece, a single `strand`, and the
+ * headpiece slot holding either a built-in headpiece or a Custom Part, with any number of
+ * Custom Parts worn (none included).
+ */
+type PixelAvatarRecipeV4 = Omit<PixelAvatarRecipeV2, 'assetVersion' | 'species' | CustomPartKey | V4Key> & {
+  assetVersion: 4;
+} & { [P in Exclude<CustomPartKey, 'headpiece'>]?: PixelCustomPart } & {
+  headpiece?: PixelCustomPart | AvatarHeadpiece;
+  strand?: AvatarStrand;
+  species: AvatarSpeciesV4;
+  pattern?: AvatarPattern;
+} & { [P in AvatarPieceColorV4]?: string };
+type PixelAvatarRecipe = PixelAvatarRecipeV1 | PixelAvatarRecipeV2 | PixelAvatarRecipeV3 | PixelAvatarRecipeV4;
 declare const DEFAULT_RECIPE: PixelAvatarRecipeV1;
 declare function isPixelAvatarRecipe(value: unknown): value is PixelAvatarRecipe;
 declare function canonicalRecipe(recipe: PixelAvatarRecipe): PixelAvatarRecipe;
@@ -123,16 +166,30 @@ declare function hiddenChoices(recipe: PixelAvatarRecipe): readonly string[];
  * 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: AvatarAnimalSpecies): PixelAvatarRecipeV4;
+declare function withSpecies(recipe: PixelAvatarRecipeV4, species: AvatarSpeciesV4): PixelAvatarRecipeV4;
 declare function withSpecies(recipe: PixelAvatarRecipeV3, species: AvatarSpecies): PixelAvatarRecipeV3;
 declare function withSpecies(recipe: PixelAvatarRecipeV1 | PixelAvatarRecipeV2, species: AvatarSpecies): PixelAvatarRecipeV2;
-declare function withSpecies(recipe: PixelAvatarRecipe, species: AvatarSpecies): PixelAvatarRecipeV2 | PixelAvatarRecipeV3;
+declare function withSpecies(recipe: PixelAvatarRecipe, species: AvatarSpeciesV4): PixelAvatarRecipeV2 | PixelAvatarRecipeV3 | PixelAvatarRecipeV4;
 /**
  * Returns the recipe wearing `part` in `slot`, or with that slot's part taken off. The recipe
- * embeds its own copy; it is asset version 3 while it wears any part and version 2 otherwise.
+ * embeds its own copy; it is asset version 3 while it wears any part and version 2 otherwise,
+ * and a version 4 recipe stays version 4.
  */
-declare function withCustomPart(recipe: PixelAvatarRecipe, slot: PartSlot, part: PixelCustomPart | undefined): PixelAvatarRecipeV2 | PixelAvatarRecipeV3;
+declare function withCustomPart(recipe: PixelAvatarRecipeV4, slot: PartSlot, part: PixelCustomPart | undefined): PixelAvatarRecipeV4;
+declare function withCustomPart(recipe: PixelAvatarRecipe, slot: PartSlot, part: PixelCustomPart | undefined): PixelAvatarRecipeV2 | PixelAvatarRecipeV3 | PixelAvatarRecipeV4;
+/**
+ * Returns the recipe as asset version 4, keeping every choice. An accessory that is now a
+ * headpiece moves into the empty headpiece slot, freeing the accessory slot; call this only when
+ * the Human edits, so saved recipes keep rendering as they were.
+ */
+declare function withPieces(recipe: PixelAvatarRecipe): PixelAvatarRecipeV4;
+/** Returns the recipe as asset version 4 wearing a built-in headpiece, or none. */
+declare function withBuiltInHeadpiece(recipe: PixelAvatarRecipe, headpiece: AvatarHeadpiece | undefined): PixelAvatarRecipeV4;
+/** The built-in headpiece worn, if any. */
+declare function builtInHeadpiece(recipe: PixelAvatarRecipe): AvatarHeadpiece | undefined;
 /** `withCustomPart` for the headpiece slot. */
-declare function withHeadpiece(recipe: PixelAvatarRecipe, part: PixelCustomPart | undefined): PixelAvatarRecipeV2 | PixelAvatarRecipeV3;
+declare function withHeadpiece(recipe: PixelAvatarRecipe, part: PixelCustomPart | undefined): PixelAvatarRecipeV2 | PixelAvatarRecipeV3 | PixelAvatarRecipeV4;
 /** The Custom Part worn in a slot, if any. */
 declare function wornPart(recipe: PixelAvatarRecipe, slot: PartSlot): PixelCustomPart | undefined;
 declare function detailedRecipe(recipe: PixelAvatarRecipe): PixelAvatarRecipe;
@@ -154,7 +211,7 @@ 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_SPECIES_SWATCHES: Record<AvatarSpeciesV4, readonly string[]>;
 declare const AVATAR_PRESETS: readonly PixelAvatarRecipe[];
 //#endregion
 //#region src/part.d.ts
@@ -217,6 +274,10 @@ declare const PART_SLOTS: {
     readonly width: 32;
     readonly height: 32;
   };
+  readonly pattern: {
+    readonly width: 32;
+    readonly height: 32;
+  };
 };
 type PartSlot = keyof typeof PART_SLOTS;
 /**
@@ -230,7 +291,7 @@ declare const isHairPartSlot: (slot: PartSlot) => slot is HairPartSlot;
  * Slots whose drawn part replaces a built-in part pixel for pixel: the part's cells are painted
  * where the built-in part would be, and every cell shows its own color and tone.
  */
-declare const REPLACE_PART_SLOTS: readonly ["outfit", "accessory", "beard", "glasses", "nose", "cheeks", "petals", "flowerBase"];
+declare const REPLACE_PART_SLOTS: readonly ["outfit", "accessory", "beard", "glasses", "nose", "cheeks", "petals", "flowerBase", "pattern"];
 type ReplacePartSlot = (typeof REPLACE_PART_SLOTS)[number];
 declare const isReplacePartSlot: (slot: PartSlot) => slot is ReplacePartSlot;
 /** Tone steps on the rig's shade ramp: two darker, the color itself, two lighter. */
@@ -330,6 +391,16 @@ declare function hairPieceStart(recipe: PixelAvatarRecipe, slot: HairPartSlot):
   front: PartCell[];
   back: PartCell[];
 };
+/**
+ * The headpiece as a Custom Part to start drawing from: the drawn headpiece worn, or the
+ * built-in headpiece flattened for this recipe in the front pose, its base on the back layer and
+ * the rest on the front layer, so an unchanged copy renders identically facing front.
+ */
+declare function headpieceStart(recipe: PixelAvatarRecipe): {
+  slot: 'headpiece';
+  front: PartCell[];
+  back: PartCell[];
+};
 /**
  * The part in a replacement slot as a Custom Part to start drawing from: the drawn part worn
  * there, or the built-in part flattened for this recipe in the front pose. Each pixel becomes a
@@ -391,5 +462,5 @@ declare function pixelSymbolCells(symbol: PixelSymbol, color: string): PixelCell
  */
 declare function symbolArtCells(rows: readonly string[], color: string): PixelCell$1[];
 //#endregion
-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, CUSTOM_PART_KEYS, type CustomPartKey, DEFAULT_RECIPE, HAIR_PART_SLOTS, type HairPartSlot, MAX_PART_FIXED_COLORS, PART_LAYERS, PART_SLOTS, PART_TONES, PIXEL_SYMBOLS, type PartCell, type PartColor, type PartInk, type PartLayer, type PartLayerName, type PartSlot, type PartTone, type PixelAvatarRecipe, type PixelAvatarRecipeV1, type PixelAvatarRecipeV2, type PixelAvatarRecipeV3, type PixelAvatarSvgOptions, type PixelCell, type PixelCustomPart, type PixelFigureOptions, type PixelGrid, type PixelMouthState, type PixelSymbol, REPLACE_PART_SLOTS, type ReplacePartSlot, canonicalCustomPart, canonicalRecipe, createCustomPart, createSeededRecipe, createSeededRecipeV2, customPartId, detailedRecipe, ditherThreshold, emptyPartLayer, faceCells, fillPartLayer, gradientPartLayer, hairPieceStart, hiddenChoices, isHairPartSlot, isPixelAvatarRecipe, isPixelCustomPart, isReplacePartSlot, mirrorPartX, noisePartLayer, paintPartLayer, partCells, partLayer, partLinePoints, partRectPoints, partToneColor, pixelAvatarSvg, pixelFigure, pixelSymbolCells, pixelTileColor, replacePartStart, seededRandom, seededRecipe, seededRecipeV2, shadePartLayer, symbolArtCells, withCustomPart, withHeadpiece, withSpecies, wornPart };
+export { AVATAR_ANIMAL_SPECIES, AVATAR_COLORS, AVATAR_EXTRA_PARTS, AVATAR_HAIR_PARTS, AVATAR_HEADPIECES, AVATAR_PARTS, AVATAR_PARTS_V2, AVATAR_PATTERNS, AVATAR_PIECE_COLORS, AVATAR_PIECE_COLORS_V4, AVATAR_PRESETS, AVATAR_RANGES, AVATAR_SPECIES, AVATAR_SPECIES_SWATCHES, AVATAR_STRANDS, AVATAR_SWATCHES, AVATAR_TURNS, type AvatarAnimalSpecies, type AvatarColor, type AvatarExtraPart, type AvatarHairPart, type AvatarHeadpiece, type AvatarPart, type AvatarPattern, type AvatarPieceColor, type AvatarPieceColorV4, type AvatarRange, type AvatarSpecies, type AvatarSpeciesV4, type AvatarStrand, CUSTOM_PART_KEYS, type CustomPartKey, DEFAULT_RECIPE, HAIR_PART_SLOTS, type HairPartSlot, MAX_PART_FIXED_COLORS, PART_LAYERS, PART_SLOTS, PART_TONES, PIXEL_SYMBOLS, type PartCell, type PartColor, type PartInk, type PartLayer, type PartLayerName, type PartSlot, type PartTone, type PixelAvatarRecipe, type PixelAvatarRecipeV1, type PixelAvatarRecipeV2, type PixelAvatarRecipeV3, type PixelAvatarRecipeV4, type PixelAvatarSvgOptions, type PixelCell, type PixelCustomPart, type PixelFigureOptions, type PixelGrid, type PixelMouthState, type PixelSymbol, REPLACE_PART_SLOTS, type ReplacePartSlot, builtInHeadpiece, canonicalCustomPart, canonicalRecipe, createCustomPart, createSeededRecipe, createSeededRecipeV2, customPartId, detailedRecipe, ditherThreshold, emptyPartLayer, faceCells, fillPartLayer, gradientPartLayer, hairPieceStart, headpieceStart, hiddenChoices, isAnimalSpecies, isHairPartSlot, isPixelAvatarRecipe, isPixelCustomPart, isReplacePartSlot, mirrorPartX, noisePartLayer, paintPartLayer, partCells, partLayer, partLinePoints, partRectPoints, partToneColor, pixelAvatarSvg, pixelFigure, pixelSymbolCells, pixelTileColor, replacePartStart, seededRandom, seededRecipe, seededRecipeV2, shadePartLayer, symbolArtCells, withBuiltInHeadpiece, withCustomPart, withHeadpiece, withPieces, withSpecies, wornPart };
 //# sourceMappingURL=index.d.ts.map