AIPET

PET SDK Reference

This page is a compact reference for custom PET plugins used by AIPET. The authoritative repo doc remains pets/README.md, but this HTML version is useful when reviewing the SDK in-browser.

Core Shape

Each plugin registers itself with registerCustomPetPlugin({...}).

registerCustomPetPlugin({
  css: `#pet.pet-custom.my-pet {}`,
  render() {
    return `<div id="my-pet-root"></div>`;
  },
  onMount({ petElement }) {
    petElement.classList.add('my-pet');
  },
  onUnmount({ petElement }) {
    petElement.classList.remove('my-pet');
  }
});

High-Value Hooks

onAnimationChange for base state transitions
onSocialEvent for semantic reactions and easter eggs
onGesture for lightweight gesture pulses
onVisionState for tracked people, faces, objects, gestures
onSystemState for throttling, thermal, CPU, battery cues

Behavior States

Normalized states expected by the runtime:

idle
awake
sleep
thinking
searching
alert_unknown_person
focus_active
focus_lost

Extended states available to plugins:

curiosity_peak
emotional_response
defensive_mode

Social Event Contract

onSocialEvent receives { type, context, ...hookContext }.

Current important social event types:

UNKNOWN_PERSON
OWNER_WITH_GUEST
OWNER_WITH_KNOWN_AND_UNKNOWN
NO_PERSON
NAIL_BITING
MIDDLE_FINGER

Recommended pattern: use onGesture for fast generic gesture effects, but use onSocialEvent when a gesture is promoted into a stronger semantic event such as MIDDLE_FINGER.

Implementation Guidance

Keep onAnimationChange authoritative for the resting visual state.
Use short-lived event classes for bursts such as social reactions.
Prefer CSS animation over heavy JS.
Clean up classes and inline styles in onUnmount.
For custom testing, use /aipet/sdk/debugger.