Throwing - ChiwaBots

Throwing lets viewers hurl objects at your VTube Studio model. The object flies across the screen, hits the model, and the model gets knocked back, plays an expression, or is even knocked clean out of frame.

What it solves

For a VTuber there are surprisingly few ways for viewers to physically reach you: chat is text, tips are numbers, both at a remove. Throwing is one of the few interactions that actually moves the model: what they threw, where it landed, how far you got pushed are all visible, and your reaction is the content.

Getting started

Add the throwing widget's OBS URL as a browser source.
Enable the API in VTube Studio and enter the connection address (usually the same machine).
New models auto-detect the hit zone for a rough fit by default; turn auto-detect off to fit it to your model by hand.
Create throwable items: image, sound, and the reaction on impact. To use your channel emotes as props, pick several at once and add them in one go; each item takes its emote name.

Hits and reactions

The hit zone is an ellipse that follows the model's anchor, sized as a proportion of the screen height. On impact the model can be knocked back, trigger a VTube Studio hotkey (an expression, say), and automatically fly back to its original position after a set number of seconds.

New models leave the hit zone to auto-detect by default, which reads the model outline VTube Studio reports and works out where the face is and how big it is. It recalculates when you switch models, so you don't have to recalibrate each one. While it is on, the hit zone fields are locked and worked out for you; turn it off to set them yourself.

Auto-detect is an estimate and gets you roughly there. It works from the model outline, and an outline can't tell hair or a hat apart from the head, so models with long hair, headwear or chibi proportions drift more. You can turn it off and adjust by hand if the placement looks wrong; to fine-tune from where it landed, use "Fill from auto values" to copy the numbers into the manual fields and edit from there.

Character HP bar

You can layer a game on top: give the character an HP bar that drains as it gets hit. Each item carries its own damage value, and when the bar empties, the viewers who took part in that round get rewarded (everyone or a random few, splitting a pool or a fixed amount each), along with a message in chat. The bar then sits empty for a few seconds before refilling.

An item with 0 damage is pure spectacle: fun to throw, no effect on the bar. Handy when you want some props to be decorative only.

Healing the bar

The bar does not only go down. There are two ways to put HP back, and you can use either one or both: auto regen restores a fixed amount every so often, which keeps a long stream from bottoming out, and heal on reward redemption binds a custom channel points reward so every redemption tops the bar back up, turning "rescue the streamer" into something viewers can do. The two amounts are set separately and do not affect each other.

For the redemption one, clearing the reward name turns it off; there is no separate switch. Neither kind goes above max HP, and neither lifts the bar out of the zero-out cooldown (during that window the bar stays at 0). Healing does not count as being hit, so a bar set to "show when damaged" will not pop up on its own just because it healed.

Common misconceptions

Testing throws yourself won't hand out rewards by accident. The bar takes damage from every hit, including ones you trigger from the test button, but the participant list only records hits it can trace back to a viewer. Emptying the bar while testing just resets it.
A reward only goes out once viewers have dealt a full bar's worth of damage. Test-button throws and hits that can't be traced to a viewer (anonymous Cheers or YouTube-triggered throws, for example) still take HP off and can empty the bar, but only viewer damage counts toward the reward. If viewers add up to less than one full bar in a round, the bar still empties and refills with no payout, and their damage carries over into the next round. Rounds emptied by viewers alone aren't affected. Such a round leaves a "Not enough viewer damage" entry in the HP log; expand it to see how much viewers dealt and how far short it fell. If several such rounds pass with no new viewer damage, only the first one is logged; the next entry appears once a viewer lands another hit. This is deliberate: otherwise anyone holding the OBS widget URL could finish the bar with a few fake hits and make one paid throw collect again and again.
Running the OBS widget in more than one place doesn't double the damage. If you have a source in two scenes, or the widget open in a browser tab as well, every copy sees the same items land, but each item takes HP off once and counts as viewer damage once.
The zero-out cooldown is how long the bar stays empty, not a "no rewards for a while" timer. The bar sits at zero for those seconds before refilling, and hits during that gap don't count at all: no damage, and no place on the next round's participant list.
"Only when hurt" isn't the same as "whenever HP is missing". The bar appears the moment damage lands, then fades out after the seconds you set with no further hits, even if HP is still well short of full. Use "always visible" to keep it on screen.
The HP bar works without Pro; only the automatic payout needs it. With auto-grant off (or a lapsed plan) the zero-out message still goes out, and your settings stay exactly as you left them, so they take effect again once Pro is back.
{percent} in the HP text doesn't include the percent sign. Write {percent}% to show 87%; that's what lets you build variants like "87 %" or "HP 87%".
HP doesn't survive a restart. The bar goes back to full when the server restarts; your settings are unaffected.
The heal reward name has to match the one on Twitch exactly. Matching is on the name itself, so renaming it on Twitch breaks the link. Picking it from the field's list is the safest route. Redemptions also ignore command permissions and cooldowns, so to limit how often it happens, set a cooldown or a per-viewer limit on that Twitch reward.
The widget connects directly to VTube Studio on your machine, not through our servers. Model position and impact reactions are handled locally, so nothing happens if VTS isn't running.
"Knocked out" is measured by how far the model's centre passes the screen edge, not by how it looks. The model is positioned by its centre, so scaled-up models need a larger value; otherwise it stops while still clearly visible.
The return delay counts from when the throwing stops. It won't snap back mid-barrage, so a sustained volley doesn't get interrupted.
Toggle-style hotkeys need a restore delay. That fires the same hotkey a second time to undo it; for hotkeys that revert on their own when the animation finishes, leave it at 0.
Images accept http(s) URLs only, not data: URLs. GIFs animate, but a cross-origin file needs CORS permission from the host.
Items over your plan's limit aren't pushed to the widget. They stay in the list but won't appear on screen; delete other items or upgrade to restore them.

Settings

Physics, hit zone, reaction and VTube Studio settings. Changes apply and save instantly to the connected widget.

Items hitting the character drain the HP bar; when it empties, participants get rewarded. HP is server-authoritative and applies live.

Pick several Twitch emotes at once and create them as items; each item takes its emote name. The sound and values below apply to the whole batch; edit an item individually to fine-tune it.

Triggers are automation rules with a Throwing action. Cooldowns, permissions and advanced conditions are edited in Automated messages.

The text below is taken from the in-app help, so it stays in sync with the actual interface.

Setting	What it does
Hit particles	Show a particle burst when an item hits the model.
Default burst interval (ms)	Delay between items in a multi-throw. 0 uses no extra delay.
Hit zone Y offset	Nudges the hit zone up/down relative to the green crosshair (the crosshair stays put); usually leave it at 0; to move both together, use Offset Y.
Auto-detect hit zone	Estimates the face position and size from the model outline VTube Studio reports, and recalculates when you switch models. It's an estimate and gets you roughly there (long hair, hats and chibi heads throw it off more). You can turn it off and adjust by hand if it doesn't look right.
Head flinch	Shake the head via parameter injection when hit.
Knockback	Push the model when hit; behavior depends on the knockback mode below.
Return delay after hits stop (s)	The model flies back to its original spot this many seconds after the hits stop; it won't return mid-barrage, even when already knocked off-screen.
Knock-out distance	How far past the screen edge the model's center must be pushed to count as knocked out (1 = just past the edge, 5 = far). The model is positioned by its center, so increase this for large or zoomed-in models, or it will stop while still visible.
VTS hotkey ID	Optional VTube Studio hotkey triggered on hit (e.g. an expression).
Hotkey restore delay (s)	For toggle-type hotkeys: triggers the same hotkey again after this many seconds to restore it; while the effect is active it won't re-trigger, and further hits postpone the restore. 0 = no auto-restore (animations that end on their own, or looping hotkeys, don't need it).
Connect VTube Studio	The widget connects to VTube Studio on the streaming PC for model position and hit reactions.
VTS API address	Usually ws://127.0.0.1:8001 (VTube Studio on the same PC as OBS).
Enable HP bar mode	Viewers deal damage when they hit the character; rewards are handed out to participants when the HP bar reaches zero
Show HP numbers	Show HP text on the bar (format and alignment are customizable)
Text format	Use {current} for current HP, {max} for max HP, {percent} for the percentage (no % sign). Leave blank to use “{current} / {max}”.
Bar label	Text shown above the HP bar (leave blank to hide)
Seconds visible after a hit	The bar appears the moment HP is deducted and hides again after this many seconds without another hit
Ranks to include	Equal damage shares a rank, so more viewers than this may win
Auto-grant points	Automatically grant points to participants when the HP bar hits zero (Pro only; the winner list is still announced when off)
Total pool	All winners split this point pool evenly
Points each	Each winner receives this many points
Minimum participants	No points are granted when fewer than this many take part (0 = grant as long as anyone joins)
Max points per payout	Most points paid out in a single zero-out (safety cap)
Zero-out cooldown	After the bar empties it stays at zero for this many seconds, then refills automatically. Hits during that window deal no damage and do not count as participation (0 = refill immediately)
Zero-out message	Announce the winner list in chat when the HP bar hits zero
Post via /announce	Send as a highlighted Twitch /announce; otherwise a normal chat message
Auto HP regen	Restores HP at a fixed interval. It pauses during the zero-out cooldown, and regen alone never makes a 'show when damaged' bar appear
HP per tick	How much HP each tick restores, never going above max HP
Heal on reward redemption	When a viewer redeems this custom channel points reward, the broadcaster gets HP back. Leave the name empty to turn it off.
HP per redemption	How much HP one redemption restores. It is counted separately from auto regen and never goes above max HP.
Weight ×	Heavier items fly slower but hit harder.
Damage	How much HP a hit removes from the character's HP bar (0 = effect only, no damage)
Over limit	This item exceeds your plan's item limit and won't be pushed to the widget; delete other items or upgrade your plan to restore it.
Calibration marker	Show the anchor cross (green) and hit-zone ellipse (red) on the widget. The cross is the model center reported by VTS; on full-body models it often sits near the hips, and can be low or even off-screen when only the upper body is shown. Use Offset to bring the cross to the character's chest, then use the hit-zone settings to cover the part that should get hit.
Zoom follow	How strongly the offset and hit zone follow when you zoom the model in VTS. 1 = exact follow (default), normally no adjustment needed; fine-tune only if a model still drifts slightly after zooming: drifts away → increase; overshoots → decrease.
Enable Throwing	When off, throwing triggers and the OBS widget stay inactive.
Points granted	Points were actually credited
Granting off	'Grant points automatically' is off, so this round only announced
Not Pro	Automatic granting is a Pro feature. Your settings are kept, but this round only announced
0 each	The amount was split down to zero or clamped by the per-settlement cap, so each winner worked out to 0
Too few winners	Fewer winners than the minimum, so this round granted nothing and stayed silent
Not enough viewer damage	The bar was emptied, but damage traced to viewers came to less than one full bar (test throws, anonymous and YouTube-triggered throws don't count). Nothing was granted or announced; the damage carries over to the next round

Other notes

The hit zone is an ellipse that follows the model anchor. Sizes are relative to the screen height.
Auto-detect is on, so these are worked out for you. You can turn it off to adjust them, or use "Fill from auto values" above and edit from there.
http(s) URL to a browser-decodable audio file (wav/mp3/ogg).
Calibration maps VTS model coordinates to screen pixels; changes apply instantly; turn on the marker and adjust against your OBS view (without VTS the marker shows the fixed anchor).
Calibration, hit zone, VTS hotkey and knockout edge are saved per VTube Studio model (up to 10); switching to a saved model applies its profile automatically, unsaved models use the global defaults.
Hotkey and knockout edge are per-model fields; adjustments are saved to this model.
Viewers throw items at your Live2D model, which reacts on impact (requires VTube Studio)
One entry per zero-out settlement, kept for 30 days only.

Other settings

These settings have no additional help text in the dashboard; only their names are listed here.

Reset to defaults
Quick apply
Gentle
Standard
Wild
Physics
Throwing
Hit zone
Hit reaction
Audio
VTube Studio
Character HP bar
Gravity (px/s²)
Throw speed (px/s)
Max spin (deg/s)
Item base size (px)
Max concurrent items
Bounciness
Spawn sides
Left
Right
Top
Bottom
Top-left
Top-right
Bottom-left
Bottom-right
Hit zone width
Hit zone height
Current auto values:
Detecting, reading the model outline…
Fill from auto values
No model outline detected, so your manual values are being used for now. Check that VTube Studio is connected and a model is loaded.
Reaction strength
Knockback mode
Bounce back
Cumulative (can knock off-screen)
Knockback strength
Return time (s)
Hotkey chance
Sound effect volume
VTS authorization saved: reloading the widget will not ask again.
Not authorized yet: the first connection pops an authorization dialog in VTube Studio.
Step-by-step guide
How to connect VTube Studio
Open VTube Studio, click the gear icon (⚙) in the top-left to open Settings, then find the "VTube Studio Plugins" panel and turn on the option to start the API (allow plugins). The port defaults to 8001; make sure it matches the "VTS API address" field below.
Once the status turns green and shows the API has started and is running, VTube Studio is ready on its side.
Back on this page, turn on "Connect VTube Studio". VTube Studio will pop up a plugin authorization dialog; find "ChiwaBots Throwing" and click Allow to finish. You only need to authorize once; it won't ask again after restarting VTube Studio.
Max HP
HP bar position
Follow model
Fixed position
Y offset
Horizontal position
Vertical position
Up
Down
Appearance
Bar width
Bar height
Text alignment
Center
Current HP
Percentage (no %)
When to show
Always visible
Only when hurt
Zero-out reward
Recipients
All participants
Random pick
Top damage
Number to pick
This is below "Minimum participants", so points will never be granted
Point mode
Split total pool
Fixed per person
Enable zero-out message
Custom message
Default:
Reset to default
Winner list
Number of winners
Points (pool or each) (full 1,200)
Points (pool or each) (Chinese units 1.2萬)
Points (pool or each) (Japanese units 1.2万)
Top damage dealer
X offset
Regen interval (s)
HP recovery
Select all
Enable
Disable
Delete
Clear selection
Add item
Add emotes
Add emotes in bulk
Add selected
No items yet.
Upgrade to Pro for a higher item limit.
Name
Image
Sound
Size ×
Volume ×
Enabled
Preview
Open Automated messages
Quick create
No throwing triggers yet.
New throwing trigger
When to throw?
No items yet; add some on the Items tab first.
Trigger
Fired
Calibration guide
Calibration & hit zone setup
Turn on the Calibration marker below; your OBS widget then shows a green crosshair (the model center reported by VTS) and a dashed red ellipse (the hit zone).
Drag Offset Y to move the green crosshair onto the character's neck or chest; it's usually negative (upward), most often between -200 and -600 depending on the model.
Back in Hit zone, adjust Hit zone height and Hit zone width so the dashed red ellipse hugs the model's outline and covers the area you want hit.
Test & calibration
Test throw
Test throw ×100
Offset X
Offset Y
Return model now
Model profiles
Current model
No model detected (OBS widget or VTube Studio not connected)
Has profile
Using global defaults (auto-saved on adjust)
Zoom baseline
Current
Scale
Zoom baseline not locked yet; adjust the calibration or hit zone to lock it, so it survives model switches.
Saved models
Per-model field: adjustments are saved to this model
Expand
Announcement
damage
Viewer damage
All results