A ball of feelings your AI can actually show

What it does

Emotion Ball is an expression engine for AI assistants: a small animated character (blob, wedge, or gem body) that reacts to a single JSON message from your AI side. The model outputs an emotionId like "30" for “thinking,” and the ball switches faces — sleepy, shy, angry, searching, error, task-complete. No framework, no image assets, no build step; it’s HTML, SVG, and native JavaScript, which makes it a natural fit for Electron floating windows and desktop pets.

The interesting bit

Every emotion is pure data — a pool of eye-ring shapes, animation primitives (sine, glance, jitter, scan…), and an optional keyframe sequence. New expressions are registered as config objects without touching engine code, and the ID scheme (00–09 lifecycle, 10–29 emotions, 30–49 agent states, 50+ custom) promises never to renumber, so integrators can hardcode IDs safely. The eyes even do spherical projection: they compress and hide as the body spins them around to the back.

Key highlights

• 32 built-in emotions across lifecycle, emotional, and agent-state groups, all config-driven
• Robust AI protocol: handleAIMessage accepts objects or JSON strings, and unknown IDs or parse failures fall back to idle instead of a blank screen
• All instances share one rAF heartbeat; off-viewport instances can be paused to save power
• Runtime registration, plus full config export/import as JSON
• Ships with a bilingual (CN/EN) gallery site with light/dark themes and two browse modes

Caveats

• Licensing is unusually layered: the ball characters’ visual designs are learning-only with no commercial option ever, while the engine code and emotion data are dual-licensed (free non-commercial, paid commercial). Read LICENSE and NOTICE.md before shipping anything.
• The mood-mates/ characters are a separate, commercially licensable sub-project — the repo is really three projects in one trench coat.

Verdict

Worth a look if you’re building a chatbot, desktop pet, or floating assistant and want expressive faces without shipping a sprite sheet or a React dependency tree. Skip it if you need a commercially usable character out of the box — the main ball’s visuals are locked to learning-only.