Package Exports
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@codexstar/pi-pompom) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
pi-pompom
A 3D raymarched virtual pet that lives in your terminal.
Install · Quick Start · Commands · Shortcuts · Features
Pompom is an interactive companion for Pi CLI. It renders a real-time 3D raymarched creature above your editor using Unicode half-block characters with 4x4 supersampled anti-aliasing. Pompom walks, sleeps, chases fireflies, plays fetch, dances, and reacts to your commands.
Install
pi install @codexstar/pi-pompomQuick Start
Pompom appears automatically when you start Pi. Toggle it with:
/pompom on
/pompom offCommands
| Command | What it does |
|---|---|
/pompom |
Toggle companion on/off |
/pompom help |
Show all commands and shortcuts |
/pompom status |
Check mood, hunger, energy, theme |
/pompom pet |
Pet Pompom |
/pompom feed |
Drop food |
/pompom treat |
Special treat (extra hunger boost) |
/pompom hug |
Give a hug (restores energy) |
/pompom ball |
Throw a ball |
/pompom dance |
Dance with sparkle particles |
/pompom music |
Sing a song |
/pompom theme |
Cycle color theme |
/pompom sleep |
Nap on a pillow |
/pompom wake |
Wake up |
/pompom flip |
Do a backflip |
/pompom hide |
Wander offscreen |
Keyboard Shortcuts
Pompom responds to Alt/Option + key while the companion is active.
| macOS | Windows/Linux | Action |
|---|---|---|
⌥p |
Alt+p |
Pet |
⌥f |
Alt+f |
Feed |
⌥t |
Alt+t |
Treat |
⌥h |
Alt+h |
Hug |
⌥b |
Alt+b |
Ball |
⌥x |
Alt+x |
Dance |
⌥m |
Alt+m |
Music |
⌥c |
Alt+c |
Theme |
⌥s |
Alt+s |
Sleep |
⌥w |
Alt+w |
Wake |
⌥d |
Alt+d |
Flip |
⌥o |
Alt+o |
Hide |
Shortcuts work across macOS (Option key), Windows (Alt key), and Linux (Alt key). Four input methods are supported: Ghostty keybinds, ESC prefix, macOS Unicode, and Kitty keyboard protocol.
Features
- 3D raymarched body with real-time lighting, shadows, and floor reflections
- 4x4 supersampled anti-aliasing (16 samples per pixel)
- Natural blinking, breathing, ear wiggling, and tail wagging
- Day/night sky cycle based on system clock
- Particle effects: sparkles, music notes, rain, crumbs, sleep Zs
- Speech bubbles with random idle chatter (12 phrases)
- Firefly companion that Pompom chases
- Hunger and energy needs system with visual status bars
- Ball physics with bouncing and fetch behavior
- 4 color themes: Cloud, Cotton Candy, Mint Drop, Sunset Gold
- Dark body outline for visibility against any background
- Compact status bar with live state messages
- Crash-isolated rendering: errors never take down the host TUI
- Namespaced widget ID to prevent conflicts with other extensions
How It Works
The renderer is a software raymarcher running in your terminal. Each frame:
- Physics simulation updates position, particles, and state machines (60fps sub-stepping)
- Scene objects (body, ears, paws, tail, antenna, ball, food) are built with rotation and oscillation
- For each character cell, 16 rays are cast (4x4 grid) and the colors averaged for anti-aliasing
- Object hits are shaded with diffuse + wrap lighting, ambient occlusion, specular highlights, and firefly point light
- The shaded pixels are encoded as ANSI true-color escape sequences using
▀half-block characters - Speech bubbles and particle overlays are composited on top
The widget re-renders at ~7 FPS via a 150ms setInterval.
Configuration
Set POMPOM_NO_KITTY=1 to force half-block rendering on terminals that report Kitty support but don't handle it well.
Contributing
See CONTRIBUTING.md for development setup and guidelines.
Security
See SECURITY.md for reporting vulnerabilities.
License
MIT. See LICENSE.