aavegotchi-sprites-generator-skill

This skill generates Aavegotchi game sprites by wrapping the official gotchi-generator package from aavegotchi/aavegotchi-game-sprites.

When to use it

Use this skill when the user wants:

game sprite style gotchi art
sprite PNG output
animated sprite GIF output
trait-layer compositing based on official sprite assets
retro or battle-sprite style gotchi output
batch sprite generation from gotchi JSON payloads

Do not use this skill when the user wants:

OG onchain SVG style output
3D gotchi renders

Chat-first behavior

For Telegram or normal chat replies, prefer:

bash ./scripts/show-gotchi-sprite.sh ...

That helper prints:

SPRITE_MEDIA
GIF_MEDIA
CAPTION_SPRITE
CAPTION_GIF
SUMMARY

and always uses a fresh output folder so chat replies do not reuse stale files.

For Telegram delivery:

animated sprite GIF requests should send GIF_MEDIA as a downloadable file/document using filePath
static sprite replies can still send SPRITE_MEDIA as normal media
do not send animated GIF replies as Telegram animated media if the goal is to preserve the actual .gif file

Background logic

Background logic matches the gotchi SVG skill:

default background: common
explicit transparent: transparent output
explicit uncommon, rare, legendary, mythical, godlike: use that exact rarity color

Official colors:

common -> #806AFB
uncommon -> #20C9C0
rare -> #59BCFF
legendary -> #FFC36B
mythical -> #FF96FF
godlike -> #51FFA8

GIF behavior

GIFs are generated by default
GIFs are the default chat output
default GIF row sequence: idle (row 0)
default FPS: 12
default GIF scale: 1x
default canvas size: 250x250
default body placement: centered on the canvas vertical axis and anchored 3px upward
default gotchi zoom: 100%
supported zoom sizes: 25%, 50%, 100%

Supported row presets:

idle
fly
throw
attack
hurt
death
all
or a custom numeric list like 0,2,3

Natural-language mapping

The wrapper accepts friendly aliases.

Collateral aliases

ETH -> aWETH
DAI -> aDAI
USDC -> aUSDC
USDT -> aUSDT
AAVE -> aAAVE
LINK -> aLINK
TUSD -> aTUSD
WBTC -> aWBTC
UNI -> aUNI

Eye presets

Use the closest sprite preset for plain-language eye requests:

common eyes -> --eye-shape common --eye-color common
uncommon high eyes -> --eye-shape uncommon_high --eye-color uncommon_high
uncommon low eyes -> --eye-shape uncommon_low --eye-color uncommon_low
rare high eyes -> --eye-shape rare_high --eye-color rare_high
rare low eyes -> --eye-shape rare_low --eye-color rare_low
mythical high eyes -> --eye-shape mythic_high --eye-color mythical_high
mythical low eyes -> --eye-shape mythic_low --eye-color mythical_low

If the user only says common, uncommon, rare, or mythical, use the closest high variant by default.

Commands

Full JSON request

node ./scripts/render-gotchi-sprite.mjs \
  --input ./Requests.sample.json \
  --output-dir ./output/sample

Slot-based request

node ./scripts/render-gotchi-sprite.mjs \
  --id 999001 \
  --collateral ETH \
  --eye-shape common \
  --eye-color common \
  --body "Witchy Cloak" \
  --background mythical \
  --gif-rows all \
  --frame-size 80 \
  --output-dir ./output/custom

Chat helper

bash ./scripts/show-gotchi-sprite.sh \
  --collateral ETH \
  --eye-shape common \
  --eye-color common \
  --body "Witchy Cloak" \
  --background common

Response format

When using this skill, report:

sprite PNG path
sprite GIF path when available
manifest JSON path
whether generation succeeded
any missing layer warnings

Implementation notes

The upstream package expects Node.js and filesystem access.
The wrapper script loads the package config from getPackageBasePath().
If generation fails because trait values do not match asset names, return the missing layer details instead of guessing.

Frame crop behavior

default source frame size: 100x100
default output canvas: 250x250
--frame-size 80 crops each source sprite frame to 80x80 before layout
--canvas-size 250 controls the final output canvas per frame
hands and pets do not shift the body anchor used for placement
Telegram/chat prompts can say 80x80 cropped canvas or tight crop when they want a tighter source crop

Zoom behavior

default zoom: 100%
--zoom 50 centers the gotchi at half-size in each sprite frame
--zoom 25 centers the gotchi at quarter-size in each sprite frame
Telegram/chat prompts can say 25% zoom or 50% zoom