59 lines
2.5 KiB
Markdown
59 lines
2.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## What this is
|
|
|
|
A KDE Plasma 6 wallpaper plugin — a dancing retrowave robot (DANCEBOT-9000) that reacts to currently playing music via `playerctl`. No build step, no dependencies to install; the plugin is deployed directly.
|
|
|
|
Plugin ID: `com.vini.dancingcharacter`
|
|
Install path: `~/.local/share/plasma/wallpapers/com.vini.dancingcharacter`
|
|
|
|
## Deploy / test cycle
|
|
|
|
```bash
|
|
# Install (or reinstall after edits)
|
|
./install.sh
|
|
|
|
# Remove
|
|
./uninstall.sh
|
|
```
|
|
|
|
After install, activate via: Right-click desktop → Configure Desktop and Wallpaper → Wallpaper Type → Dancing Character.
|
|
|
|
Plasma hot-reloads QML changes when you reinstall; for HTML/CSS/JS changes you may need to switch away and back to the wallpaper type to force a reload.
|
|
|
|
**Runtime requirement**: `QtWebEngine` QML module must be installed (e.g., `qml6-module-qtwebengine` on Debian/Ubuntu). `playerctl` must be running for the music ticker to show track info.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
plugin/
|
|
metadata.json # KPackage/KPlugin descriptor for Plasma 6
|
|
contents/ui/
|
|
main.qml # Plasma WallpaperItem — hosts everything
|
|
dancer.html # Self-contained animation (HTML + CSS + JS)
|
|
```
|
|
|
|
### main.qml — the Plasma host
|
|
|
|
- Declares a `WallpaperItem` with a full-screen `WebEngineView` pointed at `dancer.html`.
|
|
- A `Plasma5Support.DataSource` with `engine: "executable"` runs `playerctl metadata` every 2 s and injects the result into the page with `webView.runJavaScript("updateMusic(...)")`.
|
|
- JavaScript is enabled; local file access and local storage are on/off respectively.
|
|
|
|
### dancer.html — the visual layer
|
|
|
|
Pure HTML/CSS/JS, no external dependencies. All visuals are self-contained:
|
|
|
|
| Layer | Technique |
|
|
|---|---|
|
|
| Starfield | `<canvas>` + `requestAnimationFrame` |
|
|
| Nebula blobs, grid floor, horizon | CSS animations |
|
|
| DANCEBOT-9000 robot | Pure CSS (divs + `@keyframes`) |
|
|
| Chest EQ bars & VU meter | JS-driven `requestAnimationFrame` |
|
|
| Music ticker | DOM text set by `updateMusic(artist, title)` (called from QML) |
|
|
| Dance style cycling | `data-dance` attribute on `<body>`, toggled by JS every 8 s |
|
|
|
|
**Tempo anchor**: everything is keyed to 120 BPM (`BEAT_MS = 500 ms`). CSS animation durations for the robot parts use multiples/fractions of 0.5 s, 1 s, or 2 s.
|
|
|
|
**Dance styles** (cycle order): `bounce → wave → shuffle → moonwalk → spin`. CSS selectors like `[data-dance="spin"] .robot { ... }` override the default animations via `!important`.
|