Make room for
your own VIVI.

01 / START

Start with something that already moves.

The .vivipack sample includes a transparent 12-frame typing animation and a held idle pose. Unzip it to explore the structure, then replace the artwork with your own. It is a starter, not a complete motion library.

02 / YOUR FOLDER

This is where your character lives.

Right-click VIVI → Character → Open character folder to see the exact location on your PC. Create a <packId>/<packVersion>/ folder inside the following directory.

Paste the Windows path into File Explorer. On macOS, use Finder → Go → Go to Folder. On Linux, a configured XDG_DATA_HOME takes precedence over the default path.

<packId>/<packVersion>/character.json

03 / THE FILES

One character. One folder.

character.json describes the character and maps events to clips. frames.json lists each frame and its duration. All file paths are relative to the character pack root.

my-vivi.starter/
└── 1.0.0/
    ├── character.json
    ├── checksums.json
    └── clips/
        ├── idle/frames.json
        └── typing/
            ├── frames.json
            ├── typing-01.png
            └── … typing-12.png

character.json — character and events

{
  "schemaVersion": 1,
  "packId": "my-vivi.starter",
  "packVersion": "1.0.0",
  "canvas": {
    "width": 1024,
    "height": 896
  },
  "defaultDisplayHeight": 160,
  "clips": {
    "typing": {
      "frameCount": 12,
      "sequence": "clips/typing/frames.json",
      "entryPose": "typing.ready",
      "exitPose": "typing.ready",
      "loop": true
    }
  },
  "eventBindings": {
    "idle": [
      "typing"
    ],
    "chat.waiting": [
      "typing"
    ]
  }
}

frames.json — frame order

{
  "frames": [
    {
      "file": "clips/typing/typing-01.png",
      "durationMs": 100,
      "marker": "rest"
    },
    {
      "file": "clips/typing/typing-02.png",
      "durationMs": 100
    }
  ]
}

These are the key parts of the starter. Download the pack for all 12 frames and complete JSON files.

04 / MAKE IT MOVE

Draw the whole performance.

Use consecutive full-body drawings for each action. Match the opening and closing poses and keep a consistent ground contact point for natural transitions.

• Use transparent PNG or WebP images. Every frame must have the same canvas size.
• Artwork can be up to 2048×2048. Display height is 80–320px; 160px is recommended.
• A clip has 1–240 frames. Each frame lasts 16–30,000ms. The starter uses 12 frames at 100ms.
• anchor marks the ground contact; bubbleAnchor marks the speech bubble origin. Coordinates range from 0 to 1.
• A looping clip must have matching entryPose and exitPose. Connect different poses with drawn bridge clips and transitions.
• Use declarative assets, without scripts or executables. The unpacked pack may be up to 512MiB.

Give every moment a motion.

Use fallbacks for events without a dedicated motion. Fallbacks must not form a cycle. Add seasonal and media events according to the app version’s supported contract.

05 / TRY IT ON

Ready? Let VIVI try it on.

1. Easy route: ZIP the files inside your character folder and rename the extension to .vivipack. character.json must be at the ZIP root.
2. Right-click VIVI → Character → Import pack, then select the .vivipack. The app validates it before applying it.
3. Direct copy: place <packId>/<packVersion>/ in the OS-specific folder above, refresh the character list, then select it.
4. If checksums.json is present, update the SHA-256 hashes after editing. This file is optional for a personal pack.
5. An invalid pack leaves the current character in place. Do not modify the built-in VIVI inside the app installation folder.

06 / A LITTLE HELP

A few things to check.