me0nline/Catser
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: document window ledge platforming, jumping kinematics, and multi-monitor roaming

Browse Source
This commit is contained in:
me0nline
2026-09-08 23:45:00 +02:00
parent dc2d6ee9eb
commit 59ba4b988f
1 changed files with 18 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+18 -2
View File
@@ -29,9 +29,19 @@ A Windows desktop cat companion inspired by [Workcat](https://workcat.app/en/#ho
$$\text{offset}_y = \text{height} \times 0.3874$$ $$\text{offset}_y = \text{height} \times 0.3874$$
- Sprints diagonally across your screen to reach the close button, strikes it with its paw, and dispatches native `WM_CLOSE` to close the distracting app. - Sprints diagonally across your screen to reach the close button, strikes it with its paw, and dispatches native `WM_CLOSE` to close the distracting app.
- 🪟 **Window Platforming & Ledge Walking**:
- Treats the top frames of visible open application windows (browsers, editors, terminals) as physical platforms.
- Cat autonomously performs parabolic leaps onto window ledges, walks along them, sits, naps, and hops back down.
- Dynamic surface tracking: If an underlying window moves or closes while the cat is resting on it, the cat wakes up and falls under gravity to the next surface or floor.
- 🖥️ **Multi-Monitor Roaming & Elevation Navigation**:
- Full virtual desktop support spanning all connected displays with arbitrary resolutions, positions, and DPI.
- Automatically calculates distinct taskbar/work-area floors for each screen.
- Seamlessly handles elevation differences (e.g. stepping off higher floors into gravity falls, or leaping up steep monitor steps).
- 🪟 **High-Performance Transparent Overlay**: - 🪟 **High-Performance Transparent Overlay**:
- Built with Win32 Layered Windows (`WS_EX_LAYERED | WS_EX_TOPMOST | WS_EX_TOOLWINDOW | WS_EX_NOACTIVATE`). - Built with Win32 Layered Windows (`WS_EX_LAYERED | WS_EX_TOPMOST | WS_EX_TOOLWINDOW | WS_EX_NOACTIVATE`).
- Uses `UpdateLayeredWindow` with 32-bit ARGB premultiplied alpha for clean anti-aliased fur edges, soft contact shadows, and tear-free 60 FPS rendering. - Uses `UpdateLayeredWindow` with 32-bit ARGB premultiplied alpha (vectorized with numpy) for clean anti-aliased fur edges, soft contact shadows, and tear-free 60 FPS rendering.
- Pixel-perfect hit-testing allows mouse clicks on transparent regions to pass through to your apps, while clicking the cat itself allows dragging and petting. - Pixel-perfect hit-testing allows mouse clicks on transparent regions to pass through to your apps, while clicking the cat itself allows dragging and petting.
--- ---
@@ -127,13 +137,19 @@ Catser/
## Technical Details ## Technical Details
### Kinematic & Physics Constants ### Kinematic & Physics Constants
Sourced directly from Workcat's engine (`apps/desktop/src/features/pet-mode/petModeData.ts` and `cat.js`): Sourced directly from Workcat's engine (`apps/desktop/src/features/pet-mode/petModeData.ts` and `cat.js`) and desktop physics kinematics:
- `WALK_SPEED = 20.8` (stride = `26.0`, cadence = `0.9`) - `WALK_SPEED = 20.8` (stride = `26.0`, cadence = `0.9`)
- `RUN_SPEED = 300.0` (stride = `72.0`) - `RUN_SPEED = 300.0` (stride = `72.0`)
- `PAW_FPS = 24` (17 total frames, contact at index `14`) - `PAW_FPS = 24` (17 total frames, contact at index `14`)
- `CONTACT_RATIO_X = (143.0 - 11.4) / 121.2 ≈ 1.0858` - `CONTACT_RATIO_X = (143.0 - 11.4) / 121.2 ≈ 1.0858`
- `CONTACT_RATIO_Y = (40.0 - 4.2) / 92.4 ≈ 0.3874` - `CONTACT_RATIO_Y = (40.0 - 4.2) / 92.4 ≈ 0.3874`
- `ALERT_HOLD_MS = 620ms` - `ALERT_HOLD_MS = 620ms`
- `GRAVITY = 1600.0 px/s²` (smooth parabolic acceleration during falls and jumps)
- `JUMP_VELOCITY = 650.0 px/s` (dynamic trajectory calculation solving launch velocity $(v_x, v_y)$ for any elevation difference)
### Window Platforming & Multi-Monitor Support
- Uses Win32 `OpenInputDesktop` and `EnumDesktopWindows` to extract visible top frames of non-minimized desktop windows as physical ledges.
- Tracks multi-display monitor geometries via `EnumDisplayMonitors` / `GetMonitorInfoW` to support arbitrary screen resolutions and vertical offsets.
### Win32 Window Closing ### Win32 Window Closing
On contact frame 14, Catser issues both `WM_CLOSE` (`0x0010`) and `WM_SYSCOMMAND / SC_CLOSE` (`0x0112 / 0xF060`) to the target window's handle (`HWND`), ensuring smooth closing across standard Win32 apps and Chromium browsers. On contact frame 14, Catser issues both `WM_CLOSE` (`0x0010`) and `WM_SYSCOMMAND / SC_CLOSE` (`0x0112 / 0xF060`) to the target window's handle (`HWND`), ensuring smooth closing across standard Win32 apps and Chromium browsers.