@botharness/pixel-avatar 0.5.0 → 0.6.0

package/README.md

@@ -21,6 +21,7 @@ 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.
 - `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,23 @@ 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";
 };
-/** 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 +119,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 +152,40 @@ 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;
+  };
 };
 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;
 /** 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];
@@ -215,6 +250,16 @@ 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[];
+};
 //#endregion
 //#region src/random.d.ts
 declare function seededRandom(seed: string): () => number;
@@ -264,5 +309,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, canonicalCustomPart, canonicalRecipe, createCustomPart, createSeededRecipe, createSeededRecipeV2, customPartId, detailedRecipe, emptyPartLayer, faceCells, fillPartLayer, hairPieceStart, hiddenChoices, isHairPartSlot, isPixelAvatarRecipe, isPixelCustomPart, mirrorPartX, paintPartLayer, partCells, partLayer, partToneColor, pixelAvatarSvg, pixelFigure, pixelSymbolCells, pixelTileColor, seededRandom, seededRecipe, seededRecipeV2, symbolArtCells, withCustomPart, withHeadpiece, withSpecies, wornPart };
 //# sourceMappingURL=index.d.ts.map