How hstagg/critter-overlay works
Critter Overlay is a desktop pet simulation: the user launches the tray app, which starts a transparent overlay; timed or user-requested spawns create moving critters that react, render, and play sounds. Settings configure the simulation and custom critters can be imported, stored, shared, and loaded into the spawn pool. Edges reflect the shown imports/calls or README-documented behavior; some subsystem internals were not sampled, so uncertain links are omitted.
Main entry points: main.py App and tray · spawn_manager.py Spawn manager · settings_window.py Settings UI · overlay.py Desktop overlay
Components 26
App runtime
- App and tray
src/main.py - Desktop overlay
src/overlay.py - Event dispatch
src/events.py - Sound manager
src/sounds.py - App updater
src/updater.py
Critter simulation
- Spawn manager
src/spawn_manager.py - Built-in animals
src/animals.py - Behaviours
src/behaviours.py - Locomotion profiles
src/locomotion.py - Day-night activity
src/time_of_day.py - Rarity tiers
src/rarity.py - Rarity auras
src/auras.py
Custom critters
- Custom animal
src/animals_custom.py - Import pipeline
src/custom_critters/import_pipeline.py - Package sharing
src/custom_critters/sharing.py - Critter registry
src/custom_critters/registry.py - Background removal
src/custom_critters/bg_removal.py - Mask generation
src/custom_critters/masks.py - Palette extraction
src/custom_critters/palette.py - Walk-cycle generation
src/custom_critters/procedural.py
Controls and settings
- Settings UI
src/settings_window.py - Animal previews
src/animal_previews.py - Preview renderer
src/preview_renderer.py
Persistent state
- Configuration
src/config.py - Critter files
src/custom_critters/storage.py
Other components
- User
Connections 40
- User → App and tray: launches
README.md - App and tray → Configuration: loads
src/main.py - App and tray → Desktop overlay: starts
src/main.py - App and tray → Settings UI: opens
src/main.py - App and tray → Event dispatch: dispatches
src/main.py - App and tray → Critter registry: loads
src/main.py - App and tray → Sound manager: initializes
src/main.py - App and tray → App updater: uses
src/main.py - Desktop overlay → Spawn manager: requests spawns
src/overlay.py - Desktop overlay → Built-in animals: renders and updates
src/overlay.py - Desktop overlay → Rarity auras: renders
src/overlay.py - Desktop overlay → Sound manager: plays
src/overlay.py - Desktop overlay → Configuration: reads
src/overlay.py - Desktop overlay → Event dispatch: handles
src/overlay.py - Spawn manager → Built-in animals: creates
src/spawn_manager.py - Spawn manager → Custom animal: creates
src/spawn_manager.py - Spawn manager → Critter registry: queries
src/spawn_manager.py - Spawn manager → Rarity tiers: rolls tiers
src/spawn_manager.py - Spawn manager → Behaviours: triggers
src/spawn_manager.py - Spawn manager → Day-night activity: scales activity
src/spawn_manager.py - Spawn manager → Configuration: reads settings
src/spawn_manager.py - Built-in animals → Locomotion profiles: uses profiles
src/animals.py - Behaviours → Built-in animals: applies behaviours
src/behaviours.py - Rarity auras → Rarity tiers: uses tiers
src/auras.py - Settings UI → Configuration: updates
src/settings_window.py - Settings UI → Import pipeline: imports critters
src/settings_window.py - Settings UI → Package sharing: exports and imports
src/settings_window.py - Settings UI → Critter registry: refreshes
src/settings_window.py - Settings UI → Animal previews: shows
src/settings_window.py - Settings UI → Preview renderer: renders previews
src/settings_window.py - Settings UI → Sound manager: previews sounds
src/settings_window.py - Import pipeline → Background removal: removes backgrounds
src/custom_critters/import_pipeline.py - Import pipeline → Mask generation: generates masks
src/custom_critters/import_pipeline.py - Import pipeline → Palette extraction: extracts palette
src/custom_critters/import_pipeline.py - Import pipeline → Walk-cycle generation: generates animation
src/custom_critters/import_pipeline.py - Import pipeline → Critter files: writes critter data
src/custom_critters/import_pipeline.py - Package sharing → Critter files: reads and writes
src/custom_critters/sharing.py - Critter registry → Critter files: loads critter files
src/custom_critters/registry.py - Custom animal → Critter registry: uses records
src/animals_custom.py - Preview renderer → Built-in animals: renders
src/preview_renderer.py