Voxta docs
IntegrationsVirt-A-MateCreating Scenes

VAR packages

Bundle characters, scenarios, and memory books inside your scene .var so first-time users auto-install everything.

When you distribute a VAM scene as a .var, the scene references Voxta resources (characters, scenarios, memory books) by ID. Those IDs won't exist on a first-time user's Voxta server, so you have to bundle them inside the .var. At runtime the Voxta VAM plugin detects the missing resource and auto-installs it on the user's server.

Always review the Publishing Guidelines before releasing a scene.

How it works at runtime

  1. The user opens your scene.
  2. The Voxta plugin tries to start a chat with the character / scenario your scene references.
  3. The user's Voxta server reports the resource as missing.
  4. The plugin looks inside the .var for a matching PNG (by resource ID), reads the bytes, and deploys them to the server.
  5. The server imports the resource automatically and the chat starts.

You'll see this line in the VAM log on success:

Voxta: Some resources are missing and will be installed: {resource-id}

If you see Could not find a scene dependency of type {Kind} with id {id}… instead, the PNG isn't bundled correctly — see Troubleshooting.

The fast way: VamPackageUpdater

VamPackageUpdater is a small Windows utility that does the manual bundling step for you. If you've already built a .var of your scene with VAM's Package Builder, the tool opens it, scans for Voxta resources the scene references, and lets you attach the matching PNGs without re-opening Package Builder.

Typical workflow

  1. In VAM, build your scene .var as usual with Package Builder — don't worry about the Voxta PNGs yet, just package the scene and any non-Voxta dependencies.
  2. In Voxta Studio, export each character / scenario / memory book your scene uses as a .png (or export them all together as a single Package PNG — see Option B below).
  3. Download the latest VamPackageUpdater.exe from Releases and launch it.
  4. Browse → pick the .var you just built.
  5. Open the Voxta resources tab. Every Voxta resource your scene references shows up with its status — Bundled, Missing, or Attached. For each Missing row, click the … button and point it at the PNG you exported in step 2.
  6. Update Package → a new .var lands in updated_packages/ next to the source, with the Voxta PNGs embedded at the exact paths the plugin expects.

Bonus features

  • Plugin references tab — bulk-rewrite outdated plugin versions (e.g. swap AcidBubbles.Voxta.42 for AcidBubbles.Voxta.86 across the whole .var).
  • Download deps tab — pulls any missing Hub dependencies your scene needs straight into your AddonPackages folder.

The tool is free and open source. The manual options below remain the canonical reference if you'd rather do everything in Package Builder.

Two ways to bundle resources manually

Best when your scene needs only one or two resources.

  1. In Voxta Studio, open the resource (character / scenario / memory book) and export as .png. Voxta names exports like Elara Meadowlight.character.1.0.0.png.

  2. Rename the file so it starts with the resource's UUID (see Where to find the UUID below). Both of these filename forms work:

    • {id}.{kind}.png — e.g. 916a705b-7366-9d23-ddb4-66399c773194.character.png
    • {id}.{kind}.{version}.png — e.g. 916a705b-7366-9d23-ddb4-66399c773194.character.1.0.0.png

  3. Place the file in the matching folder for its kind:

    KindFolder
    CharacterSaves\PluginData\Voxta\Characters\
    ScenarioSaves\PluginData\Voxta\Scenarios\
    MemoryBookSaves\PluginData\Voxta\MemoryBooks\

  4. Open Package Builder in VAM and click Add File… to include each PNG manually. Package Builder cannot auto-detect Voxta references inside plugin data — you must add them yourself. It will mark the scene reference as FIXABLE: References local file not included in package until the PNGs are added.

  5. Add your scene JSON, then Prep Package and Finalize Package.

Best when your scene uses several resources (e.g. a scenario plus multiple characters plus a memory book).

  1. In Voxta Studio, create a Package and add all the resources your scene needs.
  2. Export the package as .png — produces a single file containing every resource inside.
  3. In the Voxta VAM plugin UI, set the Package fields (ID, name, version). The plugin UI shows the expected file path on the bottom right — use that to name the file.
  4. Place the file at Saves\PluginData\Voxta\Packages\{PackageName}.package[.{version}].png.
  5. In Package Builder, Add File… → select the package PNG plus your scene. Then Prep Package and Finalize Package.

The package route installs every contained resource in one shot the first time a user opens the scene.

Where to find the UUID

For a character, open it in Voxta Studio, go to Edit Character → Assets tab. The panel shows the character's data directory, for example:

...\Data\Users\{your-user-id}\Characters\916a705b-7366-9d23-ddb4-66399c773194\Assets

The last folder segment before \Assets is the UUID — in this example, 916a705b-7366-9d23-ddb4-66399c773194. That's the value you put in the filename.

Scenarios and memory books expose their UUIDs the same way via their own Assets tab.

As a fallback you can read the UUID straight from your scene JSON — inside the Voxta plugin block, look for "Character ID", "Scenario ID", etc.

Testing before you publish

The only reliable test is a clean-slate round-trip:

  1. In Voxta Studio, delete the character / scenario / package you bundled (so your server no longer has it).
  2. Also delete the PNG from Saves\PluginData\Voxta\... (so only the copy inside your .var exists).
  3. Load your scene from AddonPackages (not from loose Saves).
  4. Start a chat with the character.
  5. Confirm the VAM log shows Voxta: Some resources are missing and will be installed: {id} and that the resource reappears in Voxta Studio after.

Troubleshooting

Could not find a scene dependency of type Character with id {uuid}…

The plugin couldn't find a bundled PNG matching the UUID. Check:

  • Filename starts with the exact UUID from the error message (not the friendly name).
  • File is in the matching Kind-folder (for example Characters\, not Packages\).
  • File was actually Added to the package in Package Builder, not just placed on disk.

Package Builder doesn't warn about the missing character.

Expected — Package Builder only understands VAM's dependency graph. Voxta resource references are opaque plugin data. You must manually Add File… each PNG.

Nothing happens; chat just doesn't start, no missing-resource message.

Check the VAM log for Voxta output. If the server already has the resource (because you previously imported it), there's no missing-resource event — the auto-deploy path is never triggered. Do the clean-slate test above.

Studio: Packages

Building packages in Voxta Studio.

Publishing guidelines

Hub release rules.

Adding Voxta to a scene

Build the scene before you package it.

Publishing guidelines

Rules and best practices for releasing Voxta-powered scenes to VaM Hub.

Companion VAM plugins

Other VAM plugins that pair well with Voxta — what they do and when to use each.

On this page

How it works at runtimeThe fast way: VamPackageUpdaterTypical workflowBonus featuresTwo ways to bundle resources manuallyWhere to find the UUIDTesting before you publishTroubleshootingRelated