Start VRoid Studio (Steam appid 1486350, Proton) and take control of it.

Idempotent: if the window already exists it is reused, not relaunched. Then the window is parked on Hyprland workspace 9, the workspace the user was on is remembered (vroid_release puts them back), and the window is focused and fullscreened so its geometry - and therefore every coordinate you will read off a screenshot - is stable.

Cold start over Proton takes 30-90 s; the call blocks until the window is up. It does NOT wait for the start screen to finish drawing, so take a vroid_screenshot and look before clicking anything.

Report whether VRoid Studio is running, focused, and where it sits.

Cheap and side-effect free (no OCR, no input) - use it before anything else, and after anything that might have lost focus. focused false means every acting tool will refuse until vroid_launch (or any acting tool's own focus step) takes the window back.

Also reports whether the external helpers this server needs are present: the vpointer binary (built by native/build.sh), grim, tesseract, hyprctl.

Hand the desktop back: switch to the workspace the user was on before.

Leaves VRoid running on workspace 9. Call this when you are done with a session, or before handing control back to the human.

Screenshot VRoid and return the image, plus the path it was saved to.

LOOK at the returned image before you decide anything - this is the only way to see the app. Every capture is also written to the captures dir so it can be re-read later.

Coordinate space: the reported image_size is the native capture size (2560x1440 on the reference machine) and that is the space every other tool means by space="image". The transported image may be downscaled (downscale in the text block says by how much); if you read a coordinate off the picture by eye, divide it by that factor before clicking. Better: get coordinates from vroid_find_text / vroid_find_button, which always report native image px.

Gotchas carried over from the driver: capture the WHOLE window, not a crop, when checking "did that work" - modals appear in the middle of the screen and a top-strip-only check will miss them. And do not judge change by the 3D viewport, which dithers every frame; watch a UI strip instead.

OCR the current VRoid window and return where query appears.

Takes its own fresh screenshot, so coordinates are current. Results are image px, ordered by OCR confidence, ready to pass straight to vroid_click (which defaults to space='image').

Known OCR weaknesses in this UI: small, letter-spaced or light-on-dark labels get split or dropped ('Export' -> 'E' + 'xport'), and white text on VRoid's blue primary buttons often disappears entirely - use vroid_find_button for those. Icons (toolbar, left rail) have no text at all; the README's UI map has their fractional positions.

If nothing is found, that is information: the screen may not be the one you think it is, or a modal is covering it. Take a screenshot and look.

Find VRoid's primary action buttons by their colour, not their text.

VRoid's confirm buttons ('Export', 'OK', 'Create') are solid #0096FA pills whose white labels tesseract regularly loses, so this matches the button chrome. Blobs come back biggest-first, in image px, ready for vroid_click.

A grey pill (color='disabled') where you expected a blue one means the action is disabled - on the VRM Settings modal that means Avatar Name or Creators is still empty.

Click a point in the VRoid window with the real compositor cursor.

Refuses unless VRoid Studio is the focused window; it focuses the window itself first (workspace 9, fullscreen) and raises rather than clicking into somebody else's app.

The pointer glides to the target in a few steps so hover states fire, then clicks and settles ~0.35 s. Coordinates must come from a CURRENT capture - take a fresh vroid_screenshot or vroid_find_text right before clicking, because panels reflow and modals move.

Press, glide and release - slider handles, the 3D camera, hair guides.

For Parameters sliders prefer vroid_set_slider, which types an exact value into the row's numeric box; dragging is only for controls that have no numeric box. The glide is 24 interpolated steps, which is what the app needs to register a drag rather than a click.

Wheel-scroll a panel or zoom the 3D viewport.

Sent as X11 button 4/5 (6/7 horizontally): VRoid is an XWayland client and ignores Wayland virtual-pointer axis events, so this is the only wheel that works on it.

Long Parameters lists need this - a label that vroid_find_text cannot see is usually just below the fold. vroid_set_slider scrolls to its own row automatically, so you rarely need to do it by hand.

Type into whatever widget currently has keyboard focus.

Click the field first (vroid_click) - this tool has no idea where the caret is. Keystrokes go through X11 XTEST because the Wayland virtual keyboard is mis-read by this Proton client (a whole string arrives as a single character).

Always screenshot afterwards to confirm the text landed in the field you meant: VRoid's forms have several boxes with near-identical captions, and typing into the wrong one leaves the primary button greyed out with no other symptom.

Press a key combination in the focused VRoid widget.

Useful ones: Return confirms a value box or a Wine dialog's default button; ctrl+s saves the project; ctrl+shift+s is Save As; ctrl+z/ctrl+y undo/redo in the editor.

Note Escape does NOT close VRoid's hamburger menu - click elsewhere to dismiss it.

Switch the editor to a top-level tab, located by OCR of the tab strip.

Only works on the editor screen (not the start screen, the export screen or the hair editor). Waits ~2 s for the panels to redraw and returns the path of a verification screenshot - take a vroid_screenshot if you want to see the result.

Set a Parameters slider exactly, by typing into its numeric box.

Scrolls the right-hand panel from the top until the labelled row is visible (so it works for parameters below the fold), clicks the numeric box at the end of that row, clears it, types the value and presses Return.

This is far more reliable than dragging the handle - use vroid_drag only for controls with no numeric box. Open the right tab first (vroid_open_tab): each tab has its own parameter list.

Set a colour swatch by typing a hex code into its #RRGGBB box.

Scrolls the right-hand panel to the labelled row, clicks the hex field just below the label, replaces its contents and presses Return. Same caveat as sliders: the row must belong to the currently open tab and sub-category (left icon rail).

From the start screen: Create New -> pick a base -> land in the editor.

Locates the 'Create New' tile by text (so it survives the Recently Edited grid growing), clicks the card above its caption, picks the base thumbnail, then waits up to a minute for the editor - the 3D viewport takes several seconds to appear after a base is chosen.

Identify which VRoid screen is on top: start, editor, export_vrm, hair_editor, or unknown.

Cheap-ish (OCRs only the top strip, ~2 s) and worth calling whenever a flow tool fails - most failures are "you are not on the screen this tool expects". 'unknown' usually means a modal is up; screenshot the whole window and look.

Walk the entire Export-as-VRM flow and write a .vrm file.

Editor toolbar share icon -> 'Export as VRM' -> the blue Export pill -> the VRM Settings modal (fills Avatar Name and Creators, picks the export format, scrolls to the bottom and clicks Export) -> Wine's save dialog (types a Z:\ path and presses Return) -> waits for the file size to stop growing.

Must be started from the EDITOR screen with a model loaded. Takes 30 s to a few minutes depending on the model. Returns the written path and its size; raises with the path of a diagnostic screenshot if any step fails - read that screenshot before retrying, since a half-finished flow usually leaves a modal open that the next attempt will trip over.

Save the .vroid project - plain Save, or Save As to an explicit path.

With name: presses Ctrl+Shift+S and drives Wine's save dialog the same way the VRM export does, then waits for the file. Without name: opens the hamburger menu and clicks Save, which overwrites the project's existing file and opens the Wine dialog only if the project has never been saved (in that case call this again WITH a name).

Worth doing before any risky experiment: nothing else in this server persists your work, and vroid_launch(restart=true) discards it.