Modbot Docs
Companion

The SteamVR overlay

The headset panel the companion draws for SteamVR, what it shows, what it needs, and its limits today.

The companion includes a SteamVR overlay: a panel meant to show a moderator, inside the headset, who is in the group instance they are standing in and whether someone with a history of kicks or bans has just walked in. Inside VRChat you cannot see email, Discord or a browser, so this panel is how Modbot reaches you there.

The overlay is part of the same client you install and pair. There is nothing extra to download and nothing to switch on. If you do not want it, turn it off.

What it needs

  • SteamVR, or on Linux WiVRn or Monado (see below). The companion never starts any of them itself. It looks for a running one every ten seconds and attaches the panel when it finds one; when the runtime closes, the panel lets go and comes back the next time it is started. Start them in either order.
  • A paired server for the group whose instance you are in.
  • You in one of that group's instances for the group's roster, flags and alerts. In a public, friends-only or private instance, or in a group instance none of your servers manages, the panel still lists the people from your own copy of VRChat's log (see Outside group instances). With no server paired, the panel is blank (see Idle screen) and no server is contacted.

Without SteamVR, or without a headset, the client simply runs without an overlay and keeps reporting presence as normal. The overlay never stops the rest of the client from working: if it cannot start, the client carries on without it. A panel that fails to start (for example because the graphics card is out of memory) shows Could not start on the SteamVR page with a short reason, and the client tries it again once a minute, up to five times in all. Switching the panel off and on again, or restarting Modbot, starts the count again.

On a PC with more than one graphics card, the panel is drawn on the card SteamVR says the headset is on, and only that card: if it cannot make room for the panel, the panel shows Could not start rather than being drawn on a card the headset cannot show. Without SteamVR (the debug mode preview), it uses the real graphics card with the most memory of its own, skipping screen-sharing programs' and Windows' stand-in adapters.

The client window's SteamVR page shows where the overlay stands: attached (and to what), not running, not installed, refused (with the runtime's reason) or could not start (with the reason), when it attached, how many frames it has drawn, what it is showing right now, and the panel's size and position. To see the panel's picture on your desktop without a headset, start the client in debug mode.

WiVRn and Monado

On Linux with WiVRn or Monado, the companion draws the same panel through OpenXR instead of SteamVR. It needs the OpenXR loader (libopenxr_loader.so.1) and Vulkan, both of which a machine running WiVRn or Monado already has; there is nothing to install. xrizer alone is not enough, because it runs OpenVR games only and turns overlay programs away, so the companion goes to the OpenXR runtime itself. When the panel is up, the SteamVR page reads Attached to WiVRn. (or the name of the runtime it found).

Turning it off

The SteamVR page has an Overlay on switch at the top. Turn it off and the main panel stops: nothing is drawn, your controllers are not read, and SteamVR is let go. The sidebar reads off beside it.

The placement settings stay on the page, so you can arrange where the panel will sit before you turn it on. What goes away is only what has nothing to report while it is off: how long it has been attached, how many frames it has drawn, and what it is showing.

There are four panels and each has its own switch: this one, the notification overlay, the desktop overlay, and the notification overlay on a monitor. None of them can take another down. The live connection to your group's server is held open while any of the four is on and closes when the last one goes off.

The rest of the client is unaffected either way: it goes on reading VRChat's log and reporting presence to every server you paired with.

Turn it back on and the panel comes up again where you left it, without restarting the client. The setting is remembered in settings.json as overlayOn, in your own user folder, so it survives both restarts and updates.

The Modbot tab in the SteamVR dashboard

Press the system button to open the SteamVR dashboard, and Modbot has a button of its own there that opens its tab, the way OVR Advanced Settings does. It holds the overlay settings, so you can change them without taking the headset off:

CardWhat is on it
OverlayOverlay on, the main panel's switch, with Put it back in front of me beside it, Fixed to: Head, Left wrist, Right wrist or Room, and the Grip sensitivity slider
NotificationsNotification overlay on, Where on the screen (the six spots), and the Pop-up ticks, one for each kind of event
PlacementThe notification overlay's Across, Down, Distance, Width, Opacity and Pop-up stays sliders, each with a minus and a plus
ButtonShow VR button, the switch for the show and hide button, and Edit mode, the switch for the lock and the hand under the headset panels

Point at it with SteamVR's own laser and pull the trigger. A slider follows the laser while the trigger is held. These are the same settings as the window's SteamVR page and the Tell me about card's Pop-up column, saved to the same fields of settings.json, so a change in either place shows in the other.

The tab is there whenever SteamVR is running, with either panel on or off, so it is also where you switch the main panel back on from inside the headset. Like the panels, the companion never starts SteamVR to put it there. WiVRn and Monado have no dashboard, so there is no tab on them.

What it shows

Whose group it is

Across the top, above the tabs: your group's icon and your group's name, as the server gave them when you paired. If a pairing was made before servers said their group's name, the server's address is shown instead.

The roster

A list of who is in the instance right now, as your group's server knows it. At the top it says how many people are here and how fresh the list is. (In VRChat's look that is the Users heading, below.)

People are sorted so the rows that matter come first:

DotWho
RedFlagged: one of your group's flag rules matches them. The row shows what matched, such as 2 kicks or bans or Nuisance.
GreenA member of the group.
GreyEveryone else.

Staff, who are the group's owner and anyone holding a role that can kick, remove or ban, come after flagged people and before members.

Next to the count, the heading says how many of the people here are in the group, how many carry the 18+ mark and how many are staff, such as Group (25) · 18+ (12) · Staff (3). These count everybody here, not only the rows a filter leaves, and a count of nothing is still written. Staff are in the group too, so they are in both counts. A flagged person is not in the group or staff count, because the list does not say whether they are in the group; they do count as 18+ when they carry the mark. The Members choice of the Who filter is only the people shown in green, not staff.

Two small tags can follow a person's name, in both looks. Not in group is on somebody who is not a member of the group, including a flagged person, whose row shows red whether or not they are in it. A server that does not say who is a member leaves the tag off. New is on somebody who joined in the last two minutes; it goes by itself two minutes after they joined, with no need to wait for the list to refresh. It only shows for somebody your own log saw arrive, so it is never on someone who was already here when you arrived, nor on your own row, and neither tag is on a row tagged Left.

Above the list is one Filters button. Pressing it opens the filters: Who, Rank, 18+, Joined, Name and Sort; pressing it again closes them. It reads Filters (2) while two of them are on, and Clear beside it puts the whole list back. 18+ offers Any, 18+ and Not 18+. Somebody whose 18+ mark Modbot has not read yet is shown under Any only. It works together with the other filters, and Clear puts it back to Any.

If there is nobody to list, it says Nobody here. If no list has been loaded for this instance yet, it says No roster loaded for this instance.

When somebody leaves, their row stays on the list for 60 seconds, greyed and tagged Left, with the seconds still to go where their join time was. Tapping it still opens their card. They are not counted in how many are here, and if they come back the row goes back to normal.

In VRChat's look

When the desktop overlay or the headset panel is drawn in VRChat's own look, the list reads like VRChat's Users list:

  • A heading, Users (12), with the number of people here, then their group, 18+ and staff counts (Users (12) • Group (8) • 18+ (3) • Staff (1), as above), and at its far end how fresh the list is, then a chevron. Somebody who has just left is not counted, and a filter shows Users (3 of 12); the other counts still cover everybody here. When the heading is longer than the room, the last counts move to a second line rather than being cut off.
  • Your own row comes first, in a banner in your palette's highlight colour, with Other users (11) under it. It has no +. If Modbot does not know who you are yet, or your row is filtered out, there is no banner and no label. Your own row never shows a time for being here before you: when your log has no record of when you arrived, it shows no time at all.
  • Every person is a one-line card, so about twice as many people fit at once: a small rounded square picture on the left, their name in bold, their rank, 18+ mark, Not in group and New tags, flags and heads-up after the name, and at the right end when they came (or ~5m+ for somebody who was here before you, or Left and the seconds). The rank and the 18+ mark are always whole, then the time; the name takes the room that is left and is cut with an ellipsis only when it must be. The + that starts a heads-up is a square button at the right end. The whole card is the target, so tapping it opens the person's card. On the headset panel your banner and Other users scroll away with the rest of the list; on the desktop overlay they stay at the top and the rows glide under them.
  • The Audit Log tab uses taller cards: who, then what happened under the name, with the time at the right. A moderation row has no picture: the sentence takes the place of the name, with VRChat, Discord or Modbot under it.
  • The desktop panel is always the same width, whichever tab it is on, however long a name is, and whatever is filtered; long names are cut with an ellipsis first; the rank and 18+ mark are never cut, and the tags, flags and heads-up after them are only cut once the name is down to about twelve letters, so a wider panel shows them whole. The group's name at the top is in a light version of the palette's highlight colour, as VRChat's own title is.

The picture is the person's VRChat picture, when the server's own copy of it is already saved and the deployment's Proxy VRChat images through Modbot switch is on (it is off by default, so with it off every card shows the head-and-shoulders outline instead). The server saves a picture when somebody has had that face shown in the web app; the overlay never makes the server fetch one, so a person nobody has looked at on the web yet shows the outline until somebody has. The roster names a path on the same server for each saved picture, and the companion fetches it from there, with its token, and never from VRChat. Until a picture has arrived, and for anybody in an instance outside any group, the outline is shown. The headset panel draws these pictures in VRChat's look and none in the Modbot look.

The headset panel is drawn in this look when Modbot can read the colour palette you picked in VRChat's settings. The SteamVR page has a Look choice for it, VRChat colours (the default) or Modbot, the plain look the headset panel had before. It changes the headset panel only; the desktop overlay follows VRChat's palette whichever is chosen. In VRChat's colours the headset panel is laid out as the desktop one is but drawn bigger, so the words are easier to read in a headset, in a rounded frame with your group's icon and name across the top. The bar under the panel and its control hints are the headset's own and are unchanged. When Modbot cannot read a palette, the headset panel is drawn in the Modbot look.

The pop-ups follow the same look. The notification overlay in the headset is drawn in VRChat's colours when the headset panel is, and in the Modbot look when it is not. The notification overlay on a monitor is drawn in VRChat's colours whenever Modbot can read your palette (the Look choice does not change it, as it does not change the desktop overlay), and in its own plain look when it cannot. In VRChat's look each pop-up is a rounded card in the palette's button colour with a soft shadow, and a strip down its left edge in red for a flagged arrival or yellow for a Modbot fault, as before.

While a filter's choices are open (Who, Rank, 18+, Joined, Name, Sort), the Filters button, the filters and the choices sit together on one backing over the list. In VRChat's look the backing is the colour of the title strip.

The Audit Log tab

Despite its name this is not your group's audit log (that is on the web app). It is the live feed for the instance you are in, newest first: who joined, who left, who was already here, flagged joins and a watch ending. It is made from the same live connection as the roster.

If your Modbot account holds See the audit log, it also lists what the audit log records about the instance and about the people who were in it while you were watching: somebody joins the instance, then the group, then your Discord, and all three show. Each of those rows is the audit log's own sentence, such as Mira kicked Ada out of The Black Cat #39047., with where it comes from under it or beside it: VRChat, Discord or Modbot. They sit among the join and leave rows in the order they arrived, not sorted by time. The Kind filter has Changed avatar for the rows about somebody in the instance putting on another avatar and Actions for the rest of them, and Name also finds a name inside their sentence. Without that permission the tab is as above. A row appears only once it has happened while you are in the instance; nothing from before you arrived is added.

Somebody who was already in the instance when you arrived reads ~5m+ on the Instance list, in both looks, with no words: they have been there at least as long as you have, so the time is how long you have been in the instance, in whole minutes (~1h 4m+ from an hour on), and the ~ and + say it is at least that long. Open their card and it says Here before you. The Audit Log and the wrist panel say it in words, (here before you) ~5m+ (~1hr 4m+ from an hour on). If your log has no record of when you arrived, for example because the overlay was switched on after you got there, the Instance list shows no time rather than guessing, and the Audit Log says (here before you) alone. Your own row never shows it, in either look: with no record of your arrival it shows no time on your row.

Flagged user card

When someone one of your group's flag rules matches joins the instance you are in, a card appears above the roster: Flagged user joined, followed by your group's name, then the person's display name and a line saying what matched, such as 1 kick or ban · 5 warns.

Every paired moderator in that instance gets the card, including the one whose client reported the join. VRChat's log only says that someone joined; whether your group has kicked or banned them before is something only the server knows, so your own client is warned too.

Problem banner

A yellow banner at the top appears only when reporting has really stopped:

  • … rejected this device. Reporting and lookups have stopped; if you were removed from that group's staff, this is expected. See When a token is revoked.
  • Cannot reach …. Showing what was last known. The server could not be reached and the roster is no longer fresh.

Save a clip

With Clips switched on, a wide control sits under the tabs: Save a clip. With Talk on, its three small icons sit on the same row, to the right of it. Pressing it keeps the last few minutes of VRChat, picture and sound, as a video file on your own PC. That page says what the sound is. When nothing is being kept it says why instead — Waiting for VRChat, The folder cannot be used — and cannot be pressed; after a clip is written it says Clip saved for a few seconds. With Clips switched off there is no control at all.

The person card

Tapping a person opens their card, on the desktop overlay and on the headset panel alike. It has four buttons, the same on both:

  • Back returns to the screen you opened the person from.
  • Refresh reads that person's summary again.
  • Open in Modbot opens that person's page in the Modbot web app on your PC, in your default browser. In a headset you can still press it: the page opens on the PC, and you see it through your overlay tool or SteamVR's desktop view. The address is your paired server's own address and the person's id, and nothing a server or a display name says.
  • Copy name puts the person's display name on your PC's clipboard, exactly as the card shows it, for pasting into Discord or a ban reason.

Under the name, up to three short lines say what your server holds about the person:

  • Seen and First seen: how many times a moderator's client saw them arrive, and the date of the first time.
  • Notes and Watched: how many notes stand on them (notes taken back are not counted; what a note says is not shown here), and whether somebody is watching them.
  • Last action: the last kick, ban, unban or warn your group gave them, and its date.

A part with nothing behind it is left out, and so is its line: a person nobody has seen arrive has no Seen, and a person with no action has no Last action. These come from the records your server already holds, so no request goes to VRChat and the request that fetches the card is the same as before. A server too old to send them shows the card without these lines.

Outside group instances

In a public, friends-only or private instance, or in an instance of a group none of your servers manages, no server of yours knows anything about the room, so the panel works from your own copy of VRChat's log instead. It says Not in a group instance across the top (Another group's instance for a group none of your servers manages) and Not synced with the group under it, and there are no rank, flags or heads-up + on it, because those come from the group:

  • Instance lists the people the log says are here, with how long each has been here, and keeps the Left rows for a minute as above.
  • Audit Log lists who joined, who left and who was already here, as your log reports it. There are no flagged joins, because those come from the group's server.
  • Tapping a person still opens their card from the server.

No roster is read and no live connection is opened for these instances, and nothing about the instance (its id or its world) is sent. The one request that goes out is the person's card, which names the person and nothing else. With several servers paired it goes to the server whose group you were last in an instance of since the client started, or the first paired one if you have not been in any.

Idle screen

When there is nothing to show, the panel shows nothing at all, and the client contacts no server for it. That is when you are not in any instance yet, when VRChat's log has stopped, and when no server is paired. The idle sample on the debug page draws a card reading Not in a group instance in the panel's place, so you can see where it sits. The panel draws the same card by itself for 5 seconds after you press Put it back in front of me, and then goes blank again.

Save a clip is the one thing still shown there, when Clips is on, because the companion records wherever VRChat is running and a moment worth keeping can happen in a public instance too.

Holding it

The panel can be moved with a controller:

Do thisAnd
Point at the panelA ring shows where you are pointing, and the control under it lights up.
Squeeze the grip while pointingThe panel comes with your hand. Either hand can do this while its own ray is on the panel, even when the other hand is the one pointing. An ordinary hold is enough; you do not have to squeeze hard. Let go and it stays where you left it in the room, or on your wrist if you brought it to your hand.
Thumbstick up or down while holdingPushes the panel away or pulls it closer.
Thumbstick left or right while holdingMakes it narrower or wider. Either hand's thumbstick works while one hand holds it.
Squeeze the other grip on the panel while holdingPull your hands apart to make it bigger, bring them together to make it smaller.
Grip twice quickly on the panelPuts it back in front of your head, at a readable size.
Any of the above, with the hand the panel is worn onNothing. That hand ignores the panel it is carrying; use the other one.
Pull the trigger on the panelTaps what you are pointing at: the alert card to dismiss it, a person's row to open their card, Back on the card to return to the Instance or Audit Log screen you opened it from (the person stays open as a tab), Open in Modbot or Copy name on the card, Save a clip to keep the last few minutes. On a list a tap counts when the trigger comes up without your hand having moved much.
Hold the trigger on a list and move your hand up or downDrags the Instance list or the Audit Log with your hand, as a finger drags a phone's list, a pixel at a time. The whole list moves, your own row too. Letting go while your hand is still moving flings the list on, and it slows down by itself and stops at the ends; touching it stops it. Letting go after a drag taps nothing.
Right thumbstick up or down over a listScrolls the Instance list or the Audit Log smoothly, faster the further you push. Only the right thumbstick scrolls, whichever hand is pointing; the left one is left for moving in VRChat. It does nothing while the panel is worn on the right hand.

A bar on the right edge of a list that is longer than the panel shows where you are in it: the longer the bar, the more of the list you can see. It only shows; it cannot be dragged.

On the desktop overlay the mouse wheel scrolls the Instance list and the Audit Log by the pixel, with the same thin bar on the right edge: one notch is about three rows, and the list glides there over a moment instead of jumping a row at a time. J and K (or the down and up arrows) glide it one row. Your own row stays at the top of the Instance list. On a person's card the wheel is left to the window's own scrolling.

Once an Instance list or the Audit Log is scrolled down, a small arrow appears at the top of it. Pull the trigger on it on the headset panel, or click it on the desktop overlay, to go straight back to the top (on the desktop overlay the list glides there). At the top it is not there.

The Grip sensitivity slider on the SteamVR page, and on the dashboard tab's Overlay card, sets how lightly a squeeze takes hold of the panel: the further right, the lighter the squeeze. It starts at 10 of 14, the squeeze XSOverlay uses, and it is SteamVR only; on WiVRn and Monado the runtime decides.

On SteamVR these controls can be changed in SteamVR's controller bindings, under Modbot.

Where you leave the panel, its size, opacity and curve are saved and used next time. The SteamVR page has the same settings, and Put it back in front of me.

Put it back in front of me

For when you cannot find the panel. It is on the window's SteamVR page, in the command palette, and on the Overlay card of the Modbot tab in the SteamVR dashboard, so you can reach it from inside the headset. Pressing it:

  • switches the main panel on if it was off, and shows it again if you had said "hide overlay" or pressed Hide on the button;
  • fixes it to your head, straight ahead at 0.8 m and a little below your eyes;
  • sets the width back to 0.45 m, opacity to 100% and curve to 0%, and turns the lock and click-through off;
  • shows the Not in a group instance card for 5 seconds if the panel would otherwise be blank.

Width, opacity, curve, the lock and click-through are all reset, not kept as they were.

The bar under the panel

While you point at the panel a small bar comes up under it with two buttons:

ButtonWhat it does
LockThe panel can no longer be picked up, moved or resized. Tapping and scrolling still work. Press it again to unlock. The padlock is shut and purple while locked.
HandClick-through: the panel ignores your pointer, so pointing and clicking go to VRChat behind it. The bar still answers, so you can press the hand again to turn it off. The hand is struck through and purple while it is on.

Both are saved with the panel and kept when you restart. The notification panel and the show and hide button have the same bar, and so does the desktop overlay, in the strip along its top.

The notification panel is held the same way as the main panel. While it is unlocked it shows a dashed box, and you can take hold of it anywhere inside that box, between the pop-ups or with none up, not only on a pop-up or the bar. Pointing at the box, or holding it, shows the same grip hints as the main panel, over the bottom of the box.

The resize corner

With Edit mode on and the panel unlocked, the main panel and the notification panel each have a corner at the bottom right: two large, see-through slanted lines. The whole square around the lines takes the trigger, the clear parts too. Hold the trigger on it and drag to make the panel taller and wider, up to twice its ordinary size. The main panel then shows more rows, and the notification panel has room for more pop-ups at once. The text keeps its size. Let go of the trigger and the size is saved with the panel's place.

The corner is not there while the panel is locked, click-through, worn on a wrist or carried in your hand. The show and hide button has none. The thumbstick and two-hand sizing under Holding it work as before and make the whole panel bigger or smaller.

The desktop overlay and its chat window have the same corner, drawn the same way and shown by the same rules: Edit mode on, not locked, not click-through. Drag it with the mouse to make the window taller and wider, up to twice its ordinary size and never smaller. A window can grow only as far as the mouse can go, so a window against the edge of the screen grows no further that way; drag it by its strip first.

The pop-ups on a monitor have the corner too, with Edit mode on. They have no lock and no click-through, so nothing else decides it, but the window is only there while a pop-up is up, so the corner is too. Their window is held in its corner of the screen, so drag the corner toward the middle of the screen to make it bigger; a window cannot be dragged away from its corner.

On your wrist

The Placement card's Fixed to row offers Head, Left wrist, Right wrist and Room. Choosing a wrist puts the panel on that arm, facing out of the back of your hand, at 0.16 metres across — something to glance at like a watch rather than a window to work in. You can also get there with a controller: carry the panel to your hand and let go of the grip, and it settles onto that wrist.

On a wrist the panel shows four lines instead of the roster, because at that size a list of names is unreadable:

  • your group's icon and name,
  • how many people are here, in yellow when the list is no longer fresh,
  • a Modbot fault if there is one; otherwise a flagged arrival, name first with the reason under it; otherwise the newest row: a join or leave, name first with the kind under it, or one of the audit log's sentences with where it comes from under it,
  • nothing else.

The hand wearing the panel ignores it. It does not point at it, tap it, scroll it or grab it, so the panel is not in the way of that hand and squeezing that grip — for any of the reasons you squeeze a grip in VRChat — leaves the panel alone.

Use your other hand: point at it as you would at any panel, and a tap anywhere on a flagged arrival clears it. To get the roster back, grip the panel twice quickly with that other hand, or choose Head or Room on the SteamVR page. If the controller wearing the panel is switched off, the panel has nothing to hang from, so move it from that page.

On WiVRn and Monado the same works through OpenXR. The Valve Index, Oculus and Meta Touch, and HTC Vive controllers are bound: grip holds, trigger taps, and the thumbstick or trackpad scrolls and resizes. Any other controller gets OpenXR's simple controller bindings, where the select button taps and the menu button holds, and there is no scrolling.

The show and hide button

A small button of its own, always in your headset while Overlay on is on. It reads Hide with a struck-through eye while the panel is up, and Show with an open eye while the panel is down. Point at it and pull the trigger, and the panel goes away or comes back.

Hide only hides the panel. The button stays, and so does Modbot's connection to SteamVR (or to WiVRn or Monado), which is what lets the button bring the panel back. Saying hide overlay with Listening switched on does the same thing and changes the button's words too. The panel is shown again every time the client starts: whether it is hidden is not saved.

The SteamVR page's Show VR button switch, on by default, and the one of the same name on the Modbot tab in the SteamVR dashboard, are the same setting. Turn it off and the button is gone from your headset at once: nothing is drawn, and it takes no pointing or grip. The stick shortcut still shows and hides the panel. Turn it on and the button comes back where you left it.

The SteamVR page's Button place choice puts it in one of two places:

Button placeWhere it is
CornerLow and to the left of your view, following your head. The default.
WristOn your left wrist, like a watch. Point at it with your right hand.

The place only picks where the button starts. You can move it from there like the other panels: squeeze the grip while pointing at it and carry it, push or pull it with the thumbstick, or grip twice quickly to send it back to its place's own spot. With Edit mode on, the same bar comes up under it, with Lock and the hand, and the button itself stays the same size and in the same place. With the hand on, your pointer goes through the button to VRChat behind it, so turn the hand off again on the bar before you press it. The bar is only there with Edit mode on, so turn that on first. The stick shortcut shows or hides the panel too, so it works while the hand is on. Where you leave it is saved for each place, so switching between Corner and Wrist starts from the spot you left it at in that place.

It goes when the main panel goes: turn Overlay on off and it is taken down with the panel. If it cannot start, the client carries on without it and logs a warning; switching Overlay on off and on again tries it again.

The stick shortcut

Under the label the button says its shortcut, Right stick back 5s by default: hold the right stick pulled back for five seconds and the panel is hidden, or shown again if it was hidden. It works the same whether Modbot is connected to SteamVR or to WiVRn or Monado.

While you hold the stick, the line under the label counts down (Hide in 5, Hide in 4, and so on, or Show in 5 while the panel is hidden) and a bar along the foot of the button fills. Let go early and the shortcut words come back and nothing happens. When the time is up the panel hides or shows once; keep holding and nothing more happens until the stick has come back to the middle.

A stick that is busy with a panel is left out, so pushing or pulling a panel you are carrying, or scrolling a list you are pointing at (with the right stick), never counts. The stick has to be held the way it is set: a stick pushed off to the side, or only part of the way, does not start the count.

The SteamVR page has two choices for it, beside Button place:

ChoiceOptions
ShortcutWhich stick: Off, Right stick or Left stick; and which way: Back, Forward, Left or Right. Right stick and Back by default. The way is kept while the stick is off.
Hold time2 s, 3 s, 5 s or 8 s. 5 s by default.

With Off the button says nothing under its label, and the click is the only way to show and hide the panel. A controller with no thumbstick or trackpad has no shortcut either; the click still works.

How it follows you

The overlay uses the same reading of VRChat's log as the rest of the client, so it knows which instance you are in without asking anyone. If you are paired with several groups, it shows only the server whose group owns the instance you are standing in. Walking into another instance clears any card about the one you left.

If VRChat's log stops growing for about two minutes, the client treats you as no longer in that instance and the panel goes back to idle.

How fresh it is

The panel always says how old its list is:

It saysMeaning
up to dateLoaded in the last 45 seconds.
as of N seconds ago / as of N minutes ago / as of N hours agoOlder than that. Shown in yellow.
not loadedNothing has been loaded.

The panel is drawn from what the client already holds, never from a request made while drawing. If the server is slow or unreachable, you see the last list with its age, rather than a blank panel. That list is kept in memory only, never written to disk, and is thrown away when you unpair the server or quit the client.

Limits

  • One card at a time. A flagged user card stays up for 25 seconds, then clears itself.
  • The same person raises at most one card every five minutes, so someone rejoining again and again does not flood the panel.
  • Only cards for your current instance. A flagged join in a different instance is dropped, not saved for later.
  • The roster follows the instance. While you are in a group instance the companion keeps a live connection to that group's server; a join or a leave re-reads the roster at once, and it is re-read every 20 seconds regardless.
  • Nothing on the panel moderates. The trigger dismisses a card, opens a person's card, goes back from it, refreshes it, opens the person's page in Modbot on your PC's browser, copies their name to your clipboard, and — if you have Clips switched on — saves a clip to your own PC. That is all: there are no ban, kick or warn buttons, and the client's token could not do those things anyway. To act on something, use the web app.
  • The panel starts 0.45 metres wide in the headset, 0.16 metres on a wrist, and is drawn at 1024 by 1024 pixels either way.
  • Long names are cut to one line, so a display name full of line breaks cannot push the rest of the panel out of view.
  • SteamVR, WiVRn or Monado, on Windows or Linux. The panel is an OpenVR overlay for SteamVR and an OpenXR overlay session for the other two; VRChat and the runtime run on the same machine as the companion. Other OpenXR runtimes, SteamVR's own included, have no overlay extension, so the companion has nothing to hand them.
  • It starts below and to the right of your view, about an arm's length away, following your head. Move it with a controller or from the SteamVR page; see Holding it and On your wrist.

The desktop overlay and its bubble

The desktop overlay is the same panel in a window on a monitor. While VRChat's window is there, the window sits in the free space to the right of VRChat's own Esc menu and gets bigger or smaller with VRChat's window, so it does not cover the menu. It uses the full height of that free space, from just under VRChat's top-right buttons to the bottom of the window, so the roster shows as many people as fit. Modbot also puts a small bubble in VRChat's top-left row of key hints, after the Y one, showing the key that opens the overlay (Ctrl+Alt+M unless you changed it). It is purple while the overlay is open, and clicking it opens and closes the overlay, the same as the key. The bubble is there whenever the desktop overlay is on and VRChat's window is showing, and is gone when either is not, or when you untick Show Modbot button in VRChat in the settings.

With Edit mode on, the window has the resize corner at its bottom right. A size you drag it to replaces the automatic fit beside the menu, so a big window can cover VRChat's Esc menu. It is a number of times the fit's size, so it still gets bigger or smaller with VRChat's window and stays inside the screen. The text keeps its size and the roster and the Audit Log show more rows. The size is saved and is there after a restart. Click the corner twice quickly to put the automatic fit back.

The chat window on a monitor has the same corner, drawn the same way, with Edit mode on. It is not there while the window is locked or click-through. Hold the mouse on it and drag to make the window wider and taller, up to twice its ordinary size and never smaller. The log keeps following the end of the conversation, and the size is saved and is there after a restart.

The pop-ups on a monitor are a window of their own, and with Edit mode on they have the same corner at the bottom right while a pop-up is up. Hold the mouse on it and drag toward the middle of the screen to make the window wider and taller, up to twice its ordinary size and never smaller. The size is saved and is there after a restart.

The pop-ups go in their corner of the screen VRChat's window is on, and follow it if you move VRChat to another screen; with no VRChat window they go on the screen Modbot's window is on. A size you dragged them to is kept on whichever screen they are on.

To do this the client asks Windows where VRChat's window is, how big it is and whether it is minimised. It reads no pixels, no keys and nothing from inside VRChat's window, it does not move, resize or press anything in it, and nothing about it is sent anywhere.

What it sends

Nothing at all while the overlay is switched off. Otherwise, while you are in an instance belonging to one of your paired groups, only to that group's server:

  • a request for the roster of the instance you are in, every 20 seconds and again after each join or leave, which tells the server the instance id;
  • one live connection for that instance, which carries who joins and leaves and the flagged user card. It is a WebSocket; when the socket cannot be opened or keeps dropping, the companion asks for the same events with ordinary requests instead, and tries the socket again later. See live updates for the rules and the timings.
  • a heads-up, only when you press Place or Clear on one;
  • one request for a person's card, only when you tap their row. It names that person.
  • on the desktop overlay in VRChat's look only, one request for each person's picture, to that same server and only for the people the roster named a picture for. It names that person and carries the token. The server answers from its own saved copy and asks VRChat for nothing. The pictures are kept in memory while they are on the screen, never written to disk, and VRChat is not contacted from your PC for them.

The first two carry the client's token for that server, the instance you are in, and nothing else. The person's card also goes out while you are in an instance outside any group, to one paired server, carrying the token and the person and nothing about the instance. Nothing the overlay does is sent to Modbot Cloud, and SteamVR is only handed the picture to draw.

The client window's Servers page shows the connection in one word next to each server: Off (not in one of its instances), Connecting, Live, Polling or Stopped.

Modbot is not endorsed by or affiliated with VRChat Inc. or Discord Inc. VRChat is a trademark of VRChat Inc. Discord is a trademark of Discord Inc. SteamVR is a trademark of Valve Corporation. Windows is a trademark of Microsoft Corporation. Docker is a trademark of Docker, Inc. PostgreSQL is a trademark of the PostgreSQL Community Association of Canada. Railway is a trademark of Railway Corp. Other names are trademarks of their respective owners; see Legal. Modbot and its logo are trademarks of the Modbot project. Open source under AGPL-3.0.

On this page