98 lines
2.7 KiB
Markdown
98 lines
2.7 KiB
Markdown
# HyperPets
|
|
|
|
Animated pets for [Hyper](https://hyper.is) terminal panes.
|
|
|
|
The first pass includes:
|
|
|
|
- one or two pets per pane
|
|
- idle, wander, sleep, cursor-chase, and toy-chase behavior
|
|
- bounded toy spawning with cooldowns
|
|
- lightweight per-pane overlay rendering
|
|
- external cat sprite assets with state transitions between major behaviors
|
|
|
|
## Install locally during development
|
|
|
|
1. Put this folder somewhere stable.
|
|
2. Add `hyperpets` to `localPlugins` in your Hyper config.
|
|
|
|
```js
|
|
module.exports = {
|
|
config: {
|
|
hyperPets: {
|
|
petCount: 1,
|
|
petTypes: ['cat'],
|
|
maxToys: 1,
|
|
toyCooldownMs: 20000,
|
|
successToyChance: 0.35,
|
|
walkSpeed: 0.45,
|
|
animationSpeed: 0.5,
|
|
sleepMinDurationMs: 30000,
|
|
sleepMaxDurationMs: 180000,
|
|
debugFrames: false
|
|
}
|
|
},
|
|
localPlugins: [
|
|
'hyperpets'
|
|
]
|
|
};
|
|
```
|
|
|
|
On macOS the config file is typically:
|
|
|
|
`~/Library/Application Support/Hyper/.hyper.js`
|
|
|
|
Then reload Hyper with `Cmd+R`.
|
|
|
|
## Config
|
|
|
|
```js
|
|
hyperPets: {
|
|
enabled: true,
|
|
petCount: 1,
|
|
petTypes: ['cat'],
|
|
maxToys: 1,
|
|
toyCooldownMs: 20000,
|
|
successToyChance: 0.35,
|
|
chaseCursorChance: 0.04,
|
|
walkSpeed: 0.45,
|
|
animationSpeed: 0.5,
|
|
sleepMinDurationMs: 30000,
|
|
sleepMaxDurationMs: 180000,
|
|
debugFrames: false,
|
|
reducedMotion: false,
|
|
onlyActivePane: true
|
|
}
|
|
```
|
|
|
|
## Notes
|
|
|
|
- Command-success toy spawning currently uses a prompt-return heuristic from terminal output, not shell integration.
|
|
- The plugin is intentionally conservative so it does not flood panes with toys or constant motion.
|
|
- The current animation system uses asset manifests under `assets/pets/`. `cat` is currently aliased to the Maple sprite sheet so existing configs keep working.
|
|
|
|
## Asset Pipeline
|
|
|
|
- Cat frames live in `assets/pets/cat/frames/*.svg`.
|
|
- The cat manifest in `assets/pets/cat.js` maps clips and transitions to those frame files.
|
|
- Maple lives in `assets/pets/maple/` and is wired as a sprite-sheet asset through `assets/pets/maple.js`.
|
|
- The renderer supports both individual SVG frames and sprite-sheet cells behind the same clip API.
|
|
- To add a new pet type later, create another manifest under `assets/pets/` plus a matching frame directory, then register it in `assets/pets/index.js`.
|
|
|
|
## Sheet Tools
|
|
|
|
- Split a uniform sheet into per-frame PNGs:
|
|
|
|
```bash
|
|
bash scripts/split_sprite_sheet.sh assets/pets/maple/spritesheet.webp 192 208 assets/pets/maple/frames maple
|
|
```
|
|
|
|
- Stitch a frame directory back into a sheet:
|
|
|
|
```bash
|
|
bash scripts/stitch_sprite_sheet.sh assets/pets/maple/frames 8 9 /tmp/maple-sheet.png maple
|
|
```
|
|
|
|
## Debugging
|
|
|
|
- Set `hyperPets.debugFrames` to `true` to show the active clip, frame number, facing direction, sprite-sheet row/column, and a rolling history of the last 5 displayed frames beside each pet.
|