Webimaru

A lightweight, framework-agnostic JavaScript library for adding animated mascot companions to websites.

Installation

npm install webimaru

Quick Start

JavaScript API

import { MascotCompanion, bunny } from 'webimaru';
import 'webimaru/dist/style.css';

const mascot = new MascotCompanion({
  character: bunny,
  position: 'bottom-right',
  size: 'medium'
});

mascot.play('wave');
mascot.say('Hello!');

Web Component

<link rel="stylesheet" href="node_modules/webimaru/dist/style.css">
<mascot-companion character="bunny"></mascot-companion>
<script src="node_modules/webimaru/dist/webimaru.umd.js"></script>

API

Animations

mascot.play('idle');
mascot.play('wave');
mascot.play('celebrate');

Speech Bubbles

mascot.say('Hello World!');
mascot.say('Success!', {
  style: 'success',     // 'success' | 'info' | 'warning' | 'error'
  position: 'top',      // 'top' | 'bottom' | 'left' | 'right'
  duration: 3000,
  typing: true
});

Options

new MascotCompanion({
  character: bunny,                    // Character config object
  position: 'bottom-right',            // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
  size: 'medium',                      // 'small' | 'medium' | 'large' | number (pixels)
  container: document.body             // Parent element
});

Events

mascot.on('animationStart', (name) => console.log(name));
mascot.on('animationEnd', (name) => console.log(name));

Custom Characters

const custom = {
  name: 'robot',
  spriteSheet: {
    path: '/sprite.png',
    frameWidth: 128,
    frameHeight: 128,
    frames: 12,
    cols: 4
  },
  animations: {
    idle: {
      frames: [0, 1, 2, 3],
      duration: 1000,
      loop: true
    }
  }
};

new MascotCompanion({ character: custom });

Sprite Sheet Requirements:

• Grid layout (left-to-right, top-to-bottom)
• Uniform frame sizes
• Must include looping idle animation

Development

npm install
npm run dev     # http://localhost:5173
npm run build

License

MIT