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
:
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.
Just install the mod via WKit, launch Cyberpunk the way you normally do.
You can check the page on the Wolvenkit wiki.
How to create your V as an NPC
Created by @manavortex Published May 13 2023
This guide will show you how to do the following things:
Setting up a Wolvenkit project with the prepared example files
Creating your V's head in Blender (has its own sub-page)
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.
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 >= 1.6
AppearanceMenuMod >= 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 here.
If you want to edit original V's files, you're (generally) in the right place. You can find extra information on A new head for V.
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.
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.
Download the example files from Nexus
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.
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! At the very least, rename the tutorial
folders inside of archive
and resources
to your user name and then do a fulltext search and replace in json.
However, you might want to do that after preparing the head in Blender, as you would otherwise have to move the utility script around.
Step 1: How to generate your V's custom head mesh
Published by @manavortex, May 13 2023 Last documented update: Jan 04 2024
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.
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 list will give you a number of Source Mesh entries like h0_000_pwa_c__basehead.mesh
.
The .mesh
files are the 3d files making up your NPV's head. I've taken them from the game files and prepared them for you (by making them use the player animations and -expressions).
The .morphtarget
files are the character creator options (a direct game export). You can safely overwrite them with the most recent version by searching Wolvenkit for the file name – you need to put it into the correct folder, though, or it won't be picked up by the scripts.
We only need the .morphtargets to generate the actual meshes by duplicating the character creator process.
The different variants in the character creator correspond to the different meshes. For example, if you select cyberware 3 in the character creator, the mesh that will get loaded is cyberware_03
. Not so difficult, is it?
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'll go about hiding the excess in one of the later steps.
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.
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 this many 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"
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! :))
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.
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!
Spawn your NPV and check that they look like they should.
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.
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 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.
Step 2: How to create a custom NPC
It will give you a brief overview over the control files and tell you how to pull in the right meshes (and appearances).
This guide assumes that
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.
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.
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:
You find the root entity for your character here:
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.
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.
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.
It looks like this:
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.
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
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
Select the correct colour and appearance number
The values you found out will go into the components in your NPV's .app file.
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.
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!
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.
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:
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.
Go forth and create custom apperances!
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.
How to make your NPV work with the AMM Nibbles Replacer
For earlier versions, or if you have not been using the example project, you need to add the photo mode animations component.
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.
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…
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
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.
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.
Create
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
This page is a part of the . 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 .
You have downloaded the prepared Wolvenkit Project from
You have installed (confirmed working on 3.5.1, 3.6 and 4.0)
You have the Wolvenkit Blender Plugin (you won't be able to export otherwise). Check if you don't.
The final section of tells you how to safely move files.
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 .
If you don't care and just want to know what to delete, go .
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.
When deleting files that you aren't using, you need 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 |
---|
For a list, see the .
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).
Yes, you absolutely can! Once you have imported everything back into Wolvenkit, you can re-export the .mesh
files and use the to import them with materials.
If they do, proceed with
If they don't, check
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 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.
Published: May 13 2023 by Last documented update: Mar 18 2024 by
This page is a part of the . It will show you how to use the to create a custom NPC for Cyberpunk 2077, whom you can then spawn with AppearanceMenuMod.
How about ?
Find a more detailed guide about adding components to NPC app files under . This may help you if you get stuck!
you already have a head mesh (see otherwise)
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 in the #mod-development
channel.
Remember that at any time, you can check your progress by .
In the end, an NPV is just a custom prop with a god complex. For that reason, the is the same (it's just a lot more complex, because you have more than 4 components).
If diagrams help you, then to see one.
It loads our 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 .
(You don't need any of this information to finish the guide.)
You can find a more detailed guide about adding stuff to .app files under . It's optional, unless you're really stuck.
When changing component names, you want to leave the (t1_) in place — the game needs them to calculate collisions!
(You don't need any of this information to finish the guide.)
Whenever you save the file, the Wolvenkit console will show you the results of the . These will point you towards mistakes in your paths.
The next section, , will help you find the right appearance names.
If you feel completely lost, you can read up on – the concept is exactly the same.
Also, will help you by detecting broken links: keep an eye on Wolvenkit's log when you save a file.
To find out which variants and appearances to use, I suggest that you use NoraLee's excellent . It will look like this:
the numbers correspond with the type of eyebrow in the character editor (look them up )
Sometimes, the NPV picker gives you a number for . 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)
Wolvenkit's 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 (if you can do it with the information below, you don't need to)
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:
To use modded hair, find the correct files and add them to your project.
If you want to look up in-game hairs, check
Looking it up on
Using
You can find more information at (which also contains the tattoo paths).
You can , or look through the .app files for other NPCs for ideas. If you need further details, I highly recommend checking out NoraLee's , 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 .
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 .
This guide is part of the guide for creating an . It will teach you how to make your NPV compatible with xBaebsae's awesome mod, letting you use your NPV in the game's photo mode.
minimum version |
---|
You can find the original instructions in the under Creating an NPC+/NPV Replacer inside the spoiler tags.
For NPV projects >= v2.0.0 (30. October 2023), you can skip to .
Download Wkit Project - NPC App from the mod's .
You enable the feature by overwriting the dummy .app file for your chosen NPV. Instead of looking up the path in the , we're lazy and overwrite the template file, which we find in the by using the following :
If you don't find those files, your isn't installed correctly. You'll want to fix this before proceeding.
Find the file that you want to use, and .
After you have changed the appearance names and saved the file, you can your Wolvenkit project.
The paths that you need to replace are in the 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!
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 .
This is a copy for your convenience. If the paths below aren'Ät working, please check the under Adding your Pose Packs to Nibbles Replacer inside the spoiler tags.
female
tutorial\npv\your_female_character
male
tutorial\npv\your_male_character
minimum number of files | 4 |
maximum number of files | 13 (female body gender) 14 (male body gender) |
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"): |
the latest version compatible with your game |
>= 3.5 |
an NPV as per