Skip to content

Installation‐and‐Setup

Jump to bottom
Joshua Tollette edited this page Oct 28, 2025 · 2 revisions

Installation and Setup

Get Emotive Engine running in 5 minutes.

Installation

Via npm (Recommended)

npm install @joshtol/emotive-engine

Via CDN

<script src="https://unpkg.com/@joshtol/emotive-engine@2.5.1/dist/emotive-engine.min.js"></script>

Quick Start

Step 1: Create HTML with Canvas

<!DOCTYPE html>
<html>
<head>
    <title>My Emotive App</title>
    <style>
        #mascot-canvas {
            width: 400px;
            height: 400px;
            border: 1px solid #ccc;
        }
    </style>
</head>
<body>
    <canvas id="mascot-canvas"></canvas>
    <script type="module" src="app.js"></script>
</body>
</html>

Step 2: Initialize in JavaScript

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

// Get canvas element
const canvas = document.getElementById('mascot-canvas');

// Create mascot instance
const mascot = new EmotiveMascot({
    canvasId: 'mascot-canvas',
    targetFPS: 60,
    defaultEmotion: 'neutral'
});

// CRITICAL: Initialize with canvas element
await mascot.init(canvas);
mascot.start();

// Try it out!
mascot.setEmotion('joy');
mascot.morphTo('heart');
mascot.express('bounce');

Common Setup Issues

Canvas Not Found

Problem: Cannot read property 'getContext' of null

Solution: Ensure canvas element exists before calling init()

// ❌ Wrong - canvas might not exist yet
const mascot = new EmotiveMascot({canvasId: 'canvas'});
await mascot.init(canvas);

// ✅ Correct - wait for DOM to load
document.addEventListener('DOMContentLoaded', async () => {
    const canvas = document.getElementById('canvas');
    const mascot = new EmotiveMascot({canvasId: 'canvas'});
    await mascot.init(canvas);
    mascot.start();
});

Initialization Order

Problem: Nothing renders or errors occur

Solution: Always call init(canvas) before start() and always await init

// ❌ Wrong
mascot.start();
await mascot.init(canvas);

// ❌ Wrong - forgot to await
mascot.init(canvas);
mascot.start();

// ✅ Correct
await mascot.init(canvas);
mascot.start();

Canvas Size Issues

Problem: Canvas appears blurry or pixelated

Solution: Set canvas size in CSS, not HTML attributes

<!-- ❌ Wrong -->
<canvas id="canvas" width="400" height="400"></canvas>

<!-- ✅ Correct -->
<canvas id="canvas"></canvas>
<style>
    #canvas {
        width: 400px;
        height: 400px;
    }
</style>

Framework Integration

React

import { useEffect, useRef } from 'react';
import EmotiveMascot from '@joshtol/emotive-engine';

function MascotComponent() {
    const canvasRef = useRef(null);
    const mascotRef = useRef(null);

    useEffect(() => {
        const initMascot = async () => {
            mascotRef.current = new EmotiveMascot({
                canvasId: 'mascot-canvas'
            });
            await mascotRef.current.init(canvasRef.current);
            mascotRef.current.start();
        };

        initMascot();

        return () => {
            mascotRef.current?.destroy();
        };
    }, []);

    return <canvas ref={canvasRef} id="mascot-canvas" />;
}

See react-component.jsx for complete example.

Next.js

'use client';

import { useEffect, useRef } from 'react';
import EmotiveMascot from '@joshtol/emotive-engine';

export default function MascotComponent() {
    const canvasRef = useRef(null);
    const mascotRef = useRef(null);

    useEffect(() => {
        const initMascot = async () => {
            mascotRef.current = new EmotiveMascot({
                canvasId: 'mascot-canvas'
            });
            await mascotRef.current.init(canvasRef.current);
            mascotRef.current.start();
        };

        initMascot();

        return () => mascotRef.current?.destroy();
    }, []);

    return <canvas ref={canvasRef} id="mascot-canvas" />;
}

Vue

<template>
    <canvas ref="canvas" id="mascot-canvas"></canvas>
</template>

<script>
import EmotiveMascot from '@joshtol/emotive-engine';

export default {
    mounted() {
        this.initMascot();
    },
    beforeUnmount() {
        this.mascot?.destroy();
    },
    methods: {
        async initMascot() {
            this.mascot = new EmotiveMascot({
                canvasId: 'mascot-canvas'
            });
            await this.mascot.init(this.$refs.canvas);
            this.mascot.start();
        }
    }
}
</script>

Mobile Optimization

For better performance on mobile devices:

const isMobile = /iPhone|iPad|iPod|Android/i.test(navigator.userAgent);

const mascot = new EmotiveMascot({
    canvasId: 'mascot-canvas',
    particleCount: isMobile ? 150 : 300,
    adaptiveQuality: true,
    targetFPS: isMobile ? 30 : 60
});

Next Steps

Clone this wiki locally