mascot.js

Docs

Everything the mascots' script does, and how to make it do more.

On a page

<script src="https://domainmascots.com/mascot.js" data-site="YOUR_KEY" defer></script>

Its settings come from your dashboard, so you change your mascot there, not in your pages. The key works on your domain, its subdomains and localhost.

Without an account, give it settings of its own; nothing is fetched then:

<script src="https://domainmascots.com/mascot.js" data-config='{"character": "hoot", "outfit": {"eyes": "round"}, "categories": ["everyday", "law"], "gestures": ["read", "wave", "gavel", "scales"], "messages": ["Need advice? Call us."]}' defer></script>

Or set window.MascotConfig = {...} before the script. data-config and MascotConfig go over the dashboard's settings when there is a key too.

Settings

character default "quill"
Which mascot: quill, mochi, fizz, hoot, bramble, nibbles, bolt or sprout, or one of your own ("c-...", with characters).
outfit default { hat: "", eyes: "", neck: "" }
What it wears: see Dressing up.
tint default ""
Its own colour (fur, feathers, what it wears), "#rrggbb"; "" for the mascot's.
name default the mascot's
What it calls itself; {name} in its lines.
ink, paper default "auto"
Its two colours, "#rrggbb", or "auto": the page's text and background.
size default "medium"
small, medium or large (56, 74 or 96 pixels wide; a little smaller on phones).
mode default "wander"
wander: on the page's blocks, coming along as it scrolls. dock: in a corner of the window.
corner default "right"
Its corner when docked, or when there is nowhere to sit.
categories default ["everyday"]
The categories of gestures it uses (see Gestures).
gestures default the everyday ones
The gestures it may do, from any category, and your own.
messages default a few lines
What it says now and then. End a line with [a link](/path) for a link to follow.
intro default three lines
How it introduces itself, once in each browser.
ads default true
Whether it goes and sits beside the page's ads now and then.
ad_lines default three lines
What it says by an ad.
ad_selectors default ""
CSS selectors of more ads, besides the ones it finds.
perches default ""
CSS selectors of the blocks it sits on, in place of its own choice.
catching default true
Whether a click catches it, costing it a quill (all gone, it leaves for the visit).
introduce default true
Whether it introduces itself.
chatty default "normal"
quiet, normal or chatty.
hide_on default []
Paths it stays away from: "/checkout" covers /checkout and below.
custom default {}
Gestures of your own, by id ("c-surfs"): see below.
characters default {}
Mascots of your own, by id ("c-pip"): see below.

From your own code

Once it is on the page it fires mascot:ready on the document, and window.Mascot answers:

Mascot.say(text, ms)
Says something, for ms milliseconds (4,000 unless given).
Mascot.pose(name, ms, words)
Does a gesture or pose for a while, then goes back to its life. words: a line to say, or true for one of the gesture's own.
Mascot.hide() / Mascot.show()
Sends it away, and brings it back.
Mascot.update(settings)
Changes its settings on the page, as the dashboard's preview does.
Mascot.start(settings)
Starts it on a page that loaded the script with data-tiles="only", or none.
Mascot.render(element, name)
Draws a still Quill doing that gesture into any element; [data-mascot-pose] elements are drawn by themselves.
Mascot.define(id, gesture)
Adds a gesture of your own (the JSON below), checked as the dashboard checks it.
Mascot.defineCharacter(id, mascot)
Adds a mascot of your own (the JSON below); then Mascot.update({ character: id }).
Mascot.catalog
Every category and gesture, with names and lines.

document.addEventListener("mascot:ready", () => {
  Mascot.pose("confetti", 4000, "Thanks for signing up!");
});

It finds AdSense (ins.adsbygoogle), Google Ad Manager (div-gpt-ad-…), ad iframes, and anything marked data-ad, data-ad-slot or data-mascot-ad, or with the class ad, ads, ad-slot or advert. Now and then it goes to one in sight and sits beside it, or on top of it where there is no room beside, points at it and says one of its ad lines.

Dressing up

Each mascot wears one thing in each place, in its own colour (its tint):

hat
tophat (Top hat), cap (Cap), beanie (Beanie), crown (Crown), party (Party hat), wizard (Wizard hat), cowboy (Cowboy hat), flower (Flower), bow (Bow), headphones (Headphones)
eyes
round (Round glasses), square (Square glasses), shades (Sunglasses), monocle (Monocle), hearts (Heart glasses), mask (Mask)
neck
bowtie (Bow tie), tie (Tie), scarf (Scarf), bandana (Bandana), medal (Medal), bell (Bell collar)

Mascots of your own

Every mascot shares one skeleton (its eyes, mouth, arms and legs in the same places), so every gesture and outfit fits every mascot. A mascot of your own is the rest, as JSON: the dashboard's AI writes it, or you write it by hand.

{
  "name": "Pip",
  "species": "chick",
  "about": "Small, loud, and certain about everything.",
  "body": "round",
  "tint": "#f6d04d",
  "tint_body": true,
  "no_mouth": true,
  "back": "<path class=\"tn\" d=\"M30 72 Q20 78 24 90 Q32 88 36 82Z M90 72 Q100 78 96 90 Q88 88 84 82Z\"/>",
  "muzzle": "<path class=\"tn\" d=\"M54 66 L66 66 L60 73Z\"/>",
  "top": "<path class=\"tn\" d=\"M58 37 C54 28 58 22 62 26 C63 20 70 22 66 30Z\"/>",
  "lines": ["Cheep! Hello!"]
}

body
egg, round or box; filled with paper, or with its tint when tint_body is true.
back
Behind everything: a tail, wings, long ears, quills. Pieces classed qq fall off one by one when it is caught.
ears, under, belly, muzzle, cheeks, top
Behind its body; on its face under the eyes; on its body; around its nose; beside it; on top of its head.
no_mouth
True for a beak or a muzzle that is its mouth.

The drawings follow the same rules as a gesture's, below, with one more class, tn: filled with its tint.

Gestures of your own

A gesture is JSON. The dashboard's AI writes it for you; you can also write or change it by hand. Its drawings are SVG elements, without <svg> around them, in the mascots' frame: 120 wide and 112 tall, the body from x 30 to 90 and y 34 to 97, the eyes at (50, 58) and (70, 58).

{
  "name": "Surfs",
  "about": "Catching a wave.",
  "arms": "raise",
  "hand": "<path class=\"pp\" d=\"M95 47 L88 6 Q95 0 102 6Z\"/><path class=\"ln\" d=\"M95 44 L95 6\"/>",
  "free": "",
  "hat": "",
  "face": "",
  "mouth": "grin",
  "brow": "up",
  "lid": "open",
  "anim": "sway",
  "look": [2, -2],
  "lines": ["Surf's up!", "Hang ten. Or two."]
}

arms
Where its hands are, and so where hand is drawn: hold (in front, hands at 46,82 and 74,82), lift (overhead, 44,42 and 76,42), raise (one hand up at 95,47), carry (one hand low at 99,80), eyes (at the face), up, down, point, cross, wave, shrug.
hand, free, hat, face
Drawings: in its grip, anywhere, on its head, over its eyes.
mouth, brow, lid, look
Its face: smirk, grin, o, flat; none, up, frown; open or half; where its eyes look, [dx, dy] from -3 to 3.
anim
none, bob, type, hop, sway, lift, dance, bang, shake, jab, wave, press. The last five move the raised or carrying arm, and what it holds.
lines
What it says while doing it.

Drawings may use only g, path, rect, circle, ellipse, line, polyline, polygon, text, tspan, the attributes class, d, x, y, x1, y1, x2, y2, cx, cy, r, rx, ry, width, height, points, transform, transform-origin, font-size, text-anchor, stroke-dasharray, opacity, and the mascots' classes, never colours: pp paper filled and ink outlined, so solid ink, ln an ink line (with thin, thick, or inv for paper on ink), ink ink dots, tx bold text (with font-size), big a big serif character, to then ti a tube. Motion classes such as fx-ring, fx-tilt, fx-float and fx-flip turn about a transform-origin you give. Anything else is taken out, by the dashboard and again by the script, before it is drawn on your page.

Good to know

Everything it draws is in a shadow root: your page's styles do not reach it, and its styles do not reach your page. A Content-Security-Policy needs script-src to allow this site, and connect-src for its settings.
It keeps two things in the visitor's browser: that it has introduced itself, and, for the rest of a visit, that it was caught bald.
With reduced motion asked for, it sits still and reads.