NPV: Creating a custom NPC

Summary

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).

Video guide

Wait, this isn't what I want!

• How about ?

• Find a more detailed guide about adding components to NPC app files under . This may help you if you get stuck!

Prerequisites

This guide assumes that

• you already have a head mesh (see 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

Skipping and skimming

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 in the #mod-development channel.

How everything hangs together

In the end, an NPV is just a 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.

The .lua file

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

The file content

This is the file content for the female example:

It loads our from tutorial\npv\your_female_character\_your_female_character.ent. That's the file which tells the game what to load.

The root entity

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:

Let's look at the .app file now.

The app file

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

Step 1: Cleaning up

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.

Wolvenkit's will help you finding the components that you can delete.

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!

Step 2: Customizing

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.

Adding another component

If you need more components than you have, you can duplicate an existing one:

• Select and right-click

• Duplicate it from the context menu

• Change the key name to something unique

Adding another appearance

To create more appearances, you can also duplicate an existing entry:

• Select and right-click

• Duplicate it from the context menu

• change the key name to match the one in your root entity

How do I know what to put?

If you prefer to do things the hard way, you can head to and look up your individual parts. Otherwise, I suggest that you use NoraLee's excellent .

It will look like this:

The values you found out will go into the components in your NPV's .app file.

The NPV picker gives me a chunkMask...?

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:

Customizing Cyberware

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.

For cyberware added after 2.2, please see ->

Customizing eyelash colour

If you do not want to customize your eyelash colour, you can skip ahead to .

To set your custom eyelash colour, you need to set it inside the mesh file (as the player's eyelashes are coloured independently from the eye).

1. Open up the mesh file he_000_pxa_basehead. You can find it in your project browser, or open it from the component:

1. Find and expand the appearance you are using (the same you set in the .app file).

2. Find the chunk saying eyelashes_MAT (respectively eyeMat3 for mV) and change its value to the correct eyelash colour (e.g. eyelashes__blue_steel).

Customizing piercings and chrome: Chunkmasks

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:

How do I know which numbers to put?

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 hide those bits in the .app, we simply need to uncheck the corresponding boxes - check the previous screnshot!

Adding stuff to an appearance

The easiest way to add components is to duplicate an existing component.

For a single appearance

For a single appearance, right-click an existing component, and edit the properties:

For all appearances

To edit all appearances, use the menu bar entries under Appearances -> Edit Components.

1. Select "Create new component from existing"

2. Use the filter to find an appearance that you want to duplicate (e.g for a clothing item, duplicate a clothing component)

3. Give the component a unique name! You need this in the next step

1. Now, use "Change mesh component properties"

2. For "New component name", select the one from step 3

3. The other properties should be self-explanatory — this will edit the component's depot path, mesh appearance, and chunk mask.

1. If you need to change more about your component, use the to display only your new component across all appearances.

Adding modded items

For a step-by-step guide on how to add items from mods to your NPV, check -> !

Hair

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.

1. Delete the current hair from the .app — there should be 2-3 components, their names will start with either hair_ or hh_0

2. Find the correct hair mesh. You have three options for this:

1. 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:

1. 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!

The body

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 (which also contains the tattoo paths).

And that's the gist of it!

Go forth and create custom apperances!

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 .