How to customize NPCs with AMM
Summary
Created by @manavortex Published Nov 27 2023
This guide will show you how to create fully custom NPCs for AMM.
It has been tested using the following versions:
Cyberpunk 2077 game version >= 2.02
WolvenKit >= 8.11.1
AppearanceMenuMod >= 2.5.2 and its dependencies
Cyber Engine Tweaks >= 1.28.1
Codeware >= 1.5.0
If you want to create Custom props instead, check the link.
If you want to add new appearances to already existing NPCs, check AMM: Custom NPC appearances
If you want to add V as an NPC, check NPV - V as custom NPC. (It's a more advanced version of this workflow)
In this tutorial, we're creating a custom entity for Mamá Welles, because right now, she's .app-sharing with all the female Valentinos in the world (base\characters\appearances\gang\gang__valentinos_wa.app
), and frankly, she deserves better.
So we're moving her out of there and setting her up with her own files. We're also giving her a comfy outfit to wear at home.
We will be creating a new character, which we can spawn in addition to the regular Mamá Welles. That's because adding appearances to an existing character is simpler, so it has its own guide under AMM: Custom NPC appearances.
Download the example project from Nexus
Extract the downloaded zip file into your project's root directory (the source
folders should merge).
You should now see the following files:
Any links in this section will go to the NPV guide, which is a more complex version of this guide. You can read the theory and then come back here, or you can go along and find out later.
The archive contains
#the-.lua-fileto tell AMM about our files
#the-root-entity, which is where we register our appearances with the game (it's a copy of base\quest\tertiary_characters\mama_welles.ent
)
#the-app-file, which actually contains the appearances (it's a copy of base\characters\appearances\gang\gang__valentinos_wa.app
)
… and a bunch of custom meshes for the mama_welles_comfy
appearance.
When you're making your own NPC, you should make sure to take the root entity from a compatible character — what animation template and which set of facial expressions they use. If you don't know what that means, just look at Takemura-san and Viktor when they walk.
Alright, here's how you go about making changes:
Read this section if you want to take the example project and mod a different NPC than Mamá Welles. Otherwise, you can check out #adding-more-appearances below.
Replace the .ent and the .app in your project with the NPC's original files
Adjust the .lua:
entity_info
=> path
must point at your .ent
file
The list appearances
I won't repeat it here — this section will only tell you how to change things. hold entries corresponding to the name
field in your .ent. This is how AMM populates the dropdown and activates the right appearance:
Optional, but recommended: before you start custompathing, change your folder structure. Since this will break your mod, can check #finishing-and-cleaning-up for how to go about that.
In the .lua
file, add an appearance to the appearances
array to register it with AMM.
In the .ent
file, open the appearances
array at the top of the file.
Optional, but recommended: Delete all appearances that you don't want, but keep one for the next step.
Create a new appearance:
Select an existing item
In the new entry, change the following fields:
name
: must match the name that you just registered in the .lua
appearanceName
: must match the name that you are going to use in the .app file in step 3.3
In the .app
file, open the appearances
array at the top of the file.
Optional, but recommended: Delete all appearances that you don't want, but keep one for the next step.
Create a new appearance:
Select an existing appearance
Change the appearance's name
to the value you used in step 2.3.2
Now it's time to adjust the components. This guide won't go into detail about this — see Appearances: change the looks for more intel on the process.
If everything is working: Congratulations! You have successfully made a mod!
But before you can share it, you need to do one last thing, which is changing the file structure. Otherwise, everyone will overwrite the same tutorial files, and only one of those mods will work.
You can find a full guide on how to do that here.
Create a and give it a name that you can remember
Find the NPC's .app
or .ent
file by using the .
If you've found an .app
, use "" to find the correct .ent
Right-click and select "" from the context menu. This will create an exact copy of your existing appearance.
Right-click and select "" from the context menu. This will create an exact copy of your existing appearance.
How to add appearances to existing NPCs (via AMM)
Adding new appearances to an existing NPC requires you to overwrite that NPC's .ent
file (As of November 2023, it is not possible to merge entity files).
For that reason, it's recommended that you stick to AMM: Custom NPCs. This guide will only give you a very rough overview.
In that folder, create your_custom_file.lua
. (You can get a template project under AMM: Custom NPCs).
The most important thing here is the entity_id
- this is what tells AMM about the already existing file that you have modified.
As an example, look at the lua file I made for Takemura's custom appearances way back when:
The rest of the process is pretty much like the other guide.
Knowing what I know today, I probably would have created a custom entity for Takemura-san in the first place, but since I chose to go down this road, I'm doomed to provide compatibility patches for the rest of eternity.
Ah, well. There are worse fates.
In your project's directory, create the following folder structure: