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 AMM: Custom NPCs?

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

Prerequisites

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)

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

How everything hangs together

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.

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:

return {
  -- Your beautiful name :)
  modder = "tutorial",

  -- This must be UNIQUE so be creative!
  -- NO SPACES OR SYMBOLS ALLOWED
  unique_identifier = "tutorial_female_character",

  -- This is the info about your new entity
  entity_info = {
  -- name: The name that will be shown in the Spawn tab
    name = "Tutorial Woman",
  -- path: The path to your entity file. Must use double slash bars \\
    path = "tutorial\\npv\\your_female_character\\_your_female_character.ent",
  -- record: This is the TweakDB record that will be used to add your character. More information below.
    record = "Character.afterlife_merc_fast_melee_w_hard",
  -- type: Character or Vehicle
    type = "Character",
  -- customName: Set this to true if you want the name you set here to appear in AMM Scan tab.
    customName = true
  },

  appearances = {
    "tutorial_woman_casual", 
    "tutorial_woman_business", 
  },  

  -- Here you can pass a list of attributes from different records to be copied to your new character.
  -- More information below.
  attributes = {
  },
}

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.

The root entity

You find the root entity for your character here:

tutorial\npv\your_female_character\_your_female_character.ent
tutorial\npv\your_male_character\_your_male_character.ent

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

• clothes

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.

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

How do I know what to put?

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

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?

To hide those bits in the .app, we simply need to uncheck the corresponding boxes - check the previous screnshot!

Adding stuff to an appearance

Adding components is as easy as right-clicking an existing one and editing a few properties:

Adding modded items

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. Looking it up on our nifty list

   2. Using NoraLee's NPV Part Picker

   3. Filtering the files and clicking through their previews: female: base\characters\common\hair > wa_ > .mesh > !shadow male: base\characters\common\hair > ma_ > .mesh > !shadow

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

4. Once you have found the correct mesh file, right-click it and select "Find Files Using 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 Cheat Sheet: Body (which also contains the tattoo paths).

And that's the gist of it!

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.

Summary

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 Photomode NPV ( NPV: Photomode (formerly Nibbles Replacer))

Wait, this is not what I want!

• If you want to change the player head, see For V - Changing V's Head

• You can find more guides and resources for NPCs outside of the wiki. They are linked under External Community Guides: NPVs (V as NPC) - Custom NPCs.

Difficulty:

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 >= 2.3

• Wolvenkit >= 8.15 (Nightly | Stable)

• The 3d editing tools ( see WKit Blender Plugin: Current version for the currently supported version):

  • Blender

  • Wolvenkit Blender IO Suite

• AppearanceMenuMod >= 2.1

Credit

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.

Preparation: The character preset

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.

Preparation: Setting up the project

1. Create a Wolvenkit project

2. Download the example files from Nexus

3. Merge the source folder in the download with the source folder in your Wolvenkit project directory

4. Switch to Wolvenkit and toggle the project explorer to the source tab.

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

Check if it works

This is a working Wolvenkit project — let's make sure that it works.

1. On the Wolvenkit toolbar, you'll find a button to install the project

2. Click it

3. When the game starts, load a savegame

4. Open the CET overlay

5. Switch AMM to the "Spawn" tab

6. Search for Tutorial

7. Spawn Tutorial Woman or Tutorial Man

You should now see a person in front of you.

Get cracking

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

Summary

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.

Video tutorial

Prerequisites

• You have downloaded the prepared Wolvenkit Project from

• You have installed

• You have the Wolvenkit Blender Plugin (check if you don't)

• Blender and the plugin are on the current compatible versions

• You have completely read this entire section

Worth noticing

In this section, we will be moving/deleting files. You can complete these steps in Wolvenkit or in the Windows File Explorer.

Step 1: Getting head

1. Open the head folder in your project's archive section.

   1. Optional: Be confused and/or panic about why there are over 9000 files
2. Look into the head/morphtargets folder

   1. Optional: Be confused and/or panic about why there are over 9000 files again.
3. Delete all those files that you aren't using (read on as for how)

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.

Deleting unused files: the convenient option

Finding the right piercing

In the files, you will see four files for jewelry:

tutorial\npv\your_female_character\head\i1_000_pwa_c__basehead_earring_01.mesh
tutorial\npv\your_female_character\head\i1_000_pwa_c__basehead_earring_02.mesh
tutorial\npv\your_female_character\head\i1_000_pwa_c__basehead_earring_03.mesh
tutorial\npv\your_female_character\head\i1_000_pwa_c__basehead_earring_04.mesh

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

Deleting files

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

Expected result

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:

Step 2: Exporting head

Now, we will export all .morphtarget files from Wolvenkit so that we can edit them in Blender.

1. Find the Export Tool (Tools -> Export)

   1. To filter, click into the empty row under "name" and write "morphtarget"

   2. Check the box in the header to select everything

   3. Click "Export Selected"
3. 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.

1. Open it in Blender. It will take you to the scripting perspective, where you'll see something like this:

1. Press the play ▶️▶button.

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

3. Switch to the next script in the file, but don't run it yet:

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

Can I have that with textures?

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!

Step 3: Importing head

Exporting from Blender

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.

1. Find the Import Tool (Tools -> Import Tool)

2. Click "Import All". You shouldn't see any errors.

3. You're done!

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.

Step 4: Make sure that it works

Spawn your NPV and check that they look like they should.

• If they do,

  1. create a full backup of your project (copy the entire folder in Windows Explorer)

  2. delete all .morphtarget files from your project — we don't need them anymore (do not delete them if you are editing the player head)

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.

Blender won't export

Blender script errors

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:

A component I want is not showing!

Check the following:

• The component's shape looks okay in Blender

• The component's shape looks okay in Wolvenkit's .mesh preview

V was imported, but they're unsettlingly, subtly wrong

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.

Summary

Published: Oct 30 2023 by @manavortex Last documented update: January 4 2025 by @nutboy

This page shows you how to add your NPV to Photomode's spawnable character list. It is part of the guide for creating an .

Wait, this is not what I want!

• If you want to update your custom pose packs to work with photo mode NPCs, check

• If you want to add more appearances to vanilla photomode NPCs, check

• If you are trying to make or edit a NPV Nibbles replacer, read on. Nibbles Replacer is no longer compatible as of patch 2.2, and this guide will show you how to make a new Photomode NPV.

Nibbles Replacer and Photo Mode

With 2.2, CDPR added up to three spawnable Photo Mode NPCs. Before that, you could only spawn Nibbles the cat — and modders took full advantage. The result was the , a mod by xbaebsae.

What did the Nibbles Replacer do?

By integrating the Photo Mode with , modders tricked the game into believing that NPCs were valid alternate appearances for Nibbles the cat.

What does the new photo mode do?

• Adds up to 250 new spawnable NPC to the character list (this number has yet to be tested)

• Spawn different kinds of NPVs without exiting Photomode and managing Nibbles "slots"

• Switch NPC appearances directly in photo mode

• NPC now can spawn props and weapons if a pose has them

How to create a Photomode NPV

Requirements:

Prerequisites:

Step 1: Create photo mode files

1. Open your NPV's project in Wolvenkit

2. Open the dialogue

Click on File > Add Files > Add Photomode Files. &#xNAN;If the command stays disabled, restart WolvenKit

2. Fill out the dialogue

Wolvenkit will pre-fill everything based on your project name and your file names, but you can still customize the options. (Keep reading)

1. Double-check the NPC name, as Wolvenkit guesses it from your project and file names and you will see it every time you spawn your NPC in the photo mode picker. Remove any special characters from the file names.

2. Make sure that the right .app and .ent file are selected (if multiple of those are in the project, Wolvenkit can't tell which you want) &#xNAN;Note: You may have an .app for a Nibbles replacer as well as your NPV's regular AMM app. Use the AMM app (not the Nibbles replacer app) if you want to keep your character's appearance names. \

3. Next to NPC Name, select the body type of the character you're adding from the drop down. (Selecting the wrong one may lead to horrors.)

4. When you click "Finish", Wolvenkit will generate everything you need to spawn a photo mode NPC. You should now see something like this (Project browser's source tab):

Step 2: Install your Photomode NPV

It's time to test your Photomode NPV!

2. Enter Photomode. In the characters tab, you should see a new icon at the very bottom (you might need to scroll) with blue text:

1. Click the icon and your character will appear!

Step 3: Add a custom icon for your character

In this step, we'll change the blue ICON text to your very own texture.

2. Click on Export Selected

1. This will export a PNG to your raw folder:

1. Open this PNG in Photoshop or an image editor of your choice and update it with an image of your character.

1. Save over the PNG in the raw folder. Do not change the file name. You should be able to see a preview of the icon in Wolvenkit when selecting the .png:

2. Click import selected. It will overwrite the existing placeholder .xbm in your project files.

3. Select your .inkAtlas file or open it and check the Part Mapping tab to check if your new icon appears:

1. Press install and check in game to see your new character icon!

Optional: Giving your Photomode NPC Weapons for Poses

Some poses spawn props, and if the pose calls for a certain weapon type (melee, handgun, etc.), it will spawn a default weapon for your NPC. You can customize your NPC further by adding specific in-game weapons to their inventory to spawn instead.

Here's how to give your NPC weapons:

1. Open your NPC's .yaml

2. You should see a section like this:

Character.your_characters_name_Photomode_Puppet
  $type: Character
  entityTemplatePath: your_characters_name.ent
  displayName: your_characters_name
  persistentName: PhotomodePuppet
  attachmentSlots: [ AttachmentSlots.WeaponRight, AttachmentSlots.WeaponLeft ]

Add a new line underneath it, and copy and paste this:

  effectors:
    - !append
      $type: AddItemsEffector
      itemsToAdd:
        - item:

1. Find the record for the weapon(s) you'd like to add to your character's inventory. There are a few ways of doing this:

  effectors:
  - !append
    $type: AddItemsEffector
    itemsToAdd:
      - item: 

Alternatively, you can search "Items." in the Tweak Browser in Wolvenkit and find your weapons.

1. If you want to give your NPC more than one weapon, copy and paste - item: to a new line for each weapon you want . Spaces are important, make sure it's in line with the item entry above it. Multiple items registered properly will look like this:

  effectors:
  - !append
    $type: AddItemsEffector
    itemsToAdd:
      - item: Items.Item_Name
      - item: Items.Item_Name
      - item: Items.Item_Name

1. Save your yaml, check poses with weapons in game to see them.

Troubleshooting

My custom poses aren't working!

My NPV isn't showing up in Photomode!

• Make sure you have AMM's "Photomode Enhancements" turned off in the AMM settings

My image texture is completely white!

Summary

Published: May 13 2023 by @manavortex Last documented edit: Mar 02 2023 by @manavortex

Re-path your folder

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.

Troubleshooting

My NPV breaks AMM!

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.

My NPV doesn't spawn!

You can't select them in AMM

The error is with your .lua file – either it's not in the correct folder, or AMM fails to load it.

If you can select the NPV in AMM

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.

My NPV turns into someone else if I walk away from them!

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.

Clothes are floating!

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:

My feet are wrong for the shoes!

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.

My NPV loads, but I'm getting a random appearance!

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.

Another NPV is showing!

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.

I'm getting errors in Wolvenkit!

It installs, but doesn't launch

Just install the mod via WKit, launch Cyberpunk the way you normally do.

Garment Support isn't working!

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!