GitHub - joshtol/emotive-engine: Real-time 3D character animation engine with 8 elemental shaders, 160+ gestures, WebGL rendering, and emotional state system

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/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