Skip to content

Pet packs

The folder of clips and rules that makes a pet, with no code.

A pack is a folder of clips and the rules that choose them, so a new pet for your app needs no code. Put each pack in a folder named after its ID, under your app’s resources/pets/ or the directory you load. nsgo-pet’s own packs are complete examples.

Path What it is
pet.json The pet’s name, size, body and the clips it plays by name
animations.json Every clip and when it plays, in Big Blue Fish’s format
webm/<clip>.webm Each clip as VP9 with alpha, for Linux and Windows
mov/<clip>.mov The same clip as HEVC with alpha, for macOS, whose player opens no WebM
NOTICE.md Where the pet comes from, its authors and its license

Both clip forms exist because no single format with alpha plays on every platform’s player. The engine picks the form by OS and never transcodes, so a pack’s clips ship in both forms or not at all.

{
"name": "大蓝鱼",
"width": 320,
"height": 180,
"body": { "left": 33, "top": 15, "width": 34, "height": 80 },
"eventSeconds": 40,
"clips": {
"greeting": "女仆屈膝礼仪",
"exit": "女仆屈膝礼仪",
"drag": "被鼠标拖拽悬空反馈",
"idle": "待机呼吸休闲",
"daily": "晨间刷牙",
"dailyHour": 23
},
"source": "https://github.com/PC2005-cloud/dsh-pet",
"license": "Character CC BY-NC-SA 4.0 (non-commercial); see NOTICE.md"
}

body is a rectangle in percent of the frame. Only there does the pet take the pointer, so clicks elsewhere in a transparent window reach the window below. clips names the clips the pet plays outside the pools: on start, on leaving, while dragged, as the fallback idle, and once a day at dailyHour. A manifest naming a clip that animations.json lacks fails to load.

Field Meaning
Pool Idle between events, Event every eventSeconds, Click, Greeting, Daily, Drag, or Disabled
Weight How likely the clip is against the others of its pool; 0 never plays unless a condition raises it
NightOnly, SeasonOnly, SummerWeight, WinterWeight, MorningWeight Time of day and season
Meal, MealBoost A boost within an hour of 8:00, 12:00 or 18:00
Festival, RadiusDays, FestivalMode, FestivalWeight Weight near a Gregorian festival; lunar festivals keep their plain weight
WorkKind, WorkWeight Coding or Working: what your app’s Context says the user is doing
MoveKind, HourParity Run or Crab: the pet walks 70 points and back, in a window of its own only

Disabled clips never play by chance, but your app can still play them by ID, which is how it maps its own states onto clips.

Clips need a transparent background. From PNG frames with alpha:

ffmpeg -framerate 24 -i frames/%04d.png -c:v libvpx-vp9 -pix_fmt yuva420p -b:v 0 -crf 32 webm/idle.webm
ffmpeg -c:v libvpx-vp9 -i webm/idle.webm -an -c:v hevc_videotoolbox -alpha_quality 0.75 -q:v 60 -tag:v hvc1 -pix_fmt bgra mov/idle.mov

nsgo-pet’s converters in tools/ write a whole pack, both clip forms and both JSON files; run them from a clone of nsgo-pet, with go run ./tools/<tool> -h for their flags.

Tool Input
tools/codexpet A Codex sprite sheet of eight 192×208 rows, with optional seasonal outfits
tools/framepet PNG frames and a JSON spec under tools/framepet/pets/

Give each pack its license in NOTICE.md and pet.json’s license; the engine’s MIT license covers no pack. An app that ships packs ships their licenses with them, and a pack under a non-commercial license, such as NSGo-chan’s or Big Blue Fish’s, makes the build that includes it non-commercial. Each of nsgo-pet’s pets and its license is listed in Pet licenses.