# 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.