View source for Grimwar/Unity custom content

{{GameNav}}

Build one personal asset library for Vertex's '''Materials''' and '''Models''' browsers. Every map connected to that library can select the same custom materials, models, and prefabs. This walkthrough adds a wall material and a crate prefab to that shared selection.

'''Keep the library in <code>Documents/GrimwarLibrary/</code>, and create your assets under its <code>Compiler/Assets/CustomContent/</code> folder.''' Keep map projects separately, for example under <code>Documents/GrimwarMaps/</code>. Set up the library once, export its catalog, and connect your maps to the same SDK copy. A folder alone does not register its contents with Vertex.

Use this library for textures, Unity <code>.mat</code> files, models, and <code>.prefab</code> files that you want in your general selection. Vertex's '''Settings → Map details → Content…''' imports files into the map's own source folder; those imports are covered separately by [[Grimwar/Custom content]]. Content's file importer does not accept <code>.mat</code> or <code>.prefab</code> files.

== 1. Set up your shared asset library ==

# Complete [[Grimwar/SDK setup|SDK setup]]. Install Unity <code>6000.3.17f1</code> and the build modules you need.
# In Steam, open Grimwar SDK's '''Manage → Browse local files'''. Locate <code>Grimwar.vertexsdk</code> and its sibling <code>Compiler</code> and <code>Authoring</code> folders.
# Copy that SDK folder, with all its contents, to <code>Documents/GrimwarLibrary/</code> outside Steam. This is your shared working copy for all your maps; create it once.
# Keep your Vertex maps in separate folders, for example <code>Documents/GrimwarMaps/MyArena/my_arena.vertex</code> and <code>Documents/GrimwarMaps/MyOutpost/my_outpost.vertex</code>. Both will use the same library.
# In Unity Hub, add the existing project at <code>Documents/GrimwarLibrary/Compiler</code> and open it with the pinned Unity version. Select '''Compiler''', not its parent folder or its <code>Assets</code> folder. Let package resolution, script compilation, and asset imports finish.
# For Unity's scene and material previews, open '''Edit → Project Settings → Graphics'''. If '''Default Render Pipeline''' is empty, assign the supplied <code>Assets/VertexSdk/Rendering/Pipeline.asset</code>. Keep the SDK's quality settings. See [https://docs.unity3d.com/6000.3/Documentation/Manual/srp-setting-render-pipeline-asset.html Unity's render pipeline settings].

'''Checkpoint:''' Unity's Project window shows <code>Assets</code>, including <code>CustomContent</code> and <code>VertexSdk</code>. Resolve any Console errors before continuing. This is the SDK's asset-authoring and compiler project; playtest the map in Grimwar.

The Steam installation and Vertex's generated compiler cache are replaceable. Neither is a place to keep your original work. Keep the SDK's supplied packages and base assets intact in your working copy.

== 2. Create the content folders ==

In Unity's '''Project''' window, expand <code>Assets/CustomContent</code>. Right-click it and use '''Create → Folder''' to create <code>Textures</code>, <code>Materials</code>, <code>Models</code>, and <code>Prefabs</code> directly inside it. These folders belong to your general asset library. You can add subfolders for themes or asset packs as the library grows.

After completing the guide, your files will look like this. Unity also creates <code>.meta</code> files beside assets and folders; keep those files.

<pre>
Documents/
  GrimwarMaps/
    MyArena/
      my_arena.vertex
    MyOutpost/
      my_outpost.vertex
  GrimwarLibrary/                   shared by both maps
    Grimwar.vertexsdk
    Authoring/
      Grimwar.vertexgame
      CustomAssets.vertexassets    exported catalog
      previews/                    generated catalog previews
    Compiler/                      open this folder in Unity Hub
      Assets/
        CustomContent/
          CustomAssets.asset       catalog profile created in step 5
          Textures/
            BrickWall_BaseColor.png
            Crate_BaseColor.png
          Materials/
            BrickWall.mat
            Crate.mat
          Models/
            Crate.fbx
          Prefabs/
            Crate.prefab
        VertexSdk/                 supplied SDK assets
      Packages/
      ProjectSettings/
</pre>

<code>Assets/CustomContent</code> is the path '''inside Unity'''. <code>Documents/GrimwarLibrary/Compiler/Assets/CustomContent</code> is the same folder on disk. <code>Authoring</code> is outside the Unity project's <code>Assets</code> folder. Neither map folder contains the library's source assets.

A '''texture''' is an image. A '''material''' combines a shader, textures, and surface settings. A '''model''' supplies meshes. A '''prefab''' saves a model's hierarchy, assigned materials, and components such as colliders. Vertex uses the material on a brush face and the model or prefab as a placed object.

== 3. Create a wall material ==

# Drag <code>BrickWall_BaseColor.png</code> from your file manager into <code>Assets/CustomContent/Textures</code> in Unity's Project window. Wait for import to finish.
# Right-click the <code>Materials</code> folder and choose '''Create → Material'''. Name it <code>BrickWall</code>; Unity saves <code>BrickWall.mat</code> there.
# Select the material. In the Inspector, set '''Shader''' to '''Universal Render Pipeline/Lit'''. Use '''Surface Type: Opaque''' for an ordinary solid wall.
# Drag the imported image into '''Base Map''' under Surface Inputs. Leave the adjacent color white to use the image's original colors.
# For a plain non-metallic wall, start with '''Metallic: 0''' and '''Smoothness: 0'''. Increase Smoothness only if you want a shinier surface. For a matte surface without specular shine, also disable '''Specular Highlights''' and '''Environment Reflections''' under Advanced Options.
# If you have a normal map, import it into <code>Textures</code>, select that texture, set '''Texture Type: Normal map''', and click '''Apply'''. Assign it to the material's '''Normal Map''' field. A normal map is optional.
# Save your project changes. The asset you will choose in Vertex is '''BrickWall''', the material, rather than the raw PNG.

Use an SDK-supported shader such as URP/Lit. A custom material can use that shader with your own textures and settings; add-on maps cannot bring arbitrary custom shaders or Shader Graph shaders from <code>Assets</code>.

'''Checkpoint:''' <code>Materials/BrickWall.mat</code> exists and its Base Map references your texture. Vertex's preview shows basic color and transparency; judge normal maps, reflections, and final lighting in the compiled game. For the remaining material controls, see [https://docs.unity3d.com/6000.3/Documentation/Manual/urp/lit-shader.html Unity's URP Lit reference].

== 4. Import a model and save a prefab ==

# Export a model such as <code>Crate.fbx</code> from your modeling tool. Use metres, a deliberate pivot, and UVs for the material. Put its image files in your <code>Textures</code> folder and the model in <code>Models</code>.
# Select <code>Crate.fbx</code> in Unity's Project window. Check its import scale and orientation. Apply changed import settings. As a size check, compare it with a Unity cube, which is one unit across at scale 1; one Unity unit represents one metre here.
# Create <code>Materials/Crate.mat</code> using the material steps above and its own Base Map. If the model already contains embedded materials, its '''Materials''' import tab can '''Extract Materials…''' into your <code>Materials</code> folder. Check extracted materials' shaders and texture assignments. See [https://docs.unity3d.com/6000.3/Documentation/Manual/FBXImporter-Materials.html Unity's model material settings].
# Drag <code>Crate.fbx</code> from the Project window into a temporary scene. On each relevant Mesh Renderer, assign <code>Crate.mat</code> to its '''Materials''' slots. For a model with several submeshes, assign the material for each slot.
# For a solid crate, add a '''Box Collider''' and adjust its Center and Size to fit. A renderer alone does not make an object solid. Keep the example a static prop; arbitrary custom C# components are not a substitute for supported Grimwar entities or map scripts.
# Name the scene object <code>Crate</code>. Drag it from the '''Hierarchy''' into <code>Assets/CustomContent/Prefabs</code> in the '''Project''' window. If Unity asks whether to create an Original Prefab or Prefab Variant, choose '''Original Prefab''' for this example. This creates <code>Crate.prefab</code>. See [https://docs.unity3d.com/6000.3/Documentation/Manual/CreatingPrefabs.html Unity's prefab creation guide].
# Select the saved prefab in the Project window and confirm it contains the renderer's material assignments and the collider. Later changes must be saved to this prefab, not left only on a scene instance.

'''Checkpoint:''' <code>Prefabs/Crate.prefab</code> is the assembled prop you will place in Vertex. The raw <code>Models/Crate.fbx</code> can also appear in the browser, but choosing it does not include overrides or colliders that you added only to the prefab.

Keep the model, prefab, materials, and textures beneath <code>Assets/CustomContent</code>. To reuse a model's material on brush faces, use a separate <code>.mat</code> file: embedded model materials are hidden from Vertex's material picker.

== 5. Export a catalog for Vertex ==

A catalog tells Vertex which assets exist and provides their previews. The original Unity assets remain in <code>Compiler/Assets</code> for the map compiler to use.

# In the Project window, right-click <code>Assets/CustomContent</code> and choose '''Create → Vertex → Asset catalog profile'''. Name the asset <code>CustomAssets</code>.
# Select it and set '''Catalog Id''' to <code>my_library.assets</code> and '''Catalog Version''' to <code>1</code>. Keep these values stable as you edit this asset library.
# Expand '''Folders''' in the Inspector and add one element. Set that element's '''Folder''' to <code>Assets/CustomContent</code> and '''Ownership''' to <code>custom</code>.
# Enable '''Materials''', '''Models''', '''Prefabs''', and '''Textures''' for that element. Leave '''Material Dependencies Only''' disabled so your standalone materials appear in the picker. Leave the other settings at their defaults.
# Save the project. With <code>CustomAssets</code> still selected, choose '''Tools → Vertex → Export Selected Asset Catalog'''.
# In the save dialog, navigate out of <code>Compiler</code> to your copy's <code>Authoring</code> folder. Save as <code>CustomAssets.vertexassets</code>. The exporter also writes a <code>previews</code> folder beside it.

'''Checkpoint:''' Both <code>GrimwarLibrary/Authoring/CustomAssets.vertexassets</code> and its preview files exist. Keep the catalog and previews together. Do not replace the supplied <code>Assets/VertexSdk/Assets.asset</code> profile or the base-game catalog.

Use <code>custom</code> ownership for your own files. <code>base</code> means the asset already ships with Grimwar; it does not mean “shared between my maps.” Incorrectly marking a new asset as base prevents the map from carrying the asset players need. You do not need to add your files to the base game's Addressables groups.

== 6. Connect your maps to the shared library ==

Edit the library's connection once, then choose it for each map. Two small JSON edits connect its editable Unity project and exported catalog. Use a plain-text editor, preserve the other fields, and keep the original files as backups outside the Unity <code>Assets</code> folder.

=== Tell Vertex to build from your Unity project ===

Open <code>Documents/GrimwarLibrary/Grimwar.vertexsdk</code> in a text editor.

# Keep <code>"compilerProject": "Compiler"</code>.
# Remove the <code>compilerInputs</code> property and its value. That inventory describes the unmodified distributed SDK.
# Add <code>"editorProject": "Compiler"</code> alongside <code>compilerProject</code>.
# Preserve <code>formatVersion</code>, <code>game</code>, and any <code>resourceTools</code> entries exactly as supplied. Separate neighboring properties with commas and leave no trailing comma before <code>}</code>.

The two project properties should now read as follows. This fragment shows only those properties; '''do not replace the whole file''' with it.

<syntaxhighlight lang="json">
{
  "compilerProject": "Compiler",
  "editorProject": "Compiler"
}
</syntaxhighlight>

This makes the copy a local developer connection: Vertex captures the saved assets from your <code>Compiler</code> project when building. Leaving the distributed connection unchanged would use its prepared compiler cache instead.

=== Add your catalog to the game's asset list ===

Open <code>Documents/GrimwarLibrary/Authoring/Grimwar.vertexgame</code>. Find the <code>assetCatalogs</code> array. Keep every existing entry, including <code>grimwar.base</code>. Add a comma after its last existing entry, then insert this additional object before the array's closing <code>]</code>:

<syntaxhighlight lang="json">
{
  "id": "my_library.assets",
  "version": "1",
  "path": "CustomAssets.vertexassets"
}
</syntaxhighlight>

The path is relative to <code>Authoring/Grimwar.vertexgame</code>, so do not prepend <code>Authoring/</code> again. Keep the game's ID, version, entity catalogs, and build configuration unchanged. The new entry's ID and version must match the Unity catalog profile from step 5.

=== Choose this connection in Vertex ===

# Save both JSON files and your Unity asset changes. Let Unity finish importing.
# Open your map in Vertex. Under '''Settings → Game and resources''', select '''Choose game SDK…'''. Choose <code>Documents/GrimwarLibrary/Grimwar.vertexsdk</code>, the file in your shared library. '''File → Open game SDK…''' opens the same chooser.
# Save the map. Open your other maps and choose that same connection. Saved maps remember their own SDK connection; each map can reference this one library without another SDK copy or asset import.
# Use '''Settings → Game and resources → Reload resources''' after subsequent catalog exports.

'''Checkpoint:''' Open either example map. Its '''Materials''' browser contains <code>BrickWall</code> and its '''Models''' browser contains your crate entries. Both maps select from the same library. Base-game materials and entities should still be available. If the base assets disappear, restore the original entries in <code>assetCatalogs</code>.

Do not use '''Load engine assets…''' as a substitute for this setup. Loading a loose preview catalog does not connect a map's compiler to the Unity source assets.

== 7. Use the assets and test the add-on ==

# In Vertex's material browser, search for <code>BrickWall</code>. Drag it onto a brush face; hold '''Shift''' while dropping to apply it to the whole brush. Adjust the face's texture scale and alignment as needed.
# In the model browser, search for <code>Crate</code>. Choose the entry whose source is <code>Prefabs/Crate.prefab</code> and drag it into a viewport. Place it, then check its size and orientation.
# Save the map. In Build, select '''Preview''' and your desktop platform, then '''Play in Game'''. If requested, select the pinned Unity executable and your Grimwar installation in the build settings.
# Walk around the crate in Grimwar to check collision. Inspect the wall's tiling, material, and lighting. Test the actual game even when the Vertex preview looks correct.
# When ready, use '''Export add-on''' with the Release profile and follow [[Grimwar/Steam Workshop addons|the publication guide]].

The build includes referenced custom Unity assets and their required custom dependencies. The exported catalog is a browser index, not an installable add-on; distribute the built add-on rather than loose <code>.mat</code>, <code>.prefab</code>, or <code>.vertexassets</code> files. Players do not need your Unity project to play the compiled map.

Grimwar's SDK still uses '''Play in Game''' and '''Export add-on''' with this connection. It does not provide the base game's playable Unity project or a '''Save to Unity''' workflow.

== Updating assets, sharing source, and SDK updates ==

For each edit: '''change the Unity asset → save/apply it → export CustomAssets to the same CustomAssets.vertexassets file → Reload resources in Vertex → rebuild and playtest'''. All connected maps use this library update when reloaded; rebuild each map you want to distribute with the changed asset. Editing only the PNG or prefab on disk does not refresh an already exported catalog. Changing a prefab instance in a temporary scene does not update the prefab until you apply or save those changes.

Keep existing <code>.meta</code> files and the catalog ID. Vertex references Unity assets by their GUID and local file ID, not just by filename. Move assets inside Unity when reorganizing; deleting and recreating an asset can break map references even if you reuse its name.

To hand editable source to another creator, share the map and scripts plus the library's custom asset folder with all <code>.meta</code> files and its catalog profile, the catalog with its previews, and the connection setup for the matching SDK release. They can keep the library in their own general asset folder and connect the map to it. A <code>.vertex</code> map alone does not contain these Unity source assets.

If you already created a library inside a map project, move its complete SDK folder to a general location such as <code>Documents/GrimwarLibrary</code>, then choose its new <code>.vertexsdk</code> location in each map. Keep its existing catalog ID, asset names, and <code>.meta</code> files; you do not need to rename existing assets to match this guide's example names.

Your personal SDK copy does not update when Steam updates. For a new SDK release, make a fresh working copy, transfer your custom folder with its <code>.meta</code> files, repeat the connection edits on the newly supplied files, and re-export the catalog with the required Unity version. Keep the old working copy until your map builds and playtests successfully. Do not overwrite new SDK packages or the new game profile with old versions.

Your editable source stays in the shared library. An exported add-on includes the custom assets its map references and their required dependencies; selecting one crate does not bundle the whole library. Referenced custom assets can therefore appear in more than one built add-on. The SDK's shared developer materials are already base-game assets. For reusable imported media distributed once as a separate dependency, see [[Grimwar/Custom content#Make a reusable media pack|media packs]]; the file importer there still accepts the formats listed on that page, not arbitrary Unity prefabs or materials.

== If something is missing or wrong ==

{| class="wikitable"
! What you see !! What to check
|-
| Asset exists in Unity but is absent from Vertex || Confirm the file is under the catalog's folder rule, its type is enabled, and you exported the selected custom profile. Confirm the custom catalog entry is in the connected copy's <code>Authoring/Grimwar.vertexgame</code>, then reload resources.
|-
| Model appears, but its material cannot be chosen for a brush || Extract or create a standalone <code>.mat</code>. Embedded materials are hidden. Disable Material Dependencies Only on your custom folder rule and remove a <code>VertexHidden</code> asset label if you intentionally added one.
|-
| Asset previews correctly, but the build says the asset or profile is missing || Check the map's chosen <code>.vertexsdk</code>. Its local <code>Compiler</code> project must contain both the original assets and <code>CustomAssets.asset</code>. A copied catalog alone is insufficient. Check the <code>editorProject</code> edit and preserve <code>.meta</code> files.
|-
| Material is pink, gray, or missing a texture || Check the shader and renderer material slots in Unity, and confirm all texture references resolve. Use URP/Lit and check Unity's render pipeline assignment from step 1, then save, export, reload, and rebuild. A Vertex preview does not prove that an unsupported shader can run in the game.
|-
| Crate looks correct but the player walks through it || Check the saved prefab's enabled collider, the placed model's collision setting in Vertex, and whether you placed the prefab rather than the raw model. Test collision in Grimwar.
|-
| Crate is too large, too small, or rotated incorrectly || Correct the model import scale/orientation or the saved prefab transform in Unity. Apply, re-export, reload, and rebuild. Compare against a one-metre cube.
|-
| Connection fails after editing JSON || Check commas and brackets, preserve the supplied fields, and match the catalog's ID/version exactly. The catalog path is relative to the game profile; both project paths are relative to <code>Grimwar.vertexsdk</code>.
|-
| Compiler setup reports unresolved packages or missing package-resolution data || Open the copied <code>Compiler</code> project in the pinned Unity editor and let Package Manager and asset import finish successfully before building from Vertex.
|}

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