VTube Studio triggers¶

A trigger starts a macro when something happens. With VTube Studio connected, nine things can start one: you press a hotkey, your camera loses your face, you click your model, a model loads, an animation reaches an event your rigger put in it, and more. Pick them in the trigger editor under VTube Studio.

All the variables below are available as {name} in the macro's steps. The trigger editor's Variables from this event panel lists them too. The Test button on a trigger runs the macro with sample values that follow your filters, so you can try a macro without touching VTube Studio.

At a glance¶

Each filter is optional: leave a text filter empty to match everything. Text filters ignore capital letters. A trigger that is not connected simply doesn't fire, so it is safe to build macros while VTube Studio is closed.

A VTube Studio hotkey runs¶

ID vtubestudio.hotkey_triggered

Fires when a hotkey runs in VTube Studio: one you press, or one a plugin (CroStream included) triggers. Use it to hook your stream onto what you do in VTube Studio: a Surprised hotkey also plays a sound, a Tablet hotkey switches an OBS scene.

Gotchas.

• Hotkeys that plugins run also fire this. With Run by api or any a macro can start itself: a trigger on Run by any that runs the Trigger a hotkey action is a loop. The default, user, ignores everything CroStream and other plugins do, which is why it is the default.
• VTube Studio does not say whether you pressed a key, clicked a button or a timer ran: user means "not a plugin".
• A hotkey's name is whatever you named it in VTube Studio. Two hotkeys can share a name; use the ID to be exact. The picker lists the loaded model's hotkeys, so load the model first.
• hotkey_file is empty for hotkeys that don't use a file (a screenshot, for example).

Tracking is lost or found¶

ID vtubestudio.tracking

Fires when VTube Studio loses or finds your face or a hand. Use it for a "be right back" scene when you walk away, or a wave when your hand comes into view.

Gotchas.

• Each part fires on its own. If you walk away and lose face and both hands in the same moment, you get up to three runs, one per part (so Part any runs the macro for each). Use Part face for a single "away" signal.
• It fires on a change. Starting CroStream while your face is already tracked does not fire found. Only the face is read at connect: a hand that is already visible can fire found once right after connecting.
• {face_found}, {left_hand_found} and {right_hand_found} are the state after the change, so inside a face run, {face_found} always equals {found}.
• Hand triggers only fire if your VTube Studio setup tracks hands.
• Tracking flickers. A person whose camera loses their face for a split second fires lost then found. Put a delay or a condition in your macro, or the trigger's Cooldown, if that matters.

A model loads or unloads¶

ID vtubestudio.model_loaded

Fires when VTube Studio loads or unloads a model: you switch outfits, or the Load a model action runs.

Gotchas. Switching from one model to another can give an unload and a load. Use When loaded (the default) to react once. CroStream's anchors belong to a model, so a new model has none until you set them. If CroStream was waiting to undo a change tied to the old model, it drops that undo when the new model loads.

An expression turns on or off¶

ID vtubestudio.expression

Fires when an expression turns on or off in VTube Studio, whether you toggled it by hotkey or a plugin did.

Gotchas.

• When CroStream connects, VTube Studio reports which expressions are already on. Those are not treated as new events, so they do not fire.
• The expression action changes an expression too and fires this trigger. A macro that turns an expression on and a trigger on the same expression turning on is a loop.
• Expressions of Live2D items are ignored unless Include Live2D items is on.

The model is clicked¶

ID vtubestudio.model_clicked

Fires when you click your model in VTube Studio's window. Combined with the exact part you hit, it turns your model into a button: boop the nose for a sound, click the hat for a prop.

Gotchas.

• Button names are left, right and middle. Only these three can be chosen. A fourth mouse button only fires with Button any, and is reported as other.
• Pick the Part from the model's list. To learn which part is which, use Click on model on an anchor on the VTube Studio page and click the spot in VTube Studio's window.
• The ArtMesh IDs belong to the model. A trigger set to D_NOSE_00 does nothing after you switch to a model without that part.
• Clicks beside the model only reach CroStream when a trigger has Only on the model off; clicks that miss the model have an empty {art_mesh}.
• "Topmost" means the layer drawn in front. With Any layer, a click on a hat also matches the head under it.
• Only clicks in VTube Studio's own window count, not clicks on your stream or an overlay.

An animation event happens¶

ID vtubestudio.animation

Fires when an animation starts or ends, or reaches an event the rigger put into it. The last kind is the powerful one: a rigger adds an event named confetti at a certain second of a dance, and your macro fires exactly then.

Gotchas.

• Custom events are set by whoever made the animation (the rigger or animator), in Live2D Cubism's animation editor, and must be exported with "Export Event" on. CroStream cannot add them. If you don't see any, the animation has none.
• Event text has to match exactly, capitals included, and the name of the event is the text the rigger typed.
• Idle animations loop, so their start and end events fire over and over. They are off unless Include idle animations is on; with it on, a start trigger fires on every loop.
• Animation events are only requested from VTube Studio while a trigger uses them. The Animation picker lists the animations your model's hotkeys use, plus any CroStream has seen play.

Something happens to an item¶

ID vtubestudio.item

Fires when an item is added, removed, clicked, dropped, locked or unlocked in VTube Studio. Items are the extras in the scene: pictures, GIFs, Live2D items and the props CroStream puts on.

Gotchas.

• Items CroStream drops fire added too, with {ours} normally true. Set Whose to others to react only to items you or other plugins add, and to avoid a loop.
• Item file is a "contains" match: heart matches heart.png and big-heart.gif. Custom images CroStream uploads get file names that start with cs-.
• dropped means the item was let go after being dragged, pinned or not.
• Chain with the item actions: the trigger's {item_id} is what Remove items and Move an item take.

The background changes¶

ID vtubestudio.background

Fires when VTube Studio changes its background.

Gotcha. VTube Studio has no list of backgrounds for plugins to read. The picker offers the backgrounds your model's change background hotkeys use, plus any CroStream has seen change since it connected. If yours is missing, type its name.

Effects turn on/off or a preset loads¶

ID vtubestudio.post_processing

Fires when VTube Studio's visual effects (post-processing) turn on or off, or a preset loads.

Gotcha. The Set VTube Studio's effects action, and a timed revert of effects, fire this too.

Variables at a glance¶

Variables shared by several triggers carry the same meaning:

The full list is in the Variables reference.

Related¶

• Actions: what your macros can do in VTube Studio
• Recipes
• Troubleshooting
• Events reference