NPV: Creating a custom NPC
Step 2: How to create a custom NPC
Last updated
Step 2: How to create a custom NPC
Last updated
Published: May 13 2023 by Last documented update: Dec 01 2024 by
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.
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:
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.
When changing component names, you want to leave the (t0_, hx_) in place — the game needs them!
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:
For a step-by-step guide on how to add items from mods to your NPV, check Appearances: change the looks -> !
hx_, l1_ etc) - they're used by various other mods, among them EquipmentEx
