An animated spaceship (Spica) desktop pet for macOS. A Lottie-animated spaceship floats back and forth across the bottom of your screen. You can drag it around, move it with arrow keys, pause it, scale it, and adjust its speed from a settings panel.
- Lottie vector animation (Spica spaceship, 60fps)
- Click-and-drag: click the spaceship to pick it up, drop it anywhere
- Arrow key control: nudge the spaceship in any direction
- Right-click context menu: Settings, Pause/Resume, Quit
- Floating settings panel to adjust scale (3-25%) and speed (0.5-8x)
- Accessibility permission prompt on first launch and in settings
- Runs as a menu-bar accessory app (no Dock icon)
- Overlays all windows and workspaces
- macOS 13 (Ventura) or later
- Swift 5.9 or later
- Accessibility permission (the app prompts on first launch)
-
Clone the repository and cd into it:
git clone https://github.com/thiruisme/SpaceshipDesktopPet.git cd SpaceshipDesktopPet -
Build with Swift Package Manager:
swift build -c release -
Run the built binary:
.build/release/SpaceshipDesktopPetThe app looks for the frames/spaceship/ directory relative to the binary location or the current working directory. If you run from the project root, the animation will be found automatically.
-
On first launch, the app will prompt for Accessibility permission. Click "Open Settings" to go directly to System Settings > Privacy & Security > Accessibility and grant it. You can also grant it later from the in-app Settings panel.
- The spaceship floats left and right along the bottom of your screen.
- Right-click the spaceship to open the context menu:
- Settings... : opens a floating panel to adjust scale and speed
- Pause / Resume : stops or resumes movement
- Quit Spaceship : exits the app
- Click the spaceship to grab it, then drag it anywhere on screen. Release the mouse button to drop it; movement resumes automatically.
- Use arrow keys to nudge the spaceship in any direction.
The app is a Swift Package Manager project using the Lottie library for animation rendering. It uses AppKit and SwiftUI for the UI.
Source files in Sources/SpaceshipDesktopPet/:
main.swift App entry point. Creates an NSApplication with .accessory activation policy (no Dock icon), checks for Accessibility permission and prompts if needed, instantiates the overlay window, and starts the run loop.
PetSettings.swift Shared singleton (ObservableObject) holding the spaceship's position, scale, speed, pause state, drag state, and bounding rect. Bridges data between the animation engine, overlay window, and settings UI.
AnimationView.swift The Lottie animation engine. SpaceshipAnimator locates the Lottie JSON file at startup and manages horizontal movement via a 60fps timer. LottieNSView wraps LottieAnimationView (using the main thread renderer for full effect support) as an NSViewRepresentable. AnimationView is the SwiftUI view that scales and positions the animation on screen.
OverlayWindow.swift A full-screen transparent NSPanel set to .floating level. Uses a hover timer to toggle click-through (ignoresMouseEvents) when the cursor is over the spaceship. Handles click-drag via local and global event monitors. Supports arrow key movement via a global key monitor. Also manages the right-click context menu.
StatusBarController.swift Contains SettingsView (SwiftUI) and SettingsPanel (NSPanel). The settings panel is a floating window with sliders for scale and speed, a pause toggle, a button to grant Accessibility permission, and a quit button.
Supporting files:
Package.swift Swift PM manifest. Targets macOS 13+. Depends on lottie-ios for animation rendering. Uses unsafeFlags to embed Info.plist into the binary via the -sectcreate linker flag.
Info.plist Sets the bundle identifier and LSUIElement=true (hides Dock icon).
frames/spaceship/ Contains spica-hero.lottie (dotLottie archive) and the extracted spica-hero.json used by the Lottie renderer at runtime.
NO NETWORK ACCESS The app makes zero HTTP requests, has no URL connections, no telemetry, no analytics, and no update checks. It is entirely offline.
NO DATA COLLECTION OR PERSISTENCE The app does not use UserDefaults, does not write files, does not save settings, and does not store any data to disk. All state exists only in memory while the app is running.
ONE DEPENDENCY The app depends on lottie-ios (Airbnb's Lottie for Apple platforms) for animation rendering. All other code uses only Apple's AppKit and SwiftUI frameworks.
ACCESSIBILITY PERMISSION The app uses NSEvent.addGlobalMonitorForEvents to detect mouse clicks and arrow key presses while other applications are in the foreground. This requires macOS Accessibility permission. The app monitors left-click, right-click, and arrow key events and only acts when they are relevant to the spaceship.
NOT SANDBOXED The app is not sandboxed, which is expected for a desktop pet that overlays all windows using a floating NSPanel. The only file system access is reading the Lottie JSON from the local frames/ directory.
NOT NOTARIZED Unless you notarize the build yourself, macOS Gatekeeper may block it. To allow it, go to System Settings > Privacy & Security and click "Open Anyway" after the first launch attempt, or remove the quarantine attribute: xattr -d com.apple.quarantine .build/release/SpaceshipDesktopPet
unsafeFlags IN PACKAGE.SWIFT The Package.swift uses .unsafeFlags to pass -sectcreate to the linker, which embeds Info.plist into the binary. The "unsafe" designation is a Swift Package Manager term meaning the package cannot be used as a dependency by other packages. It is not a security concern.
PROVIDED AS-IS This software is provided as-is, without warranty of any kind. See the LICENSE file for full terms. You are responsible for reviewing the code and ensuring it meets your requirements before running it.
This project is licensed under the MIT License. See the LICENSE file for details.