Map an event to an action

A mapping is a rule on the Events tab: one trigger, one action, and a set of conditions on how often it may run. This page covers the parts that are not obvious the first time.

If you have not made one yet, start with Make your first reaction.

VFINITYv1.5.0VTSTIK

When this happens

Event Type

GiftLikeFollowShareChat messageAPI trigger

Gift Name

RosePick

Minimum gifts

10

Do this

Action Type

VTS HotkeyMove ModelVFX Preset

VTS Hotkey

Wave

Duration (seconds)

—

Empty means permanent

Hold (s)

0

How often it can run

Quantity Behavior

Once per gift eventRepeat the action xNExtend the duration xN

Count Mode

Count from all viewers

Max Triggers

3

Time Window (seconds)

10

Rate limitAction Queue

Delay (ms)

0

Add Mapping

DashboardEventsThrowingOverlaySettings

Choosing a trigger

Event Type is one of:

Gifts

Use Pick to choose from the catalog rather than typing the name. The catalog stores the gift's numeric id, and Vfinity matches on that id first, falling back to a case-insensitive name match. Typed names break when TikTok localises the gift name.

Minimum gifts sets a threshold: 10 roses before the action fires, rather than every rose.

Chat messages

Trigger Text is matched three ways, chosen with the button beside the field:

• Exact matches the whole message.
• Contains matches anywhere in the message.
• Starts with is the one to use for commands like !dance.

There is a case-sensitivity toggle next to it. Leave it off unless you have a reason.

Likes

TikTok sends likes in bursts, not one at a time. Minimum likes is the count that has to accumulate before the action runs.

Choosing an action

Move Model takes Position X, Position Y, Size, a Transition (s) for how long the move takes and a Hold (s) for how long it stays there. Return to original position sends the model back afterwards, which is almost always what you want for a reaction.

VFX Preset Name has to match the preset name in VTube Studio exactly.

Controlling how often it runs

This is where a stream goes from fun to unusable, so it is worth setting up properly.

Quantity behaviour

When a viewer sends five roses in one combo, Quantity Behavior decides what happens:

• Once per gift event runs the action a single time.
• Repeat the action xN runs it five times.
• Extend the duration xN runs it once but holds it five times as long. This needs a duration or hold above zero, and Vfinity refuses to save it otherwise.

Rate limiting

Max Triggers and Time Window (seconds) cap a rule: at most three triggers every ten seconds, for example. Turn it on with the toggle beside the fields.

Count mode

For thresholds like "10 roses", Count Mode decides whose roses count:

• Count from all viewers accumulates across everyone until the threshold is reached.
• Count per viewer means each viewer has to reach it alone.

The action queue

Action Queue decides whether a triggered action waits its turn. Every mapping with the queue on shares one first-in, first-out queue, so two gifts arriving together play one after the other instead of fighting over the model. With the queue off, the action runs immediately.

Use the queue for animations that look wrong when interrupted. Leave it off for anything instant.

Delay

Delay (ms) holds the action back before it runs. Useful for lining a model move up with a sound in OBS.

Managing the list

The Events tab has a search box that matches trigger names, a filter for event type, and a duplicate button on each row. Each mapping has a toggle: switching it off keeps the rule but stops it firing, which is easier to undo than deleting it.

Testing

Use the Event Simulator on the Dashboard. It fires gifts, likes, follows, shares, chat, subscriptions, joins and room stats, without a live connection.

Triggers Fired on the Dashboard counts rules matching, not VTube Studio reacting. If it moves and nothing happens on the model, the problem is downstream of the mapping.

Related