API reference

avatar

Import

import * as api from "@fungi.computer/sprite/avatar";

Exports

Kind	Export	Description
type alias	AvatarCharacter	One character in the closed v1 avatar catalog.
type alias	AgentColors	Whether an Agent created from a member’s avatar wears a shifted identity.
type alias	Avatar	A parsed, envelope-valid Avatar v1 descriptor.
type alias	AvatarCatalogEntry	Pure per-character facts a catalog owner (e.g. `sprite-zdog`) supplies.
type alias	AvatarCatalog	Pure character facts for every avatar character, owned by its renderer.
type alias	Hsl	A hexadecimal colour decomposed into hue (degrees), saturation, lightness.
type alias	AgentAppearance	The mushroom’s two identity controls for one seed: its cap and cap spots take a hue from the seed, so an Agent wears the same cap in every list it appears in. Kept byte-identical to the Sprite seen before avatars existed.
constant	avatarCharacters	The closed v1 catalog of avatar characters. Adding a character is a new major version; this list is not meant to grow silently.
constant	agentColorsSchema	A saved `agentColors` preference: shift an Agent’s identity, or copy it.
constant	avatarEnvelopeSchema	The Avatar v1 envelope: a closed character, up to 16 appearance values, a resting expression, and a render style. It is a complete snapshot, not a reference into character data, so it survives a later change to the catalog. This checks shape only; it does not know a character’s real controls or expressions, so a bound catalog cannot validate against it by name alone. `createAvatarSchema`/`parseAvatar` build the catalog-refined schema a caller should actually parse untrusted data with; `sprite-zdog`’s `avatarSchema` is that schema, bound to the built-in catalog.
constant	AGENT_HUE_MIN_SHIFT	Lower bound (degrees) every colour-shift step must clear, each direction.
function	createAvatarSchema()	Build the full avatar schema for a catalog: the envelope above, refined so every appearance key is one of the character’s controls, every value is typed by that control, and the expression is one the character declares.
function	parseAvatar()	Parse an unknown value into a catalog-valid Avatar v1 descriptor.
function	hexFromHsl()	Encode HSL (hue in degrees, saturation/lightness in percent) as `#rrggbb`.
function	hslFromHex()	Decode a `#rrggbb` colour into HSL (hue in degrees, saturation/lightness in percent).
function	hueDistance()	Shortest angular distance between two hues in degrees, 0 to 180.
function	seedHash()	A deterministic FNV-1a hash: the same seed always lands on the same value. A copy of `@fungi.computer/caps`’s `seedHash` so this package stays free of a React-package dependency; both must keep computing the same value.
function	agentHueStep()	The hue-rotation step for `seed`, chosen against `hex`’s own realised result, not the idealised `hue + step` arithmetic: `shiftHue` rounds to a `#rrggbb` colour, and re-decoding that colour can land a few tenths of a degree short of an exact-degree step, which the 40-degree guarantee must still hold against. A step is only a candidate when rotating `hex` by it and reading the result’s hue back out clears 40 degrees from `hex`‘s own hue. When `avoid` carries other agents’ identity hues, the candidate farthest from all of them (by minimum distance, scored on the same realised hue) is preferred; ties keep whichever candidate is nearest the seed’s own deterministic default step, so an unconflicted seed keeps its usual look.
function	shiftHue()	Rotate one hex colour’s hue by `step` degrees, keeping its saturation and lightness.
function	agentAppearance()	The seeded mushroom identity colours for `seed`.
function	seededAvatar()	The avatar an Agent wears until its owner chooses one: the mushroom, in the cap colour seeded from the Agent’s id, at rest, undecorated. It is a pure function of identity, so hosts compute it instead of storing it.
function	deriveAgentAvatar()	Derive an Agent’s avatar from its creator’s, for a catalog’s character. `"keep"` hands back the member’s look unchanged (their Agent is a visible copy, told apart only by name). `"shift"` resolves the member’s full appearance against the catalog and rotates only the character’s identity slots by one shared hue step, so accessories, face and drawing style carry over untouched. `avoid` lists hues already worn by the creator’s other Agents so a new one does not land beside them. An achromatic primary identity colour has no hue to rotate, so its resolved appearance is kept.

AvatarCharactertype alias

type AvatarCharacter = (typeof avatarCharacters)[number];

One character in the closed v1 avatar catalog.

AgentColorstype alias

type AgentColors = z.infer<typeof agentColorsSchema>;

Whether an Agent created from a member’s avatar wears a shifted identity.

Avatartype alias

type Avatar = z.infer<typeof avatarEnvelopeSchema>;

A parsed, envelope-valid Avatar v1 descriptor.

AvatarCatalogEntrytype alias

type AvatarCatalogEntry = object;

Pure per-character facts a catalog owner (e.g. sprite-zdog) supplies.

Properties

controls

readonly controls: Readonly<Record<string, Control>>;

Every control the character’s document declares.

expressions

readonly expressions: readonly string[];

Every expression name the character’s document declares.

identitySlots

readonly identitySlots: readonly string[];

Controls that carry the character’s identity colour, in priority order.

AvatarCatalogtype alias

type AvatarCatalog = Readonly<Record<AvatarCharacter, AvatarCatalogEntry>>;

Pure character facts for every avatar character, owned by its renderer.

Hsltype alias

type Hsl = object;

A hexadecimal colour decomposed into hue (degrees), saturation, lightness.

Properties

h

readonly h: number;

s

readonly s: number;

l

readonly l: number;

AgentAppearancetype alias

type AgentAppearance = Readonly<{
  cap: string;
  capSpot: string;
}>;

The mushroom’s two identity controls for one seed: its cap and cap spots take a hue from the seed, so an Agent wears the same cap in every list it appears in. Kept byte-identical to the Sprite seen before avatars existed.

avatarCharactersconstant

const avatarCharacters: readonly ["mushroom", "cat", "burger"];

The closed v1 catalog of avatar characters. Adding a character is a new major version; this list is not meant to grow silently.

agentColorsSchemaconstant

const agentColorsSchema: ZodEnum<{
  shift: "shift";
  keep: "keep";
}>;

A saved agentColors preference: shift an Agent’s identity, or copy it.

avatarEnvelopeSchemaconstant

const avatarEnvelopeSchema: ZodObject<
  {
    v: ZodLiteral<1>;
    character: ZodEnum<{
      mushroom: "mushroom";
      cat: "cat";
      burger: "burger";
    }>;
    appearance: ZodRecord<
      ZodString,
      ZodUnion<readonly [ZodString, ZodNumber, ZodBoolean]>
    >;
    expression: ZodString;
    renderStyle: ZodEnum<{
      plain: "plain";
      pencil: "pencil";
      manga: "manga";
      riso: "riso";
      halftone: "halftone";
      blueprint: "blueprint";
      crt: "crt";
      watercolor: "watercolor";
    }>;
  },
  $strict
>;

The Avatar v1 envelope: a closed character, up to 16 appearance values, a resting expression, and a render style. It is a complete snapshot, not a reference into character data, so it survives a later change to the catalog. This checks shape only; it does not know a character’s real controls or expressions, so a bound catalog cannot validate against it by name alone. createAvatarSchema/parseAvatar build the catalog-refined schema a caller should actually parse untrusted data with; sprite-zdog’s avatarSchema is that schema, bound to the built-in catalog.

AGENT_HUE_MIN_SHIFTconstant

const AGENT_HUE_MIN_SHIFT: 40 = 40;

Lower bound (degrees) every colour-shift step must clear, each direction.

createAvatarSchema()function

function createAvatarSchema(catalog): ZodObject<
  {
    v: ZodLiteral<1>;
    character: ZodEnum<{
      mushroom: "mushroom";
      cat: "cat";
      burger: "burger";
    }>;
    appearance: ZodRecord<
      ZodString,
      ZodUnion<readonly [ZodString, ZodNumber, ZodBoolean]>
    >;
    expression: ZodString;
    renderStyle: ZodEnum<{
      plain: "plain";
      pencil: "pencil";
      manga: "manga";
      riso: "riso";
      halftone: "halftone";
      blueprint: "blueprint";
      crt: "crt";
      watercolor: "watercolor";
    }>;
  },
  $strict
>;

Build the full avatar schema for a catalog: the envelope above, refined so every appearance key is one of the character’s controls, every value is typed by that control, and the expression is one the character declares.

Parameters

Parameter	Type
`catalog`	`AvatarCatalog`

Returns

ZodObject<{ v: ZodLiteral<1>; character: ZodEnum<{ mushroom: "mushroom"; cat: "cat"; burger: "burger"; }>; appearance: ZodRecord<ZodString, ZodUnion<readonly [ZodString, ZodNumber, ZodBoolean]>>; expression: ZodString; renderStyle: ZodEnum<{ plain: "plain"; pencil: "pencil"; manga: "manga"; riso: "riso"; halftone: "halftone"; blueprint: "blueprint"; crt: "crt"; watercolor: "watercolor"; }>; }, $strict>

parseAvatar()function

function parseAvatar(data, catalog): object;

Parse an unknown value into a catalog-valid Avatar v1 descriptor.

Parameters

Parameter	Type
`data`	`unknown`
`catalog`	`AvatarCatalog`

Returns

object

Name	Type	Default value
`v`	`1`	-
`character`	`"mushroom" \| "cat" \| "burger"`	-
`appearance`	`Record<string, string \| number \| boolean>`	-
`expression`	`string`	-
`renderStyle`	`\| "plain" \| "pencil" \| "manga" \| "riso" \| "halftone" \| "blueprint" \| "crt" \| "watercolor"`	`renderStyleSchema`

hexFromHsl()function

function hexFromHsl(hue, saturation, lightness): string;

Encode HSL (hue in degrees, saturation/lightness in percent) as #rrggbb.

Parameters

Parameter	Type
`hue`	`number`
`saturation`	`number`
`lightness`	`number`

Returns

string

hslFromHex()function

function hslFromHex(hex): Hsl;

Decode a #rrggbb colour into HSL (hue in degrees, saturation/lightness in percent).

Parameters

Parameter	Type
`hex`	`unknown`

Returns

Hsl

hueDistance()function

function hueDistance(a, b): number;

Shortest angular distance between two hues in degrees, 0 to 180.

Parameters

Parameter	Type
`a`	`number`
`b`	`number`

Returns

number

seedHash()function

function seedHash(seed): number;

A deterministic FNV-1a hash: the same seed always lands on the same value. A copy of @fungi.computer/caps’s seedHash so this package stays free of a React-package dependency; both must keep computing the same value.

Parameters

Parameter	Type
`seed`	`string`

Returns

number

agentHueStep()function

function agentHueStep(hex, seed, avoid?): number;

The hue-rotation step for seed, chosen against hex’s own realised result, not the idealised hue + step arithmetic: shiftHue rounds to a #rrggbb colour, and re-decoding that colour can land a few tenths of a degree short of an exact-degree step, which the 40-degree guarantee must still hold against. A step is only a candidate when rotating hex by it and reading the result’s hue back out clears 40 degrees from hex‘s own hue. When avoid carries other agents’ identity hues, the candidate farthest from all of them (by minimum distance, scored on the same realised hue) is preferred; ties keep whichever candidate is nearest the seed’s own deterministic default step, so an unconflicted seed keeps its usual look.

Parameters

Parameter	Type	Default value
`hex`	`string`	`undefined`
`seed`	`string`	`undefined`
`avoid`	`readonly number[]`	`[]`

Returns

number

shiftHue()function

function shiftHue(hex, step): string;

Rotate one hex colour’s hue by step degrees, keeping its saturation and lightness.

Parameters

Parameter	Type
`hex`	`string`
`step`	`number`

Returns

string

agentAppearance()function

function agentAppearance(seed): AgentAppearance;

The seeded mushroom identity colours for seed.

Parameters

Parameter	Type
`seed`	`string`

Returns

AgentAppearance

seededAvatar()function

function seededAvatar(seed): object;

The avatar an Agent wears until its owner chooses one: the mushroom, in the cap colour seeded from the Agent’s id, at rest, undecorated. It is a pure function of identity, so hosts compute it instead of storing it.

Parameters

Parameter	Type
`seed`	`string`

Returns

object

Name	Type	Default value
`v`	`1`	-
`character`	`"mushroom" \| "cat" \| "burger"`	-
`appearance`	`Record<string, string \| number \| boolean>`	-
`expression`	`string`	-
`renderStyle`	`\| "plain" \| "pencil" \| "manga" \| "riso" \| "halftone" \| "blueprint" \| "crt" \| "watercolor"`	`renderStyleSchema`

deriveAgentAvatar()function

function deriveAgentAvatar(member, agentColors, seed, catalog, avoid?): object;

Derive an Agent’s avatar from its creator’s, for a catalog’s character. "keep" hands back the member’s look unchanged (their Agent is a visible copy, told apart only by name). "shift" resolves the member’s full appearance against the catalog and rotates only the character’s identity slots by one shared hue step, so accessories, face and drawing style carry over untouched. avoid lists hues already worn by the creator’s other Agents so a new one does not land beside them. An achromatic primary identity colour has no hue to rotate, so its resolved appearance is kept.

Parameters

Parameter	Type	Default value
`member`	`{ v: 1; character: "mushroom" \| "cat" \| "burger"; appearance: Record<string, string \| number \| boolean>; expression: string; renderStyle: \| "plain" \| "pencil" \| "manga" \| "riso" \| "halftone" \| "blueprint" \| "crt" \| "watercolor"; }`	`undefined`
`member.v`	`1`	`...`
`member.character`	`"mushroom" \| "cat" \| "burger"`	`...`
`member.appearance`	`Record<string, string \| number \| boolean>`	`...`
`member.expression`	`string`	`...`
`member.renderStyle`	`\| "plain" \| "pencil" \| "manga" \| "riso" \| "halftone" \| "blueprint" \| "crt" \| "watercolor"`	`renderStyleSchema`
`agentColors`	`"shift" \| "keep"`	`undefined`
`seed`	`string`	`undefined`
`catalog`	`AvatarCatalog`	`undefined`
`avoid`	`readonly number[]`	`[]`

Returns

object

Name	Type	Default value
`v`	`1`	-
`character`	`"mushroom" \| "cat" \| "burger"`	-
`appearance`	`Record<string, string \| number \| boolean>`	-
`expression`	`string`	-
`renderStyle`	`\| "plain" \| "pencil" \| "manga" \| "riso" \| "halftone" \| "blueprint" \| "crt" \| "watercolor"`	`renderStyleSchema`

avatar

Import

Exports

AvatarCharacterTtype alias

AgentColorsTtype alias

AvatarTtype alias

AvatarCatalogEntryTtype alias

Properties

controls

expressions

identitySlots

AvatarCatalogTtype alias

HslTtype alias

Properties

h

s

l

AgentAppearanceTtype alias

avatarCharactersconstconstant

agentColorsSchemaconstconstant

avatarEnvelopeSchemaconstconstant

AGENT_HUE_MIN_SHIFTconstconstant

createAvatarSchema()fnfunction

Parameters

Returns

parseAvatar()fnfunction

Parameters

Returns

hexFromHsl()fnfunction

Parameters

Returns

hslFromHex()fnfunction

Parameters

Returns

hueDistance()fnfunction

Parameters

Returns

seedHash()fnfunction

Parameters

Returns

agentHueStep()fnfunction

Parameters

Returns

shiftHue()fnfunction

Parameters

Returns

agentAppearance()fnfunction

Parameters

Returns

seededAvatar()fnfunction

Parameters

Returns

deriveAgentAvatar()fnfunction

Parameters

Returns

AvatarCharactertype alias

AgentColorstype alias

Avatartype alias

AvatarCatalogEntrytype alias

AvatarCatalogtype alias

Hsltype alias

AgentAppearancetype alias

avatarCharactersconstant

agentColorsSchemaconstant

avatarEnvelopeSchemaconstant

AGENT_HUE_MIN_SHIFTconstant

createAvatarSchema()function

parseAvatar()function

hexFromHsl()function

hslFromHex()function

hueDistance()function

seedHash()function

agentHueStep()function

shiftHue()function

agentAppearance()function

seededAvatar()function

deriveAgentAvatar()function