aavegotchi-sprites-generator-skill

name	aavegotchi-sprites-generator-skill
description	Generate official-style Aavegotchi game sprites and animated GIFs with the upstream gotchi-generator package. Use when the user wants sprite-sheet style outputs rather than OG SVG renders or 3D renders.

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