From 28b6cb4fe653f9558e2a6aa428d7ebaabbddb1f1 Mon Sep 17 00:00:00 2001 From: vprdev Date: Sun, 11 Oct 2026 23:09:08 -0700 Subject: [PATCH] Trim the README to the essentials, keeping every image --- CONTRIBUTING.md | 3 +- README.md | 199 +++++------------------------------------------- 2 files changed, 20 insertions(+), 182 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ab92d66..d3d8830 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -379,8 +379,7 @@ bun dev/gif.ts all # re-renders the README's GIFs 1. Put it in `wallpapers/.ts` as a named export, and add it to `wallpapers/index.ts`. 2. Run `bun run typecheck` and `bun dev/check.ts `, and look at `dev/snap.ts` and `dev/preview.ts` output at every time of day. -3. Add it to the README's wallpaper, activity, time-of-day, agent reaction and click sections, and to the gallery and - GIF grid. Add its best-looking time of day to `BEST` in `dev/gif.ts`, then run `bun run screenshots:update` and +3. Add it to the README's wallpaper list, gallery and GIF grid. Add its best-looking time of day to `BEST` in `dev/gif.ts`, then run `bun run screenshots:update` and `bun dev/gif.ts all`. ## Your own package diff --git a/README.md b/README.md index e8a14f5..13109e2 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,6 @@ # OpenCode Wallpapers -Animated wallpapers for the OpenCode terminal UI. A slow, quiet scene fills the background behind everything, drawn -with Unicode block characters and kept readable behind text. +Animated wallpapers for the OpenCode terminal UI: slow, quiet scenes behind everything, kept readable behind text. ![Beach, tundra, jungle, desert and space wallpapers in motion](screenshots/hero.gif) @@ -9,215 +8,55 @@ with Unicode block characters and kept readable behind text. ## Install -Requires OpenCode 2. Clone the repository into OpenCode's plugin directory and restart OpenCode: +Requires OpenCode 2. Clone into OpenCode's plugin directory and restart OpenCode: ```sh git clone https://github.com/vaprdev/opencode-wallpapers.git ~/.config/opencode/plugins/wallpapers ``` -To keep the clone elsewhere, add its absolute path to `plugins` in `~/.config/opencode/cli.json` instead. Update with -`git pull` in the clone. +Update with `git pull`. ## Use -Type `/wallpaper` to open the wallpaper menu: +Type `/wallpaper` to open the menu. ↑/↓ picks a setting, Enter or ←/→ changes it, Escape closes it. ![The wallpaper menu](screenshots/menu.png) -Use ↑/↓ to pick a setting, and Enter or ←/→ to change it. The wallpaper crossfades to each choice as you go, and -Escape closes the menu. Your choices are kept across restarts. +- **Activity:** calm, lively or teeming: how much moves behind your work. +- **Time:** day, sunset or night, or auto to follow your clock. +- **Season and weather:** follow the calendar, or the real weather where you are (`/wallpaper location Berlin`). +- **Brightness, shuffle, per project and power:** subtle to vivid, a new wallpaper every hour, one per project, and + slowing down when idle. -- **Brightness** is subtle, normal or vivid. Brighter scenes are dimmed more, so text stays readable. -- **Shuffle** switches to a different wallpaper every hour, or each time OpenCode starts. -- **Per project** remembers a wallpaper for each project directory. A project starts from the global choice until you - pick one there. - -With a light OpenCode theme the scene is washed out toward white instead of dimmed. +Scenes react to your agent: they speed up while it works, a visitor shows up when it finishes, and clouds roll in after +an error. With mouse support, clicking empty background nudges the scene, and each wallpaper hides a rare surprise. ## Wallpapers -| Wallpaper | Description | -| --- | --- | -| `ocean` | Deep water, god rays, marine snow, and a whale that drifts past now and then. | -| `desert` | Mesas and dunes with a saguaro, a cow skull, and a tumbleweed now and then. | -| `jungle` | A misty rainforest with a waterfall, light through the canopy, and a toucan flying by now and then. | -| `space` | A ringed planet turning slowly below a nebula and drifting stars, with a comet now and then. | -| `farm` | Rolling fields with a red barn, a turning windmill and swaying corn, and a tractor now and then. | -| `tundra` | Snowy peaks, a frozen lake, igloos and a snowman under falling snow, with a snowy owl now and then. | -| `beach` | Waves washing up a sandy beach between swaying palms, with a sailboat on the horizon now and then. | -| `city` | A skyline over a river, traffic on an elevated highway, and a blimp drifting over now and then. | -| `zen` | A koi pond under a red bridge, raked gravel, stone lanterns and falling cherry petals, with a heron now and then. | -| `prehistoric` | A smoking volcano over a lake, a winding river and lush ferns, cycads and tree ferns, with a T. rex stomping by now and then. | -| `rider` | A red capsule bike on pale cracked concrete, its rider walking up to it, with another of the gang speeding by now and then. | -| `megacity` | A canyon of towers over a neon avenue, where motorbikes ride off into the haze trailing red light. | -| `dome` | A vast black energy dome over a ruined city, its foot blazing with light under a ring of clouds, with a gunship crossing now and then. | -| `haunted-house` | A crooked Victorian haunted house on a rise above a foggy graveyard under a huge moon, with a witch flying by now and then. | - -### Activity - -Every wallpaper has three activity levels, which set how much is going on behind your work: - -| Wallpaper | Calm | Lively | Teeming | -| --- | --- | --- | --- | -| `ocean` | Water, light and the whale | Adds a fish and an octopus | Adds a shark, diver, turtle and kelp | -| `desert` | Mesas, a saguaro and a skull | Adds a soaring eagle (an owl at night) and a rattlesnake | Adds vultures (bats at night), a howling coyote and more cacti | -| `jungle` | Trees, vines, a waterfall and swaying leaves | Adds a swinging spider monkey and blue morpho butterflies | Adds a jaguar, scarlet macaws, a tree frog and more butterflies | -| `space` | The planet, its rings, a moon and the stars | Adds an orbiting space station and a satellite | Adds asteroids, a floating astronaut and a flying saucer | -| `farm` | Barn, windmill, fields and corn | Adds grazing cows and pecking chickens | Adds a farmer, pigs in the mud and crows over the corn | -| `tundra` | Peaks, igloos, a snowman and falling snow | Adds waddling penguins and an arctic fox | Adds a polar bear, an ice fisher and another snowman | -| `beach` | Sea, waves, sand and palm trees | Adds leaping dolphins and seagulls | Adds a crab, a surfer, an umbrella and a sandcastle | -| `city` | Skyline, river and light traffic on the highway | Adds a train crossing the bridge and more traffic | Adds neon signs, boats on the river, people on the street, and rain at night | -| `zen` | Garden, pond ripples, petals and a bamboo fountain | Adds koi circling under the lily pads | Adds more koi, a frog on a lily pad and dragonflies | -| `prehistoric` | Volcano, smoke, lake, river and plants | Adds a browsing sauropod and circling pterosaurs | Adds a triceratops herd, dragonflies and something in the lake | -| `rider` | The bike, the rider standing by it, and drifting dust | He walks slowly up to the bike and back, and paper and pebbles skitter in the gusts | He rides off in a red tail-light streak and slides back in sideways | -| `megacity` | The glowing city, windows coming and going, and a distant bike now and then | Adds bikes riding up the avenue with their light trails, and searchlights sweeping the sky | Adds a biker gang streaming through, a sideways slide now and then, and an airship overhead | -| `dome` | The dome, its slowly breathing light and the creeping cloud ring | Light pulses out along the streets, rubble floats up and the sky's ripples spread | The dome swells and recedes, shockwaves roll through the clouds, rubble swirls up and lightning flickers | -| `haunted-house` | The house, a flickering candle and jack-o'-lanterns, creeping fog, a bat or two and a swaying swing | Adds bats pouring from the turret, ghosts drifting by and a ghoul peeking out from behind a gravestone | Adds a zombie shuffling through the graveyard, a hand clawing out of a grave, a witch crossing the moon and a light moving room to room | - -### Time of day - -Every wallpaper has a day, sunset and night look. By default the time of day follows your clock: day from 7am, -sunset from 6pm (and at dawn, 6 to 7am), night from 8pm, fading from one to the next over 45 seconds. Pick one in the -menu to keep it fixed. - -- **Ocean:** sunlit water by day, golden light at sunset, and at night moonlit blue water with dark silhouettes, - glowing plankton and, in teeming, a diver's torch. -- **Desert:** a high sun with sunlit rock and shadows by day, silhouettes and long shadows in a hot ochre dust haze at - sunset, and a moonlit night with stars, the Milky Way and a campfire, where an owl and bats take over the sky. -- **Jungle:** sunlit greens by day, warm backlit mist at sunset, and a moonlit night lit by fireflies, where the - jaguar's eyes glow. -- **Space:** the planet's sunlit side by day, an orbital sunrise with the star flaring at its edge at sunset, and its - night side with city lights and aurora under a bright Milky Way. -- **Farm:** sunny fields under drifting cloud shadows by day, golden-hour light and long shadows over warm grass at - sunset, and a moonlit night with glowing windows, an open barn door and fireflies. -- **Tundra:** crisp blue-white snow by day, pink alpenglow at sunset, and deep blue snow under a green and violet - aurora at night, with warm light from the igloos. -- **Beach:** turquoise water mirroring the sky by day, a pastel pink and teal sunset over a pink-lit sea, and a moon - path at night with glowing bioluminescent waves and a bonfire on the sand. -- **City:** glass towers in the sun by day, a smoggy amber and magenta sunset dropping between the towers, and at - night windows, lamps and neon in saturated colors mirrored in the river, with rain and a wet street in teeming. -- **Zen garden:** a sunlit pond mirroring the sky by day, a soft peach and lavender sunset glittering in it, and at - night amber lanterns, fireflies and the gold moon reflected in dark blue water. -- **Prehistoric:** a hazy blue sky over glowing lava by day, dinosaurs under an ashy red sky with the sun dimmed by - smoke at sunset, and a moonlit night where red and orange lava runs down the volcano, lights its smoke and shimmers - on the lake. -- **Rider:** pale cool concrete by day, warm amber ground and long shadows at sunset, and dark blue asphalt at - night, where the bike's amber headlamp and red tail lamp glow and the pill on the rider's back turns cobalt. -- **Megacity:** a hazy steel-blue city under a pale smoggy sky by day, an orange and magenta sun glaring down - the avenue between the towers at sunset, and at night deep blue towers full of cyan and gold windows over a - green-teal haze, with red-orange light trails on the road. -- **Dome:** a smoky pale sky over a gray-green ruin with the dome's light dimmed by day, warm-lit clouds under an - orange-red sky and a green-gold blaze at sunset, and at night a near-black sky over deep blue clouds with the city - lit green and teal from the dome's foot. -- **Haunted house:** a grim overcast afternoon in sickly green-gray light, a blood-orange sun sinking behind the - house with everything in silhouette at sunset, and a deep violet night under a huge gold-orange moon, with glowing - windows, flickering jack-o'-lanterns, teal ghosts and a green-tinged zombie. - -## Seasons and weather - -By default the season follows the calendar: spring from March, summer from June, autumn from September, winter from -December, flipped in the southern hemisphere once a location (below) puts you there. Pick a season in the menu to keep -it fixed. - -- **Farm:** blossom, wildflowers and young corn in spring; ripe corn and fireflies in summer; gold fields, dry corn, - pumpkins and falling leaves in autumn; snow on the fields, roofs and bare trees in winter, with a light flurry. -- **Desert:** a wildflower bloom and flowering saguaros in spring, and a dusting of snow on the mesas in winter. -- **Jungle:** the rainy season (summer and autumn) brings thicker mist, a fuller waterfall and a light shower. -- **Beach:** a crowd of umbrellas, sunbathers and swimmers in summer, and an empty beach with cooler water in autumn and - winter. -- **Zen garden:** cherry blossom in spring, green leaves in summer, red and gold leaves falling in autumn, and bare - branches under a light snowfall in winter. -- **Ocean, space, tundra, city, prehistoric, rider, megacity, dome and haunted house** look the same all year. +`ocean` · `desert` · `jungle` · `space` · `farm` · `tundra` · `beach` · `city` · `zen` · `prehistoric` · `rider` · +`megacity` · `dome` · `haunted-house` | Spring | Summer | Autumn | Winter | | --- | --- | --- | --- | | ![Farm in spring](screenshots/farm-spring.png) | ![Farm in summer](screenshots/farm-summer.png) | ![Farm in autumn](screenshots/farm-autumn.png) | ![Farm in winter](screenshots/farm-winter.png) | -Every wallpaper except ocean and space can show rain with splashes, snow, fog or an overcast sky, tinted blue rather -than white at night. The menu's weather setting: - -- **Off** (the default): each wallpaper's own weather, such as the tundra's snowfall and the seasonal showers above. -- **Local**: the real weather where you are, from [Open-Meteo](https://open-meteo.com) (free, no API key), checked at - most every 30 minutes. It needs a place: `/wallpaper location Berlin` or `/wallpaper location 52.52,13.41`, or the - `WALLPAPER_LOCATION` variable. Nothing is fetched unless you pick Local, your location is never guessed, and if the - lookup fails the sky stays clear. -- **Clear, Rain, Snow, Fog**: always that weather. `/wallpaper weather overcast` is also available. - ![Farm in the rain](screenshots/farm-rain.png) -## Agent reactions - -Wallpapers quietly follow what the agent is doing: - -- **Working:** the scene moves a little faster while any session runs, barely at all when calm. -- **Done:** when the last running session finishes, the wallpaper's visitor shows up: the whale, a tumbleweed, a - toucan (fireflies flashing together at night), a comet, the tractor, a snowy owl, a sailboat, the blimp, the heron, - the T. rex, another rider of the gang, a biker gang, the gunship or a witch on her broomstick. -- **Error:** after a failed run, dark clouds roll in (in the ocean and jungle the light shafts fade, in space the star - dims, on the rider's concrete their shadows drift by, over the dome its blaze sinks, and at the haunted house - lightning cracks and the lights gutter) and the scene darkens - slightly. It clears when the agent works again, or after a couple of minutes. - -## Clicks and surprises - -With mouse support on, clicking an empty patch of background, away from text, nudges the scene. OpenCode still gets -every click; dialogs, popups and text are never pokes. - -| Wallpaper | Click | Very rarely | -| --- | --- | --- | -| `ocean` | Bubbles rise, and the fish, shark and octopus dart away | A little yellow submarine putters past | -| `desert` | Birds burst up out of the scrub | A roadrunner sprints through and stops to look around | -| `jungle` | The spider monkey swings harder | A sloth lowers itself down a vine to smile at you | -| `space` | A shooting star | A starship cruises across the sky | -| `farm` | The nearest cow looks up and turns toward you | A flying saucer beams up a cow | -| `tundra` | The penguins hop | A yeti looms out of the snow and waves | -| `beach` | Gulls take off | A message in a bottle washes up for a while | -| `city` | Pigeons burst up off the street | A caped superhero flies over the towers | -| `zen` | A ripple on the pond, or sparrows up out of the garden | A tanuki with a leaf on its head sits by the pond | -| `prehistoric` | Little feathered dinosaurs flap up out of the ferns | A time machine arrives in a flash and leaves trails of fire | -| `rider` | The pavement cracks a little and pebbles scatter | Chunks of pavement float up around a crater, then drop back | -| `megacity` | A bike rides up the avenue from the road, or a burst of windows lights up on the towers | A dome of light swells up silently at the far end of the avenue | -| `dome` | A ripple through the clouds, a shockwave from the dome, or rubble kicked up off the city | A red motorbike tears across the city in a streak of tail light | -| `haunted-house` | A window flashes with a figure standing in it, a ghoul pops up behind a gravestone, or bats burst out | Zombies climb out of their graves and dance in step | - -Click reactions that involve animals need the lively or teeming level. The rare events come along about once every -hour or two of watching, never sooner than half an hour apart, and changing settings doesn't reset the wait. - -## Power - -Wallpapers animate at 15 frames per second. On **Saver**, the default, they slow to 5 frames per second after 30 -seconds without typing, mouse or agent activity, and pause while the terminal window is in the background (in -terminals that report focus, such as Ghostty, kitty, iTerm2 and tmux). Any input brings back full speed at once. -**Smooth** always runs at 15. - ## Terminals -Any truecolor terminal works. Ghostty and kitty get octant characters (2x4 sub-pixels per cell), plus diagonal wedges -and eighth blocks along edges, which they draw themselves; other terminals get quadrant blocks (2x2). These environment -variables tune rendering: +Any truecolor terminal works. Ghostty and kitty get finer octant characters; others get quadrant blocks. | Variable | Effect | | --- | --- | -| `WALLPAPER_PIXELS=1` | In Ghostty or kitty, draw the scene as a real image behind the text instead of characters | -| `WALLPAPER_SUPERSAMPLE=2` | Smoother edges in character mode, at about 2.5x the CPU | +| `WALLPAPER_PIXELS=1` | In Ghostty or kitty, draw the scene as a real image | +| `WALLPAPER_SUPERSAMPLE=2` | Smoother edges, at about 2.5x the CPU | | `WALLPAPER_OCTANTS=0` or `1` | Force quadrant or octant characters | -| `WALLPAPER_SMOOTH=0` | Octants only, without the wedges and eighth blocks (if a font draws them badly) | -| `WALLPAPER_LOCATION` | A place or `latitude,longitude` for local weather, if none is set with `/wallpaper location` | - -## How it works - -The plugin post-processes each frame OpenCode draws. Cells painted with OpenCode's neutral surface colors are replaced -by the scene, while colored backgrounds such as diffs and selections are left alone. The whole scene is dimmed evenly -toward a dark tint, so text reads anywhere without a backing of its own. Scenes render in HDR with bloom and tone -mapping, then are fitted to two colors per character cell. While one look fades into another, both scenes render and -blend, scrim included, so only transitions cost extra. Scenes keep their landmarks toward the edges, and the engine tells them where text sits, so -creatures and visitors stop where they can be seen. Outdoor scenes share one wind: now and then a gust rolls across -the screen, bending plants and carrying petals, snow and dust. +| `WALLPAPER_SMOOTH=0` | Octants without wedges and eighth blocks | +| `WALLPAPER_LOCATION` | A place or `latitude,longitude` for local weather | ## Make a wallpaper -[CONTRIBUTING.md](CONTRIBUTING.md) explains how wallpapers work, the dev tools for making them, and how to load -wallpapers from a package of your own with the plugin's `wallpapers` option. +See [CONTRIBUTING.md](CONTRIBUTING.md). ## Gallery