balaur

Balaur avatars and sprites

Balaur avatars use one canonical source:

1. Per-avatar 64×64 PNG sprite sheets — source of truth under pi/assets/avatars/.
2. Kitty PNG render — proper pixel-art image avatar when the terminal supports Kitty graphics.
3. ASCII badge — maximum-compatibility fallback when image avatars are unsupported.
4. Generated ANSI pixel renderer — explicit/debug backend only, derived from the PNG frame.

Do not maintain separate PNG and ASCII art by hand. New avatars start as 64×64 frames in their own sprite sheet, then the renderers scale/degrade them for the terminal.

Current art direction follows Basm: 16-bit, woven, Romanian-fairy-tale pixel craft. Balaur is a wise dragon — calm ancient eyes, horns/crest, gold/umber body, restrained teal/ember accents. The human/user is a mage — pointed hood/hat, robe, staff/glow, indigo/teal palette.

Avatar mode and backend

Configured by .env:

BALAUR_AVATAR_MODE=avatar   # portrait only; default
BALAUR_AVATAR_MODE=badge    # ASCII nameplate only; safest fallback
BALAUR_AVATAR_MODE=both     # portrait with badge underneath

BALAUR_AVATAR_BACKEND=auto  # default: Kitty image when supported, badge otherwise
BALAUR_AVATAR_BACKEND=image # prefer image; still falls back to badge if unsupported
BALAUR_AVATAR_BACKEND=ansi  # force generated terminal pixel renderer for debugging
BALAUR_AVATAR_RECENT_LIMIT=10 # rich image avatars only for latest N panels; 0 = active-only; all = uncapped

Legacy aliases still work: ascii -> badge, pixel -> avatar; backend aliases include kitty/png -> image and blocks/text -> ansi.

In a running terminal session:

/balaur-avatar [badge|avatar|both] [auto|image|ansi]

This changes the current session; edit .env to persist. If unset or unknown, Balaur uses avatar + auto.

Rendering rules

• auto uses Kitty-compatible image rendering only when Pi reports getCapabilities().images === "kitty".
• Under tmux or unsupported terminals, Balaur falls back to text badges rather than terminal image escapes.
• badge remains pure text and works everywhere.
• iTerm2 image support exists in Pi, but Balaur’s inline chat gutter currently uses the Kitty path only; iTerm2 falls back to badges for consistency.
• Chat messages, input editor, and tool panels use the same avatar renderer path; animation keeps stable image IDs to reduce churn.
• For long conversations, rich image avatars are capped to recent panels by BALAUR_AVATAR_RECENT_LIMIT so old history falls back to badges instead of keeping many terminal images alive.
• Tool avatars animate only while the tool is actively running; pending/ok/error panels render frame 0 with their state background.
• The transient thinking panel is a Balaur-owned widget, not Pi’s built-in Loader/Text row. In Kitty-capable terminals it renders PNG sprite frames with a stable image ID; unsupported terminals fall back to badges. The old Loader/Text fallback remains ANSI-only because that path cannot safely repaint animated image escapes.

Sprite sheets

Every avatar-like entity owns a dedicated 3×3 sheet: 9 frames, each 64×64 px.

pi/assets/avatars/mage.png          3 columns × 3 rows, 9 frames, 64×64 each
pi/assets/avatars/balaur.png        3 columns × 3 rows, 9 frames, 64×64 each
pi/assets/avatars/tools/scroll.png  3 columns × 3 rows, 9 frames, 64×64 each
pi/assets/avatars/tools/needle.png  3 columns × 3 rows, 9 frames, 64×64 each
...

Index files live beside each image:

pi/assets/avatars/mage.txt
pi/assets/avatars/balaur.txt
pi/assets/avatars/tools/<tool>.txt

Frame 0 is idle/base. Frames 1–8 are animation variants for that avatar. The user/human role uses the mage sheet; Balaur uses the balaur sheet; each tool/domain icon uses its own sheet under tools/. Do not add another shared mixed sprite sheet.

Nameplate fallback

[ cico   ] | user message
[ Balaur ] | assistant message

Rules:

• Fixed-width gutter across all roles.
• ASCII brackets and divider by default: [ Name ] |.
• Keep visible labels simple: no @, B, ?, or T prefix inside badges.
• Role color lives inside the brackets; divider stays muted/smoke.
• Never let message background color bleed into the gutter.

Portrait mode

avatar mode renders the portrait in the left RPG dialog cell; it does not show the badge/nameplate:

+----------+----------------+
|          | message        |
| portrait |                |
| portrait |                |
|          |                |
+----------+----------------+

both mode shows the simple [ Name ] badge under the portrait inside the same cell. Tool panels use sprite-sheet pixel icons on the same rail and follow the same both badge rule.

Implementation:

• Mode/backend helpers: ../pi/lib/ui/sprites.ts
• Sprite-sheet renderers: ../pi/lib/ui/pixel-avatar.ts (legacy filename)
• Message renderer patch: ../pi/lib/ui/avatars.ts
• Editor panel: ../pi/lib/ui/editor.ts
• Working/thinking panel: ../pi/lib/ui/working.ts

Palette

The sprite sheet uses the Basm palette family:

outline / ink
smoke shadow
parchment highlight
gold / umber
ember
folk red
teal accent
indigo / indigo shadow
skin / parchment
transparent

The left avatar cell has a role/state background so the portrait fills the whole box:

user       muted indigo field
Balaur     dark umber/gold field
thinking   dark teal field
tool       state-tinted field

Tool icons are generated pixel icons, color/background-tinted by state:

pending    gold / umber
running    bright parchment / steel
success    teal
error      folk red / ember

Evolution rules

Sprites can evolve over time, but each change should remain:

• single-source: edit that avatar’s canonical 3×3, 9-frame, 64×64 PNG sprite sheet, not separate PNG/ASCII copies;
• versioned in git;
• documented here;
• legible in screenshots;
• compact enough for daily chat;
• fallback-safe through BALAUR_AVATAR_MODE=badge and BALAUR_AVATAR_BACKEND=ansi.

Future work: add richer multi-frame pixel animations per tool/state without adding a second avatar implementation.

This site is open source. Improve this page.