Changing an NPC's default appearances (and adding more via AMM)
Published December 27 2022 by @manavortex Last documented update: January 06 2024 by @manavortex
This guide will walk you through editing NPC appearances for Cyberpunk 2077.
You can find a more detailed guide under Altering Appearances within Wolvenkit - Full Workflow
It uses the following versions:
Cyberpunk 2077 game version >= 1.6
WolvenKit >= 8.15 (some of the UI elements will be missing in older versions)
(only if you want to add new appearances) AppearanceMenuMod >= 1.15
For an overview of NPC files, check NPCs and their files
If you want to add custom NPCs to Cyberpunk 2077 with AMM, check AMM: Custom NPCs
If you want to add AMM appearances to existing NPCs, check AMM: Custom NPC appearances
If you want to add V as an NPC, check NPV - V as custom NPC
If you want a more basic guide that goes into more detail for the basic stuff (including Blender), see Altering Appearances within Wolvenkit - Full Workflow
If you're after hair colours, check Hair Profiles: .hp and follow the links from there.
Links will give you additional context. If you can complete the guide without them, feel free to ignore them.
This section will show you how to find an NPC's .app file, which you will add to your project. We do this by finding the NPC's .ent file, since it will be linked in there.
The NPC's root entity file is the entry point for the game. It defines an NPC's appearances, linking them to the actual definitions inside the corresponding .app file.
You don't need to add this file to your project (and if you do it by accident, you should delete it later). For details, see AMM: Custom NPC appearances.
You can try finding your NPC's .ent file on NPCs and their files. If you can't find your entry, the page has information how you can search for it — please add it to the page, this wiki is a community project!
The array appearances will contain a list with every appearance that's defined for this NPC, matching the key appearanceName in the .ent file.
Not all of these have been "published" (as in "hooked up to .ent files"). For an example of this, check base\characters\appearances\citizen\citizen__children_mc.app
The only thing you need to care about is the components array (learn more about these here). This is where you add, remove, or modify parts of an NPC's appearance:
The names of components should be unique so you can manipulate them outside of the .app file. You should generally stick to CDPR's naming scheme, including the prefixes (why is this important?).
CDPR's style of unique naming allows us to find components and their usage across the game files, which will come on handy when we're trying to add items.
This is where the magic happens.
Change items by selecting a different appearance or a different mesh:
Remove items by deleting their entries from the list or by setting their chunkMasks to 0:
For a detailed guide on adding hair, check NPV: Creating a custom NPC - #hair
If you want to add a new item, first duplicate an existing one. After that, you can pretend that it is just another change:
And this might work.
Or it might end up leaving them standing in an exploded pixel cloud. In case of animated components, editing them will almost certainly break them (see #animations-if-you-cant-avoid-them-copy-them-as-well)
Anything of the type entGarmentSkinnedMeshComponent is prone to breaking unless you copy everything it needs.
Let's do it…
You need to find the thing you want to add in the files, check where it is defined, and then copy all of its components.
Search for the mesh name of the vest that you want to use (e.g. ma_vest__high_collar*.mesh)
Anything of the type entAnimatedComponent means that components are animated. That's mostly the case for physics-enabled stuff influenced by gravity, such as coats, jackets, or long hair.
Physics gave us the atomic bomb. (It also gave us computers, but this is besides the point right now.)
Animations are usually unique to meshes on a by-pixel basis and do not react kindly to edits or swaps. (Try splitting the obi from Saburo's kimono into its own submesh if you don't believe me).
If you copy an animated component (e.g. Johnny's vest), then you need to copy the corresponding entAnimatedComponent as well, or the mesh won't move.
If you delete a physics-enabled component, you can safely delete the corresponding AnimatedComponent.
Add the file(s) you want to your Wolvenkit project
Many ArchiveXL mods contain a number of meshes for different body mods and body genders. You only need one of them — the one for your body mod and body gender.
Look for w/m to indicate gender, and base_body to indicate the body mod.
Move them to a custom path (you don't want them to interfere with the original modded files)
Before adding the necessary dependencies, delete all appearances from the .mesh file that you don't want:
From the Clean up menu, use Delete unused Materials
Save the file
From the Materials menu, use add material dependencies
Wolvenkit will now run a scan of all your mods. This may take a moment!
You will now see a textures folder with all files for your materials.
If there isn't one, the mesh only uses base game materials and textures. There's no need to custompath those — if you want to do it anyway, hold the shift key while selecting the option.
Optional: If any of the files in your texture folders are .mi, .mltemplate, or .mlsetup files, open them and run add material dependencies again (your mesh will have a weird purple hue if any of those are missing)
You can now save your .mesh!
This works for simple components. Anything more complicated with physics (.anim or .rig), you should stealcopy from an .ent file inside the mod (see the previous section, #safely-adding-components)
Open your NPC's .app file
find the appearance that you want to change
duplicate an existing entSkinnedMeshComponent:
Select the new component. In the panel on the right, change the following properties:
mesh -> DepotPath: relative path to your mesh
tutorial\npv\your_female_character\feet\s1_converse\s1__pwa__converse.mesh
You can right-click on the .mesh file in the project browser and select copy relative path
mesh -> meshAppearance: the appearance that you did not delete during cleanup
e.g. black
You find this in the appearances array inside the .mesh file
name: a unique name that identifies your component.
You should get into the habit of using garment prefixes, as they come in handy for clothing items.
chunkMask: Extend the dropdown and make sure that the submeshes you want are visible (just check the boxes for 0-11 if you're not sure)
That's it! Save and test!
Adding new appearances to an existing NPC requires you to overwrite that NPC's .ent file (see AMM: Custom NPC appearances). For that matter, it's recommended that you create a new entity instead. You can find a guide for this under AMM: Custom NPCs.
You may have forgotten to copy the animation file. Look for an entAnimatedComponent inside the .app — they're usually called something like xxx_dangle(s) or collar. (See here)
If it's a clothing item not moving, check the skinning array for the component and make sure the bindName is set to root. If you swapped out a component for something else, you also might need to update its matching entry in AppearanceVisualController -> appearanceDependency. But don't do that unless necessary.
That's what happens when the game can't find the appearance you picked. You're probably trying to add an AMM appearance. Check the spelling between your lua file with the appearance name, the mapping entry inside the .ent, and the appearance's name in the .app file.
You have
Point your to the file you have found. We want to find the .app file and add it to our project. You can right-click on the .ent file and select , or you look up the path in the .ent file:
Now that you have found the .app file, let's and look inside.
Select the mesh, then "":
If you find an .ent file called _pwa_ or _pma_, that's a player mesh entity, which contains only the components you need — jackpot, use that one. Otherwise, find any .app file that sounds promising - for example Scorpion's.
it to the project (you don't need the file).
Find and select the components in the other NPC's appearance list:
Select ""
Go back to your original .app file and select either the root of the components array, or any component inside the array. Now right-click and select "".
If you haven't done that yet, the original component(s) and its animations/dangles. Skipping this step will give Johnny two vests, and he's not the type to do that.
Save the .app file, , and go testing!
Switch your Asset Browser to
Use the to find mesh files in your target .archive:
archive:my_mod_name > .mesh
You can now save your mesh and optionally run from the menu bar.
This page will cover how to modify a character's body mesh and/or clothes, in detail.
Created: December 26 2023 by @madmaximusjb Last documented edit: August 17 2024 by
This guide will edit Viktor's body and clothing: he's an ex-boxer, he should be more muscular!
In the process, you'll learn the following things:
Locating an NPC's files
Editing a body in Blender
refitting a clothing item in Blender
Creating a Mod in Wolvenkit will not be covered by this guide.
If you just want the quick and dirty version, check Appearances: change the looks
Or maybe you only care about Exporting Characters to Blender
Blender (the version that is compatible with the plugin)
Hey choombas! Today we're going to be going over the entire workflow of modifying the appearance (body mesh or clothing) of a character in the game. For this guide, we'll be giving Vic (the ripperdoc) bigger pecs, but this guide should work with any character. Ready? Let's go.
The .app file lists the NPC's components, so everything that the game will add to them. This section will tell you how to find either the .app file directly, or an .ent file that leads to it.
Entity files are using the .app files, so you can find them from there. For instructions on how to find them, just keep reaidng.
Under NPCs and their files, you can find a bunch of paths. If you're lucky, then your character is on that list.
Almost all entity files are in the following folder:
Most main characters have their .app files here:
You can read more about this under Appearance: .app files, but you don't have to.
For us, we'll be wanting to locate victor_vektor.app, which is in the main_npc folder I listed earlier.
Once we add this file to our project and open it, we will see an array named "appearances".
All of the different appearances for Victor are located in this array. Upon expanding it, we see that he only has three.
We'll edit the default appearance in this guide, but the process is the same for all of them, or even creating new appearances.
Open the default appearance and then the Components array. This is where all of the components for that appearance are stored: clothes, body meshes, hair meshes, etc.
As you can see, there are quite a lot to sort through. Don't worry, most of these things you won't have to mess with anyway.
A quick tip: most of these components are prefaced by something like t0 or l1. Here's what that means: t=torso (t0 is usually the body mesh, t1 is usually clothes), l=legs, h=head, s=shoe. For more information, read here — you don't have to.
Here are the components for body and shirt: "t0_001_ma_body__ripper_doc6245" (body mesh) and "t1_001_ma_full__ripper_doc1487" (shirt).
We'll start with the body mesh.
To modify the body mesh, we'll export it to Blender.
First, add the mesh file to your project by clicking on the yellow arrow next to the mesh file's path:
Next, we want to export the file out of Wolvenkit to enable us to edit the mesh in Blender, since right now, the file is in a format Blender can't read.
You can find step-by-step instructions under the plugin's import/export page
Once that's open, check the box next to your body mesh and click "Export Selected".
You need to have the Wolvenkit Blender IO Suite installed for this!
Open up Blender, delete everything from the default project, and click on "File>Import>Cyberpunk GLTF".
Import it.
If all went well, you should see a blank body mesh in your viewport.
To edit this mesh, there are two ways to do it. You can use edit mode to edit specific vertices, or use sculpt mode if you prefer. We're going to use edit mode. Make sure you have your mesh selected, and enter edit.
Side note: for the purposes of ease, I'm going to join together the components of the mesh so I can edit the whole body without having to switch objects. To do this, go into Object Mode, select all components of the body (highlight the whole thing), and press Ctrl+J. Done.
You should see something like this:
These are all of the vertices that make up your mesh. Before we begin editing, you'll want to enable this button right here:
This enables proportional edit mode. Now, select a few vertices at random on Vic's pec muscles. It should look like this:
Now, to edit these vertices, we're going to press "g" and then "y" to edit them on the y-axis. Remember to scroll up until you see the circle around your cursor shrink to a little less than the width of Vic's chest. Now, we'll drag the cursor out a little to pull those areas out. Use some creative independence to determine what looks good. For me, this is fine.
Now that we've done that, make sure there aren't any rough edges on your mesh and then select your mesh and export it as a Cyberpunk GLB to the same file that you edited.
Now, you must go back to Wolvenkit to import the mesh. Even though you exported the file from Blender, it's still in a raw format and unreadable by the game. Go to "Tools>Import Tool". Select your mesh and "Import Selected".
Cool! You've just edited your first body mesh! Now we can change the shirt to account for our changes.
Keep in mind that instead of modifying the mesh in the game files, you could have made a copy of the mesh, modified that, and pointed the .app file to use that mesh. The same thing applies for the clothes. Find out how to custompath assets here: Custompathing
For more intel about clothes refitting, check Refit Clothes Easily
The first thing we want to do is find the piece of clothing that we want to edit within the .app file. For us, that's "t1_001_ma_full__ripper_doc1487". Let's export it using the same process as with the body mesh (remember to add it to your project before trying to export it).
Before we import the mesh into Blender, let's first import the edited body mesh so that we can see what we need to change. Follow the same process we used to import it the first time. You should get something like this:
Now that we can see what we need to edit, let's begin. Make sure to select all of the meshes that make up the shirt, as there are several. Once you have done so, select multiple vertices in the areas that the body is clipping, similar to what we did with the body mesh. Also, remember to enable proportional editing mode in the toolbar up top. Again, press "g" to enter edit mode and "y" to edit the mesh on the y-axis. Remember to scroll up until the circle around your cursor is small enough. Edit the shirt out until it doesn't clip anymore. This looks good to me:
Once you're happy with your edits, select ALL of the shirt meshes and export as a Cyberpunk GLB to the same file you imported.
Now, head back to Wolvenkit and import your changes. "Tools>Import Tool", check your mesh and click "import selected".
All that's left is to replace the depot path of the mesh you just edited. Head back to Vik's .app file, and find the shirt component ("t1_001_ma_full__ripper_doc148"). Replace the "mesh" path with the relative path of your mesh (right click on your mesh in the project explorer and "copy relative path"). Click save on the top left.
Now, you can pack your mod or install it directly to your game.
Note that if you did copy the mesh and created a custom path, you would have to also replace the path under "AppearanceVisualController>appearanceDependancy" for the component to appear correctly.
Also note that since we didn't copy the mesh and use a custom path, this mod would not display the other two appearances correctly. You would have to modify the other clothes.
Congratulations! You just edited an appearance and changed the clothes to match! This guide can be applied to most characters, so I'm excited to see what you'll do with it!
Until next time, chooms!
Type something like character > .ent in the Wolvenkit Search Bar and scroll a lot, or click on to learn more
Type something like character > .app in the Wolvenkit Search Bar and scroll a lot, or click on to learn more
To export the .mesh into something that Blender can read, find the .
Locate your project folder, then find your mesh file in your project's . It'll probably be somewhere like "Ripperdoc_Tutorial\source\raw\base\characters\main_npc\ripper_doc".
