Adding decals

Summary

Published: Jan 21 2024 by Last documented update: Mar 21 2024 by

This guide will teach you how to add decals to existing items.

It will walk you through the following:

#step-1-cutting-the-decal-mesh

1. Adding it to the mesh entity

2. Setting up the material

Wait, this is not what I want!

• To add new items to the game, check Adding new items

• To learn about materials, check the Shaders section or follow the links from there.

Prerequisites

Software versions

The rest

This guide assumes that you have an existing Wolvenkit project with your item and just want to add the decal mesh. If you don't have one, you can grab the template project from ItemAdditions: Dynamic Appearances.

Inside your Wolvenkit project, you need an .xbm texture for your decal, and its .png export that we'll use for Blender. If you don't have a texture yet, you can

1. add any .xbm to your project (and put it in a custom path)

2. export it to png

3. Replace this png with your decal

4. import the png again (premultiplyAlpha must be checked)

Step 1: Cutting the decal mesh

For this guide, I will be using a sock mesh.

Start by exporting your mesh from Wolvenkit and importing it into Blender. You should see something like this:

1. In the viewport, click on the submesh that you want to have the decal.

1. Switch to Edit Mode (shortcut: Tab)

2. Turn the viewport to the side (shortcut: Numpad 3)

3. Turn on X-Ray mode (shortcut: Alt+Z). This lets you select right through the mesh, in my example, on both sides of the leg.

4. Use the selection tool (shortcut: W, it should be active) to select your decal mesh. It should look something like the left side of the screenshot below.

1. Duplicate these vertices (Shortcut: Shift+D)

2. Split them into a new submesh or new submeshes (Shortcut: P -> Selection)

3. You should now have something like the right half of the screenshot.

Step 2: Renaming our new submesh

If you take a look at the outliner, you will notice a new submesh in the scene collection. This is your decal mesh. We need to change its name to register it as a new chunk.

1. Switch back to Object Mode (Hotkey: Tab)

2. In the Outliner, click on your meshes until your decal mesh lights up

3. Change the name: it needs to be the submesh with the highest number (see the red box in the screenshot below). Double-click the name, then change it to (in this example)submesh_04_LOD_1.

Step 3: Fixing up the decal

With your new submesh selected, it's now time to clean up.

1. Switch back to Edit Mode (Hotkey: Tab)

2. Cut away all vertices that you don't need. (Hotkey: X)

1. After cutting away everything that you don't want/need as part of your decal, select the rest (Hotkey: A)

2. The decal should be one piece, so let's make sure to merge by distance now (hotkey: M).

Now, let's make sure that our decal is above the surface of the original mesh by using the Shrinkwrap Modifier.

1. Switch back to Object Mode (Hotkey: Tab)

2. Duplicate your mesh (Hotkey: Shift+D)

3. Select just one of the two meshes, and switch to the Data tab

4. Delete all shapekeys (starting at the bottom).

1. Now, switch to the Modifiers tab. Leave the Armature modifier alone.

2. Add a Shrinkwrap Modifier (Deform -> Shrinkwrap).

1. Configure it. Try the standard parameters below — if you have clipping, you can play around with the modifier after.

   1. target: The mesh you originally cut from (you can use the eyedropper symbol)

   2. Wrap Method: Select Nearest Vertex

   3. Offset: 0.0005 m (sometimes it's necessary to increase it to something like 0.002 m)

2. Your decal should be floating directly on the surface of your mesh, with just enough offset that it's not clipping. When you're satisfied, apply the shrinkwrap modifier:

1. Now let's merge it with the original submesh with the garment support. Select the duplicate that you made in Step 6.

   1. Switch to Edit Mode (Hotkey: Tab)

   2. Select all vertices (Hotkey: A)

   3. Delete them (Hotkey: X)

   4. Switch back to Object Mode (Hotkey: Tab)

   5. First, select your decal mesh (with the offsets) by clicking on it in the Outliner

   6. Second, select your empty mesh (with the shapekeys) by shift-clicking on it in the Outliner

   7. Now, join them together (Hotkey: Ctrl+J)

You now have a decal mesh with an offset and garment support shapekeys. Awesome! Let's take care of the material now.

Step 4: Material assignment

With your new submesh selected in Object Mode, switch to the Shading perspective. Delete the existing material assignment and create a new material:

1. Click the X above the node browser to delete the existing material assignment

2. Create a new material

1. In the node browser, add a new image texture (Hotkey: Shift+A, Texture -> Image Texture)

1. Click on "open" in the orange node and point the path to your decal png

2. Drag-and-drop the "Color" dot on the orange box to the "Base Color" dot on the green one

3. If your mesh's surface hasn't changed yet, you need to assign the material:

   1. Open the Material tab

   2. Switch to Edit mode (Hotkey: Tab)

   3. Select all vertices (Hotkey: A)

   4. Assign them to your new material

Step 5: UV projection

Our decal is now showing our new material. Make sure that it has exactly one UV map by checking the Data tab:

Time to change to the UV Editing perspective. You should be in Edit Mode (Hotkey: Tab if not) and have all pixels of your decal mesh selected (Hotkey: A if not).

You will see something like this (to learn more about UV maps, look up our theory page):

We will now unwrap our decal. I'll do both UV islands at once - if you have only one (because your decal is on a jacket or something), then your life will be easier.

1. With everything selected in the UV Editor on the left, select UV -> Unwrap -> Unwrap (Hotkey: Ctrl+U)

2. This will unwrap the mesh. Hopefully, you get nice and clean UV islands. If not, you may have to play puzzle

At the end, we want a nice and straight grid over the full width and height of the decal, with the correct orientation. Let's start by fixing up the UV islands.

1. Select a row or column. From the right-click menu, select one of the following:

   1. Straighten: Will put them all in a line

   2. Align Auto, which does one of the following:

      • Align Horizontally: Will put them all on the same Y-axis

      • Align Vertically: Will put them all on the same X-axis

2. Keep doing that until you have a nice grid.

1. If you have multiple UV islands, you can move them on top of each other.

1. Check the individual decals in your viewport and fix up any that are flipped/rotated:

   1. Click on a vertex in the viewport

   2. Select linked (Hotkey: Ctrl+L)

   3. Fix the UV mapping (Right-click: Flip horizontal/vertical, or rotate)

2. When you are done, export your mesh from Blender to glb. Include all submeshes.

Now it's time to head back to Wolvenkit and activate our new decal chunk.

Step 6: Adding a new material

After successfully importing your new submesh into Wolvenkit and open it.

Appearances

First, we need to add your new chunk to each of your appearances. For this example, we will use the material decal.

1. Find the appearances array at the top of the file and expand it.

2. Under each appearance, find the chunkMaterials array and expand it.

3. If you already have an entry for your new submesh, change its value to decal. If you don't, right-click on the last entry to duplciate it. You should now have something like this:

Material definition

If you save your mesh now, file validation will complain that the decal material doesn't exist. It's right; we haven't added a material definition yet. Let's do that.

1. Find the materialEntries array inside your mesh and duplicate the last entry

2. Change its name to decal

3. Make sure that isLocalInstance is checked

4. Increment its index by one (e.g. 29 -> 30)

Material instance

Now that our chunk knows which material it's supposed to look up, we need to provide the actual material.

1. Find the array localMaterialBuffer

2. Find the array materials (directly underneath)

   1. If it's empty, go back up and find preloadMaterialBuffer instead

3. Duplicate the last entry. This is your new decal material. Now we need to make sure it behaves like a decal, too.

   1. Change its baseMaterial to base\materials\mesh_decal.mt. This will tell the game which shader to use, and mesh_decal is for exactly this.

   3. As of now, your decal will be completely transparent. Let's change that.

4. Now we need to get the right material properties. The easiest way is to find another material that uses mesh_decal and steal them from there:

   3. Sort the results by file type by clicking on the column, then find and open a .mi or .mesh

   5. Switch back to your own mesh and copy these values into your mesh_decal material's values array (the one from step 3.3)

5. 1. If you don't have one, go back to #prerequisites -> #the-rest

6. The other properties should be numbers only. If you don't know what they do, you can delete them for now.

Time to test!

Troubleshooting

Issues with your texture

See Textures: Importing, editing, exporting -> #troubleshooting

Issues with the mesh

See Troubleshooting your mesh edits

Issues with the material

See Materials: troubleshooting

Video