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

Crystal Soul Subsurface scattering shader	Moon Phases 8 phases with tidal lock	Solar Eclipse Corona and diamond ring
Blood Moon Eclipse Rayleigh scattering simulation

2D Canvas

Hello World	Basic Usage	Breathing App
Event Handling	Rhythm Sync

---

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/three@0.170.0/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