For the following examples, we will use Jelly the tiny bird, whose BBS cart ID is jelly.
Substitute ./desktopPet.p64 for the location of the cart on your system. For example, if you saved it as /carts/pet.p64.png, the help command becomes /carts/pet.p64.png --help. All help text is dynamic and will update to say this path.

You can pass --help when running the cart from the terminal to get a printout of installed characters and how to use the command:

> ./desktopPet.p64 --help

This is also where the cart will tell you the path custom characters can be manually installed in, as well as the following extra commands:

To install a character from the BBS:

> ./desktopPet.p64 --install jelly

The cart will download the cart with ID jelly from the Lexaloffle BBS (here!) and save it into the custom characters path. (currently /appdata/cubee/pet/)
As of rev5b, this will also check if it's a valid character and if a character with the same name already exists. It will only replace it if the downloaded meta.version is greater than the installed one. Use --force-install to ignore all checks.

Then, you can run DesktopPet using that character:

> ./desktopPet.p64 jelly

To delete an installed character:

> ./desktopPet.p64 --remove jelly

Put your work-in-progress characters in /appdata/cubee/pet/ and the program will allow you to load them.
If you want your character to be easily discoverable, you can post the cart directly in this thread if you like, or make your own thread and use the tag #desktop-pet.

If you'd like a template character, install scribble_base. It comes with everything needed, as well as more in-depth instructions and a simple preview/label image when run on its own.

Characters use the following format:

character.p64/
- gfx/
--- 0.gfx
- meta.pod
- main.lua

main.lua isn't used by DesktopPet, but you can make a nice little preview of your character if you like! Or an auto-install script, idk. scribble_base has a simple animation of the pet jumping, saying to use the cart with DesktopPet.
0.gfx is your character's spritesheet. The most important part!
meta.pod is required for the cart to allow installation from the BBS, though most values are optional. It provides the following metadata:

name - the pet's name
version - the version of the pet. must be a number!
author - name for the person who made the pet
l - left padding for floors
r - right padding for floors
wl - left padding for climbing walls
wr - right padding for climbing walls
t - top padding
b - bottom padding

Version is used to determine if DesktopPet should automatically replace an installed cart or not. Use --force-install if you need to install an older version of a cart. This is the only "required" field. It must be a number for version checking to function correctly. (i.e. 1.2 is fine but entering 1.2.3, 1.1a, or no may crash the cart)
The pet and author names are displayed when running DesktopPet from the terminal, and when using the template main.lua.
Positive padding increases the size of the pet's collider, while negative padding shrinks the collider. Useful for if your character starts "floating" on the edges of windows.
At the top of DesktopPet's main.lua, you can set debug mode to show colliders.

If you made too many or want to get rid of them, you can grab them with the mouse and press [X] to send them away.

If you'd like to have it autostart when Picotron opens, save the cart file somewhere, then edit or create "/appdata/system/startup.lua" and add the line:

create_process("/carts/desktopPet.p64")

... changing the path to lead to the cart file you just saved.
This will simply start the cart with in the default workspace (the Desktop) as soon as Picotron boots, with a randomly-select pet from the ones installed.

To change the character used when run from startup.lua you would add the following argv parameter:

create_process("/carts/desktopPet.p64", {argv = {"jelly"}})

Where jelly is replaced with the character's name as shown in the --help output.

As of rev2 (BBS release), you can now:

• Give them head pats. Sometimes they will go to sleep afterward.
• Pick them up.
• Place them on the side of the screen.
• Wake them up from sleep.
• Interrupt them when they jump; to catch them or make them fall.

As of rev3, they will jump to and sit on desktop icons!
You can place them on the icons yourself too, or move the icon and they will fall. Sometimes they will fall off on their own, heh.
^^ rev3a fixes a crash in the BBS player due to it lacking desktop icon metadata.

As of rev4/5, you can add custom characters and select them using the command line! See the Custom/BBS Pets section for more information.
The cart currently includes only Scribble the cat, but more can be added easily.

And new in rev5:

• Thanks to @Palette, pets can now walk on windows, and appear in front of them at all times.
• Extra commands to install and uninstall custom pet carts from the BBS!
• Launching the cart without any parameters will select a random pet.
• A new, colourful help printout.
• Jelly is no longer included by default due to issues saving more than one pet.p64 in the main cart .png. You may install him again by running with --install jelly instead of just jelly.

^^ rev5a bugfix:

• Fixed icon colliders being offset weirdly depending on pet collider size. They are also slightly shorter to line up with the bottom (even though the pets don't currently collide with the bottom)
• Fixed accidentally making pets fall unconscious sometimes when dropped.
• Fixed characters failing to load if the (supposedly optional) meta.pod file was missing.

^^ rev5b patch:

• DesktopPet now has version checking in place so BBS pets will only be overwritten if the downloaded version is newer than the installed one.
• There are now checks to prevent "invalid" (i.e. non-pet) BBS carts from being installed. These can still be installed and used manually if desired.
• All of the above checks can be ignored/skipped by running with --force-install instead of --install