Skip to main content
The avatar browser is the main interface for exploring the avatar database. It streams avatars from a local NDJSON cache file, renders them in a responsive card grid, and lets you equip avatars directly via the VRChat API.

Search

Filter by avatar name, author, and description simultaneously with case-insensitive matching.

Platform filtering

Toggle PC, Quest, and iOS filters independently to find cross-platform avatars.

Async image loading

Thumbnail images are fetched concurrently by 4 worker threads with a 256-texture LRU cache.

Equip avatars

Wear any avatar directly from the browser without opening the VRChat website.

​
Loading flow

On startup, the browser opens cache/avatar_entries.ndjson and streams it line by line. Each line is a single JSON-serialized AvatarEntry object (newline-delimited JSON). The file is produced by the database downloader. The file path is hardcoded as cache/avatar_entries.ndjson relative to the working directory. If the file does not exist, the browser displays an error prompting you to run the downloader first.

​
Avatar entry fields

FieldTypeDescription
nameStringAvatar display name
authorStringCreator’s VRChat display name
descriptionStringAvatar description
avatar_idStringFull VRChat avatar ID (avtr_...)
platformsVec<String>Normalized platform list: ["PC"], ["PC", "Quest"], etc.
questboolRaw Quest flag from the database
iosboolRaw iOS flag from the database
The platforms field is derived from quest and ios at load time: all avatars include "PC" by default, with "Quest" and "iOS" appended as appropriate. The browser provides three independent search fields — avatar name, author name, and description — all evaluated simultaneously. Matching is case-insensitive substring search. An avatar must satisfy every non-empty search field to appear in results.
Tag search is not currently implemented. The tags field is stored in each entry but is not included in the search filter. Tag-based filtering is planned for a future release.
Filters are applied by pressing Enter in any search field or clicking Apply Filters. The browser re-scans the full NDJSON file from the beginning to count all matching entries before loading the first page.
Applying a search filter or switching pages requires a full sequential scan of avatar_entries.ndjson. On large databases this causes an approximately 2-second UI freeze. An async fix is planned.

​
Platform filtering

Three checkboxes — PC, Quest, and iOS — act as inclusion filters. When a platform checkbox is enabled, only avatars with that platform in their platforms list are shown. Multiple platform filters can be active at the same time, requiring an avatar to match all of them.

​
Grid layout and pagination

Avatars are arranged in a responsive grid that fills the available window width. Column count is calculated dynamically based on the card width:
ConstantValueDescription
CARD_WIDTH240.0 pxFixed width of each avatar card
CARD_GAP12.0 pxSpacing between cards
CARD_IMAGE_WIDTH140.0 pxThumbnail image width
CARD_IMAGE_HEIGHT105.0 pxThumbnail image height (4:3 ratio)
PAGE_SIZE200Avatars loaded per page
Each page shows up to 200 avatars. Use the Previous and Next buttons in the toolbar to navigate between pages. The current page and total page count are displayed in the status bar.

​
Image loading

Thumbnail images are fetched asynchronously from the VRChat API by a pool of background threads:
ConstantValueDescription
WORKER_COUNT4Number of concurrent image-fetching threads
MAX_PENDING48Maximum number of in-flight image requests at once
MAX_TEXTURE_CACHE256Maximum number of decoded textures kept in memory
When the texture cache reaches 256 entries, the oldest textures are evicted (LRU order) to free GPU memory. Images are fetched via GET /avatars/{id} to retrieve the imageUrl or thumbnailImageUrl, then downloaded and decoded to RGBA8 before being uploaded as egui textures. Avatars that have been deleted, set to private, or removed from the VRChat platform are shown with a red (Removed) overlay instead of a thumbnail.

​
Avatar details panel

Each avatar card displays:
  • Thumbnail image (140×105 px, 4:3)
  • Platform badge(s): PC (green), Quest (orange), iOS (blue)
  • Avatar name (bold)
  • Author name
  • Description (italic, small)
Tags are stored in the underlying AvatarEntry but are not currently shown in the card view.

​
Actions

Each card exposes two action buttons: Open Web — opens https://vrchat.com/home/avatar/{avatar_id} in the system browser. Disabled for removed avatars. Wear — equips the avatar on your VRChat account by calling PUT /avatars/{id}/select. Requires an active login session. After equipping, the current avatar panel in the toolbar is refreshed automatically. Disabled for removed avatars.

​
VRChat API calls

MethodEndpointPurpose
GET/auth/userRetrieve the currently equipped avatar ID on startup and after equipping
GET/avatars/{id}Fetch avatar metadata and thumbnail URL for image loading
PUT/avatars/{id}/selectEquip an avatar

Build docs developers (and LLMs) love

Get started for freeTalk to us