Companion.js

Inspired by oneko.js by @adryd325, expanded with support for multiple characters and customizations that can animate multiple sprite-based characters. Each variant follows the pointer, idles, attacks on click, and occasionally plays special animations such as collapsing and reviving.

Preview

Using Companion.js

This project is entirely front-end, so you can copy the files into any site or web app without additional tooling:

1. Copy companion.js and the folders that hold the sprite sheets you want (for example Samurai/, Fire Wizard/). Place them somewhere your project can serve static assets (e.g. public/).

2. Reference the script from your HTML or template system, pointing the src to the copied location:

   <script src="/companion.js" data-variant="samurai"></script>

3. Optionally add the data overrides described above (data-height, data-speed, etc.) to tune the behaviour per page.

4. If you add custom sprites later, update the variants object in companion.js so every project can reuse the same script.

Selecting a Character

All client-side logic lives in companion.js. To switch characters, include the script and provide a data-variant value in your HTML:

<script src="./companion.js" data-variant="samurai"></script>

Supported variant keys:

• shinobi
• samurai
• fighter
• fire-wizard
• lightning-mage
• wanderer-magician
• knight-1
• knight-2
• knight-3

Customizing Behaviour

You can override animation behaviour per instance using additional data attributes on the script tag:

Attribute	Description	Default
data-height	Render height in pixels (scales the sprite)	80
data-speed	Movement speed toward the cursor	9
data-idle-distance	Distance threshold before idling instead of chasing	54
data-death-interval	Seconds between automatic collapse animations	42
data-death-duration	Frames to remain collapsed before reviving	75
data-persist-position	true (default) or false to toggle localStorage position persistence	true

Example with overrides:

<script
  src="./companion.js"
  data-variant="lightning-mage"
  data-height="100"
  data-speed="12"
  data-idle-distance="60"
  data-death-interval="30"
  data-persist-position="false"
></script>

Interactions

• Chase: Move the pointer and the character will pursue you until it reaches the idle distance threshold.
• Idle: When close enough to the pointer, the character loops through idle frames.
• Attack: Click the character to play its attack sequence.
• Collapse and revive: After the configured interval, the character plays a death animation, rests for a short duration, then automatically revives.