> For the complete documentation index, see [llms.txt](https://wiki.redmodding.org/cyberpunk-2077-modding/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/npcs/npv-v-as-custom-npc/how-to-add-a-new-appearance-to-an-npv.md). # NPV: How to add a new appearance to an NPV ## Summary Created: Jul 3 2025 by [ratstick](mailto:undefined)\ Last documented update Apr 10 2026 by [mana vortex](mailto:undefined) This page will show you how to add an appearance to an already-existing NPV. ## Introduction Commissioned an NPV or had someone make one for you and want to add new appearances yourself? It’s easy! Well, sort of. All the hard work has been done, but there are still some things you’ll want to consider. Here’s a guide walking you through it, step by step. Don’t hesitate to DM me on Discord or Nexus (`ratsstick/ratstick` respectively) if you need help, or if the guide is unclear! You can find me in the [modding community discord](https://discord.gg/redmodding), the AMM server, the KS server, and Veegee’s server. <3 ### Disclaimer I love subfolders and organizing my NPVs. The screenshots I’ll be sharing are from a mostly vanilla fem V NPV that I was commissioned to make. You’ll see my stupidly detailed folder organization for clothing meshes and textures. If you want to use this in your own projects, you can [download it here](https://drive.google.com/file/d/1McSM228BlsY-4HRoe-lGqPQUGybtkBpT/view?usp=sharing)! These steps will be the same for adding new hairstyles, tattoos, cyberware, anything that is only on a new appearance and not the base appearance. ### The Mr. Potato Head and Barbie Dress-Up Metaphor You can think of it like a Mr. Potato Head or Barbie doll. The `component`s are the eyes, nose, ears, mouth, hats and such. When we add components to the .app file (see below), we’re putting on another item. #### The .ent file A list of appearances for any given entity. Every name points to an `.app` file and an associated appearancce.\ \&#xNAN;*You can (but don't have to) read more about it here:* [https://github.com/CDPR-Modding-Documentation/Cyberpunk-Modding-Docs/blob/main/for-mod-creators-theory/files-and-what-they-do/file-formats/entity-.ent-files](https://github.com/CDPR-Modding-Documentation/Cyberpunk-Modding-Docs/blob/main/for-mod-creators-theory/files-and-what-they-do/file-formats/entity-.ent-files "mention") #### The .app file A list of appearances with their associated components. This file tells the game what to load when spawning the character.\ \&#xNAN;*You can (but don't have to) read more about it here* [https://github.com/CDPR-Modding-Documentation/Cyberpunk-Modding-Docs/blob/main/for-mod-creators-theory/files-and-what-they-do/file-formats/appearance-.app-files](https://github.com/CDPR-Modding-Documentation/Cyberpunk-Modding-Docs/blob/main/for-mod-creators-theory/files-and-what-they-do/file-formats/appearance-.app-files "mention") Most of the work takes place here, and this is where we'll start. ### Do I need \? Most likely not. The player has to support first and third person and character customization options. As of 2026, ArchiveXL lets us add things more easily; but in the past, people had to get tricky. That's where frameworks like `More Head/Body Meshes` are from. An NPC is just a list of components in your .app. Want extra cyberware? You can just add the mesh! {% hint style="info" %} You may still need files from certain texture frameworks, but you’ll find that out when you’re beginning to custompath textures. {% endhint %} ### What's “custom pathing”, and why do we do it? {% hint style="info" %} You can learn more about this on out the[Custompathing assets](/cyberpunk-2077-modding/modding-guides/items-equipment/custompathing-assets.md) page. {% endhint %} Custom pathing is the process of moving files/folders into a unique place so that they don't influence existing mods or game files. For example: We're both have Arthe's Universal Skin Tone installed, but your NPV uses a different skin tone from my V. If you do not custompath your file, one of the two will have the wrong skin tone on my computer. I take a broad approach to custom pathing and path nearly everything that isn’t an engine file or file type not commonly edited. I still recommend doing this for vanilla clothing items, as replacers are still used for some clothing items. In general, I recommend custom pathing the following file types: * .mesh * .mi * .xbm * .mlsetup * .mlmask ## Adding new appearances ### Step 1: The project If you already have a Wolvenkit project for your NPV, you can skip this step and go straight to [#step-2-duplicating-an-existing-appearance](#step-2-duplicating-an-existing-appearance "mention"). 1. Open WolvenKit and select “create a new project”. 2. Fill out the stuff. Make sure you use underscores instead of spaces. WolvenKit will freak out, and your mod may not work if you use spaces in folders and such.
3. Follow the guide for [Analysing other mods](/cyberpunk-2077-modding/modding-guides/analysing-other-mods.md) on how to add your NPV's files from the `.archive` you have installed. Add every file in the archive. 4. You'll want to make sure you add any extra files like the `.lua` for spawning via AMM or a custom `.xl` file that may contain things like localization or scope info. Don't worry if none of that makes sense, the only thing you need to worry about is getting all the NPV files into your project. 5. The `.xl` file will be found in `archive/pc/mod` and goes directly into your project's `source/resources` folder 6. The `.lua` file goes into the resources folder, too. When we pack this, we need to make sure AMM can read our file. You'll want to create a new folder in `source/resources` using the following path: `bin\x64\plugins\cyber_engine_tweaks\mods\AppearanceMenuMod\Collabs\Custom Entities` . You can use Wolvenkit's Create Folder button to create the entire thing in one go, then move the .lua file there. To do that, right click on the resources folder and select "Create new folder" (or hit F7 on your keyboard). Then, copy and paste the path shown above! You click the yellow button to open the folder in Windows Explorer and move the `.lua` file into it.\\

This is what it should look like if you're using the "Create Folder" function inside Wolvenkit

### Step 2: Duplicating an existing appearance Since all the hard work has been done for you with the base appearance, you can duplicate an existing appearance. Personally, I usually duplicate one with the same t0 submeshes hidden because I frequently forget to unhide them. (We’ll get to this in a later step). 1. Find your .app file and click the blue button to open it (you’ll see it when you hover the file).

You can also double-click the file

2. Right-click on the appearance you want to duplicate and select “Duplicate in Array/Buffer”.
3. **It is imperative that you change the name of the appearance.** After duplicating, make sure the new appearance is selected. In the right pane, you’ll see a field that says “name”, that’s where you can change the appearance name. **Remember: You must use underscores, no spaces!**

You have to change the name of the appearance, as duplicates will confuse the game.

### Step 3: Playing Barbie Dress-Up (Adding items) 1. Once the name has been changed, click the carat next to the appearance to expand it. 2. Click the carat next to `components` \\
3. In some template NPV .app files, clothing has its own section. If your .app file looks different, you can find the clothing components by looking for `entGarmentSkinnedMeshComponent` or `entSkinnedMeshComponent` and checking the component names for clothing prefixes. Some modded items may use custom names but it should (hopefully) be obvious which of those are clothing items. The clothing prefixes are as follows: 1. t1 inner torso) 2. t2 (outer torso) 3. s1 (shoes) 4. h1 and h2 (headwear) 5. l1 (legs) 6. g1 (gloves) 7. i1 (items e.g. pouches and bags) {% hint style="info" %} These prefixes aren't necessary for NPVs to function. However, ACM uses them to sort items into the correct categories so it can be useful if you or anyone you share the NPV with want to use [ACM](https://www.nexusmods.com/cyberpunk2077/mods/10795) to play dress up. {% endhint %} 4. Since we duplicated an appearance, there may be clothing items you don't want or need in the new one. I don’t want the sunglasses in this appearance, so I’m going to delete it. Right-click on the item and select “Delete Item in Array/Buffer”.
Now it's time to play Barbie dress-up! #### Finding clothing items You can either[ search ](https://wiki.redmodding.org/wolvenkit/wolvenkit-app/usage/wolvenkit-search-finding-files)for the name of the item if you know what it is, or peruse the asset browser. You can also use the Tweak Browser after finding a vanilla item's baseID to find the mesh you need. You can follow[ this guide ](/cyberpunk-2077-modding/for-mod-creators-theory/references-lists-and-overviews/equipment/spawn-codes-baseids-hashes.md)to see how to do that. {% hint style="info" %} With the [Toggle Mod Browser](https://wiki.redmodding.org/wolvenkit/wolvenkit-app/editor/asset-browser#mod-browser) button, you can switch the Asset Browser to search only in modded files. {% endhint %}
I want to use the vanilla Converse so I need to add the mesh to my project. 1. Right-click on the .mesh\ \&#xNAN;*(p)ma = (player) male average; (p)wa = (player) woman average* 2. Click “Add selected items to the project”. This will duplicate the folder structure in your project as well.
I’m going to add a new subfolder (right click on one of the folders) to “feet” for the converse and add another subfolder inside that for the textures. You can also rename the mesh, however I prefer a more organized file structure as I find it easier to navigate, especially if I ever need to change textures! 4. Drag and drop the .mesh into the new subfolder.
Nice, we're following custom pathing best practices. Next, we need to tell the game that instead of the boots in this appearance, we want it to load the Converse instead. We can either duplicate an existing clothing component or swap the paths and mesh/appearance names in the `.app` file. Sincere there's already a shoe component in this appearance, I'm going to just swap the mesh path and mesh and appearance names. 1. ight-click on the mesh and select “copy relative path to game file”.
2. Paste it into the “DepotPath” section on the right pane. 3. The component can be renamed to whatever you want. I’m going to put “converse”.
#### Finding mesh appearances Now we need to find the mesh appearance and clean up any unused mesh appearances. This just keeps it nice and tidy and easy to find the materials you actually need to change. Just like we did when opening the .app file, hover over the mesh and click the blue button to open it (or double click). The first section you see contains the mesh appearance names, and these are what we’ll put in the `meshAppearance` field. I like the look of the black converse, so I’m going to choose the “black” `meshAppearance`.
The component in the .app should now have the mesh appearance, component name, and path to the mesh changed.
#### Optional, but recommended: Cleanup {% hint style="info" %} This will reduce the time it takes Wolvenkit to complete file validation and makes it easier for you to review the mesh appearances if you need to make any changes or updates to textures and the like. {% endhint %} Now, it’s time to clean up the mesh appearances! If you use more than one appearance in the mesh, it’s fine to keep those entries in the mesh file. I only want to use the black appearance, so I’m going to delete the rest of the material entries. WolvenKit has a very handy tool that will do this part for you. 1. Select the appearance entries you don’t want, then right click and hit “Delete Item in Array/Buffer”. Alternatively, you can also select the entry you want, hold shift, and click "Delete everything but selection".
2. Now, we can use a function in WolvenKit to clean up the entries we don’t need in the `localMaterialBuffer` and `materialEntries`. Click on “Clean up” and then “Delete unused materials”.
Everyone say “thank you Wolvenkit devs.” #### Custompath the material files {% hint style="info" %} Mods that change base game files are increasingly more rare, but this is how you can keep your NPV clean and ensure only the appearances your NPV is using will be used, regardless of the mods your friends are using. {% endhint %} Now to edit the path of the textures. 1. Find the `localMaterialBuffer` and click the carat on the left to expand it. Do the same thing for `materials`, `CMaterialInstance` and the values. These contain the paths to the textures we’re going to change.
2. Click the yellow arrow to add the texture to your project. We can ignore the `baseMaterial` because that’s an engine\materials file and I don’t think those are ever changed in any mod. Just like when we added the mesh to our project, the textures will replicate the folder structure.
3. Just like we did with the mesh, we want to drag and drop those into the “textures” subfolder.
4. Just like we did the mesh path, right-click on the texture, select “copy relative path” and paste it into the corresponding field in the .mesh. Then save it. Do this for all the textures that need to be pathed.
This guide is getting hella long already, so I won’t bore you with adding more clothes. The process will be the same no matter what you add. #### Hiding body submeshes One thing you may want to do is hide some of the body submeshes to prevent clipping through clothes. 1. Find the `t0` mesh component in your appearance and toggle off or on the chunkmasks. You can also open the mesh and switch to the preview tab to see which submeshes you may want to hide.
### Step 4: The Paperwork Save the `.app` file after you’re done updating and adding your clothing. This can take a while sometimes depending on a few different factors. But just wait until it’s done. Now, we need to tell the game that there’s a new appearance that can be used for the entity. That means we have to update the `.ent` file. Find that file in your project and click the blue icon to open it. 1. Right-click on any one of the `.ent` entries and select “Duplicate in array/buffer.” 2. Just like we did when we duplicated the .app appearance, we’ll need to rename it. Rename it to the same name you used for the appearance. Pay close attention to the formatting of the “name” field. You only need to append the new name to the end of the NPV name. This is what it should look like.
3. Save the `.ent` file. #### Optional: Add the appearance to AMM If you don't want to use AMM, you can skip straight ahead to [#step-5-the-finish-line](#step-5-the-finish-line "mention") If you also want it to spawn in AMM, we’ll need to add the appearance to the `.lua` too. You can do this in any text editor, I use notepad++. ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXd66sJpksFjctlUiqSvQqOAwg5fAGoBSu5zGVyokhTK_cCZe4gPPLhGo7gd0lDJvG9yEz8lxsLk1wfSe43C58r6aoVtr2ifn2EbNG36ZtjPl5iWeb30QZWQRqogFb6if57a5yR4gw?key=v-1XJeip1aB1Hl1kfJwyYA) Pay close attention to the formatting of these names!
And don’t forget the comma!
If you also want the NPV to show up in photomode, you’ll need to regenerate the photomode files. Thankfully, WolvenKit has a way to do this automatically too! Follow this guide to generate those: [NPV: Photomode (formerly Nibbles Replacer)](/cyberpunk-2077-modding/modding-guides/npcs/npv-v-as-custom-npc/npv-amm-nibbles-replacer.md#step-1-create-photo-mode-files) ### Step 5: The Finish Line This guide assumes you’ve never opened WolvenKit in your life so I’m going to show you how to pack the project. If you're raring to go, and not using a mod manager like MO2, you can just click "Install Mod" or "Install and launch" if you're ready to test it right now.
This will pack your mod, install it to the game directory, and then launch the game for you. However, I think it's important to also know how to pack the project so you know where to find the packed file and if you need to install it to a mod manager. #### Packing the project 1. In the top bar, click “Build” then “Pack Project”.
2. The log will show you when the packing is complete.
3. You can click Build and Install or you can click the yellow folder in the Project Explorer to open the project folder.
4. Go up a level and you’ll find a .zip file with the packed mod, ready to install.
{% hint style="warning" %} If you made a new project and aren’t using the one the modder did, make sure you **uninstall** the old NPV by deleting all of its files. {% endhint %} And that’s it! Install and go, test it out! ### Final Notes Garment support doesn’t work on NPVs. You can hide submeshes in ACM or in Wolvenkit. You can also edit the mesh(es) in Blender to cut out or [resize](/cyberpunk-2077-modding/modding-guides/items-equipment/recolours-and-refits/r-and-r-refitting-step-by-step.md) the parts that clip with other items. This process should work for NPC+ too. And again, please don’t hesitate to reach out to me (`ratstick`) if you need help! --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/npcs/npv-v-as-custom-npc/how-to-add-a-new-appearance-to-an-npv.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.