How to create your V as an NPC
Created & Published: May 13 2023 by @manavortex
This guide will show you how to do the following things:
Setting up a Wolvenkit project with the prepared example files (this section)
Creating your V's head in Blender (NPV: Preparing the head in Blender)
Customizing their appearance and clothes (NPV: Creating a custom NPC)
Making sure that they are unique so that you can share them ( NPV: Cleanup and troubleshooting)
Creating a Nibbles replacer preset ( NPV: AMM Nibbles Replacer)
If you want to change the player head, see A new head for V
You can find more guides and resources for NPCs outside of the wiki. They are linked on the Community Guides page.
Easy, but not trivial: you don't need any prior knowledge, but the process is complex, and if you miss steps or deviate from the instructions, things will end up not working for you.
If you run into issues with this guide, the right place to ask for help is #mod-dev-chat on the redmodding Discord server.
This guide uses the following versions:
Cyberpunk 2077 game version >= 2.3
The 3d editing tools ( see WKit Blender Plugin: Current version for the currently supported version):
AppearanceMenuMod >= 2.1
None of this would have been possible without NoraLee, who pioneered the process and taught me everything that I needed to know to set up these tools. This guide doesn't use any of their resources, but a lot of their knowledge. For the full guide with all edge-cases, bells, whistles and context, see their Google Drive.
This is the speedrun version. If you want extra details and context, please check Nora's Google Doc.
Due to the complexity of V's head mesh, you have to do a little bit of prep work here.
Don't worry, I'll walk you through it step by step.
To create a face, we need to know your character's values. For that, you need to have AppearanceChangeUnlocker installed, or you won't see them:
Eyes
Eyebrows
Nose
Mouth
Jaw
Ears
Find the mirror in V's apartment and note down the numerical values.
Download the example files from Nexus
Merge the source folder in the download with the source folder in your Wolvenkit project directory
We will have one NPC per Wolvenkit project (I mean this!), so we'll delete the files for the body gender that we won't be using (find a table after the image)
female
archive\tutorial\npv\your_female_character
raw\tutorial\npv\your_female_character
resources\bin\x64\plugins\cyber_engine_tweaks\mods\AppearanceMenuMod\Collabs\Custom Entities\tutorial\tutorial_custom_female_character.lua
male
archive\tutorial\npv\your_male_character
raw\tutorial\npv\your_male_character
resources\bin\x64\plugins\cyber_engine_tweaks\mods\AppearanceMenuMod\Collabs\Custom Entities\tutorial\tutorial_custom_male_character.lua
This tutorial assumes that you will rename and re-path your files at the very end, because the prepared files rely on a certain file structure. We'll get to it!
This is a working Wolvenkit project — let's make sure that it works.
You can do this at any time during the tutorial to check your progress!
Click it
When the game starts, load a savegame
Open the CET overlay
Switch AMM to the "Spawn" tab
Search for Tutorial
Spawn Tutorial Woman or Tutorial Man
You should now see a person in front of you.
Now it's time to do the actual work.
If you want to create your V's head for Cyberpunk, go to NPV: Creating a custom NPC
If you just want to set up the file structure, go to NPV: Creating a custom NPC
Please remember that before sharing your NPV, you have to change the paths! We will do this at the very end of the project, as the tooling requires the paths to be set up in a certain way.
Step 1: How to generate your V's custom head mesh
Published: May 13 2023 by @manavortex Last documented update: Dec 19 2024 by
This page is a part of the . It will show you how to
change the head to your V's custom head shape in Blender
import the changed head back into Cyberpunk
This section will not deal with the following (that comes in ):
Changing V's body
Changing anything that is not the head shape (e.g. colours or materials)
If you want a 3d model, you probably know what you're doing; in that case, make sure to run the script and get the shape right, then go wild. If you want to export a body, you can still complete this guide, then follow the to get everything into Blender.
IWouldiwas Sh00kspeared made a video tutorial for visual learners (Nov 2024). You can find it on , or check out the box below.
In this section, we will be moving/deleting files. You can complete these steps in Wolvenkit or in the Windows File Explorer.
It's important that you leave the file structure as it is. Moving or renaming files will confuse Wolvenkit and break the example project.
Open the head folder in your project's archive section.
Look into the head/morphtargets folder
Delete all those files that you aren't using (read on as for how)
It's too many of them!
True! That's because I included all options for any given V. But don't worry: after you have deleted the ones that you won't be using, you should be left with a maximum of 13 .morphtarget files for female V and 14 files for male V.
I have included all meshes and morphtargets from the game files. We'll now thin out the options, deleting those parts that your NPV won't be using.
The list will give you a number of Source Mesh entries like h0_000_pwa_c__basehead.mesh.
In the files, you will see four files for jewelry:
… none of which is your V's exact piercings. Instead, there are full sets of jewelry, most of which will be hidden.
You have to look at the meshes and find the file that includes your set of piercings. We will delete the ones you don't need later.
Number in file name <=> Number in character creator
Many of the files are variants and your V will be using one or none of them. That means you have a bunch of files to delete.
When deleting files that you aren't using, make sure to remove both the .mesh file in the head folder and the .morphtarget file in the head/morphtargets folder.
The following table will show you examples on what to keep (as in, you delete everything else):
After deletions, both head and head/morphtargets should hold only the files that your V is actually using.
Once you're done, you should have between 4 and 13/14 files:
Now, we will export all .morphtarget files from Wolvenkit so that we can edit them in Blender.
You will complete most of these steps in Blender, only the import/export happen in Wolvenkit.
Find the Export Tool (Tools -> Export)
To filter, click into the empty row under "name" and write "morphtarget"
Check the box in the header to select everything
Click "Export Selected"
In head folder, find the file head_import.blend.
This file is a utility file which will automatically import and export the files for you. For that reason, it needs to be in a certain relative path.
If you have already changed your structure (by re-naming your folders), you need to make sure that head_import.blend is in the folder head right next to the folder morphtargets.
Open it in Blender. It will take you to the scripting perspective, where you'll see something like this:
Press the play ▶️▶button.
The script will now import a bunch of armatures from the morphtargets folder. You will see them showing up in the topright corner (see the next screenshot under 7. for how it should look)
Switch to the next script in the file, but don't run it yet:
If you've been previously afraid of scripting: This is a good place to stop! :))
You don't need to select the eyebrows here, as those are "painted on" later via mesh appearance. The mesh only needs to have the right shape, which is what we're doing here.
After you've changed the values to those of your V, click the "play" button again. This will apply the morphs to your V's face:
Some shapekeys don't correspond 1:1 with their numbers in the character creator. If a part of V's head is shaped subtly wrong or looks weird in the game, undo your changes (Ctrl+Z), add or subtract 1 from the corresponding shape key, and run the script again.
Yes, you absolutely can! Once you have completed Step 3, you can re-export the .mesh files. Importing those into Blender will give you materials!
Now that your head looks the way you want, it's time to run the final script, which will export your changed head to .glb for you:
This will overwrite already existing files, leaving you with a set of import-ready mesh files.
Now it's time to get them back into Wolvenkit.
Find the Import Tool (Tools -> Import Tool)
Click "Import All". You shouldn't see any errors.
You're done!
At this point of the guide, you should see your NPV's head in Wolvenkit (re-select the mesh to refresh the preview).
If everything works, you're done with Blender (unless you want to get fancy).
If the head mesh has not changed, you ran into a problem — check the Log View and/or make sure that you completed all steps in the right order. Especially changing any paths will break things.
Spawn your NPV and check that they look like they should.
If they do,
create a full backup of your project (copy the entire folder in Windows Explorer)
delete all .morphtarget files from your project — we don't need them anymore (do not delete them if you are editing the player head)
Optimally, this process just runs with no hitches. However, during beta testing and troubleshooting, people ran into a few issues, so I'm listing them here.
You can check if Blender has run into errors by opening the Blender console window - from the menu, select Window -> Toggle System Console.
The supported versions are:
Check the following:
The component's shape looks okay in Blender
The component's shape looks okay in Wolvenkit's .mesh preview
If that's not it, then you ran into the shapekey offset issue: some shapekeys don't correspond 1:1 with their numbers in the character creator. If a part of your shape is shaped wrong or looks weird in the game, add or subtract 1 from the corresponding shape key, and run the script again.
I'm done, what's next?
Published: May 13 2023 by @manavortex Last documented edit: Mar 02 2023 by @manavortex
You need to re-name the template folders. Unless you want to make more NPVs, it will be enough to re-name tutorial to your_username. Find a full guide to the process under .
That's how you know that you have syntax errors in your NPV's .lua file. Copy the contents of the file into a , then run the code and make sure to fix all errors.
It's usually missing quotation marks or commas. The tool above will give you a line number. Compare the line with the working template and fix the differences.
If you feel stuck, you can ask ChatGPT – just tell it that you're trying to fix LUA code, or it won't know the syntax.
The error is with your .lua file – either it's not in the correct folder, or AMM fails to load it.
If you click on the button, but nothing happens, that means that the game can't find your .ent file. The error is between your .lua and your .ent.
Most likely, the path to the .ent file is not correct. If it is, make sure that it has no upper-case characters.
For each of the mesh components that aren't moving, expand it and find the skinning entry. Make sure that the bindName points at root:
You need to manually enable the correct foot mesh.
Add an extra component and point the depotPath to the mesh for the correct feet. This is either l0_000_pXa_base__cs_flat or l0_000_pXa_base__cs_heels.
That happens when you're loading an appearance that the game doesn't know about — the problem is between your .lua file and your root entity. The names must match exactly, and must contain not typos or leading/trailing spaces.
If that was not it, double-check the path in your lua file and make sure that it points to the correct .ent file, and not to a backup or backup project.
This particular problem is always between those two files. Other mistakes will have other effects.
Just install the mod via WKit, launch Cyberpunk the way you normally do.
GarmentSupport only works on actual garment items that have been equipped using the game's transaction system. As of October 2024, that's not the case for NPCs.
Unfortunately, you'll have to go refitting. Sorry!
Create
Switch to Wolvenkit and toggle the to the .
On the Wolvenkit toolbar, you'll find a button to
The final section of tells you how to safely move files.
Optional: Be confused and/or panic about why there are files
Optional: Be confused and/or panic about why there are files again.
The best and most convenient tool for the job is . It will give you a list of files that you need to keep.
You need to keep these files inside the head folder and the .morphtarget file in the subfolder morphtargets. If you want to understand why, keep reading; otherwise, you can proceed to .
To learn what the prefixes mean, check .
If your V isn't using any piercings, you can skip this step and go directly to .
Do not delete any files if you're (Ignore this hint if you aren't).
If you have chosen , you should already have a list of files that you need to keep.
Otherwise, you need to refer to and use the table below for some oversight.
For a list, see the .
If you run into any errors, check
Switch to your project's or Wolvenkit's raw perspective. You will find the entire file structure mirrored there.
Find line 26 and following in the script, and alter the values to those of your V (which you get from the character preset, see for further explanation).
If they don't, check
then, proceed with
You need to use the for export. Make sure that it is installed and up-to-date.
As of December 2023, any script errors have been because the person encountering them has been using the wrong version. You can see which version is currently running either or by checking the path in the system console window's title:
If both of these things are true, then you can fix this problem in the next step of the tutorial, .
If you had the example project lying around for a very long time, please try and redownload it (), as the first version had been using an NPC animationgraph for facial expressions.
That is due to appearance proxies, which are how the game saves performance. If you're using the most recent , you shouldn't have any, but if you set up your files from scratch, you'll have to .
Hide 5-7 of the base body (original component name is t0_000_pXa_base__full):
If you don't have these meshes (they should be included in the sample project), you can extract them from the .
This is the reason for the section in this guide. If you want more information, read . Otherwise, you can temporarily remove all other NPVs or make sure to complete the re-pathing.
You can check the page on the Wolvenkit wiki.
female V, cyberware 03
male V, scars 01
male V, big beard
female V, tattoo 09
male V, no earring
Files to delete (0* means "01 - 04"):
minimum number of files
4
maximum number of files
13 (female body gender)
15 (male body gender)
How to make your NPV work with the AMM Nibbles Replacer
This guide is part of the guide for creating an NPV - V as custom NPC. It will teach you how to make your NPV compatible with xBaebsae's awesome Nibbles to NPCs 2.0 mod, letting you use your NPV in the game's photo mode.
the latest version compatible with your game
>= 3.5
Wolvenkit
You can find the original instructions in the mod description under Creating an NPC+/NPV Replacer inside the spoiler tags. If you stick to this guide, you won't need them.
If you experience floating clothes, try switching appearances. Often, that resolves the issue. If not, you can check Appearances: change the looks for how to copy the correct components.
Create a copy of your .app file. It doesn't matter much where you put it - simply hold down ctrl and drag it anywhere in your project browser.
Open your copied file.
Do not do this with your NPV .app file, as it will be destroyed.
From the Appearances menu, select Convert to Photo Mode .app
In the dialogue, select which file you want to use:
Check the box under "Convert appearance names".
When you click "Finish", Wolvenkit will move your file and convert the appearance names.
You need a Wolvenkit version released after Nov 29 2024 for this. If yours is older (e.g. stable 8.15), you need to download a Nightly.
Wolvenkit now has a dialogue that will do all the hard work for you. Open your photo mode .app file, and let's get specific.
To keep the values currently in your .app file, simply leave the fields blank.
From the appearances dropdown, pick Select Facial Animation
You will now see a dialogue. Keep reading for which values you need to select.
From the Animation set dropdown, select one of the first two entries (the ones starting with Photo Mode)
From the Animation Entries dropdown, pick a set of animations to load.
Photo mode expressions won't work if you pick the NPC entry, and vice versa!
Optional: You can use the Expression Set dropdown (and the text filter) to select any NPC expressions. They might or might not work - fuck around and find out!
To be on the safe side, pick Player Woman or Player Man for photo mode.
That's it! You're done! Only read on here if you care for the theory. Otherwise, go to #step-4-pack-and-test.
The photo mode replacer assumes that your appearances will be named like this:
For the sake of clarity, the NPV appearances are not named this way. Open the photo mode .app that you copied in the previous step, and change the names of your appearances.
Before entering photo mode, select the correct replacer in AMM:
Open the AMM overlay
Switch to Settings -> Photomode Nibbles Replacer
Select the correct replacer corresponding to your file
The paths that you need to replace are in the mod description under Adding your Pose Packs to Nibbles Replacer inside the spoiler tags. For your convenience, there's a duplicate in the expandable box below. If that's not working, please check the mod description!
To add more compatibility to a pose pack, you only have to edit the mod's .xl file, which you can do with a text editor. An entry looks like this:
There might be one or multiple entries for each supported .ent file. Find out which entry or entries belong together, then duplicate them and replace the paths with the one to your NPV replacer's .ent file.
Make sure that you keep the indent at the beginning (the number of spaces) exactly the same as it is for the other entries, or the file will break. If that happens, you'll see an entry in the .
To make sure that your file is okay, run it through yamllint.
Force a refresh - select a different pose.
If that isn't working, refresh the appearance:
Open the AMM overlay
Switch to the Tools tab
Click the Target Replacer button
In the scan tab or the target tools, assign a different appearance. You can switch back right away.
Repeat #step-3-picking-animations. Make sure to pick the correct options in the first and the last dropdown.
You made a mistake when editing your yaml file. Go back and read the yellow box.
Step 2: How to create a custom NPC
Published: May 13 2023 by manavortex Last documented update: Dec 01 2024 by manavortex
This page is a part of the NPV guide. It will show you how to use the provided example project to create a custom NPC for Cyberpunk 2077, whom you can then spawn with AppearanceMenuMod.
It will give you an overview over the control files and tell you how to pull in the right meshes (and appearances).
created a video guide for this (November 2024). You can find it on youtube.
How about AMM: Custom NPCs?
Find a more detailed guide about adding components to NPC app files under Appearances: change the looks. This may help you if you get stuck!
This guide assumes that
you already have a head mesh (see this section otherwise)
that you're using a set of default paths (if not, you will have to adjust)
the corresponding files are in either of these folders
tutorial\npv\your_female_character\head
tutorial\npv\your_male_character\head
the meshes are named like their in-game equivalents, e.g. h0_000_pwa_c__basehead.mesh (if not, you will have to adjust)
This guide contains as little fluff as possible, and since much of it has been covered in other guides, extra information will be contained in the links. These will be annotated as clearly as possible with what you need to read and what's optional.
If you're skimming in this guide, you will end up making mistakes. Read thoroughly. If at the end of a section you aren't where the guide says you're supposed to be, fall back and double-check your process. If you still have trouble, you can hit us up on discord in the #mod-development channel.
Remember that at any time, you can check your progress by spawning your custom character.
This section will explain what the template files do and how they hang together. You do not need to follow links; they add extra information or context if you want them.
If you like suffering, you can rely on the "fuck around and find out" approach, but I recommend at least reading through it.
In the end, an NPV is just a custom prop with a god complex. For that reason, the file structure is the same (it's just a lot more complex, because you have more than 4 components).
If diagrams help you, then click on the link to see one.
We're registering our NPC with AppearanceMenuMod via a .lua file, which needs to end up in AMM's Custom Entities folder. The full path in the Cyberpunk directory will be this:
bin\x64\plugins\cyber_engine_tweaks\mods\AppearanceMenuMod\Collabs\Custom Entities
I have prepared two example files in the Wolvenkit's project's resources. Delete the one that you aren't using, then let's take a look at the other one:
tutorial_custom_female_character.lua
tutorial_custom_male_character.lua
This is the file content for the female example:
It loads our root entity from tutorial\npv\your_female_character\_your_female_character.ent. That's the file which tells the game what to load.
You can and should change this file — see the inline documentation above for what to change. To do that, you can use a text editor such as Notepad++.
You find the root entity for your character here:
Would you like to know more? (You don't need any of this information to finish the guide.)
The root entity hooks up your .app file and the appearance names in the .lua file, and that's about everything there is to say about it. Here's how it looks:
If you want to add more appearances:
duplicate an existing entry
change the last key name to match the one in your .lua
change the first key appearanceName to the one you want to put in your .app
Let's look at the .app file now.
You can find a more detailed guide about adding stuff to .app files under Appearances: change the looks. It's optional, unless you're really stuck.
Do you want to know more? (You don't need any of this information to finish the guide.)
This section will tell you how to edit your NPV's appearance – their skin colour, chrome, piercings, tattoos. We will do this in the .app file.
When changing component names, you want to leave the #component-prefixes (t0_, hx_) in place — the game needs them!
An .app file holds a number of appearances. These are connected by name to your entity file:
Inside each appearanceDefinition (appearance for short), the components array defines your NPC's properties. This is where the game is told to pull in facial expressions, animations, hair, skin, and equipment.
This is where all of your NPC's appearances are defined (appearanceDefinition, linked to the root entity via name). The appearanceDefinition's components define your NPV's properties, such as
animations
their shadow
hair
body
clothes
Deleting meshes from the mod's files left you with a bunch of inactive components. If you start the game now, there's a chance that you might crash.
Their names will show up in the log:
Go through the appearances and delete all components that File Validation warned you about. After that, you're good go customize your NPC!
The next section, #how-do-i-know-what-to-put, will help you find the right appearance names.
If you feel completely lost, you can read up on how to change NPC appearances – the concept is exactly the same.
If you want to add another appearance
duplicate an existing entry
change the key name to match the one in your root entity
change the components
To find out which variants and appearances to use, I suggest that you use NoraLee's excellent NPV Part Picker. It will look like this:
The NPV picker does this for you, but here's how to select your eyebrow appearance by hand:
open up the mesh file and expand the first list appearances
see a bunch of entries with naming schemas like colour_01
the numbers correspond with the type of eyebrow in the character editor (look them up here)
Select the correct colour and appearance number
The values you found out will go into the components in your NPV's .app file.
This property is used for hiding parts of a mesh. If the part picker gives you this number, simply paste it into the corresponding box in your component:
You can learn more about this under Submeshes, Materials and Chunks, but this is not necessary for the tutorial.
If you skip this step, you will end up with invisible cyberware or the wrong colour/appearance.
When selecting a different cyberware than the preconfigured one, you have to set the appearance name, or the whole thing will show up in grey. The appearance names are usually identical to the cyberware (cyberware_01, cyberware_02 etc.), but if you are uncertain, you can also open the mesh file and check the appearances list at the top.
If you skip this step, you will end up with the wrong or too many piercings and cyberware. To learn more about chunkmasks, check this wiki page (if you can do it with the information below, you don't need to)
You have the full piercing or cyberware file, but you're only using parts of it — yet the game stubbornly shows you the whole mesh.
Fortunately, you don't have to edit it in Blender, because you can hide the parts you aren't using via chunkmasks.
Find the piercing or cyberware component in your .app file:
To hide those bits in the .app, we simply need to uncheck the corresponding boxes - check the previous screnshot!
Adding components is as easy as right-clicking an existing one and editing a few properties:
For a step-by-step guide on how to add items from mods to your NPV, check Appearances: change the looks -> #adding-items-from-mods!
This section will teach you how to add another hair mesh to your NPV. We will first remove the default hair, then replace it with the one you want.
To use modded hair, find the correct files inside the mod and add them to your project.
If you want to look up in-game hairs, check Cheat Sheet: Hair
For more information on hair files, check the Basic Hairstyle Replacement Tutorial
Delete the current hair from the .app — there should be 2-3 components, their names will start with either hair_ or hh_0
Find the correct hair mesh. You have three options for this:
Looking it up on our nifty list
Filtering the files and clicking through their previews:
female: base\characters\common\hair > wa_ > .mesh > !shadow
male: base\characters\common\hair > ma_ > .mesh > !shadow
Enter the name of the hair mesh that you want to use into the Asset Browser's search bar (see next screenshot) and hit Return.
Once you have found the correct mesh file, right-click it and select "Find Files Using This":
This will give you a list of files, which you can mostly ignore.
The only thing we care about is the hair's control file, which is usually an .ent file:
Some hair mods don't use an .ent file. In this case, the components will be inside the .app file's appearances, similar to NPC apps. You can copy the entire components array of the appearance that you want to use.
If there are multiple files, check which one uses the most components per appearance.
Open the .ent file and expand the components array. You will find three components in there, which you can now copy over to your .app!
As of version 2.2.0, the body mesh and arms are included for easier replacing.
The process is the same as what you did with the hair: find the files in the mod, add them to your project, move them to your NPVs folder and customize them to your liking.
You can find more information at Cheat Sheet: Body (which also contains the tattoo paths).
Go forth and create custom apperances!
You can check this guide, or look through the .app files for other NPCs for ideas. If you need further details, I highly recommend checking out NoraLee's much more detailed tutorial, which will also give you all the context you could possibly need.
For guides on how to export a whole animated character to Blender, you can check here.
Please remember that before sharing your NPV, you have to change the paths! You can find a full guide on the fastest way to do that here.
Don't forget, you can pack the Wolvenkit project by pressing the green button in Wolvenkit's toolbar, spawning Tutorial Man and Tutorial Woman via AMM to check out your progress.
an NPV as per
newer than December 03 2024 (8.16 or )
After you have changed the appearance names and saved the file, you can your Wolvenkit project.
Wolvenkit's will help you finding the components that you can delete.
Also, will help you by detecting broken links: keep an eye on Wolvenkit's log when you save a file.
Wolvenkit's triggers when you save a file, and it will help you to spot mistakes.
You can see that inside the .mesh file (which you can see in the component's depotPath). Open it in Wolvenkit, then switch to the tab and toggle the checkboxes on the right; those directly correspond to the boxes you need to uncheck in the .app file:
hx_, l1_ etc) - they're used by various other mods, among them EquipmentEx
