Changing an NPC's default appearances (and adding more via AMM)
Published December 27 2022 by @manavortex Last documented update: January 06 2024 by @manavortex
This guide will walk you through editing NPC appearances for Cyberpunk 2077.
It uses the following versions:
Cyberpunk 2077 game version >= 1.6
WolvenKit >= 8.7.1-nightly.2022-11-04
(only if you want to add new appearances) AppearanceMenuMod >= 1.15
For an overview of NPC files, check NPCs and their files
If you want to add custom NPCs to Cyberpunk 2077 with AMM, check AMM: Custom NPCs
If you want to add AMM appearances to existing NPCs, check AMM: Custom NPC appearances
If you want to add V as an NPC, check NPV - V as custom NPC
If you want a more basic guide that goes into more detail for the basic stuff (including Blender), see Altering Appearances within Wolvenkit - Full Workflow
If you're after hair colours, check and follow the links from there.
Links will give you additional context. If you can complete the guide without them, feel free to ignore them.
This section will show you how to find an NPC's .app file, which you will add to your project. We do this by finding the NPC's .ent file, since it will be linked in there.
The NPC's root entity file is the entry point for the game. It defines an NPC's appearances, linking them to the actual definitions inside the corresponding .app file.
You don't need to add this file to your project (and if you do it by accident, you should delete it later). For details, see AMM: Custom NPC appearances.
You can try finding your NPC's .ent file on NPCs and their files. If you can't find your entry, the page has information how you can search for it — please add it to the page, this wiki is a community project!
The array appearances will contain a list with every appearance that's defined for this NPC, matching the key appearanceName
in the .ent file.
Not all of these have been "published" (as in "hooked up to .ent files"). For an example of this, check base\characters\appearances\citizen\citizen__children_mc.app
The only thing you need to care about is the components
array (learn more about these here). This is where you add, remove, or modify parts of an NPC's appearance:
The names of components should be unique so you can manipulate them outside of the .app file. You should generally stick to CDPR's naming scheme, including the prefixes (why is this important?).
CDPR's style of unique naming allows us to find components and their usage across the game files, which will come on handy when we're trying to add items.
This is where the magic happens.
Change items by selecting a different appearance or a different mesh:
Remove items by deleting their entries from the list or by setting their chunkMasks to 0
:
For a detailed guide on adding hair, check NPV: Creating a custom NPC - #hair
If you want to add a new item, first duplicate an existing one. After that, you can pretend that it is just another change:
And this might work.
Or it might end up leaving them standing in an exploded pixel cloud. In case of animated components, editing them will almost certainly break them (see #animations-if-you-cant-avoid-them-copy-them-as-well)
Anything of the type entGarmentSkinnedMeshComponent
is prone to breaking unless you copy everything it needs.
Let's do it…
You need to find the thing you want to add in the files, check where it is defined, and then copy all of its components.
Search for the mesh name of the vest that you want to use (e.g. ma_vest__high_collar*.mesh
)
Anything of the type entAnimatedComponent
means that components are animated. That's mostly the case for physics-enabled stuff influenced by gravity, such as coats, jackets, or long hair.
Physics gave us the atomic bomb. (It also gave us computers, but this is besides the point right now.)
Animations are usually unique to meshes on a by-pixel basis and do not react kindly to edits or swaps. (Try splitting the obi from Saburo's kimono into its own submesh if you don't believe me).
If you copy an animated component (e.g. Johnny's vest), then you need to copy the corresponding entAnimatedComponent
as well, or the mesh won't move.
If you delete a physics-enabled component, you can safely delete the corresponding AnimatedComponent.
Adding new appearances to an existing NPC requires you to overwrite that NPC's .ent file (see AMM: Custom NPC appearances). For that matter, it's recommended that you create a new entity instead. You can find a guide for this under AMM: Custom NPCs.
You may have forgotten to copy the animation file. Look for an entAnimatedComponent inside the .app — they're usually called something like xxx_dangle(s)
or collar.
(See here)
If it's a clothing item not moving, check the skinning array for the component and make sure the bindName
is set to root
. If you swapped out a component for something else, you also might need to update its matching entry in AppearanceVisualController -> appearanceDependency
. But don't do that unless necessary.
That's what happens when the game can't find the appearance you picked. You're probably trying to add an AMM appearance. Check the spelling between your lua file with the appearance name, the mapping entry inside the .ent, and the appearance's name in the .app file.
You have
Point your to the file you have found. We want to find the .app file and add it to our project. You can right-click on the .ent file and select , or you look up the path in the .ent file:
Now that you have found the .app file, let's and look inside.
Select the mesh, then "":
If you find an .ent file called _pwa_
or _pma_
, that's a player mesh entity, which contains only the components you need — jackpot, use that one. Otherwise, find any .app file that sounds promising - for example Scorpion's.
it to the project (you don't need the file).
Find and select the components in the other NPC's appearance list:
Select ""
Go back to your original .app file and select either the root of the components
array, or any component inside the array. Now right-click and select "".
If you haven't done that yet, the original component(s) and its animations/dangles. Skipping this step will give Johnny two vests, and he's not the type to do that.
Save the .app file, , and go testing!