Step 1: How to generate your V's custom head mesh
Published: May 13 2023 by @manavortex Last documented update: Jan 04 2024
This page is a part of the NPV guide. It will show you how to create your V's head in Blender. If you want to load your head back into Cyberpunk, note that you aren't changing anything in the files itself — that will come in NPV: Creating a custom NPC.
We will not be dealing with the body, this is part of the next section as well.
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.
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.
The final section of NPV: Creating a custom NPC tells you how to safely move files.
Open the head
folder in your project's archive
section.
Optional: Be confused and/or panic about why there are over 9000 files.list
Look into the head/morphtargets
folder
Optional: Be confused and/or panic about why there are over 9000 files again.
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 best and most convenient tool for the job is NoraLee's NPV picker. It will give you a list of files that you need to keep.
The list will give you a number of Source Mesh entries like h0_000_pwa_c__basehead.mesh
.
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 Deleting Files.
If your V isn't using any piercings, you can skip this step and go directly to Deleting Files.
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
Do not delete any files if you're editing the player head (Ignore this hint if you aren't).
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.
If you have chosen the convenient option, you should already have a list of files that you need to keep.
Otherwise, you need to refer to #what-the-actual-fuck-are-all-those-files and use the table below for some oversight.
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.
For a list, see the table above.
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.
If you run into any errors, check #step-5-optional-troubleshooting
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"
Switch to your project's raw
folder or Wolvenkit's raw
perspective. You will find the entire file structure mirrored there.
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! :))
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 here for further explanation).
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 your shape 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 imported everything back into Wolvenkit, you can re-export the .mesh
files and use the Wolvenkit Blender IO suite to import them with materials.
Unless you are editing original V, start by deleting the morphtargets from the template file — we don't need them anymore.
Remove the entire folder, both from raw
and archive
. From now on, it's meshes only!
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 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, proceed with NPV: Creating a custom NPC
If they don't, check #step-5-optional-troubleshooting
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 need to use the Wolvenkit Blender IO Suite for export. Make sure that it is installed and up-to-date.
You can check if Blender has run into errors by opening the Blender console window - from the menu, select Window -> Toggle System Console.
As of December 2023, any script errors have been because the person encountering them has been using the wrong Blender version. You can see which version is currently running either via UI or by checking the path in the system console window's title:
As of plugin version 1.5.5.1, you should have at least 4.0 installed.
The problem went away after the person having it upgraded Blender.
If you had the example project lying around for a very long time, please try and redownload it (Nexus link), as the first version had been using an NPC animationgraph for facial expressions.
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.
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
Adding them as an NPC to spawn them with AppearanceMenuMod (has its own sub-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.
This guide uses the following versions:
Cyberpunk 2077 game version >= 1.6
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.
Eyes
Eyebrows
Nose
Mouth
Jaw
Ears
Find the mirror in V's apartment and note down the numerical values.
Body gender:
As a rule of thumb, I'll document the process for an NPV with a female body gender, because as we all know, the other doesn't exist I have one of those. If yours has a male body gender, your file paths will be slightly different, but the process is exactly the same.
Merge the source
folder in the download with the source
folder in your Wolvenkit project directory
Delete the one you're not using (do one Wolvenkit project per NPC. No, really, I mean it.)
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!
Switch it to "Install and launch"
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.
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, both in the and the section.
Body gender/variant | Files not to delete from variants |
---|---|
Creating your V's head in Blender (has its own )
If you run into issues with this guide, the right place to ask for help is #mod-dev-chat
on the .
Wolvenkit >= 8.12 ( | )
4.1
>=
>= 2.1
This tutorial should cover your basic needs, but there are many more guides and resources about NPV creation outside of this wiki. You can find them .
If you want to edit original V's files, you're (generally) in the right place. You can find extra information on .
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 .
To create a face, we need to know your character's values. For that, you need to have installed, or you won't see them:
Create
Download the example files from
In Wolvenkit's , find the prepared folders per body gender:
body gender | file path |
---|
In Wolvenkit's , delete the .lua
file for the body gender that you don't want to use.
On the Wolvenkit toolbar, you'll find a button to
If you want to create your V's head for Cyberpunk, go to
If you just want to set up the file structure, go to
Please remember that before sharing your NPV, you have to change the paths! At the very least, rename the tutorial
folders inside of archive
and resources
to your user name and then do a .
However, you might want to do that after , as you would otherwise have to move the utility script around.
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)
14 (male body gender)
female |
|
male |
|
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 Moving and renaming in existing projects.
That's how you know that you have syntax errors in your NPV's .lua
file. Copy the contents of the file into a lua validator, 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.
That is due to appearance proxies, which are how the game saves performance. If you're using the most recent NPV template project, you shouldn't have any, but if you set up your files from scratch, you'll have to disable the proxy appearance.
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.
Hide chunks 5-7 of the base body (original component name is t0_000_pXa_base__full
):
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
.
If you don't have these meshes (they should be included in the sample project), you can extract them from the Toggleable Feet mod.
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.
This is the reason for the #re-path-your-folder section in this guide. If you want more information, read #why-are-we-doing-this. Otherwise, you can temporarily remove all other NPVs or make sure to complete the re-pathing.
You can check the Troubleshootingpage on the Wolvenkit wiki.
Just install the mod via WKit, launch Cyberpunk the way you normally do.
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.
You can find the original instructions in the mod description under Creating an NPC+/NPV Replacer inside the spoiler tags.
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.
For NPV projects >= v2.0.0 (30. October 2023), you can skip to #the-photo-mode-.app-file.
For earlier versions, or if you have not been using the example project, you need to add the photo mode animations component.
Download Wkit Project - NPC App from the mod's optional files.
In the .app file, open the first appearance
Open the components
array
Find the entAnimationSetupExtensionComponent
with the name of PhotomodeAnimations
Copy it to each appearance in your NPV's .app file.
You enable the feature by overwriting the dummy .app file for your chosen NPV. Instead of looking up the path in the mod description, we're lazy and overwrite the template file, which we find in the Mod Browser by using the following search query:
If you don't find those files, your AMM Nibbles Replacer isn't installed correctly. You'll want to fix this before proceeding.
Find the file that you want to use, and add it to your project.
If a file name shows up more than once, you already have an NPV with photo mode replacer support installed. In that case, you'll want to pick the other file — there are two for each body type.
Adding support for more than two .app files requires you to edit both the photo mode replacer and AMM, so it won't be covered in this tutorial.
Instead of the dummy file, you will want to put your own app file there. You can copy the file by holding the ctrl
key while dragging in the Wolvenkit Project Browser.
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.
For each appearance definition in In your photomode .app file, find the component with the name face_rig
.
Make sure that the depotPath
is of the graph
is set to the correct .animgraph
depending on your body gender:
Save the file. You now have photo mode expressions, but no more AMM expressions. Can only have one…
After you have changed the appearance names and saved the file, you can install and launch your Wolvenkit project.
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.
Step 2: How to create a custom NPC
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 a brief overview over the control files and tell you how to pull in the right meshes (and appearances).
How about ?
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. 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\Custon 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\ops\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.
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 (t1_) in place — the game needs them to calculate collisions!
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, pulling in equipment, facial expressions, hair and skin.
Would you like to know more? (You don't need any of this information to finish the guide.)
It looks like this:
Whenever you save the file, the Wolvenkit console will show you the results of the file validation. These will point you towards mistakes in your paths.
If you get a bunch of errors that complain about "mesh not found in project files" or "no depot path set, only hash given," that's no reason to panic – those errors come from files that you deleted, but which are still linked in the .app
. If you deleted them by accident, restore them from the template project. Otherwise, you can (and should) delete the components.
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.
Also, File Validation will help you by detecting broken links: keep an eye on Wolvenkit's log when you save a file.
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.
Sometimes, the NPV picker gives you a number for chunkMask
. You can paste that directly into the box in your component's properties. (Check the link to see an example of how it looks like)
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.
Wolvenkit's file validation triggers when you save a file, and it will help you to spot mistakes.
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:
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 Mesh Preview tab and toggle the checkboxes on the right; those directly correspond to the boxes you need to uncheck in the .app
file:
To hide those bits in the .app, we simply need to uncheck the corresponding boxes - check the previous screnshot!
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
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.
minimum version | |
---|---|
Published: May 13 2023 by Last documented update: Mar 18 2024 by
the latest version compatible with your game
>= 3.5
an NPV as per the tutorial