Audio and VFX Assets

Audio in Vastopia#

Audio assets are sound effects and music files that live in your project's assets/audio/ folder, are tracked by the asset library like any other asset, and ship to players inside the game's PCK. Today, audio is played in game by locations: named areas you paint on a map in the Map Editor's Regions mode. A location can carry an ambient loop, a music track, and one-shot sounds for entering and leaving. The server tells a player's client when they cross into or out of a location, and the client plays the audio attached to it.

Use audio assets when you want:

• A looping soundscape for an area (wind on a cliff, a crackling fire in a tavern).
• A music track that starts when the player walks into a zone and fades when they leave.
• A stinger when the player enters a boss arena, or a sting when they leave a safe zone.

There is no client-side scripting, so there is no way for a server script to play an arbitrary sound on a player's client; audio reaches players through location data only. See Regions and elements for locations themselves.

Supported formats and where they go#

The asset library classifies audio by file extension when you import it:

An imported file is copied into the folder for its type and renamed to its generated asset id (for example assets/audio/sfx/01J8…Z.ogg); the original file name and the display name are kept in the library entry. The library also records the format, the file size and, when it can read it, the duration.

The client can load all three formats straight from the packed game files, so nothing else needs to be converted or configured for a sound to play.

Import audio#

Audio is imported from a file dialog rather than by dropping files into a grid. Any of these routes works, and they all produce the same library entry:

From the Assets editor#

1. Click Assets in the top bar.
2. Click Import in the toolbar. The "Import Asset" dialog opens; choose the Audio filter (*.wav, *.ogg, *.mp3) and pick one or more files.
3. The files appear under the Sound Effects or Music category according to their extension.

The category you have selected on the left does not change the type — an .mp3 becomes Music and a .wav or .ogg becomes a Sound Effect regardless of where you were browsing.

From a location's audio picker#

Each audio field on a location has its own Import button inside the picker popup (see the next section). A file imported from a picker takes the picker's type: an .ogg chosen through the Music Track picker is imported as Music and lands in assets/audio/music/. The picker then selects it for you.

From the Library tab#

Library in the top bar has an Import Asset button that accepts the same audio formats. Anything imported here is also queued for upload to the cloud library, as is every import (see Cloud Library).

Browse, preview and inspect#

In the Assets editor, pick Sound Effects or Music in the categories rail. Selecting a file fills the details panel on the right:

• The name and project path.
• Type, import date, Duration (when it could be read), Format and File size.
• Tags, or "No tags".
• Play and Stop buttons to audition the file.
• A Used by: list.

Attach audio to a location#

Locations are created and edited in the Map Editor's Regions mode (the Region button in the viewport's edit-mode toggle) with the Locations tool — the "Paint Location" button in the region toolbar. Select a location to see its properties in the right-hand panel; the audio fields sit in a collapsible section headed Audio.

Each field is an asset picker: a thumbnail-and-name display, a Select asset button, a play button that previews the selected sound (press again to stop), and an X button that clears the field.

To set one:

1. Click Select asset next to the field.
2. In the popup, type in Search assets... to filter the list, then click the sound you want.
3. If the sound is not in the project yet, click Import in the popup, choose the file, and it is imported and selected in one step.
4. Save the map (Ctrl+S). Audio changes mark the map as modified like any other edit.

The selection is stored as the asset's path in the map's regions.json, and exported for the server into server/data/maps/location_bounds/<map>.json as a path relative to the project root (for example assets/audio/music/01J8….mp3), alongside the location's tiles, environment overrides and other settings. See Map files and export.

The Tools editor's Location Editor groups same-named locations across maps and edits their shared properties in one place; its Enter sound and Leave sound fields are plain text boxes holding those same paths.

What the player hears#

On the client, every player has three audio buses — Ambient, Music and SFX — and the behavior on crossing a location boundary is fixed:

1. Entering. The Enter Sound plays once. The Ambient Track starts looping, crossfading from whatever ambient was playing before (about two seconds). The Music Track starts looping after the enter sound finishes (immediately if there is none), also crossfading. If the new location uses the same music file as the previous one, the track keeps playing rather than restarting. The location's environment (fog, ambient light, sun) transitions at the same time.
2. Leaving. The Leave Sound plays once, and the music and ambient fade out.

A field left empty is simply skipped, so a location can have only ambient, only music, or just an enter stinger.

Audio in the cloud library#

Audio you import is uploaded to the cloud library in the background and appears under Misc › Audio in the Library tab, with SFX and Music chips. Audio cards carry a waveform thumbnail, and an audio asset's details popup has a Preview button so you can listen before adding it to a project. Cloud audio files are capped at 64 MB each. Audio pulled from the cloud is an ordinary file in assets/audio/, recorded in the project's cloud_assets.json so it can be restored on another machine. See Cloud Library.

Visual effects (VFX)#

VFX are not assets in the Assets editor; they are authored in the Data Editor's VFX sub-editor. Each effect is a small node graph — plain nodes, particle emitters, primitive meshes, and imported 3D models — saved as a self-contained scene at assets/vfx/<name>.tscn, with assets/data/vfx_database.json holding only the effect's id, name, scene path and scale. Models placed inside an effect come from the same model library as everything else, with the chosen animation clip baked into the scene so the client plays it without any special handling.

Effects cannot carry audio: there is no sound node in a VFX graph, and sounds play through locations as described above.

Read VFX for the node types, how models are embedded, and the rule that a saved effect must not reference any external resource file.

Reference#

Audio formats by surface#

Files touched#

With AI (MCP)#

• import_asset — import a .wav, .ogg or .mp3 from disk into the project's asset library; the type is detected from the extension, or pass type to force Sound Effect or Music.
• list_assets — list what the project holds, including audio.
• define_location — define or edit a location's tiles, fog, weather and difficulty from an agent. It does not take audio fields, but it upserts by name and keeps any audio tracks you set in the editor, so you can attach audio in the Map Editor and let an agent reshape the area afterwards.
• request_asset — record that the project needs a sound the agent cannot make, so it shows up under AI Asset Requests in the Library tab for you to import.