How to customize NPCs with AMM
Published: Nov 27 2023 by Last documented update: Jun 02 2024 by
This guide will show you how to create fully custom NPCs for AMM.
If you want to create AMM: 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.
You need at least the following versions and mods (newer is fine):
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
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)
This guide has not yet been updated to use ArchiveXL: Resource patching. As such, you will probably end up overwriting an existing NPC's file, breaking compatibility.
Until the guide updates, you should stick to AMM: Custom NPCs. This guide will only tell you how to target the right (vanilla) NPC file, since the rest of the process is the same.
In your project's #resources directory, create the following folder structure:
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 documented in 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.