@rapyuta-robotics/spirit

The first version of Spirit is finally here!

Design concept by Juho can be found in this link: https://www.rapyuta-robotics.com/ja/character/

How to add this package to your project

In your project's directory, run yarn add @rapyuta-robotics/spirit

import { SpiritWrapper } from '@rapyuta-robotics/spirit';

const YourComponent = () => {
  return (
    <>
      ...
      <SpiritWrapper width={400} height={300} />
    </>
  )
}

Preview in RobotUI:

https://github.com/rapyuta-robotics/spirit/assets/117139683/b0b5ca27-0ad6-40aa-b9b5-bb25a9fa9d05

Animation Types

Spirit supports two animation modes: Phaser (WebGL/Canvas-based) and GIF (lightweight static GIFs).

Phaser Mode

Uses Phaser.js to render an interactive, shader-driven spirit with aura effects. Best for rich, dynamic animations.

import { SpiritWrapper, AnimationType, SpiritExpression } from '@rapyuta-robotics/spirit';


<SpiritWrapper width={400} height={300} animationType={AnimationType.PHASER} />

Available expressions (SpiritExpression):

• DEFAULT
• UPWARD
• DOWNWARD
• SIMILING

GIF Mode

Uses lightweight GIF images for the spirit animation. Best for performance-sensitive contexts or simpler UIs.

import { SpiritWrapper, AnimationType, SpiritGif } from '@rapyuta-robotics/spirit';

<SpiritWrapper
  width={400}
  height={300}
  animationType={AnimationType.GIF}
  expression={SpiritGif.spiritDefaultGif}
/>

Available GIF expressions (SpiritGif):

• spiritDefaultGif
• spiritLookRightDownGif
• spiritLookLeftDownGif
• spiritDeterminedFaceGif
• spiritHappyFaceGif
• spiritMouthRightUpGif

Preview of animations:

https://github.com/user-attachments/assets/b42cff0c-0ca1-49b6-95ee-82b160f67d7d

Spirit Position

The spiritPosition prop controls which side the spirit appears relative to the chatbox.

| Value | Description | |-------|-------------| | Spiritposition.RIGHT (default) | Spirit on the right, chatbox on the left. Chatbox tail points right. | | Spiritposition.LEFT | Spirit on the left, chatbox on the right. Chatbox tail points left. |

How to develop this package locally

Start development:

1. First, make sure that you have added this package to your project (see: How to add this package to your project)
2. In this package's 📦 directory, run yarn link to create the symlink
3. In this package's 📦 directory, run yarn start to watch this package's file changes and rebuild automatically
4. In your project's 📝 directory, run yarn link @rapyuta-robotics/spirit to establish the symlink
5. Your project is now referencing to the local copy of this package everytime you import such as import { helloWorld } from '@rapyuta-robotics/spirit'
6. When you edit the code of this package, your project will hot-reload and reflect the new changes

Stop development:

1. In your project's 📝 directory, run yarn unlink @rapyuta-robotics/spirit to disband the symlink (NOTE: you need to do this before step (3), otherwise the unlink will fail. In the case that you mistakenly run (3) before (1), run yarn link in this package's 📦 directory and restart from (1))
2. In your project's 📝 directory, run yarn install --force to ensure that it's using the correct remote version of @rapyuta-robotics/spirit
3. In this package's 📦 directory, run yarn unlink to cancel the symlink

How to publish a new version

A new version will be published to NPM everytime a new release is created

The workflow shall be:

1. Create a new release targeting devel. No release branch should be created as we are using trunk-based development approach.
2. Tag of the new release should follow semantic versioning with [breaking change (compatibility issue)].[feature update].[bugfix patches] -> (x.y.z)
3. Once release is created, github action will automatically publish it to npmjs.

FAQs

1. If CI fails when trying to publish npm package, there is a chance that the project does not have access to RR_NPM_TOKEN in organization's secrets. Contact [email protected] when such case occurs.

References

1. This project uses tsup for bundling and hot-bundling on code changes (see: https://github.com/egoist/tsup)
2. Yarn link & unlink workflow reference: https://gist.github.com/alanbsmith/6c581e5042b8e5e558b0b4454192eb69
3. Trunk-based development: https://www.atlassian.com/continuous-delivery/continuous-integration/trunk-based-development