body-engine-sprite

Install

npm install @davi-ai/body-engine-sprite

Usage

Example with a simple button to change the 'speaking' state of the character

import React, { useState } from 'react'

import MyComponent from '@davi-ai/body-engine-sprite'
import '@davi-ai/body-engine-sprite/dist/index.css'

const App = (): JSX.Element => {
  const [speaking, setSpeaking] = useState<boolean>(false)

  const handleClick = (): void => {
    setSpeaking(!speaking)
  }

  const props = {
    licence: 'licence', // no use ATM
    agentData: string, // address to get character's data (name, gender, animations, ...)
    height: undefined | number | string, // margin-top above the character. ***
    size: undefined | number | string, // vertical size of the character. *** + Undefined gives full viewport height (100vh)
    speak: boolean // speaking state of the character
  }

  *** : "either in pixels (number - ex: 200) or % / vh (string - ex : '5%' / '10vh')"

  return (
    <React.Fragment>
      <button onClick={handleclick}>Change speaking</button>
      <MyComponent {...props} />
    </react.Fragment>
  )
}

About the animations (retrieved from agentData)

Your animations MUST follow the following rules

Folder architecture

The parameter 'agentData' in the props is an URL so that the body-engine is able to load the animations. This URL must lead to a folder with the following architecture :

└── <folder_name>
          ├── webm
          │    ├── small
          │    │    ├── move
          │    │    │     ├── ns
          │    │    │     │   ├── explain1_ns.webm
          │    │    │     │   ├── ...
          │    │    │     │   ├── explain<x>_ns.webm
          │    │    │     │   ├── idle1_ns.webm
          │    │    │     │   ├── ...
          │    │    │     │   └── idle<x>_ns.webm
          │    │    │     └── sp
          │    │    │         ├── explain1_sp.webm
          │    │    │         ├── ...
          │    │    │         ├── explain<x>_sp.webm
          │    │    │         ├── idle1_sp.webm
          │    │    │         ├── ...
          │    │    │         └── idle<x>_sp.webm
          │    │    ├── still
          │    │    │     ├── ns
          │    │    │     │   ├── still1_ns.webm
          │    │    │     │   ├── ...
          │    │    │     │   └── still<x>_ns.webm
          │    │    │     └── sp
          │    │    │         ├── still1_sp.webm
          │    │    │         ├── ...
          │    │    │         └── still<x>_sp.webm
          │    │    ├── <custom>
          │    │    │     ├── ns
          │    │    │     │   ├── <custom>1_ns.webm
          │    │    │     │   ├── ...
          │    │    │     │   └── <custom><x>_ns.webm
          │    │    │     └── sp
          │    │    │         ├── <custom>1_sp.webm
          │    │    │         ├── ...
          │    │    │         └── <custom><x>_sp.webm
          │    │    └── ...
          │    ├── medium
          │    │    └── <same as small>
          │    └── large
          │         └── <same as small>
          ├── mp4
          │    ├── small
          │    │    └── <same as webm with mp4 files>
          │    ├── medium
          │    │    └── <same as webm with mp4 files>
          │    └── large
          │         └── <same as webm with mp4 files>
          └── manifest.json

webm / mp4 are used in different browsers (mostly mp4 for Safari, webm for the others). The 3 sub-folders small, medium and large contain the animations which are scaled for different screen sizes. The sizes below are those used basicaly :

• small : 480x480 pixels (mobiles)
• medium : 1200x1200 px (laptops / desktops)
• large : 2000x2000 px (very large screens)

'ns' and 'sp' sub-folders mean 'no-speak' and 'speak'. In the 'ns' folders are the animations where the character's lips aren't moving and the 'sp' folder contains the same animations, in which the lips are moving to simulate a speech.

Naming convention

Only the folders 'move' and 'still' are necessary. The folder 'move' contains the basic animation that are displayed when the character is performing an action, and is divided in 2 main categories :

• idle : animation where the character moves while there is no text to speak
• explain : animation where the character makes movements to explain something while speaking.

The folder 'still' contains the animations where the character stays still. These are used for transition between each loading of an idle or explain animation.

The other folders contain the animations only usable in a custom queue where the given animations will be played one after another, with a fallback to the normal behavior when every animation has been played.

Each animation file MUST follow this pattern :

  'move' folder :
  <explain|idle><index>_<ns|sp>.<webm|mp4>

  'still' folder :
  <still><index>_<ns|sp>.<webm|mp4>

  <other_folder> folder :
  <other_folder><index>_<ns|sp>.<webm|mp4>

The index begins at 1 and goes one by one up to 99. There MUST be an index even if there is only 1 animation in the folder.

For example :

└── <folder_name>
          ├── webm
          │    ├── small
          │    │    ├── chatting
          │    │    │     ├── ns
          │    │    │     │   ├── chatting1_ns.webm
          │    │    │     │   └── chatting2_ns.webm
          │    │    │     └── sp
          │    │    │         ├── chatting1_sp.webm
          │    │    │         └── chatting2_sp.webm

Manifest.json

At the root of the main folder reached when using the URL, there has to be a 'manifest.json' file containing some data related to the animations :

• gender : 'male' | 'female' | 'other' : the gender of the character, used to choose a correct voice inside the framework
• name : the name of the agent displayed in the framework
• portrait : link to the portrait image displayed in the widget or mobile in text conversation mode
• data : contains the number of animations related to each folder. The mandatoty keys are "idle", "explain" and "still". For every other animation folder, there must be a pair "key" : value with the name of the folder (lowercase) as key and the number of animations available as value.

For example if you have :

• a female character
• 5 explain animations
• 3 idle animations
• 1 still animation
• taking the example above, 2 chatting animations the manifest.json file will be as follows :

{
  "gender": "female",
  "name": "Anna",
  "portrait": "portrait.png",
  "data": {
    "idle": 3,
    "explain": 5,
    "still": 1,
    "chatting": 2
  }
}

License

MIT ©