bleh
This commit is contained in:
commit
75df901d2d
1852 changed files with 11873 additions and 0 deletions
185
README.md
Normal file
185
README.md
Normal file
|
|
@ -0,0 +1,185 @@
|
|||
# Desktop Chomik
|
||||
|
||||
A hamster that lives on top of your screen and reacts to typing, screenshots, music and being dragged
|
||||
around with the mouse. It runs on Linux (X11 and Wayland) and Windows; macOS, the tray and packaging
|
||||
are still on the list ([`docs/PLAN.md`](docs/PLAN.md)).
|
||||
|
||||
Source frames live in [`frames/`](frames) (18 animation folders, 1812 JPEG frames on black). The
|
||||
converter turns them into a transparent, lossless WebP set in `assets/animations/` — 30 clips, 1811
|
||||
frames, 24.7 MB — plus the `manifest.json` the app reads at startup.
|
||||
|
||||
## Running it
|
||||
|
||||
```bash
|
||||
cargo run -p convert_frames -- --in frames --out assets/animations # regenerate assets
|
||||
cargo test --workspace # unit + asset tests
|
||||
|
||||
cargo run --release # the pet, on your screen
|
||||
cargo run --release -- --backend x11 # force a backend (auto follows the session)
|
||||
cargo run --release -- --headless --seconds 20 # tick loop without a window
|
||||
cargo run --release -- --replay scripts/demo.txt --seed 4 # scripted event sequence
|
||||
./build.sh # release binaries in dist/
|
||||
```
|
||||
|
||||
Flags: `--assets`, `--config`, `--seed`, `--fps-scale`, `--backend`, `--no-sensors`, `--no-dialog`,
|
||||
`--seconds`, `--trace`, `--headless`, `--replay`. A replay script is `<milliseconds> <command>` with
|
||||
`key`, `drag_start`, `drag_stop`, `screenshot`, `music_on` and `music_off`; `--replay` and `--trace`
|
||||
print every clip hand-off with its timestamp, which is how the rules below are verified.
|
||||
|
||||
## Building
|
||||
|
||||
[`build.sh`](build.sh) builds release binaries into `dist/`. With no argument it builds everything
|
||||
this machine can produce; targets can also be named, several at once:
|
||||
|
||||
```bash
|
||||
./build.sh # everything available here
|
||||
./build.sh all # the same, explicit
|
||||
./build.sh win64amd # only the Windows x86_64 .exe
|
||||
./build.sh linux64amd linux64arm
|
||||
```
|
||||
|
||||
The aliases are `linux64amd`, `linux64arm`, `mac64amd`, `mac64arm`, `win64amd` and `win64arm`.
|
||||
Missing Rust targets or linkers are reported with the command that enables them, and each file is
|
||||
named after its target (e.g. `dist/hamster-pet-x86_64-unknown-linux-gnu`). Windows x86_64
|
||||
cross-builds from Linux with mingw; arm64 Windows uses MSVC on Windows and LLVM-MinGW elsewhere. On
|
||||
Windows run the script from Git Bash in a Visual Studio developer shell (rustc needs `link.exe`).
|
||||
macOS builds on a Mac only, and its window backend is still planned (M5), so that binary exits with
|
||||
an unsupported-platform message.
|
||||
|
||||
## The window
|
||||
|
||||
A transparent, always-on-top window the size of the canvas plus its padding (252x223), drawn by three
|
||||
backends: X11 (a dock-type window with a 32-bit ARGB visual), Wayland (a `wlr-layer-shell` top surface
|
||||
bound to one output, as KWin, sway and Hyprland provide) and Windows (a `WS_EX_LAYERED` popup whose
|
||||
frames go through `UpdateLayeredWindow`). On a display scaled above 100% the canvas is rendered at
|
||||
that scale. Without layer-shell the pet becomes an ordinary toplevel that the compositor places, so
|
||||
it cannot be dragged there; on X11 without a compositor it falls back to a shape mask — hard edged,
|
||||
but still animated and click-through outside the silhouette.
|
||||
|
||||
Pixels the hamster does not cover are cut out of the input region, so clicks reach whatever is
|
||||
behind: the shape extension on X11, an input region on Wayland, the alpha hit test of a layered
|
||||
window on Windows. Drag with the left button — the pet follows the cursor exactly and keeps playing
|
||||
its drag animation; right click quits. It wakes up in the bottom right corner and remembers where you
|
||||
left it, in global screen coordinates. Dragging is not clamped, so it can hang over an edge or sit on
|
||||
any monitor; only a saved position that is off every monitor is pulled back on screen.
|
||||
|
||||
## Sensors
|
||||
|
||||
| Sensor | How it works |
|
||||
| --- | --- |
|
||||
| Typing | `/dev/input` on Linux (needs the `input` group), a `WH_KEYBOARD_LL` hook on Windows; starts only on a burst of `typing_start_keys` presses inside `typing_start_window_ms`, so one shortcut key does not make it type |
|
||||
| Screenshots | the `PrintScreen` key from that same reader, so a shot that is never saved still counts, plus a folder watch on `sensors.screenshot_dirs` (the pictures folder by default) for shots taken with another shortcut. A file saved within 8 s of the press is that same shot. `sensors.screenshot`: `auto` (both), `key` (no disk), `files` (disk only), `off` |
|
||||
| Music | MPRIS over the session D-Bus on Linux, the media session manager (SMTC) on Windows: any player that reports `Playing` |
|
||||
|
||||
No privileges beyond read access: run the pet as your own user (root has no session bus). If typing
|
||||
is reported as off, `sudo usermod -aG input $USER` and log back in; the startup dialog says the same.
|
||||
Anything the pet cannot use (no `/dev/input`, no session bus, no screenshot folder) is shown once in a
|
||||
startup dialog with its fix, using whatever the desktop ships (kdialog, zenity, yad) or the native
|
||||
message box on Windows; `startup_dialog: false` or `--no-dialog` turns that off.
|
||||
|
||||
## Config
|
||||
|
||||
[`config.json`](config.json) is read from the working directory, next to `assets/`, so it lives in the
|
||||
project and nothing of the pet ends up in your home directory. It lists every option, so the knobs
|
||||
are easy to find and edit; without the file the pet runs on the defaults below and writes nothing.
|
||||
`--config <file>` uses another file instead, and creates it with all defaults when it does not exist
|
||||
yet. Only the window position is written back, into whichever file was read; command line overrides
|
||||
never are. A partial file keeps the defaults, out-of-range values are clamped, and a broken or
|
||||
unknown field falls back to the defaults with a warning — never a pet that refuses to start.
|
||||
|
||||
| Key | Default | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `position` | bottom right | Last anchor position on the desktop |
|
||||
| `backend` | `auto` | `auto`, `wayland` or `x11` |
|
||||
| `output` | largest | Wayland output the surface is bound to, e.g. `HDMI-A-1` |
|
||||
| `typing_start_keys` | `3` | Presses needed before the hamster starts typing |
|
||||
| `typing_start_window_ms` | `1500` | Window those presses are counted in |
|
||||
| `typing_stop_delay_ms` | `700` | How long it keeps typing after the last key |
|
||||
| `idle_delay_ms` | `[2000, 7000]` | Pause between idle activities |
|
||||
| `activity_loop_ms` | `[2500, 5000]` | How long the looping middle of an idle activity runs |
|
||||
| `fps_scale` | `1.0` | Playback speed multiplier for every clip, or `--fps-scale <f>` for one run |
|
||||
| `clip_fps` | `{}` | Frame rate of single clips, e.g. `{"idle_blink": 15}`; names are the keys of `assets/animations/manifest.json` |
|
||||
| `min_loops` | `{}` | Minimum full plays of a loop, e.g. `{"idle_activity_sleep_loop": 3}`; only the idle activity loops run for a set time, so only they can be stretched |
|
||||
| `disabled_activities` | `["dig"]` | Idle activities that must never play |
|
||||
| `screenshot_request_ttl_ms` | `3000` | How long a queued screenshot reaction may wait before it is dropped |
|
||||
| `sensors` | all on | `typing` (`auto`/`evdev`/`off`), `music`, `screenshot` (`auto`/`key`/`files`/`off`), `screenshot_dirs` (empty means the pictures folder) |
|
||||
| `startup_dialog` | `true` | Dialog at startup for anything the pet cannot use |
|
||||
|
||||
The wording of that dialog lives in [`texts.json`](texts.json), next to the config: `title`, `intro`,
|
||||
`outro`, the `problem` template and one entry per situation. `{reason}` and `{folders}` are filled in at
|
||||
runtime, an unknown placeholder stays visible (so a typo is easy to spot), a message without `fix`
|
||||
drops the arrow line, and anything left out or unreadable keeps its built-in wording.
|
||||
|
||||
## Playback rules
|
||||
|
||||
1. **Frame rate belongs to the clip, not to the display.** Every clip plays at its own `fps` from the
|
||||
manifest (30 fps today) against a monotonic clock, so a 60 Hz, 144 Hz or throttled compositor all
|
||||
show the same speed. One render tick never advances more than 100 ms of animation, so a stall slows
|
||||
playback instead of fast-forwarding it.
|
||||
2. **A running animation finishes before it is overridden.** When a higher priority state takes over,
|
||||
the current chain plays its `finish` clip first, and the new clip starts when that ends. A `start`
|
||||
clip that is already playing always plays out. Chains without a finish clip (the screenshot
|
||||
reaction, one-shot idle gags) are cut, as the source engine did.
|
||||
3. **Dragging is the exception:** it takes the hamster instantly, without waiting for a finish clip.
|
||||
4. **Priorities:** `drag > screenshot > typing > music > idle activity > main idle`. A condition that
|
||||
is still valid keeps its chain running — a screenshot arriving mid-drag waits instead of ending it.
|
||||
5. **Idle life:** the resting animation picks a weighted random activity (blink dominates, props like
|
||||
the newspaper are rare) after a random pause, then returns to the main idle. The digging idle is
|
||||
disabled by default, matching the source data. The looping middle runs for `activity_loop_ms`,
|
||||
measured from the loop clip itself, and at least `min_loops` full cycles when it has an entry there.
|
||||
|
||||
## Development rules
|
||||
|
||||
1. **All code, comments, docs and commit messages in English.** Keep the README short and factual.
|
||||
2. **Comments only where they earn their place.** One or two lines on *why*, never a narration of what
|
||||
the code already says. No commented-out code.
|
||||
3. **No over-engineering.** No abstraction, configuration knob or dependency for a single use case.
|
||||
4. **Shared logic gets a named helper** in one small module, never copy-pasted.
|
||||
5. **Platform code stays behind interfaces.** The core (animation, state machine, config) is
|
||||
platform-free and unit-testable; no `cfg` blocks in business logic.
|
||||
6. **Edge cases are part of the feature.** Every external input — files, config, sensors, monitors,
|
||||
clock — is untrusted: validate, clamp, debounce, degrade gracefully, never crash, never fail
|
||||
silently.
|
||||
7. **Test the logic that can break quietly:** state machine transitions, chain timing, scheduler
|
||||
weights, config clamping, manifest validation and asset matting, with a fake clock. The generated
|
||||
assets are checked against everything the manifest promises.
|
||||
8. **The frame loop does no unbounded work.** Frames are decoded on demand into a bounded LRU cache;
|
||||
nothing waits on a process or a display-server round trip per frame.
|
||||
9. **Targets: idle CPU < 1%, RAM < 60 MB.** Measure before claiming a speedup.
|
||||
10. **Keep the tree small and obvious.** `frames/` is a read-only local input; generated assets are
|
||||
reproducible from it and never edited by hand.
|
||||
|
||||
## Repository layout
|
||||
|
||||
```
|
||||
frames/ raw source frames (read-only input, not committed)
|
||||
assets/animations/ generated lossless WebP clips + manifest.json (built by tools/)
|
||||
config.json behaviour, edited before a build
|
||||
texts.json wording of the startup dialog
|
||||
tools/convert_frames/ JPG -> transparent WebP converter and clip table
|
||||
src/core/ manifest, frame cache, clip/chain player, engine, config, texts, replay
|
||||
src/platform/ the pet window: shared frame loop, compositor, X11, Wayland and Windows
|
||||
backends, startup dialog
|
||||
src/sensors/ keyboard (evdev or a Windows hook: typing + PrintScreen), music (MPRIS/SMTC),
|
||||
screenshot folder watch
|
||||
src/main.rs CLI: window, headless tick loop and --replay mode
|
||||
tests/assets.rs checks the generated asset set against the manifest
|
||||
build.sh release builds into dist/ (named targets, or all)
|
||||
scripts/ replay scripts used to verify the animation rules
|
||||
docs/PLAN.md implementation plan, asset format, per-OS support matrix
|
||||
```
|
||||
|
||||
## Asset pipeline
|
||||
|
||||
The converter (`cargo run -p convert_frames`, see above) is deterministic — the same input gives
|
||||
byte-identical output — and verifies its own output: the first and last frame of every clip are
|
||||
decoded back and compared byte for byte, a missing source frame or a size mismatch stops the run, and
|
||||
unused source frames are reported (the stray neutral frame in `pacidle0` is expected).
|
||||
|
||||
Matting clears only the background reachable from the image border: enclosed dark details (eyes, belly)
|
||||
stay fully opaque, and a one pixel alpha ramp keeps a whisker a hair instead of a thick dark spike.
|
||||
The baked drop shadow is kept by default, because removing it needs a threshold high enough to eat
|
||||
whiskers and dark props; `--shadow drop` does it anyway.
|
||||
|
||||
`frames/` is not committed: `assets/animations/` is the set that ships, and the source frames are only
|
||||
needed to regenerate it.
|
||||
Loading…
Add table
Add a link
Reference in a new issue