Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,13 @@ tmp/
.env.*
!.env.example

# Python
__pycache__/
*.py[cod]

# Python virtual environments (the pet importer's Pillow lives in one)
.venv/

# Claude Code's working directory: local settings, and the throwaway worktrees
# subagents are given. Those worktrees are checkouts of this repository, so
# committing one would nest a clone inside itself.
Expand Down
91 changes: 90 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,7 +129,7 @@ Three, and each earns its place:
| Toolchain | Needed for | Needed to build? |
|---|---|---|
| **Rust** | everything: the core crate, the Tauri shell | yes |
| **Python** | `pre-commit`, and the Characters' frame generators | no |
| **Python** | `pre-commit`, the Characters' frame generators, and the pet importer (the one script that needs Pillow) | no |
| **Node** | the renderer's unit tests, and nothing else | no |

Node is the newest and the least obvious, so: the webview front end has been
Expand Down Expand Up @@ -491,6 +491,89 @@ python3 scripts/make-blip-character.py
Standard library only, so there is nothing to install, which is the same reason
Nim is generated the same way.

### Importing a pet

`scripts/import-pet.py` translates a pet from another desktop-pet ecosystem
into a Character Package, once. An authoring tool rather than a build step: the
output lands in a directory you review, hand-tune, and own — not a runtime
dependency and not a live bridge (#112). It is the one script allowed to need
Pillow, because petscodex ships webp sprite sheets and decoding webp rules out
the standard library.

Two formats have adapters:

- **petscodex** — [petscodex.com](https://petscodex.com/)'s fixed-grid sprite
sheets. `npx petscodex install <id>` lands a pack at `~/.codex/pets/<id>/`;
the importer slices it by petdex's row semantics and builds the whole
Required Animation Set, with `waiting` as an idle `variant_of` ring member.
- **shimeji** — Shimeji-ee packs: per-pose PNGs plus the pack's `actions.xml`
naming pose sequences, every frame mirrored to head right. A pack of bare
`shime*.png` files with no conf (shimejishop distributes these) rides
Shimeji-ee's standard conf instead.

Pillow lives in a [uv](https://docs.astral.sh/uv/)-managed virtual
environment, never in a system Python:

```sh
uv venv
uv pip install pillow

npx petscodex list
npx petscodex install labubu
.venv/bin/python scripts/import-pet.py ~/.codex/pets/labubu --format petscodex \
-o characters/labubu --accept-license
cd src-tauri && AI_BUDDY_CHARACTER=labubu cargo run
```

The first run after an import rebuilds, which refreshes the shipped-character
copy beside the binary; `AI_BUDDY_CHARACTERS=/path/to/characters` skips the
rebuild by searching the directory itself.

The importer notices a missing Pillow and says exactly this rather than
tracing back.

A `.zip` works as a source wherever a directory does, `--force` replaces an
existing output directory, and `--stand` names the on-screen height in
logical pixels when the default band (100–130, where a shimeji stands) is
not the right size for the pet. The importer prints the pet's license and
refuses a silently-unknown one without `--accept-license`; an import is a
development asset unless its license says otherwise, and one that ships gets a
line in [Prior art and attribution](#prior-art-and-attribution). Success is
declared only after `character::load` accepts the output, through a validator
that is also useful on its own:

```sh
cargo run -p ai-buddy-core --example validate -- characters/labubu
```

Then look at the frames — the tool says so at the end of every run, because
two things are the reviewer's to judge, not code's:

- **Walk must head right**; the Engine's facing mirrors it for leftward
travel. Every petscodex pet sampled so far draws petdex's "running-right"
row heading left, so the importer cuts walk from the other row by default.
`--walk-row 1` picks the first row anyway, and `--mirror-walk` flips
whichever row is chosen, for the pet whose only clean walk heads left.
- **Sleep must read as sleep.** petscodex has no sleep row, so the importer
synthesizes one: idle's stillest frame, twice, the second lifted a pixel as
the breath. Swap in a better pose when the sheet has one.
- **Every animation must read as its name.** The row semantics are labels
each generated pet interprets loosely — one pet's "jumping" row is a sword
lunge, and its sleeping art lives in the "waiting" row. `--map` recuts an
animation from the row the pet actually drew: `--map sleep=6:2,3` takes
frames 2 and 3 of row 6, `--map react=7` takes all of row 7. Remaps are
recorded in the manifest header.
- **A personality is authored, never derived.** The importer writes no
`personality.txt` — the pet's own description is provenance, not a voice.
Write one that fits the art, the way the shipped characters' read.

`characters/cat/` is the first shipped import — petscodex's `cat`, with the
defaults. The importer's self-test runs with no pet installed:

```sh
.venv/bin/python scripts/import-pet.py --self-test
```

## Prior art and attribution

[WindowPet](https://github.com/SeakMengs/WindowPet) (MIT) is the reference for a
Expand All @@ -511,6 +594,12 @@ flipped to head right, with a one-pixel breathing shift added for sleep. BMO
is Cartoon Network IP and the pack is fan art; the character is a development
asset, and none of this repository's license claims cover that art.

Cat's frames are cut from the [petscodex](https://petscodex.com/pets/cat) pet
`cat` by `scripts/import-pet.py` (#112). The installed package declares no
license, so the import was accepted with `--accept-license`; the character is
a development asset, and none of this repository's license claims cover that
art.

## License

MIT.
89 changes: 89 additions & 0 deletions characters/cat/character.manifest
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
# Cat imported from petscodex (petdex) by scripts/import-pet.py.
# Source pet id: cat — https://petscodex.com/pets/cat
# Source description: A chibi gray-and-white Scottish Fold cat Codex pet based on the reference photo.
# Mapping: idle<-row 0, walk<-running-left row 2
# (the row drawn heading right), talk<-waving row 3,
# fall/land/hold<-jumping row 4, react<-failed row 5, waiting<-row 6
# (idle variant), sit<-review row 8; sleep is idle's stillest frame
# with a one-pixel breath. The other walk row (the engine mirrors
# instead) and row 7 (running in place) go unused.
# Remapped for this pet's art (--map): sleep<-row 5[2].
# License: none declared anywhere in the source ecosystem;
# accepted at import with --accept-license. A development asset
# unless a license surfaces — this repository's license claims
# do not cover the art.

name = "Cat"
render_mode = "smooth"
scale = 1

[animations.idle]
frames = ["frames/idle-0.png", "frames/idle-1.png", "frames/idle-2.png", "frames/idle-3.png", "frames/idle-4.png", "frames/idle-5.png"]
fps = 5

[animations.waiting]
frames = ["frames/waiting-0.png", "frames/waiting-1.png", "frames/waiting-2.png", "frames/waiting-3.png", "frames/waiting-4.png", "frames/waiting-5.png"]
fps = 6
variant_of = "idle"

[animations.walk]
frames = ["frames/walk-0.png", "frames/walk-1.png", "frames/walk-2.png", "frames/walk-3.png", "frames/walk-4.png", "frames/walk-5.png", "frames/walk-6.png", "frames/walk-7.png"]
fps = 8

[animations.talk]
frames = ["frames/talk-0.png", "frames/talk-1.png", "frames/talk-2.png", "frames/talk-3.png"]
fps = 6

[animations.fall]
frames = ["frames/fall-0.png", "frames/fall-1.png"]
fps = 6

[animations.land]
frames = ["frames/land-0.png", "frames/land-1.png"]
fps = 6
loop = "once"

[animations.hold]
frames = ["frames/hold-0.png", "frames/hold-1.png"]
fps = 6

[animations.react]
frames = ["frames/react-0.png", "frames/react-1.png", "frames/react-2.png", "frames/react-3.png", "frames/react-4.png", "frames/react-5.png", "frames/react-6.png", "frames/react-7.png"]
fps = 7
loop = "once"

[animations.sit]
frames = ["frames/sit-0.png", "frames/sit-1.png", "frames/sit-2.png", "frames/sit-3.png", "frames/sit-4.png", "frames/sit-5.png"]
fps = 6

[animations.sleep]
frames = ["frames/sleep-0.png"]
fps = 1

# A starter life, copied from BMO's — tune it to the pet.
[behaviors.walk]
play = ["walk"]
weight = 1
when = "idle over 30s"

[behaviors.patrol]
play = ["walk", "idle", "walk"]
then = "walk"
weight = 3
when = "idle over 2m"

[behaviors.fidget]
play = ["idle"]
weight = 2
when = "idle over 10s"

[behaviors.report]
play = ["talk", "idle", "talk"]
weight = 3
when = "idle under 1m"

[behaviors.greet]
play = ["talk"]
then = "patrol"
weight = 4
when = "idle under 10s"
Binary file added characters/cat/frames/fall-0.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/fall-1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/hold-0.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/hold-1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/idle-0.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/idle-1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/idle-2.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/idle-3.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/idle-4.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/idle-5.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/land-0.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/land-1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/react-0.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/react-1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/react-2.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/react-3.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/react-4.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/react-5.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/react-6.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/react-7.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/sit-0.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/sit-1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/sit-2.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/sit-3.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/sit-4.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added characters/cat/frames/sit-5.png
Binary file added characters/cat/frames/sleep-0.png
Binary file added characters/cat/frames/talk-0.png
Binary file added characters/cat/frames/talk-1.png
Binary file added characters/cat/frames/talk-2.png
Binary file added characters/cat/frames/talk-3.png
Binary file added characters/cat/frames/waiting-0.png
Binary file added characters/cat/frames/waiting-1.png
Binary file added characters/cat/frames/waiting-2.png
Binary file added characters/cat/frames/waiting-3.png
Binary file added characters/cat/frames/waiting-4.png
Binary file added characters/cat/frames/waiting-5.png
Binary file added characters/cat/frames/walk-0.png
Binary file added characters/cat/frames/walk-1.png
Binary file added characters/cat/frames/walk-2.png
Binary file added characters/cat/frames/walk-3.png
Binary file added characters/cat/frames/walk-4.png
Binary file added characters/cat/frames/walk-5.png
Binary file added characters/cat/frames/walk-6.png
Binary file added characters/cat/frames/walk-7.png
10 changes: 10 additions & 0 deletions characters/cat/personality.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
Cat is a small gray-and-white Scottish Fold that has decided the desk is
territory. Calm, self-possessed, and quietly affectionate: it supervises the
work from wherever it sits, blinks slowly at what it approves of, and waves a
paw once rather than asking twice.

Everything it does is deliberate, including ignoring you — sitting with its
back turned is still keeping you company. It lands every jump like the landing
deserves applause, sulks where you can see it when something fails, and curls
up to sleep the moment nothing needs supervising. Speaks in short, unhurried
sentences: mostly observations, occasionally verdicts.
60 changes: 60 additions & 0 deletions crates/core/examples/validate.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
//! Validate a Character Package directory with `character::load`.
//!
//! ```sh
//! cargo run -p ai-buddy-core --example validate -- characters/cat
//! ```
//!
//! `scripts/import-pet.py` runs this before declaring an import a success;
//! the shell's own reader adds archive and size handling this example does
//! not need, so the walk here stays a plain recursive read.

use std::collections::BTreeMap;
use std::path::Path;
use std::process::ExitCode;

use ai_buddy_core::character;

fn collect(root: &Path, dir: &Path, files: &mut BTreeMap<String, Vec<u8>>) -> std::io::Result<()> {
for entry in std::fs::read_dir(dir)? {
let path = entry?.path();
if path.is_dir() {
collect(root, &path, files)?;
} else {
let name = path
.strip_prefix(root)
.expect("every walked path starts at the root")
.components()
.map(|part| part.as_os_str().to_string_lossy())
.collect::<Vec<_>>()
.join("/");
files.insert(name, std::fs::read(&path)?);
}
}
Ok(())
}

fn main() -> ExitCode {
let Some(root) = std::env::args().nth(1) else {
eprintln!("usage: validate <package-directory>");
return ExitCode::FAILURE;
};
let root = Path::new(&root);
let mut files = BTreeMap::new();
if let Err(why) = collect(root, root, &mut files) {
eprintln!("{}: {why}", root.display());
return ExitCode::FAILURE;
}
match character::load(&files) {
Ok(character) => {
println!("{} is a valid Character Package", character.name);
ExitCode::SUCCESS
}
Err(errors) => {
eprintln!("{} is not a valid Character Package:", root.display());
for error in errors {
eprintln!(" - {error}");
}
ExitCode::FAILURE
}
}
}
Loading
Loading