Taskmasterfront matter

[09]entry 9 of 34

Taskmaster

desktop companion · Swift/SpriteKit2024

Fig. 1. A red panda takes small steps above a row of Mac app icons while its ringed tail follows.

this entry is written twice, in full

  1. 1.in brief

    a desktop companion for the Mac: a red panda that lives on your screen

  2. 2.in general

    A little company and a little mischief: a red panda who wanders along the bottom of your Mac’s screen while you work.

  3. 3.in particular

    A deterministic companion simulation with no UI code, drawn by SpriteKit with a Metal eye shader and a warp-grid rig, in a click-through strip that drops to 30 fps when calm and 20 asleep.

  1. 1.in brief

    a small animated pet that lives on the bottom of your Mac’s screen

  2. 2.in general

    A red panda who wanders along the bottom of your screen while you work, for a little company and a little mischief.

  3. 3.in particular

    All of its behaviour runs in a part with no screen code at all, it is drawn with real footsteps, eyes that follow your pointer and blinks, and it slows its own redrawing right down when nothing is happening.


context

Taskmaster is a desktop companion for the Mac: Miso, an original red panda, wanders along the bottom of the screen, watches the cursor, naps while you are away and brings you images, and a second companion, a small fan-made dragon, flies. It is a SwiftPM package with two targets: CompanionCore, the behaviour, games, physics and scheduling with no UI code, and the app, where SwiftUI3 draws the companion room and customisation, AppKit4 the menu bar and the transparent window, and SpriteKit2 the companion itself. It ships as a universal DMG for macOS 14+, and every push to main that passes CI becomes a signed Sparkle6 release.

the problem

A companion that lives on top of every other window is an intruder unless it is built not to be. It must take no click it was not aimed at and never steal keyboard focus; it must look alive, which means feet that stay planted and eyes that follow the pointer rather than a sprite sliding across the screen; and it must cost almost nothing, because a full-screen transparent layer redrawn at 60 fps is paid for in GPU time on every frame, all day.

what i built

  1. 1.

    CompanionCore: a deterministic state machine that takes time, cursor position, idle time and actions and returns events and snapshots, imports Foundation only, caps each step at 0.1 s and runs on seeded randomness, so long sessions are tested directly

  2. 2.

    A procedural rig over ten painted poses per companion: a warp grid for head, ears, tail, wings and legs, a gait that keeps each foot planted for 62% of its cycle with Hermite swing curves and contact shadows, and critically damped springs for landings and carried inertia

  3. 3.

    An eye shader, an SKShader through SpriteKit2’s Metal translation, that shifts the painted pupils toward the pointer and blinks by sliding lids coloured from the fur ringing each eye, with oval landmarks for an eye seen almost edge-on

  4. 4.

    A borderless, nonactivating panel that never becomes key: clicks pass through except on an opaque character pixel or a prop, and ignoresMouseEvents is assigned only when it changes, because each assignment is a window-server round trip

  5. 5.

    Frame pacing at 60 fps while anything moves or the pointer is near, 30 when calm and 20 asleep, suspended while the display sleeps; and an overlay that covers only a strip along the floor, growing to the whole screen only while something is carried, falling or flying

  6. 6.

    Things to do together: petting, treats and a ball, drag and drop with a squash on landing, high fives, follow-me and snack hunts, focus sessions, three moods with a mischief slider, and an opt-in cursor heist that a click, Esc or a 1.5 s deadline ends

  7. 7.

    Image deliveries that are careful with input: ImageIO5 conversion in a detached task to PNG at most 1,600 pixels across, files capped at 25 MB, HTTPS links streamed to a temporary file and cancelled past the limit, and a damaged index rebuilt from the stored copies

  8. 8.

    Private and quiet by default: no account, analytics, camera or microphone, sound off, Reduce Motion honoured, settings kept in Application Support with atomic writes, and the network used only for pasted image links and Sparkle6’s update check

outcome

5,612 lines of Swift1 in 56 files, 1,625 of them in CompanionCore, with 64 tests in Swift Testing7 covering the simulation, scheduling, frame pacing, the overlay’s extent, preferences, image import and rendering, and a self-check of every shipped pose and its landmarks; all pass. In the project’s own interleaved measurement on an M2, the frame pacing and the floor strip took a sitting companion from 9.45% to 5.30% of one core and a sleeping one from 9.35% to 3.60%, and the GPU load one companion adds from about 31 points to 12. The universal DMG is 11.9 MB.

It stays out of the way by construction: clicks pass through everything but the companion, it never takes keyboard focus, and at rest it costs a few per cent of one core, because nothing redraws faster than it needs to.

context

Taskmaster is a desktop companion for the Mac. Miso, an original red panda, wanders along the bottom of the screen, watches your pointer, naps while you are away and brings you pictures; a second companion, a small fan-made dragon, flies. It is built in two parts: one that holds all the behaviour, games, physics and timing and draws nothing, and the app on top, which draws the companion, its room of settings and the icon in the menu bar. It comes as a single installer for both kinds of Mac, and every change that passes its checks becomes an update the app installs itself.

the problem

Something that lives on top of every other window is a nuisance unless it is built not to be. It must not catch clicks meant for what is underneath, and must never steal the keyboard; it has to look alive, with feet that stay put on the ground and eyes that follow you, rather than a picture sliding across the screen; and it has to cost almost nothing, because a see-through layer over the whole screen, redrawn sixty times a second, costs the graphics chip something on every frame, all day.

what i built

  1. 1.

    An engine for the pet’s behaviour that takes in the time, where your pointer is, how long you have been away and what you do, and hands back what happens next; it never touches the screen, files or the internet, and its randomness can be replayed exactly, so whole days of behaviour can be tested automatically.

  2. 2.

    Movement built on ten painted poses per companion: the head, ears, tail, wings and legs bend smoothly, each foot stays planted for most of every step and swings forward on a smooth curve with a small shadow where it lands, and landings and being carried have a natural, settling bounce.

  3. 3.

    Eyes drawn by a small program on the graphics chip that moves the painted pupils toward your pointer and blinks by sliding eyelids coloured to match the fur around each eye, even for an eye seen almost side-on.

  4. 4.

    A see-through window that can never take over the keyboard: clicks go straight through to whatever is underneath unless they land on the pet or one of its toys, and it only tells the system when that changes, because every such message costs a round trip.

  5. 5.

    Redrawing sixty times a second only while something moves or your pointer is near, thirty when things are calm and twenty while it sleeps, and not at all while the screen sleeps; and a window that covers only a strip along the bottom of the screen, growing to full height only while the pet is carried, falling or flying.

  6. 6.

    Things to do together: stroking, treats and a ball, picking it up and dropping it, high fives, follow-the-leader and snack hunts, focus sessions, three moods with a mischief setting, and an optional game where it borrows your pointer for a moment, which a click, the Escape key or a second and a half always ends.

  7. 7.

    Picture deliveries that are careful with what they are given: images are converted in the background and shrunk to a sensible size, files over 25 megabytes are refused, web links are downloaded with a strict size limit, and a damaged list of pictures is rebuilt from the copies it kept.

  8. 8.

    Private and quiet by default: no account, no tracking, no camera or microphone, sound off, reduced motion respected when the system asks for it, settings saved safely on your own Mac, and the internet used only for picture links you paste and to check for updates.

outcome

About 5,600 lines of code, with 64 automated tests covering the behaviour, the timing, the redrawing speeds, the window’s size, settings, picture imports and drawing, plus a check of every painted pose; all of them pass. In the project’s own side-by-side measurements on a recent Mac, the slower redrawing and the smaller window took a sitting pet from about 9 per cent of one processor core to about 5, and a sleeping one from about 9 to under 4, and cut the extra work for the graphics chip by more than half. The installer is about 12 megabytes.

It stays out of your way by design: clicks go straight through everything except the pet itself, it never takes over the keyboard, and at rest it uses only a few per cent of one processor core, because it never redraws faster than it has to.