microsoft/vscode/chat-pet-sprite-creation

Chat Pet Sprite Creation

Create pet sprites that feel like one continuous character rather than separate drawings. Start from the current pet body, preserve its visual anchor, and make every difference intentional.

Source of truth

• Sprite art: src/vs/workbench/contrib/chat/browser/widget/media/chatPet/
• Runtime states, dimensions, timing, and transitions: src/vs/workbench/contrib/chat/browser/widget/chatPetWidget.ts
• Eye geometry, facing, clipping, and motion CSS: src/vs/workbench/contrib/chat/browser/widget/media/chatPet.css
• Unit tests: src/vs/workbench/contrib/chat/test/browser/widget/chatPetWidget.test.ts

Read the current implementation before drawing. Existing dimensions and timings may have changed since this skill was written.

PR precedence and lineage

This skill distills the complete pet PR history. When rules conflict, use this precedence:

1. Current code and tests
2. The newest relevant open PR
3. Newer merged PRs
4. Older historical behavior

In particular, animation cleanup PR #330399 supersedes the old revive-sign flow and several earlier sprite/timing assumptions.

The logical pixel

The canonical art unit is one logical pixel:

• 8×8 source pixels
• 4×4 CSS pixels at the standard 96×96 source → 48×48 display scale

Core silhouettes, facial features, props, and repeated details must use the same logical-pixel scale. Do not make a new object from smaller or larger blocks simply to fit more detail.

Effects may deliberately subdivide the logical pixel—for example, small stars, bubbles, or curved motion—but the subdivision must:

1. Serve a specific effect that cannot read on the core grid.
2. Stay consistent throughout that effect.
3. Never come from antialiasing or resampling.

Use nearest-neighbor rendering only. Keep transparent backgrounds and hard pixel edges. Do not introduce blur, feathered alpha, color interpolation, or accidental off-grid scaling.

Start from a baseline

Never redraw the pet body from memory.

• Use the current idle sprite as the baseline for resting, pointer-driven, or playful states.
• Use the current rendering sprite as the baseline for request/processing states.
• Copy the complete body first, then alter only the parts required by the new state.

This preserves:

• Body width and height
• Bottom baseline
• Antenna roots and spacing
• Highlight and shadow ramps
• Eye sockets
• Collision/interaction footprint

The first and last key poses must transition cleanly to idle or rendering without a body-position, silhouette, baseline, or scale pop.

Canvas and anchoring

The default source canvas is 96×96, or 12×12 logical pixels.

Use a larger canvas only when content intentionally extends outside the canonical body box:

• A terminal or button may need extra width.
• A note, star, or bubble may need extra height.
• The body must remain anchored exactly where it sits in the baseline sprite.

Do not center the body inside a wider frame. Keep the body in the canonical 96×96 region and let the prop/effect overhang. Declare every nonstandard source dimension in chatPetWidget.ts and update wide-sprite boundary handling.

The runtime collision and movement box belongs to the pet body, not to a decorative overhang.

Eyes

The standard open eye is `1×2` logical pixels:

• 8×16 source pixels
• 4×8 CSS pixels

Use a different eye shape only when the state communicates a special expression, such as sleep, dizzy, love, worry, or impact.

DOM eye layer

The DOM eye layer has two independent modes:

• Tracking supplies gaze, facing, blink, and drag expressions.
• Blinking can temporarily show DOM eyes for a non-tracking state and can vary by sprite frame.

States that use runtime gaze must use eye-less *-tracking-96 assets. States that use DOM blinking, such as typing, button press, or love in PR #330399, must also leave the corresponding pupil area available for the overlay.

When adding or changing a DOM-eye state:

1. Keep the sprite eye sockets empty.
2. Add cursor behavior to doesChatPetStateTrackCursor when appropriate.
3. Add blink behavior to doesChatPetStateBlink(state, frameIndex) when appropriate.
4. Verify the tall-eye blink, state-specific eye height, and pointer offsets in both facing directions.
5. Verify frames that intentionally stop blinking, such as a held terminal pose.

Never combine baked pupils with the runtime eye overlay.

Baked-eye states

States with a fixed expression should bake the eyes into the art and opt out of cursor tracking. Preserve the standard eye position unless the expression intentionally changes it.

Stable and Insiders parity

Stable and Insiders are palette variants of the same animation.

They must have identical:

• Canvas dimensions
• Frame count and ordering
• Alpha mask and geometry
• Body anchor and overhang
• Static fallback pose
• Timing and iteration behavior

Create one geometry master and apply the two established palettes. Do not redraw variants independently.

Review the two variants side by side. Any shape difference is a bug unless the product explicitly requires it.

Facing and mirroring

Author one canonical facing direction and let the runtime mirror it for the other direction.

Test both directions because mirroring also changes where wide sprites overhang. Keep enough room for boundary correction near the left and right edges.

Decorations that must retain their screen orientation—such as text, musical notation, or directional symbols—must not be baked into a layer that the runtime mirrors. Model them as fixed-orientation decorations or render them separately.

Static asset and sprite sheet

Each animated state needs both variants of:

• A static PNG for reduced motion: buddy-<state>-<variant>-<height>.png
• A horizontal sprite sheet: buddy-<state>-<variant>-<height>.spritesheet.png

The sprite sheet contract is:

sheet width = frame width × frame count
sheet height = frame height

Every frame uses the same rectangle. Never shift frame boundaries or add per-frame padding.

Choose a meaningful static pose that communicates the state without motion. Do not assume the first animation frame is automatically the best reduced-motion fallback.

Layered accessories

Wearable accessories use a body-owned attachment rig and one palette-independent atlas per appearance under media/chatPet/accessories/. Do not export copies for individual runtime states or frames. Body animation metadata owns attachment movement; an accessory atlas only contains the few canonical shapes needed when the body geometry changes.

The default atlas is 256×192, divided into 64×64 cells. A hat whose supplied silhouette genuinely needs the full 12-logical-pixel body width may declare atlasCellSize: 96 and use a 384×288 atlas with 96×96 cells. Do not choose the wider tier merely to add detail; both tiers still use the same whole 8×8 logical pixels.

columns: upright | sleeping | impact | splat
row 0:   head back layers
row 1:   head front layers
row 2:   right-eye front layers

An appearance may leave any cell transparent. For example, a plain hat leaves the eye row empty, while a combined Top Hat & Monocle appearance uses both head rows and the eye row. The airborne rig pose reuses the upright column. Add another canonical column only when an existing pose plus body-owned translation cannot preserve the intended silhouette.

Attachment tracks live in chatPetAccessoryRig.ts. Each track uses compressed frame spans with a canonical pose and independent head/right-eye anchors. A slot is omitted while a body-authored expression, prop, or complete silhouette replacement owns the same geometry, such as dizzy eyes, sunglasses, or the rare icon transformation. When frames inside one sheet bake different facing directions, the track marks those frames so the head accessory mirrors with the body before the whole pet's outer facing transform is applied. Update the body-owned track only when body geometry changes. Adding an ordinary accessory must not require editing tracks or renderer code.

Head-slot anchors include a one-logical-pixel wear offset so hats overlap the top of the head rather than resting on its silhouette. The love animation suppresses head accessories because its transformed head/antenna silhouette is the reaction. Treat slot visibility and fit as body-owned behavior, not per-hat exceptions.

Appearances that tuck the antennae under a larger hat opt into coversAntennae. The compositor uses body-owned occlusion bounds before drawing the hat front, so the behavior follows animation tracks and mirroring without painting body-colored cover pixels into each atlas.

Directional head accessories are authored for the canonical right-facing body and mirror with the complete pet canvas. A hat with directional structure should stay visually balanced over the head while expressing facing through a restrained one-logical-pixel cue in its brim, visor, lean, nose guard, or other asymmetric detail; do not shift the whole silhouette far off-center. Make asymmetric parts read correctly after mirroring. Identity-bound eye accessories may opt out of mirroring and use a direction-specific eye anchor so they remain on the same eye; the Top Hat & Monocle is the reference. Fixed-eye anchors must include the body origin shift for wide frames (frameWidth - 96). Review every appearance in both directions with the facing fixture.