Emotive Engine

Expressive AI mascots for modern interfaces

Real-time character animation engine with Canvas 2D and WebGL 3D rendering. 8 elemental shader systems. 160+ elemental gestures. One replicable pattern.

Live Demo · Elemental Gestures Demo · NPM

Quick Start

npm install @joshtol/emotive-engine

3D Mode (WebGL)

import { EmotiveMascot3D } from '@joshtol/emotive-engine/3d';

const mascot = new EmotiveMascot3D({
    coreGeometry: 'crystal',
    assetBasePath: '/assets', // self-hosted assets (see below)
});

mascot.init(document.getElementById('container'));
mascot.start();

mascot.setEmotion('joy');
mascot.express('bounce');
mascot.morphTo('heart');
mascot.feel('happy, bouncing'); // Natural language control

3D mode requires Three.js: npm install three

2D Mode (Canvas)

import { EmotiveMascot } from '@joshtol/emotive-engine';

const mascot = new EmotiveMascot();
await mascot.init(document.getElementById('container'));
mascot.start();
mascot.feel('happy, bouncing');

2D mode has no dependencies and requires no external assets.

Features

3D WebGL Rendering

• Custom GLSL shaders with subsurface scattering
• Physically-based materials and bloom effects
• 8 moon phases with tidal lock camera
• Solar and lunar eclipse simulations
• Runtime geometry morphing

2D Canvas Rendering

• Lightweight pure Canvas 2D
• Dynamic particle effects
• Shape morphing animations
• Gaze tracking
• Mobile-optimized

Shared: 15 emotions · 180+ gestures · Natural language feel() API · TypeScript definitions · Unified API

Demo Gallery

3D WebGL

2D Canvas

3D Assets

The npm package ships JavaScript only. GLB models, textures, and HDRI maps must be self-hosted (~24 MB). They live in assets/ in this repository.

new EmotiveMascot3D({
    assetBasePath: '/assets', // wherever you host the assets folder
});

| Hosting Option | assetBasePath | | --------------------- | --------------------------------------------------- | | Copy to public/ | '/assets' | | CDN / S3 | 'https://cdn.example.com/emotive-engine/assets' | | GitHub Pages | 'https://joshtol.github.io/emotive-engine/assets' |

<assetBasePath>/
├── models/Elements/   # GLB models for elemental effects
├── textures/          # Crystal, Moon, Sun textures
└── hdri/              # Environment maps (optional)

CDN Usage

<!-- 2D (UMD, no dependencies) -->
<script src="https://unpkg.com/@joshtol/emotive-engine/dist/emotive-mascot.umd.js"></script>

<!-- 3D (ESM, requires Three.js import map) -->
<script type="importmap">
    {
        "imports": {
            "three": "https://unpkg.com/[email protected]/build/three.module.min.js"
        }
    }
</script>
<script type="module">
    import { EmotiveMascot3D } from 'https://unpkg.com/@joshtol/emotive-engine/dist/emotive-mascot-3d.js';
</script>

Documentation

| Doc | Description | | ------------------------------------------------ | ------------------------------------------------------------------ | | API Reference | All methods, configuration options, emotions, gestures, geometries | | LLM Integration | Natural language feel() API, system prompt examples | | Gestures | Full gesture catalog (180+ base + 160+ elemental) | | Quick Reference | Cheat sheet for emotions, undertones, and common patterns | | Architecture | Internal design and rendering pipeline |

Running Locally

git clone https://github.com/joshtol/emotive-engine.git
cd emotive-engine
npm install && npm run build && npm run local
# → http://localhost:3001

License

MIT — see LICENSE.md

Created by Joshua Tollette