@clawhash/core

Style-agnostic engine for deterministic avatar generation. Part of the clawhash monorepo.

Same seed, same avatar. Always. No storage, no API calls, pure math.

Install

npm install @clawhash/core

Usage

import { createAvatar } from '@clawhash/core';
import { crustacean }   from '@clawhash/crustacean';

const avatar = createAvatar(crustacean, { seed: 'hal-9000', size: 128 });

avatar.toString();   // raw SVG string
avatar.toDataUri();  // base64 data URI for <img src>
avatar.meta;         // { palette, body, claw, eye, marking, accessory, seed, size }

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | seed | string | 'default' | Any string. Same seed = same avatar. | | size | number | 200 | Width/height in px. Clamped to [16, 512]. | | badge | boolean | true | Show the style badge. | | backgroundColor | string | (from palette) | Override the background fill colour. |

API

createAvatar(style, options?)

Creates a deterministic avatar from a style pack and options. Returns an AvatarResult with toString(), toDataUri(), and meta.

toSeed(str)

Converts any string to a stable 32-bit unsigned integer using djb2.

makeRng(seed)

Returns a seeded PRNG (mulberry32). Same seed always produces the same sequence.

pick(rng, arr)

Picks a random item from an array using the PRNG.

Writing a custom style

Implement the StyleDefinition interface:

export const myStyle = {
  meta: { title: 'My Style', version: '1.0.0', combinations: 3125 },
  generate(rng, opts) {
    const svg = `<svg ...>...</svg>`;
    return { svg, meta: { variant: 'my-variant' } };
  },
};

License

MIT