Items Guide

This guide covers working with items (accessories, effects, etc.) in VTube Studio.

Getting Item List

To get a list of all available items:

from vtpy.data.requests import ItemListRequestData

response = await vts.request_item_list(ItemListRequestData())
items = response.data

for item in items:
    print(f"Item: {item.name}")
    print(f"  ID: {item.itemID}")
    print(f"  File: {item.fileName}")

Loading Items

To load an item:

from vtpy.data.requests import ItemLoadRequestData

response = await vts.request_item_load(
    ItemLoadRequestData(fileName="item-name.vtsitem")
)

if response.data:
    print(f"Item loaded: {response.data.itemID}")

Unloading Items

To unload an item:

from vtpy.data.requests import ItemUnloadRequestData

response = await vts.request_item_unload(
    ItemUnloadRequestData(itemID="item-id-here")
)

if response.data:
    print("Item unloaded successfully")

Controlling Item Animations

To control item animations:

from vtpy.data.requests import ItemAnimationControlRequestData

response = await vts.request_item_animation_control(
    ItemAnimationControlRequestData(
        itemInstanceID="item-instance-id",
        animationType="SetAnimation",
        animationName="animation-name"
    )
)

Animation Types

Available animation types:

• “SetAnimation”: Set a specific animation

• “SetAnimationFrame”: Set animation to a specific frame

• “SetSpeed”: Set animation speed

• “SetPause”: Pause/unpause animation

Moving Items

To move an item:

from vtpy.data.requests import ItemMoveRequestData, ItemPosition

position = ItemPosition(
    positionX=0.0,
    positionY=0.0,
    rotation=0.0,
    size=1.0
)

response = await vts.request_item_move(
    ItemMoveRequestData(
        itemInstanceID="item-instance-id",
        timeInSeconds=1.0,
        valuesAreRelativeToModel=False,
        position=position
    )
)

Sorting Items

To change the rendering order of items:

from vtpy.data.requests import ItemSortRequestData

response = await vts.request_item_sort(
    ItemSortRequestData(
        itemInstanceID="item-instance-id",
        moveUp=True  # or False to move down
    )
)

Pinning Items

To pin an item to a specific position:

from vtpy.data.requests import ItemPinRequestData

response = await vts.request_item_pin(
    ItemPinRequestData(
        itemInstanceID="item-instance-id",
        pin=True  # or False to unpin
    )
)

Listening to Item Events

You can listen to item-related events:

from vtpy.data.events import EventType, ItemEvent

async def on_item_event(event: ItemEvent) -> None:
    data = event.data
    print(f"Item event: {data.itemName}")

vts.on_event(EventType.ItemEvent, on_item_event)

# Subscribe to events
from vtpy.data.events import ItemEventSubscriptionRequestData

await vts.event_sub_item(
    ItemEventSubscriptionRequestData(subscribe=True)
)

Complete Example

import asyncio
from vtpy import VTS
from vtpy.data.requests import (
    ItemListRequestData,
    ItemLoadRequestData,
    ItemMoveRequestData,
    ItemPosition,
)

async def main():
    vts = VTS(plugin_name="MyPlugin", plugin_developer="MyName")

    try:
        await vts.start(host="localhost", port=8001)

        # Get available items
        items_response = await vts.request_item_list(ItemListRequestData())
        print("Available items:")
        for item in items_response.data:
            print(f"  - {item.name} ({item.fileName})")

        # Load an item (if you know the filename)
        # load_response = await vts.request_item_load(
        #     ItemLoadRequestData(fileName="some-item.vtsitem")
        # )
        # item_id = load_response.data.itemID

        # Move an item
        # await vts.request_item_move(
        #     ItemMoveRequestData(
        #         itemInstanceID=item_id,
        #         timeInSeconds=1.0,
        #         valuesAreRelativeToModel=False,
        #         position=ItemPosition(
        #             positionX=0.5,
        #             positionY=0.5,
        #             rotation=0.0,
        #             size=1.0
        #         )
        #     )
        # )

    finally:
        if vts.connected:
            await vts.close()

asyncio.run(main())