🐟 CyberKoi

A cyborg koi that treats your multi-monitor desktop as one endless aquarium. Built for Rainmeter 4.x/5.x. Fully autonomous: it wanders, bobs, startles when clicked, speaks the occasional fact or useful shortcut, and (with the optional cursor plugin) stops to watch your cursor and approaches it if you idle.

Install

Easy: double-click CyberKoi.rmskin and accept the Rainmeter prompt.

Manual: copy the CyberKoi folder into your Rainmeter Skins folder (right-click tray icon → Manage → Open skins folder), then in Rainmeter Manager: Refresh all, and load:

1. CyberKoi\CyberKoi.ini — the fish
2. CyberKoi\CyberKoiBubble.ini — the speech bubble (starts hidden)

The fish is draggable — drop it anywhere and it adopts the position.

Enabling cursor awareness (optional)

Out of the box the koi swims, startles on click, and speaks. To make it notice your cursor from a distance (CURIOUS / APPROACH behaviors):

1. Download the MouseXY plugin: https://forum.rainmeter.net/viewtopic.php?t=22900 (install the .rmskin from that thread, which includes 32/64-bit dlls)
2. Open @Resources\..\CyberKoi.ini and uncomment the [MeasureMouseX] / [MeasureMouseY] block.
3. Refresh the skin.

Behaviors

State	What happens
DRIFT	Wanders toward random waypoints across the virtual screen (both monitors), gentle sine bobbing, occasional pauses.
PAUSE	Hovers in place, slow idle animation.
CURIOUS	Cursor within ~240 px → stops and faces it.
APPROACH	Cursor idle >7 s while curious → glides toward it, stops at a polite distance.
STARTLE	Click → dart away, sometimes with a quip bubble.
NIGHT	11pm–6am → sinks to the lower half of the tank and dims.

Tuning

All knobs live at the top of @Resources\Scripts\brain.lua (speeds, cursor distances, idle threshold, speech frequency, night dimming, margins).

Art swap

Frames are plain PNGs in Frames\, all 128×64, facing RIGHT (leftward travel is a horizontal mirror via TransformationMatrix, so no duplicate art is needed). To use your own concept art, drop files with these names:

• swim_00.png … swim_07.png — 8-frame swimming cycle
• idle_00.png … idle_03.png — 4-frame hover
• dart_00.png … dart_03.png — 4-frame burst

Then update FishW/FishH in CyberKoi.ini and FISH_W/FISH_H in brain.lua if you change the frame size.

The current placeholder frames are generated pixel art (see make_frames.py if you want to regenerate or restyle them).

Repo layout

The repository root is the skin folder — clone it straight into your Skins directory under the name CyberKoi:

git clone https://github.com/0d0sys/CyberKoi.git "Documents/Rainmeter/Skins/CyberKoi"

make_frames.py regenerates the placeholder art, pack.py builds a CyberKoi.rmskin installer locally, and the GitHub Action in .github/workflows/ builds and attaches a fresh .rmskin to every v* tag release.

License

MIT — see LICENSE.

Known limitations / notes

• Speech bubbles clamp to the virtual screen edge rather than flipping direction yet.
• Coordinates are primary-monitor-relative, matching Rainmeter/Windows virtual screen space — monitors to the left of/above the primary will use negative values and work fine.
• The bubble skin must be loaded (once) for speech to appear.

Roadmap

• v1.5: persistence of mood/stats, "feed me" pellet events, WebParser live facts
• v2: ambient bubble particles, multiple koi, clickable tip → action