Grimwar/Custom content - Revision history

DocumentationBot: Clarify custom content navigation and standardize asset examples

2026-10-04T16:29:52Z

Clarify custom content navigation and standardize asset examples

DocumentationBot: Keep custom assets in one library shared across maps

2026-10-04T16:11:47Z

Keep custom assets in one library shared across maps

← Older revision		Revision as of 12:11, 4 October 2026
Line 3:		Line 3:
	Use Content in Vertex or VSDK to import your own media. A map or VMod can own its files, or reference assets from another installed add-on. The SDK builds the required files and records those dependencies.		Use Content in Vertex or VSDK to import your own media. A map or VMod can own its files, or reference assets from another installed add-on. The SDK builds the required files and records those dependencies.

	'''~~Creating materials or model prefabs in Unity?~~''' ~~Follow~~ [[Grimwar/Unity custom content\|Unity materials and models for Vertex]]. ~~It shows exactly where to~~ create your textures, <code>.mat</code> files, models, and <code>.prefab</code> files, ~~how~~ to ~~export their~~ catalog, and ~~how to use them in an add-on map~~. The file-import workflow on this page ~~creates content from supported source~~ files; it does not import Unity <code>.mat</code> or <code>.prefab</code> files.		'''For custom assets shared across maps,''' follow [[Grimwar/Unity custom content\|Unity materials and models for Vertex]]. Keep one shared library outside your map folders, create your textures, <code>.mat</code> files, models, and <code>.prefab</code> files there, and connect each map to its catalog. They appear in your general Materials and Models selection. The file-import workflow on this page owns files within the map or resource; it does not import Unity <code>.mat</code> or <code>.prefab</code> files.

	== Add a sound to a map ==		== Add a sound to a map ==

DocumentationBot: Guide custom Unity materials and models into Vertex

2026-10-04T15:55:08Z

Guide custom Unity materials and models into Vertex

← Older revision		Revision as of 11:55, 4 October 2026
Line 2:		Line 2:

	Use Content in Vertex or VSDK to import your own media. A map or VMod can own its files, or reference assets from another installed add-on. The SDK builds the required files and records those dependencies.		Use Content in Vertex or VSDK to import your own media. A map or VMod can own its files, or reference assets from another installed add-on. The SDK builds the required files and records those dependencies.

			'''Creating materials or model prefabs in Unity?''' Follow [[Grimwar/Unity custom content\|Unity materials and models for Vertex]]. It shows exactly where to create your textures, <code>.mat</code> files, models, and <code>.prefab</code> files, how to export their catalog, and how to use them in an add-on map. The file-import workflow on this page creates content from supported source files; it does not import Unity <code>.mat</code> or <code>.prefab</code> files.

	== Add a sound to a map ==		== Add a sound to a map ==

	# Save the map, for example <code>my_arena.vertex</code>.		# Save the map, for example <code>my_arena.vertex</code>.
	# Open '''Map → Content…''', choose '''Sound''', then '''Import files'''. Select <code>wind_loop.wav</code>.		# Open '''Settings → Map details → Content…''', choose '''Sound''', then '''Import files'''. Select <code>wind_loop.wav</code>.
	# Set '''Playback''' to '''AmbientLoop''' for a looping sound with a world position. Adjust '''Volume''' between 0 and 1.		# Set '''Playback''' to '''AmbientLoop''' for a looping sound with a world position. Adjust '''Volume''' between 0 and 1.
	# Place an [[Grimwar/Entities/env_ambient\|env_ambient]] entity and select the imported sound in '''Custom Cue'''. Leave '''Play On Start''' enabled to hear it when the map loads.		# Place an [[Grimwar/Entities/env_ambient\|env_ambient]] entity and select the imported sound in '''Custom Cue'''. Leave '''Play On Start''' enabled to hear it when the map loads.

DocumentationBot: Version 1

2026-10-01T04:13:05Z

Version 1

New page

{{GameNav}}

Use Content in Vertex or VSDK to import your own media. A map or VMod can own its files, or reference assets from another installed add-on. The SDK builds the required files and records those dependencies.

== Add a sound to a map ==

# Save the map, for example <code>my_arena.vertex</code>.
# Open '''Map → Content…''', choose '''Sound''', then '''Import files'''. Select <code>wind_loop.wav</code>.
# Set '''Playback''' to '''AmbientLoop''' for a looping sound with a world position. Adjust '''Volume''' between 0 and 1.
# Place an [[Grimwar/Entities/env_ambient|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 <code>asset:my_arena/wind_loop</code>. 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 <code>Content/</code>, with its settings in <code>content.json</code>. Keep both with the map. Use '''Replace media''' to update the sound without changing its key.

=== Pick the playback type ===

{| class="wikitable"
! 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 [[Grimwar/VSig#Server and client logic|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.

== Make a reusable media pack ==

# Open VSDK and select '''Media pack''', then '''Create…'''. Choose a new source folder outside the SDK installation, such as <code>shared_sounds</code>. 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 <code>asset:shared_sounds/wind_loop</code> points to the provider. The consuming build records <code>shared_sounds</code> 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 <code>round_start</code> with the Announcer or Sfx2D playback type:

<syntaxhighlight lang="csharp">
var result = context.Audio.PlayToAll("round_start");
if (!result.Success)
context.Log.Warn(result.Message);
</syntaxhighlight>

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

<syntaxhighlight lang="csharp">
var result = context.Audio.PlayFromPlayer(
playerId, "asset:shared_sounds/wind_loop", 0.5f);
</syntaxhighlight>

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

<code>PlayToAll</code> and <code>PlayToPlayer</code> accept non-spatial cue types. <code>PlayAt</code> and <code>PlayFromPlayer</code> 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 <code>requires</code>. <code>dependencies</code> instead lists VMod IDs for script load order.

API 15 also exposes declared text/data through <code>Content</code>:

<syntaxhighlight lang="csharp">
string rules;
if (context.Content.TryReadText("rules", out rules))
context.Log.Write(rules);
</syntaxhighlight>

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

== Supported imports ==

{| class="wikitable"
! 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.

== 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 <code>addon.json</code> and catalogs. The editable <code>content.json</code> is source; it is not an installable package by itself. See [[Grimwar/Steam Workshop addons]] for dependencies and updates.

[[Category:Grimwar]] [[Category:Addons]]