piixpal

<script src="https://cdn.jsdelivr.net/npm/piixpal@0.4/piixpal.min.js"></script>

<h1>
  Hello world
  <piix-pal pal="bitbug"></piix-pal>
</h1>

That's it. The bug finds the outline of your letters and starts walking.

Install: pick whatever suits your site

No download, no build step, no account.

data-pals format: name@css-selector, comma separated, optional ?attr=value (e.g. moss@p?at=.9). The docs site has a Builder that writes this line for you, and a bookmarklet that drops pals onto any website you're looking at. TypeScript types live in types/piixpal.d.ts. The npm package is prepared (package.json exports for the core, single components and wrappers) but not published yet.

The pals

Every pal is an original character with a job: something it lives on, something that scares it, something that happens when you poke it.

More characters:

Toy box (do="toss")

ball duck dice pebble cube can: grab and throw them. They land on real elements (headings, paragraphs, buttons, cards), roll off edges onto whatever is below, and can be batted with a fast cursor swipe. Dice land on a random face; the pebble thuds so loudly other pals react. land="css" sets what counts as a surface.

Groups: one tag, a whole crew

New ways to play

Pals that react to what people actually do on your site:

Plus Hiss (a snake, crawl), Pinch (a crab that walks sideways, crawl), Shibe (a shiba, lounge) and Capy (a capybara with a yuzu on its head, mind).

Pals notice each other, too. A hard landing from Boing makes Moss grumble, Lurk duck, Pip take off and Bitbug run. Two Bitbugs that meet share a little heart and turn around.

Superpowers

Pals that step out of the page, do real interface jobs, or turn your site into a game. One tag each.

Beyond the page

Pals with jobs

Play your site

Any pal can be kept inside one element with box="selector".

Sprites

Sprites are simpler: they sit inline like an image, wherever you paste them.

<piix-sprite name="mochi"></piix-sprite>
<piix-sprite name="gloop" size="200" color="#6b4cff"></piix-sprite>

Their eyes follow the cursor, they blink, breathe a pixel, hop when clicked and nap when ignored.

• 30 small sprites: mochi, toast, robo, cloud, ufo, egg, loaf, onigiri, cactus, planet, candle, pudding, coffee, boba, cookie, cherries, donut, avocado, sushi, star, prompty, floppy, inbox, modem, heart, token, alien, wizard, dragon, battery
• 19 big 3D sprites (recolourable with color): gloop, hops, tofu, inky, mumu, spud, fluff, flick, whale, bolt, gpu, server, brain, crt, keycap, llama, elephant, astronaut, unicorn

Every sprite can render three ways with render:

Other attributes: size, scale, depth (voxel extrusion), color, eye, hue, look="mouse|wander|none", shy, tilt (no-shy / no-tilt on big ones), still, sleep-after.

Browse and customise them all on the components pages (components/sprites.html).

Crowd

<piix-crowd mode="form" text="HELLO" count="200"></piix-crowd>

A stage of tiny agents, hundreds of them on one canvas, depth-sorted on a 2.5D floor. crowd: they wander, wave and high-five. swarm: they flock after the cursor. form: they spell text. Click the floor to drop one in; grab one and throw it. scatter() knocks everyone flying.

Usage

Put a pal inside the element it should live on:

<footer>
  …
  <piix-pal pal="boing"></piix-pal>
</footer>

or point at it from anywhere with on:

<piix-pal pal="pip" on=".btn"></piix-pal>   <!-- every .btn is a perch -->

Attributes

All optional.

Events and methods

const pal = document.querySelector('piix-pal');
pal.addEventListener('piix:ready', e => console.log(e.detail.pal));
pal.addEventListener('piix:poke', () => console.log('ow'));
pal.poke();          // poke it from code

Pals sit on one overlay layer above your page. If you have a sticky header, tuck them under it:

:root { --piix-z: 40; }   /* lower than your header's z-index */

<piix-type>: pixel lettering pals can walk on

<piix-type text="piixpal" rows="22" cell="14" shade="#c6f432" fit></piix-type>
<piix-pal pal="bitbug" on="piix-type"></piix-pal>

Any font, rasterised into chunky blocks with an extruded shadow. Pixels rain in on load, lift off their shadow around the cursor, and ripple when clicked or when a pal lands on them.

Draw your own pal

Sprites are plain strings. Each character is a palette key and . is transparent.

Piixpal.sprite('blip', {
  w: 6, h: 4, scale: 4,
  does: 'crawl',
  palette: { k: '#17121f', g: '#c6f432' },
  frames: {
    walk: [['.kkkk.', 'kgkgkk', 'kggggk', '.k..k.'],
           ['.kkkk.', 'kgkgkk', 'kggggk', 'k..k..']]
  },
  fps: { walk: 8 }
});

<piix-pal pal="blip"></piix-pal>

Behaviours ask for clips by name (walk, idle, hop…) and skip the ones a pal doesn't have, so any pal can borrow any behaviour. Piixpal.art has helpers (compose, put, flipV, flipH, shift, swap, trim) for building frames from parts instead of copy-pasting grids.

Good manners

• Never blocks clicks. Pals only catch pointer events on their own pixels.
• Respects prefers-reduced-motion. Pals sit still and stay put.
• Decorative. The overlay is aria-hidden; <piix-type> keeps a real aria-label.
• Cheap. One shared requestAnimationFrame loop; pals far off-screen skip their updates.
• Framework-agnostic. Standard custom elements: plain HTML, React, Vue, Svelte, Astro, Webflow and Framer embeds.

Develop

npm run dev     # http://localhost:5173, rebuilds piixpal.js on every request
npm run build   # concatenates src/ into piixpal.js (+ piixpal.min.js)
npm run docs    # regenerates components/*.html

• src/core.js: loop, pointer, overlay layer, sprite baker, Actor
• src/pals/*.js: the characters (art + clips)
• src/behaviors/*.js: what they do
• src/elements/type.js: <piix-type>
• src/elements/sprite.js: <piix-sprite> (pixel, dots and voxel renderers)
• src/sprites/*.js: the sprites (big-* are the big 3D ones)
• src/boot.js: <piix-pal>
• lab/: sprite lab and a playground page

Originals only

Every character here is drawn from scratch. Themes nod to tech, AI and internet culture (a GPU, a server rack, a chat bubble that is always thinking, a startup unicorn, a captcha robot), but none copy a company's logo or mascot or any copyrighted character, so they're safe to use anywhere.

License

MIT. Use it anywhere. A star on GitHub is plenty.