Creating .var Packages

When you distribute your Virt-A-Mate scene as a .var file, the scene references Voxta resources (characters, scenarios, memory books) by ID. Those resources won’t be 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.

Make sure to review the Publishing Guidelines before publishing.

How it works at runtime

  1. User opens your scene.
  2. 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 (since they haven’t imported it).
  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.

Two ways to bundle resources

Option A — Drop-in individual resource PNGs (simplest)

Best when your scene needs only one or two resources.

  1. In Voxta Studio, open the resource (character/scenario/memory book) and export it 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:

    Kind Folder
    Character Saves\PluginData\Voxta\Characters\
    Scenario Saves\PluginData\Voxta\Scenarios\
    MemoryBook Saves\PluginData\Voxta\MemoryBooks\

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

  5. Also add your scene JSON, then Prep Package and Finalize Package.

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 character’s UUID — in this example, 916a705b-7366-9d23-ddb4-66399c773194. That’s the value you use in the filename.

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

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

Option B — Bundle multiple resources as a Voxta 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 — this 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.

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\... (leaving only the copy inside your .var).
  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 afterwards.

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.