WhimsyDesk

Make your own object

From nothing to your own object on your desktop in about 15 minutes, then as long as you like on the art. No Swift needed.

You start from a template: a wooden crate that already opens, closes, stores files, gives them back and remembers where it sits. You swap in your art, describe it, and send it in.

What you need

You can use any editor, but Phoenix Code with the Desktop Objects Studio extension makes the visual parts easier:

To install it, open the Extension Manager in Phoenix Code (the building-block icon in the right-hand toolbar), search for Desktop Objects Studio, and click Install. Then click the fridge icon in the same toolbar to open the panel.

1. Get your own copy

  1. Open github.com/Electrofist/whimsydesk and click Fork. This makes your own copy on GitHub.
  2. Download your copy. In Phoenix Code: Start Project, Get from Git, paste https://github.com/your-username/whimsydesk.git and pick a folder. Or in Terminal (replace your-username):
git clone https://github.com/your-username/whimsydesk.git
cd whimsydesk

2. Create your object

Pick a name and run (replace the name and username):

scripts/new-object.sh "Toaster" your-username

This creates objects/toaster/ with everything inside, ready to build.

In Phoenix Code with the extension, choose File, New Desktop Object… instead. It does the same thing.

3. See it on your desktop

In Terminal, or Phoenix Code's terminal panel:

cd objects/toaster
bash build.sh run

The first build takes a minute or two. A wooden crate appears at the lower left of your screen, behind your windows, just above the desktop icons.

Try it:

4. Draw your art

Your object is two pictures: Art/closed.png and Art/open.png.

Replace the two files, keep their names, then quit the object and run ./build.sh run again.

5. Tell it where files go

When your object is open, stored files are laid out inside one rectangle. Set it in object.json:

"look": {
  "itemsArea": [0.12, 0.12, 0.76, 0.74],
  "iconSize": 48
}

The four numbers are x, y, width and height, as fractions of your image, measured from the bottom left.

Working it out from your design: if your image is 560 x 480 px and the inside of your toaster starts 60 px from the left, 120 px up from the bottom, and is 440 px wide and 200 px tall, then:

iconSize is the size of file icons in points, from 24 to 128.

6. Add an app icon (optional, but people love it)

Design a square icon on a plain background (any colour) and save it as PNG or JPG. Then, from the top folder of the repo:

swift scripts/make-icon.swift ~/Desktop/my-icon.png objects/toaster/Art

It removes the background, places the icon on Apple's icon grid with a soft shadow, and writes Art/AppIcon.icns. The next ./build.sh run uses it.

7. Add sounds (optional)

Put open.wav and close.wav in the Sounds folder. Keep them short and quiet. Leave them out for a silent object.

8. Describe it

In object.json, write your own tagline (one line) and description (a few sentences). In README.md, describe how to use it.

Record a short clip: press Shift + Command + 5, choose Record Selected Portion, and capture your object opening and taking a file. Turn the video into a GIF with a free tool like Gifski, save it as media/hero.gif in your object's folder, and add "media/hero.gif" to screenshots in object.json.

9. Check it

From the top folder of the repo:

scripts/check-objects.sh

Fix anything it lists. It catches missing details, template text you forgot to replace, and art or build files that are missing.

10. Send it in

In Phoenix Code, use the Git panel: make a new branch, commit objects/toaster and .github/CODEOWNERS, and push. Or in Terminal:

git checkout -b add-toaster
git add objects/toaster .github/CODEOWNERS
git commit -m "Add Toaster"
git push -u origin add-toaster

Open your fork on GitHub. Click Compare & pull request, fill in the checklist, attach your GIF, and submit. GitHub checks and builds your object automatically. If something fails, the pull request shows what, and you can push a fix to the same branch.

Going further

The template covers the basics. Anything beyond it, like a door that swings with weight, frost, or a drawer that slides, is Swift code. The fridge (objects/fridge) and the drawer (objects/drawer) show how, and an AI coding assistant can help you change the template's code in Sources/.

Whatever you add, keep the rules in CONTRIBUTING.md: files are moved, never lost; Put Back works; nothing runs while nobody is touching the object; no network or tracking.

Troubleshooting