@botharness/pixel-avatar 0.5.0 → 0.7.0

package/README.md

@@ -21,6 +21,8 @@ const svg = pixelAvatarSvg(recipe); // 32×32 viewBox, crisp edges, no ids or sc
 - `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.
+- `HAIR_PART_SLOTS`, `hairPieceStart(recipe, slot)`, `withCustomPart(recipe, slot, part)`, `wornPart`: drawn hair pieces. `bangs`, `leftSideHair`, `rightSideHair` and `backHair` each take a Custom Part (front layer only) that replaces the built-in piece while it stays saved underneath. In a hair part, a `hairColor` cell at tone 0 is live hair: it is shaded with the rest of the hair exactly like the built-in piece, so `hairPieceStart` flattens the worn built-in piece into such cells and an unchanged copy renders identically. Other cells show their own color. Drawn hair follows turns and is hidden under a helmet or hood and on a flower, like built-in hair.
+- `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.
 - `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

@@ -72,9 +72,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 } & {
-  headpiece?: never;
-};
+} & { [P in AvatarPieceColor | AvatarExtraPart]?: never } & { [P in CustomPartKey]?: 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.
@@ -84,14 +82,31 @@ 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] } & {
-  headpiece?: never;
+} & { [P in AvatarPieceColor]?: string } & { [P in AvatarExtraPart]?: (typeof AVATAR_EXTRA_PARTS)[P][number] } & { [P in CustomPartKey]?: never };
+/** The recipe key that embeds the Custom Part worn in each slot. */
+declare const CUSTOM_PART_KEYS: {
+  readonly headpiece: "headpiece";
+  readonly bangs: "bangsPart";
+  readonly leftSideHair: "leftSideHairPart";
+  readonly rightSideHair: "rightSideHairPart";
+  readonly backHair: "backHairPart";
+  readonly outfit: "outfitPart";
+  readonly accessory: "accessoryPart";
+  readonly beard: "beardPart";
+  readonly glasses: "glassesPart";
+  readonly nose: "nosePart";
+  readonly cheeks: "cheeksPart";
+  readonly petals: "petalsPart";
+  readonly flowerBase: "flowerBasePart";
 };
-/** Asset version 3: version 2 with an embedded Custom Part in the headpiece slot. */
-type PixelAvatarRecipeV3 = Omit<PixelAvatarRecipeV2, 'assetVersion' | 'headpiece'> & {
+type CustomPartKey = (typeof CUSTOM_PART_KEYS)[PartSlot];
+/**
+ * Asset version 3: version 2 wearing at least one embedded Custom Part. A drawn hair piece
+ * replaces the built-in piece, which stays saved and returns when the part is taken off.
+ */
+type PixelAvatarRecipeV3 = Omit<PixelAvatarRecipeV2, 'assetVersion' | CustomPartKey> & {
   assetVersion: 3;
-  headpiece: PixelCustomPart;
-};
+} & { [P in CustomPartKey]?: PixelCustomPart };
 type PixelAvatarRecipe = PixelAvatarRecipeV1 | PixelAvatarRecipeV2 | PixelAvatarRecipeV3;
 declare const DEFAULT_RECIPE: PixelAvatarRecipeV1;
 declare function isPixelAvatarRecipe(value: unknown): value is PixelAvatarRecipe;
@@ -112,10 +127,14 @@ declare function withSpecies(recipe: PixelAvatarRecipeV3, species: AvatarSpecies
 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.
+ * 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.
  */
+declare function withCustomPart(recipe: PixelAvatarRecipe, slot: PartSlot, part: PixelCustomPart | undefined): PixelAvatarRecipeV2 | PixelAvatarRecipeV3;
+/** `withCustomPart` for the headpiece slot. */
 declare function withHeadpiece(recipe: PixelAvatarRecipe, part: PixelCustomPart | undefined): PixelAvatarRecipeV2 | PixelAvatarRecipeV3;
+/** The Custom Part worn in a slot, if any. */
+declare function wornPart(recipe: PixelAvatarRecipe, slot: PartSlot): PixelCustomPart | undefined;
 declare function detailedRecipe(recipe: PixelAvatarRecipe): PixelAvatarRecipe;
 declare const AVATAR_SWATCHES: Record<AvatarColor, readonly string[]>;
 /**
@@ -141,16 +160,79 @@ declare const AVATAR_PRESETS: readonly PixelAvatarRecipe[];
 //#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.
+ * drawn behind the hair and its front layer over it. Hair slots replace one built-in hair piece
+ * and use only the front layer. 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;
   };
+  readonly bangs: {
+    readonly width: 32;
+    readonly height: 32;
+  };
+  readonly leftSideHair: {
+    readonly width: 32;
+    readonly height: 32;
+  };
+  readonly rightSideHair: {
+    readonly width: 32;
+    readonly height: 32;
+  };
+  readonly backHair: {
+    readonly width: 32;
+    readonly height: 32;
+  };
+  readonly outfit: {
+    readonly width: 32;
+    readonly height: 32;
+  };
+  readonly accessory: {
+    readonly width: 32;
+    readonly height: 32;
+  };
+  readonly beard: {
+    readonly width: 32;
+    readonly height: 32;
+  };
+  readonly glasses: {
+    readonly width: 32;
+    readonly height: 32;
+  };
+  readonly nose: {
+    readonly width: 32;
+    readonly height: 32;
+  };
+  readonly cheeks: {
+    readonly width: 32;
+    readonly height: 32;
+  };
+  readonly petals: {
+    readonly width: 32;
+    readonly height: 32;
+  };
+  readonly flowerBase: {
+    readonly width: 32;
+    readonly height: 32;
+  };
 };
 type PartSlot = keyof typeof PART_SLOTS;
+/**
+ * Hair slots. In a hair part, a `hairColor` cell at tone 0 is live hair: it is shaded with the
+ * rest of the hair, exactly like a built-in piece. Every other cell shows its own color.
+ */
+declare const HAIR_PART_SLOTS: readonly ["bangs", "leftSideHair", "rightSideHair", "backHair"];
+type HairPartSlot = (typeof HAIR_PART_SLOTS)[number];
+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"];
+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. */
 declare const PART_TONES: readonly [-2, -1, 0, 1, 2];
 type PartTone = (typeof PART_TONES)[number];
@@ -161,7 +243,7 @@ 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;
+declare const MAX_PART_FIXED_COLORS = 32;
 /**
  * A Human-drawn Custom Part. Its content is immutable and its identity is `customPartId`;
  * name, author, origin and parent are metadata kept outside it.
@@ -215,6 +297,28 @@ declare function pixelFigure(recipe: Recipe, yawDeg: number, options?: PixelFigu
   head: string;
   cells: PixelCell$1[];
 };
+/**
+ * The hair piece in `slot` as a Custom Part to start drawing from: the drawn part worn there,
+ * or the built-in piece flattened for this recipe in the front pose as live `hairColor` cells.
+ * A flattened piece keeps this shape and no longer follows face shape or hair length.
+ */
+declare function hairPieceStart(recipe: PixelAvatarRecipe, slot: HairPartSlot): {
+  slot: HairPartSlot;
+  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
+ * color slot and tone when it is exactly one, so it recolors with the Avatar, and a fixed color
+ * otherwise; an unchanged copy renders identically. A flattened helmet or hood no longer hides
+ * the hair: only the built-in ones do.
+ */
+declare function replacePartStart(recipe: PixelAvatarRecipe, slot: ReplacePartSlot): {
+  slot: ReplacePartSlot;
+  front: PartCell[];
+  back: PartCell[];
+};
 //#endregion
 //#region src/random.d.ts
 declare function seededRandom(seed: string): () => number;
@@ -264,5 +368,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, 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 };
+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, emptyPartLayer, faceCells, fillPartLayer, hairPieceStart, hiddenChoices, isHairPartSlot, isPixelAvatarRecipe, isPixelCustomPart, isReplacePartSlot, mirrorPartX, paintPartLayer, partCells, partLayer, partToneColor, pixelAvatarSvg, pixelFigure, pixelSymbolCells, pixelTileColor, replacePartStart, seededRandom, seededRecipe, seededRecipeV2, symbolArtCells, withCustomPart, withHeadpiece, withSpecies, wornPart };
 //# sourceMappingURL=index.d.ts.map