@botharness/pixel-avatar 0.3.0 → 0.5.0

package/README.md

@@ -19,5 +19,8 @@ const svg = pixelAvatarSvg(recipe); // 32×32 viewBox, crisp edges, no ids or sc
 - `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.
+- `PixelCustomPart`, `withHeadpiece(recipe, part)`, `customPartId`, `isPixelCustomPart`: a Human-drawn Custom Part in the `headpiece` slot (the top 32×16 of the tile). Its back layer is drawn behind the hair and its front layer over it, and both follow the head through turns. Each cell is `[x, y, color, tone]`, where `color` is an appearance color slot (`hairColor`, `skinColor`, `eyeColor`, `shirtColor`), so the part recolors with the Avatar, or a fixed `#rrggbb`, and `tone` is a step from −2 to 2 on the rig's shade ramp (`partToneColor`). A recipe wearing a part embeds its own copy as asset version 3. `customPartId` is the SHA-256 of the canonical content; names, authors and origins belong to the consumer's library.
+- `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.
 - `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

@@ -34,44 +34,88 @@ type AvatarColor = (typeof AVATAR_COLORS)[number];
  * 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"];
+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];
-type BaseRecipe = {
+/** 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';
   rigVersion: 1;
-} & { [P in AvatarPart]: (typeof AVATAR_PARTS)[P][number] } & Record<AvatarColor, string>;
+} & Record<AvatarColor, string>;
 /** Asset version 1: optional split hair and geometry, all six or none. */
-type PixelAvatarRecipeV1 = BaseRecipe & {
+type PixelAvatarRecipeV1 = Meta & {
   assetVersion: 1;
-} & { [P in AvatarHairPart]?: (typeof AVATAR_PARTS)['hair'][number] } & { [P in AvatarRange]?: number } & {
+} & { [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]?: never };
+} & { [P in AvatarPieceColor | AvatarExtraPart]?: never } & {
+  headpiece?: 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 & {
+type PixelAvatarRecipeV2 = Meta & {
   assetVersion: 2;
-} & { [P in AvatarHairPart]: (typeof AVATAR_PARTS)['hair'][number] } & { [P in AvatarRange]: number } & {
+} & { [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 };
-type PixelAvatarRecipe = PixelAvatarRecipeV1 | PixelAvatarRecipeV2;
+} & { [P in AvatarPieceColor]?: string } & { [P in AvatarExtraPart]?: (typeof AVATAR_EXTRA_PARTS)[P][number] } & {
+  headpiece?: never;
+};
+/** Asset version 3: version 2 with an embedded Custom Part in the headpiece slot. */
+type PixelAvatarRecipeV3 = Omit<PixelAvatarRecipeV2, 'assetVersion' | 'headpiece'> & {
+  assetVersion: 3;
+  headpiece: PixelCustomPart;
+};
+type PixelAvatarRecipe = PixelAvatarRecipeV1 | PixelAvatarRecipeV2 | PixelAvatarRecipeV3;
 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 withSpecies(recipe: PixelAvatarRecipeV3, species: AvatarSpecies): PixelAvatarRecipeV3;
+declare function withSpecies(recipe: PixelAvatarRecipeV1 | PixelAvatarRecipeV2, species: AvatarSpecies): PixelAvatarRecipeV2;
+declare function withSpecies(recipe: PixelAvatarRecipe, species: AvatarSpecies): PixelAvatarRecipeV2 | PixelAvatarRecipeV3;
+/**
+ * Returns the recipe wearing a Custom Part in the headpiece slot (asset version 3), or without
+ * one (asset version 2). The recipe embeds its own copy of the part.
+ */
+declare function withHeadpiece(recipe: PixelAvatarRecipe, part: PixelCustomPart | undefined): PixelAvatarRecipeV2 | PixelAvatarRecipeV3;
 declare function detailedRecipe(recipe: PixelAvatarRecipe): PixelAvatarRecipe;
 declare const AVATAR_SWATCHES: Record<AvatarColor, readonly string[]>;
 /**
@@ -79,12 +123,80 @@ 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/part.d.ts
+/**
+ * Custom Part slots. A headpiece covers the top of the tile, around the hair: its back layer is
+ * drawn behind the hair and its front layer over it. Cells are in tile coordinates, so the
+ * Avatar centerline sits between x = 15 and x = 16.
+ */
+declare const PART_SLOTS: {
+  readonly headpiece: {
+    readonly width: 32;
+    readonly height: 16;
+  };
+};
+type PartSlot = keyof typeof PART_SLOTS;
+/** Tone steps on the rig's shade ramp: two darker, the color itself, two lighter. */
+declare const PART_TONES: readonly [-2, -1, 0, 1, 2];
+type PartTone = (typeof PART_TONES)[number];
+/** An appearance color slot (it follows the Avatar's color) or a fixed `#rrggbb` color. */
+type PartColor = AvatarColor | `#${string}`;
+/** One painted cell: `[x, y, color, tone]`. */
+type PartCell = readonly [x: number, y: number, color: PartColor, tone: PartTone];
+declare const PART_LAYERS: readonly ["front", "back"];
+type PartLayerName = (typeof PART_LAYERS)[number];
+/** Most fixed colors one part may use. */
+declare const MAX_PART_FIXED_COLORS = 16;
+/**
+ * A Human-drawn Custom Part. Its content is immutable and its identity is `customPartId`;
+ * name, author, origin and parent are metadata kept outside it.
+ */
+interface PixelCustomPart {
+  slot: PartSlot;
+  front: readonly PartCell[];
+  back: readonly PartCell[];
+}
+/** A dense layer for drawing: `layer[y][x]` is a color and tone, or `null` when empty. */
+type PartInk = {
+  color: PartColor;
+  tone: PartTone;
+};
+type PartLayer = (PartInk | null)[][];
+declare function isPixelCustomPart(value: unknown): value is PixelCustomPart;
+/** The part with cells in row order and fixed colors in lowercase. */
+declare function canonicalCustomPart(part: PixelCustomPart): PixelCustomPart;
+/** Content identity: a SHA-256 of the canonical slot, cells and color references. */
+declare function customPartId(part: PixelCustomPart): string;
+declare function emptyPartLayer(slot: PartSlot): PartLayer;
+declare function partLayer(slot: PartSlot, cells: readonly PartCell[]): PartLayer;
+declare function partCells(layer: PartLayer): PartCell[];
+/** Builds a canonical part from two drawn layers. */
+declare function createCustomPart(slot: PartSlot, layers: Record<PartLayerName, PartLayer>): PixelCustomPart;
+/** The column mirrored across the Avatar centerline. */
+declare function mirrorPartX(slot: PartSlot, x: number): number;
+/** Sets cells (pencil with ink, eraser with `null`), optionally mirrored across the centerline. */
+declare function paintPartLayer(slot: PartSlot, layer: PartLayer, points: readonly (readonly [number, number])[], ink: PartInk | null, mirror?: boolean): PartLayer;
+/**
+ * 4-connected flood fill from a cell: every cell reachable through cells equal to the start
+ * becomes `ink`. With `mirror`, the mirrored start is filled too.
+ */
+declare function fillPartLayer(slot: PartSlot, layer: PartLayer, x: number, y: number, ink: PartInk | null, mirror?: boolean): PartLayer;
+//#endregion
 //#region src/figure.d.ts
 type Cell = string | undefined;
 type Grid = Cell[][];
@@ -93,6 +205,8 @@ type PixelMouthState = 'saved' | 'closed' | 'half-open' | 'open';
 interface PixelFigureOptions {
   mouthLayers?: boolean;
 }
+/** The color a Custom Part cell shows at a tone step on the rig's shade ramp. */
+declare function partToneColor(color: string, tone: PartTone): string;
 type Recipe = PixelAvatarRecipe;
 declare function pixelTileColor(hair: string): string;
 declare function pixelFigure(recipe: Recipe, yawDeg: number, options?: PixelFigureOptions): {
@@ -150,5 +264,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_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 };
+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, 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, canonicalCustomPart, canonicalRecipe, createCustomPart, createSeededRecipe, createSeededRecipeV2, customPartId, detailedRecipe, emptyPartLayer, faceCells, fillPartLayer, hiddenChoices, isPixelAvatarRecipe, isPixelCustomPart, mirrorPartX, paintPartLayer, partCells, partLayer, partToneColor, pixelAvatarSvg, pixelFigure, pixelSymbolCells, pixelTileColor, seededRandom, seededRecipe, seededRecipeV2, symbolArtCells, withHeadpiece, withSpecies };
 //# sourceMappingURL=index.d.ts.map