Won't Update Here Anymore

I move tutorial to this website with 6 languages : https://vfinity.zyphite.com/

Prerequisites

Required

Optional (Recommended)

Network Notes

• Vfinity talks to VTube Studio over a local WebSocket (default port 8001).
• The TikTok bridge sidecar connects outbound to TikTok's live servers — make sure your firewall allows it.
• The OBS overlay uses a local WebSocket on a configurable port.
• The Generic API connects outbound to your custom WebSocket server (default localhost:8080).

Getting Started

1. Install Vfinity

Windows

1. Download Vfinity_x.x.x_x64-setup.exe (or the .msi).
2. Run the installer and follow the prompts.
3. Launch Vfinity from the Start Menu or desktop shortcut.

⚠️ Windows SmartScreen may warn on first run — click More info → Run anyway. The app is not code-signed yet.

macOS

1. Open the .dmg and drag Vfinity into Applications.
2. On first launch, right-click → Open to bypass Gatekeeper (only needed once).

Linux

1. Download vfinity_x.x.x_amd64.AppImage.
2. Make it executable and run:

chmod +x vfinity_*.AppImage
    ./vfinity_*.AppImage

Some distros require libfuse2 for AppImage. Install via your package manager if prompted.

2. First Launch

Vfinity opens on the Dashboard tab. The app has four tabs:

3. Connect VTube Studio

Open VTube Studio and load your model.

Go to Settings → API and toggle Enable API on.

In Vfinity, go to the Dashboard or Connections tab.

Set the VTS host and port (defaults: localhost / 8001).

Click Connect VTS.

VTube Studio shows a permission prompt, click Allow.

The status turns green (Authenticated). You can now trigger hotkeys, move your model, and apply VFX presets.

4. Connect TikTok LIVE

• Make sure your TikTok account can go live.
• In Vfinity, go to Dashboard or Connections.

• Enter your TikTok username (your @handle).

• Choose a connection type:

Built-in Bridge - Vfinity launches a native bridge process for a reliable connection.

WebSocket(Tikfinity) - for advanced users running their own TikTok event server.

• Click Connect TikTok.

• Start a TikTok LIVE - events (gifts, likes, follows, comments) appear in Vfinity in real time.

5. Create Your First Event Mapping

Event mappings tell Vfinity what to do when a TikTok event occurs.

• Go to the Events tab and click New Event.
• Set the Event Type — Gift, Like, Follow, Chat, Sub, or API Trigger.

• Add a Condition (optional) - filter by gift name/ID, minimum diamonds, chat keyword, etc.

• Choose an Action Type:

Trigger Hotkey — fires a VTube Studio hotkey by name.

Move Model — nudges or teleports your model.

VFX Preset — applies a post-processing preset.

Throw Item — launches a physics object at your model (visible in the OBS overlay).

• Set the action parameters and click Add Mapping.
• The mapping is active immediately then test it during a live!

6. Set Up the Throwing System

The Throwing system turns TikTok gifts into physics objects that fly at your VTuber model, collide with body-part hitboxes, and trigger reactions (flinches, sounds, knockback).

6a. Define the Throwing Zone & Body Parts

1. Go to the Throwing tab.
2. Use the Throwing Zone Editor to place and resize the zone where gifts appear.
3. Add Body Parts (e.g., head, torso, left_arm) as named hitbox regions.
4. Optionally set per-part: hit sound, reaction (hotkey/move/VFX), and cooldown (ms).

6b. Configure Gift Physics

In the Throwing tab, set physics overrides per gift — custom mass, friction, restitution (bounciness), and scale. Expensive gifts can hit harder or look bigger.

6c. Enable Auto-Throw on Gift

Toggle Auto-throw on gift in the Throwing tab. Every incoming gift automatically launches a projectile at a mapped body part — no manual event mapping needed.

6d. Add the Overlay to OBS

1. In Vfinity, go to Connections and note (or set) the Overlay Port.
2. In OBS, add a Browser Source.
3. Set the URL to the overlay address shown in Vfinity (typically <a href="http://localhost:">http://localhost:</a>">http://localhost:"><a href="http://localhost:">http://localhost:</a>/throwing).
4. Set dimensions to your stream resolution (e.g., 1920×1080).
5. The throwing physics now renders on top of your VTube Studio capture during lives!

Generic API WebSocket (For Developers)

Vfinity connects to an external WebSocket server you control, letting Stream Deck plugins, Python scripts, or custom games trigger events.

Vfinity is the client — it connects to your server.

1. Run a WebSocket server (Node.js ws or Python websockets).
2. In Vfinity → Connections, enable Generic API WebSocket and set host/port.
3. Click Connect API.
4. In the Events tab, create a mapping with Event Type → API Trigger and a matching Trigger Name.
5. Send this JSON from your server:

{
      "type": "trigger",
      "name": "your_trigger_name"
}

Node.js Server Example

Requires ws (npm install ws):

const WebSocket = require("ws");
    const wss = new WebSocket.Server({ port: 8080 });
    wss.on("connection", (ws) => {
      console.log("Vfinity connected!");
      setInterval(() => {
        ws.send(JSON.stringify({ type: "trigger", name: "test_trigger" }));
      }, 5000);
    });

Python Server Example

Requires websockets (pip install websockets):

import asyncio, websockets, json
    async def handler(websocket):
        print("Vfinity connected!")
        while True:
            name = await asyncio.to_thread(input, "Trigger name: ")
            await websocket.send(json.dumps({"type": "trigger", "name": name}))
    async def main():
        async with websockets.serve(handler, "localhost", 8080):
            await asyncio.get_running_loop().create_future()
    asyncio.run(main())

Appearance & Themes

Three built-in themes: Streetwear, Modern, and Potato. Switch from Connections → Appearance. Light/dark mode persists across sessions.

Auto-Connect

Don't want to manually connect every time?

1. Go to Connections.
2. Toggle Auto-connect on launch.
3. Vfinity reconnects to VTube Studio, TikTok LIVE, and the Generic API automatically on startup.

Troubleshooting

Debug Mode

Enable Debug Mode in Connections for verbose logging. Press F12 in Vfinity to open the developer console.

Quick Reference