Grimwar/Custom content

Overview · Getting started · SDK setup · Maps · Custom content · Entities · VSig · VMod · Workshop · Addons · Servers · Help

Custom content includes sounds and music, textures and materials, models and prefabs, plus fonts, video, and data. Start with the kind of asset you want to add:

Content	Guide
Sounds, ambient audio, and music	Import and play audio, including playback types and volume.
Textures and Unity materials	Create a material in your shared asset library.
Models and prefabs	Import a model, assign materials, and add collision.
One Materials and Models selection for all your maps	Set up a shared Unity asset library outside map folders.
Shared sounds and other imported media	Create a media pack and reference it from your maps or mods.
Audio and data in C# mods	Use media in a VMod.
File extensions, size limits, and naming	Supported imports and naming examples.

Keep reusable source assets in a general library outside your map folders. Use a Unity asset library for authored materials and prefabs, or a media pack for imported sounds and other supported files. Vertex's map Content window also supports files owned by one map. The SDK builds the required assets and records package dependencies.

Sounds and music

Import audio through the Sound type in Vertex or VSDK. It accepts WAV, Ogg Vorbis, and MP3, with a 32 MiB limit per source. Playback settings cover sound effects, ambience, announcements, and music; you do not need to create Unity materials or export a model catalog for audio.

For sounds shared across maps, first create a media pack in your general source library, then select its sound in the map's Content window and choose Use this package. Place an env_ambient entity and select that sound in Custom Cue, as in the placement steps below. Your original audio stays in the pack's source folder.

The following example imports a sound owned by one map. The same playback and entity controls apply when selecting a sound from a shared pack.

Add a sound to a map

Save the map, for example arena_mycustommap.vertex.
Open Settings → Map details → Content…, choose Sound, then Import files. Select my_wind_loop_01.wav.
Set Playback to AmbientLoop for a looping sound with a world position. Adjust Volume between 0 and 1.
Place an env_ambient entity and select the imported sound in Custom Cue. Leave Play On Start enabled to hear it when the map loads.
Build with Play in Game and check the volume and placement in Grimwar.

The imported sound has a key such as asset:arena_mycustommap/my_wind_loop_01. Custom Cue takes priority over the entity's base-game Event Name. You do not need to build Wwise banks or write an audio manifest.

The source stays under Content/, with its settings in content.json. Keep both with the map. Use Replace media to update the sound without changing its key.

Pick the playback type

Type	Use
Announcer	Non-spatial announcements.
Sfx2D	A non-spatial one-shot sound.
Sfx3D	A one-shot sound at a world position.
AmbientLoop	A looping sound at a world position.
MusicLoop	Looping music.
Ambience2DLoop	Looping non-spatial ambience.

For a sound that starts from a door or objective, disable Play On Start and call the ambient entity from a client VSig handler. See Server and client logic.

An ambient entity's Audible Distance is its emitter radius, not a guaranteed cutoff distance. Point mode stays at the marker. Volumetric mode follows the nearest boundary of its oriented box when the listener is outside and plays in 2D inside.

For Grimwar's built-in loading and gameplay score, see Map Settings and music. Importing an audio file does not add it to the built-in Music Set choices.

Make a reusable media pack

Open VSDK and select Media pack, then Create…. Choose a new source folder outside the SDK installation, such as shared_sounds. The folder name becomes the pack's stable ID.
Open Content… and set its title, author, and version.
Import your files and choose their settings. Mark assets intended for other packages with Include in build.
Select Check build contents and review the file list and size.
Build into Grimwar's add-on folder and enable the package in the game.

In another map or VMod's Content window, select an installed asset from this pack and choose Use this package. A reference such as asset:shared_sounds/my_wind_loop_01 points to the provider. The consuming build records shared_sounds as a requirement and leaves the sound bytes in the provider's package.

Install and enable both packages to test them. Publish the media pack first, then the map or mod that depends on it. Keep the provider ID and asset keys stable in updates. Removing or renaming a published key can break consumers even if the pack's display title stays the same.

Choose Copy files into this package when you want an independent copy you can edit and distribute. Check the creator's redistribution terms first. Other external references still keep their own dependencies.

Use media in a VMod

Open the VMod's Content… controls in VSDK. For an attached VMod, select it under the map's SDK resources and use that resource's Content button. Importing there gives the script local names for its own assets.

For a sound imported as my_round_start_01 with the Announcer or Sfx2D playback type:

var result = context.Audio.PlayToAll("my_round_start_01");
if (!result.Success)
    context.Log.Warn(result.Message);

Use a full asset key for a sound from a shared pack:

var result = context.Audio.PlayFromPlayer(
    playerId, "asset:shared_sounds/my_wind_loop_01", 0.5f);

Here context is the IModContext saved in OnLoad, and playerId identifies a connected player. This second example needs an AmbientLoop or Sfx3D cue. PlayFromPlayer uses the player's authoritative pawn position. Save result.Value from a successful play if you need to stop it later with context.Audio.Stop.

PlayToAll and PlayToPlayer accept non-spatial cue types. PlayAt and PlayFromPlayer accept Sfx3D and AmbientLoop. Playback gain multiplies the cue's own volume.

Use Use this package to record a selected provider. When declaring a dependency directly in a VMod manifest, put its add-on ID in requires. dependencies instead lists VMod IDs for script load order.

API 15 also exposes declared text/data through Content:

string rules;
if (context.Content.TryReadText("rules", out rules))
    context.Log.Write(rules);

Import the file through the resource's Content window and keep it included in the build. Content.Describe(key) reads asset metadata. These APIs operate on declared assets; they do not give a VMod access to arbitrary files.

Supported imports

Type	Source formats	Notes
Sound	WAV, Ogg Vorbis, MP3	Up to 32 MiB per source. Set the playback type and volume.
Surface material	PNG, JPG/JPEG, TGA	Creates a surface material from an image. Up to 16 MiB per source.
Image / texture	PNG, JPG/JPEG, TGA	Up to 16 MiB per source. Select the type the consuming field expects.
Model	FBX, OBJ	Import supported MTL and image companions alongside it. Review scale and collision.
Font	TTF, OTF	Requires a supported game consumer.
Video	MP4, WebM, MOV	Requires a supported game consumer; importing a clip does not place a video screen.
Text / data	TXT, JSON, CSV, Markdown	Up to 8 MiB per source; usable through the VMod Content API.
Binary data	BIN	Packaged data for supported consumers, not executable code.

Native Unity media, including models, materials, textures, fonts, and video, needs the SDK's pinned Unity compiler and target modules. Sounds and ordinary data use platform-independent files. Import support does not imply that every entity or VMod service can consume every type.

Naming examples

Use lowercase names with underscores for map and custom asset files. Give asset variants a numbered suffix such as _01. These examples use the same names throughout the guides:

Asset	Example
Map and companion script	`arena_mycustommap.vertex` and `arena_mycustommap.vsig`
Wall material	`my_brick_wall_01.mat`
Color texture	`my_brick_wall_01_basecolor.png`
Crate material, model, and prefab	`my_crate_01.mat`, `my_crate_01.fbx`, and `my_crate_01.prefab`
Ambient sound	`my_wind_loop_01.wav`
Catalog profile and exported catalog	`my_custom_assets.asset` and `my_custom_assets.vertexassets`

The map filename determines its ID: arena_mycustommap.vertex exports as arena_mycustommap. A readable display title such as My Custom Map is separate. Keep existing asset keys, catalog IDs, and Unity .meta files stable when updating published work. Keep supplied SDK files and folders at their installed names.

Keep builds small and repeatable

Use Check build contents to see what is included and why. Unreferenced files can stay in your source folder without shipping. Include in build keeps an asset available when code chooses its key at runtime; a referenced asset is included even if that checkbox is off.

Keep model companion files together. Use Rebuild model previews after editing a model externally. Rebuild the package after any source change; the compiler reuses matching verified output where it can.

Avoid copying the same large library into every map. Put shared assets in a media pack when you want a common update and dependency. Use an owned copy when a map needs to keep its own version.

Artwork and distribution

Set a media pack's title, author, version, and PNG thumbnail in Content. Use a 1920 × 1080 thumbnail for Release. Enable Release package in VSDK, build, and publish the result as Content from Grimwar's Addons screen.

Keep the entire output folder, including its generated addon.json and catalogs. The editable content.json is source; it is not an installable package by itself. See Grimwar/Steam Workshop addons for dependencies and updates.