@botharness/pixel-avatar 0.4.0 → 0.6.0

package/README.md

@@ -20,5 +20,8 @@ const svg = pixelAvatarSvg(recipe); // 32×32 viewBox, crisp edges, no ids or sc
 - `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.
+- `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,7 +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 };
+} & { [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.
@@ -82,8 +82,24 @@ 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] };
-type PixelAvatarRecipe = PixelAvatarRecipeV1 | PixelAvatarRecipeV2;
+} & { [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";
+};
+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;
+} & { [P in CustomPartKey]?: 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;
@@ -99,7 +115,18 @@ 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: 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 `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[]>;
 /**
@@ -122,6 +149,89 @@ declare const seededRecipe: (seed: string) => PixelAvatarRecipe;
 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. 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];
+/** 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[][];
@@ -130,6 +240,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): {
@@ -138,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;
@@ -187,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, PIXEL_SYMBOLS, type PixelAvatarRecipe, type PixelAvatarRecipeV1, type PixelAvatarRecipeV2, type PixelAvatarSvgOptions, type PixelCell, type PixelFigureOptions, type PixelGrid, type PixelMouthState, type PixelSymbol, canonicalRecipe, createSeededRecipe, createSeededRecipeV2, detailedRecipe, faceCells, hiddenChoices, isPixelAvatarRecipe, pixelAvatarSvg, pixelFigure, pixelSymbolCells, pixelTileColor, seededRandom, seededRecipe, seededRecipeV2, 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, 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