Jump to content

Grimwar/Custom content/Materials and models

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

← All custom content · Sounds and music · Shared media packs

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.

For custom sounds, ambient audio, and music, follow Sounds and music. Audio uses the Sound import type and can live in a shared media pack outside your map folders.

Keep the library in Documents/GrimwarLibrary/, and create your assets under its Compiler/Assets/CustomContent/ folder. Keep map projects separately, for example under Documents/GrimwarMaps/. 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 .mat files, models, and .prefab 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 .mat or .prefab files.

1. Set up your shared asset library

  1. Complete SDK setup. Install Unity 6000.3.17f1 and the build modules you need.
  2. In Steam, open Grimwar SDK's Manage → Browse local files. Locate Grimwar.vertexsdk and its sibling Compiler and Authoring folders.
  3. Copy that SDK folder, with all its contents, to Documents/GrimwarLibrary/ outside Steam. This is your shared working copy for all your maps; create it once.
  4. Keep your Vertex maps in separate folders, for example Documents/GrimwarMaps/arena_mycustommap/arena_mycustommap.vertex and Documents/GrimwarMaps/arena_mysecondmap/arena_mysecondmap.vertex. Both will use the same library.
  5. In Unity Hub, add the existing project at Documents/GrimwarLibrary/Compiler and open it with the pinned Unity version. Select Compiler, not its parent folder or its Assets folder. Let package resolution, script compilation, and asset imports finish.
  6. For Unity's scene and material previews, open Edit → Project Settings → Graphics. If Default Render Pipeline is empty, assign the supplied Assets/VertexSdk/Rendering/Pipeline.asset. Keep the SDK's quality settings. See Unity's render pipeline settings.

Checkpoint: Unity's Project window shows Assets, including CustomContent and VertexSdk. 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 Assets/CustomContent. Right-click it and use Create → Folder to create Textures, Materials, Models, and Prefabs 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 .meta files beside assets and folders; keep those files. 

Documents/
  GrimwarMaps/
    arena_mycustommap/
      arena_mycustommap.vertex
    arena_mysecondmap/
      arena_mysecondmap.vertex
  GrimwarLibrary/                       shared by both maps
    Grimwar.vertexsdk
    Authoring/
      Grimwar.vertexgame
      my_custom_assets.vertexassets     exported catalog
      previews/                         generated catalog previews
    Compiler/                           open this folder in Unity Hub
      Assets/
        CustomContent/
          my_custom_assets.asset        catalog profile created in step 5
          Textures/
            my_brick_wall_01_basecolor.png
            my_crate_01_basecolor.png
          Materials/
            my_brick_wall_01.mat
            my_crate_01.mat
          Models/
            my_crate_01.fbx
          Prefabs/
            my_crate_01.prefab
        VertexSdk/                      supplied SDK assets
      Packages/
      ProjectSettings/

Assets/CustomContent is the path inside Unity. Documents/GrimwarLibrary/Compiler/Assets/CustomContent is the same folder on disk. Authoring is outside the Unity project's Assets 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.

Use lowercase names with underscores and numbered asset variants, as shown in the naming examples. Keep the supplied SDK filenames and folder names unchanged.

3. Create a wall material

  1. Drag my_brick_wall_01_basecolor.png from your file manager into Assets/CustomContent/Textures in Unity's Project window. Wait for import to finish.
  2. Right-click the Materials folder and choose Create → Material. Name it my_brick_wall_01; Unity saves my_brick_wall_01.mat there.
  3. Select the material. In the Inspector, set Shader to Universal Render Pipeline/Lit. Use Surface Type: Opaque for an ordinary solid wall.
  4. Drag the imported image into Base Map under Surface Inputs. Leave the adjacent color white to use the image's original colors.
  5. 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.
  6. If you have a normal map, import it into Textures, 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.
  7. Save your project changes. The asset you will choose in Vertex is my_brick_wall_01, 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 Assets.

Checkpoint: Materials/my_brick_wall_01.mat 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 Unity's URP Lit reference.

4. Import a model and save a prefab

  1. Export a model such as my_crate_01.fbx from your modeling tool. Use metres, a deliberate pivot, and UVs for the material. Put its image files in your Textures folder and the model in Models.
  2. Select my_crate_01.fbx 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.
  3. Create Materials/my_crate_01.mat 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 Materials folder. Check extracted materials' shaders and texture assignments. See Unity's model material settings.
  4. Drag my_crate_01.fbx from the Project window into a temporary scene. On each relevant Mesh Renderer, assign my_crate_01.mat to its Materials slots. For a model with several submeshes, assign the material for each slot.
  5. 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.
  6. Name the scene object my_crate_01. Drag it from the Hierarchy into Assets/CustomContent/Prefabs in the Project window. If Unity asks whether to create an Original Prefab or Prefab Variant, choose Original Prefab for this example. This creates my_crate_01.prefab. See Unity's prefab creation guide.
  7. 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: Prefabs/my_crate_01.prefab is the assembled prop you will place in Vertex. The raw Models/my_crate_01.fbx 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 Assets/CustomContent. To reuse a model's material on brush faces, use a separate .mat 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 Compiler/Assets for the map compiler to use.

  1. In the Project window, right-click Assets/CustomContent and choose Create → Vertex → Asset catalog profile. Name the asset my_custom_assets.
  2. Select it and set Catalog Id to my_library.assets and Catalog Version to 1. Keep these values stable as you edit this asset library.
  3. Expand Folders in the Inspector and add one element. Set that element's Folder to Assets/CustomContent and Ownership to custom.
  4. 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.
  5. Save the project. With my_custom_assets still selected, choose Tools → Vertex → Export Selected Asset Catalog.
  6. In the save dialog, navigate out of Compiler to your copy's Authoring folder. Save as my_custom_assets.vertexassets. The exporter also writes a previews folder beside it.

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

Use custom ownership for your own files. base 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 Assets folder.

Tell Vertex to build from your Unity project

Open Documents/GrimwarLibrary/Grimwar.vertexsdk in a text editor.

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

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

{
  "compilerProject": "Compiler",
  "editorProject": "Compiler"
}

This makes the copy a local developer connection: Vertex captures the saved assets from your Compiler 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 Documents/GrimwarLibrary/Authoring/Grimwar.vertexgame. Find the assetCatalogs array. Keep every existing entry, including grimwar.base. Add a comma after its last existing entry, then insert this additional object before the array's closing ]: 

{
  "id": "my_library.assets",
  "version": "1",
  "path": "my_custom_assets.vertexassets"
}

The path is relative to Authoring/Grimwar.vertexgame, so do not prepend Authoring/ 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

  1. Save both JSON files and your Unity asset changes. Let Unity finish importing.
  2. Open your map in Vertex. Under Settings → Game and resources, select Choose game SDK…. Choose Documents/GrimwarLibrary/Grimwar.vertexsdk, the file in your shared library. File → Open game SDK… opens the same chooser.
  3. 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.
  4. Use Settings → Game and resources → Reload resources after subsequent catalog exports.

Checkpoint: Open either example map. Its Materials browser contains my_brick_wall_01 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 assetCatalogs.

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

  1. In Vertex's material browser, search for my_brick_wall_01. 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.
  2. In the model browser, search for my_crate_01. Choose the entry whose source is Prefabs/my_crate_01.prefab and drag it into a viewport. Place it, then check its size and orientation.
  3. 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.
  4. 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.
  5. When ready, use Export add-on with the Release profile and follow 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 .mat, .prefab, or .vertexassets 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 my_custom_assets to the same my_custom_assets.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 .meta 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 .meta 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 .vertex 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 Documents/GrimwarLibrary, then choose its new .vertexsdk location in each map. Keep its existing catalog ID, asset names, and .meta 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 .meta 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 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

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 Authoring/Grimwar.vertexgame, then reload resources.
Model appears, but its material cannot be chosen for a brush Extract or create a standalone .mat. Embedded materials are hidden. Disable Material Dependencies Only on your custom folder rule and remove a VertexHidden 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 .vertexsdk. Its local Compiler project must contain both the original assets and my_custom_assets.asset. A copied catalog alone is insufficient. Check the editorProject edit and preserve .meta 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 Grimwar.vertexsdk.
Compiler setup reports unresolved packages or missing package-resolution data Open the copied Compiler project in the pinned Unity editor and let Package Manager and asset import finish successfully before building from Vertex.
Retrieved from "https://developer.vellocetsoftware.com/w/index.php?title=Grimwar/Custom_content/Materials_and_models&oldid=275"