sam70361/aora-bot

What it solves

Emotion Ball is a lightweight, zero-dependency expression engine designed to provide AI assistants, chatbots, and desktop pets with a visual emotional layer. It allows developers to easily switch between 32 predefined emotional states (such as thinking, happy, or sleeping) using a simple ID-based protocol, eliminating the need for complex image assets or heavy frameworks.

How it works

The engine uses pure SVG and vanilla JavaScript to render characters in real-time. It operates on a data-driven configuration system where expressions are defined by a combination of "eye-ring pools," animation primitives (like sine waves or jitters), and keyframe sequences.

Key technical features include:

• Spherical Projection: Eyes are mapped to the body's contour using longitude conversion and cosine compression to maintain a 3D feel.
• Dynamic Adaptation: The same animation system automatically adapts to three different body shapes: blob, wedge, and gem.
• AI Integration: A robust handleAIMessage method accepts JSON strings or objects, allowing an AI to trigger expression changes by simply outputting an emotionId.
• Performance: All instances share a single requestAnimationFrame (rAF) heartbeat to minimize CPU overhead.

Who it’s for

• AI Developers: Those building LLM-based assistants or agents that need a non-verbal emotional interface.
• Frontend Engineers: Developers looking for a lightweight, SVG-based animation system for floating assistants or Electron-based desktop pets.
• UI/UX Designers: Users who want to customizable, data-driven character expressions without needing to create individual frames of animation.

Highlights

• 32 Predefined States: Covers life cycles (wake/sleep), emotional reactions, and agent-specific states (searching/thinking/error).
• Zero Dependencies: Built with HTML, SVG, and vanilla JS, making it easy to integrate into any web environment or Electron app.
• Customizable: Supports runtime registration of new expressions and custom body shapes/colors.
• Interactive: Includes mouse-gaze tracking with exponential smoothing and physics-based particle effects for celebrations.
• Coreset of Animation Primitives: Uses a library of 6 animation types (sine, glance, pulse, jitter, scan, blink) to create complex behaviors.