@tomtev/touchgrass-avatar

@touchgrass/avatar

Pixel-art avatar system for touchgrass.sh. Each avatar is encoded as a 7-character hex DNA string (~32M combinations) that deterministically renders a unique character with hat, eyes, mouth, body, legs, and two independent color hues.

Install

npm install @touchgrass/avatar
# or
bun add @touchgrass/avatar

Usage

Core (framework-agnostic)

import {
  generateRandomDNA,
  decodeDNA,
  encodeDNA,
  generateGrid,
  traitsFromName,
  renderSVG,
  renderTerminal,
  renderTerminalSmall,
  hslToRgb,
  SLOTS,
  EYES, MOUTHS, HATS, BODIES, LEGS,
} from '@touchgrass/avatar';

Generate a random avatar

const dna = generateRandomDNA(); // e.g. "0a3f201"

Decode / encode DNA

const traits = decodeDNA('0a3f201');
// { eyes: 0, mouth: 2, hat: 5, body: 1, legs: 3, faceHue: 8, hatHue: 2 }

const dna = encodeDNA(traits); // "0a3f201"

Derive avatar from a name (no DNA needed)

const traits = traitsFromName('my-agent');
// Deterministic — same name always produces same traits

Render to SVG string

const svg = renderSVG('0a3f201');           // default 10px per pixel
const svg = renderSVG('0a3f201', 20);       // 20px per pixel
const svg = renderSVG('0a3f201', 10, 1);    // walking frame 1

Returns a complete <svg> string with transparent background. Use it as innerHTML, write to a .svg file, or embed in an <img> via data URI.

Render to terminal (ANSI)

const ansi = renderTerminal('0a3f201');      // full size (██ per pixel)
const ansi = renderTerminalSmall('0a3f201'); // compact (half-block ▀▄)

console.log(ansi);

Generate the pixel grid directly

const grid = generateGrid(traits, walkFrame, talkFrame, waveFrame);
// Pixel[][] — 9 columns wide, variable rows tall

Svelte

<script>
  import { Avatar } from '@touchgrass/avatar/svelte';
</script>

<!-- From DNA string -->
<Avatar dna="0a3f201" />

<!-- From name (deterministic hash) -->
<Avatar name="my-agent" />

<!-- Sizes: sm (3px), lg (8px, default), xl (14px) -->
<Avatar dna="0a3f201" size="xl" />

<!-- Animations -->
<Avatar dna="0a3f201" walking />
<Avatar dna="0a3f201" talking />
<Avatar dna="0a3f201" waving />

Props:

Prop	Type	Default	Description
dna	string	—	7-char hex DNA string
name	string	—	Fallback: derive traits from name hash
size	'sm' | 'lg' | 'xl'	'lg'	Pixel size (3/8/14px per cell)
walking	boolean	false	Animate legs
talking	boolean	false	Animate mouth
waving	boolean	false	Animate arms

Either dna or name should be provided. If both are set, dna takes priority.

DNA Encoding

7 traits packed into a single integer using mixed-radix encoding with fixed slot sizes for forward compatibility:

Trait	Variants	Slot size	Description
eyes	11	12	normal, wide, close, big, squint, narrow, etc.
mouths	7	12	smile, smirk, narrow, wide variants
hats	24	24	none, tophat, beanie, crown, cap, horns, mohawk, etc.
bodies	6	8	normal, narrow, tapered (each with/without arms)
legs	6	8	biped, quad, tentacles, thin, wide stance
faceHue	12	12	0-330 degrees in 30-degree steps
hatHue	12	12	independent from face hue

Total slot space: 12 x 12 x 24 x 8 x 8 x 12 x 12 = 31,850,496 (~32M, 7 hex chars).

New variants can be added within slot limits without breaking existing DNA strings. Legacy 6-char DNAs decode identically (leading zero is implicit).

Pixel Grid

The avatar is a 9-column grid with variable height (depends on hat). Each cell is a Pixel type:

Pixel	Meaning	Rendering
f	Face/body	Solid face color
e	Eye	Solid dark color
s	Squint eye	Face bg + dark bottom half
n	Narrow eye	Face bg + dark center strip
m	Mouth	Face bg + dark top half
q	Smile corner left	Face bg + dark bottom-right quarter
r	Smile corner right	Face bg + dark bottom-left quarter
d	Dark accent	Solid dark (hat bands, etc.)
h	Hat	Solid hat color
l	Thin leg	Half-width face color
k	Thin hat detail	Half-width hat color
a	Arm	Half-height face color
_	Transparent	Empty

Colors

Each avatar has 3 colors derived from two hue indices (0-11, mapped to 0-330 degrees):

• Face color: hsl(faceHue * 30, 50%, 50%)
• Dark color: hsl(faceHue * 30, 50%, 28%) — eyes, mouth
• Hat color: hsl(hatHue * 30, 50%, 50%)

Animations

The grid generator supports three animation types via frame parameters:

• Walking (frame): Cycles through leg variant frames
• Talking (talkFrame): 0 = normal mouth, 1+ = open mouth animation
• Waving (waveFrame): 0 = normal body, 1+ = alternating arm positions

Exports

@touchgrass/avatar          — Core TypeScript (DNA, grid, SVG, terminal, colors)
@touchgrass/avatar/svelte   — Svelte 5 component (Avatar)

License

MIT