Skins & Animations Reference

Skins define the visual appearance of your desktop companion. A skin consists of numbered PNG frames organized in specific subfolders representing animation variants.

Sprite Pack Structure

A valid skin is packaged as a .jacky (or .zip) archive containing a manifest.json configuration manifest at the root, along with animation folders containing sequential PNG frames. Note that each animation must contain at least 4 frames to playback correctly:

manifest.json Manifest

The manifest.json file defines the package metadata, the skin dimensions, playback rate, and shop card details.

Here is an example manifest.json configuration:

{
  "type": "skin",
  "name": "MyJacky",
  "version": "1.0.0",
  "author": "Jacky Team",
  "description": "MyJacky skin in .jacky file",
  "skin": {
    "sprite_size": 128,
    "fps": 16,
    "sprite_facing": "left",
    "card": {
      "title": "MyJacky",
      "description": "EmoteLab MyJacky skin para Lu",
      "author": "Cate",
      "link": "https://yourwebsite.com"
    }
  }
}

Package Metadata (Root)

• type: Must be set to "skin" for skin packages.
• name: The display name of the skin package.
• version: Semantic versioning string (e.g., "1.0.0").
• author: The user or organization who compiled and packaged the .jacky file.
• description: A short description of the package.

Skin Settings (skin)

• sprite_size: Width and height of each (square) frame. Defaults to 128.
• fps: Target playback frames-per-second. Defaults to 8.
• sprite_facing: Whether the source assets face left or right. Defaults to right. Optional.

Character Card (skin.card)

You can optionally include a card object under the skin block to display information in the character selector or shop:

• title: The display name of the skin card.
• description: A brief description of the skin.
• author: The artist/designer who created the visual assets.
• link: A URL pointing to the artist's website or portfolio.

Animation States & Mappings

Jacky supports 26 distinct state enums (PetState) that are resolved dynamically into internal Animation Variants.

To help you verify your packages, here is the reference list of all recognized folder names on disk. Only the Idle folder is strictly required:

Row entries below explain the relationship between the internal PetState enums and their primary animation variants. Expand a row to view its fallback chain path:

The Fallback System

You do not need to create every sprite folder to make a valid skin. If a folder is missing, Jacky walks the Fallback Chain (shown in the table explorer above) to locate a suitable match.

For example:

• If Typing2 is missing, it falls back to Typing.
• If Typing is missing, it falls back to Talk.
• If Talk is missing, it falls back to Idle Blinking.
• If Idle Blinking is missing, it falls back to Idle.

Skin Development Guidelines

When creating custom skins, keep these key rules and recommendations in mind to ensure compatibility and smooth rendering:

• Minimum 4 Frames per Animation: Every single animation you include (e.g., Idle, Walking, etc.) must have at least 4 frames (e.g., 000.png to 003.png).

• Minimum Viable Skin: The simplest possible skin only requires the Idle folder with at least 4 frames. With this single folder, Jacky can appear on the screen, move around, and run, since every state will gracefully fallback to the Idle animation.

• Recommended Simple Skin: For a fast but natural-feeling skin, creating just 5 folders with 4 frames each is highly recommended:

  1. Idle (Default resting animation)
  2. Walking (Movement across the screen)
  3. Talk (Active during speech bubbles)
  4. Happy (Triggered on petting, greetings, or victories)
  5. Hurt (Reaction to fights or errors)

  These 5 basic folders cover all main interactions, giving your companion a lively, responsive feel with minimal effort.