Summary

Published: April 2023 by @manavortex Last documented update: Sep 20 2024 by @manavortex

This guide will teach you how to create AMM props in two variants:

• the old way by using a mesh entity with a .mesh file with only one appearance

• customizable by chaining a root entity, an .app, and a .mesh file with multiple appearances

Its focus is on the file structure and the relations between the files.

Wait, this isn't what I want!

• If you want to play around with materials and an existing prop, check AMM: Textured items and Cyberpunk Materials using Custom Props

• If you want to enable collisions, see Enable embedded collisions

• If you want to make meshes out of 2d textures, see Your image as custom mesh

• … or use the wiki's AI-assisted search function, or simply poke around

Where to find models

Many websites host free stuff; you can find the largest archives below. Browse this list for a more comprehensive collection, or use the following queries in your search engine of choice:

thing_I_want free 3d model
thing_I_want free fbx file

For game design or rendering, usually textured:

• Sketchfab

• TurboSquid (there's a drop-down menu on the left-hand side where you can select to search for free models!)

• CGTrader

• Renderosity

• Daz3D

• ArtStation

• RenderHub

For 3d printing, usually not textured:

• thingyverse

• MyMiniFactory

• Pinshape

Requirements:

• Cyberpunk 2077 game version

• WolvenKit >= 8.12 for 2.1, 8.8.1 for 1.6.1 (DLSS)

• Appearance Menu Mod (>= version 2.1, anything earlier won't have customizable appearances)

• Optional, but recommended if you want to create multiple props: Notepad++

Level of difficulty: You know how to read.

Setting up the project

This section will tell you how to get the files, then give you an explanation of what they do and finally show you a diagram on how they hang together.

2. Download the AMM prop template from Nexus. Download the complete source folder, as it will have the files as depicted below.

3. Prepare your Wolvenkit project by merging the source folder you downloaded with the one from your project. By the end of it, you should have the following files:

1. Optional, but recommended: Start the game and spawn the props, as in the green hint box at the beginning of this section.

2. Optional, but very recommended: Read through the next section to understand what's going on here.

3. If you're the more hands-on kind of learner, skip to #using-other-meshes or #creating-another-prop to fuck around and find out.

Explanation: what did you just download?

LUA file

This file registers your prop with AMM. File content looks like this:

return {
  -- put your name. Unless that's what you're called, not judging.
  modder = "your_name_here",
  
  -- you're supposed to put your _OWN_ thing here
  unique_identifier = "amm_custom_props_tutorial",

  props = {
    {
      name = "Tutorial item (customizable)",
      path = "tutorial\\amm_props\\template\\template.ent",
      category = "Misc",
      distanceFromGround = 1,
      appearances = {
          "template_item_textured",
          "template_item_multilayered",
      }
    }, 
    {
      name = "Tutorial item",
      path = "tutorial\\amm_props\\template_no_variants\\template_no_variants.ent",
      category = "Misc",
      distanceFromGround = 1,
    },
  }
}

Without a lua file, AMM won't know about your props, and thus can't spawn them.

Here's what the lines do:

Entity file

Defined in your LUA file, this file holds the game entity that AMM spawns when you click the button. There are two ways of using entity files:

Mesh entity (the legacy version)

One entity file per variant. The props will not have appearances — AMM's prop browser has one entry per entity file (e.g. cube_black, cube_white, cube_glowing).

Edit this kind of prop by opening the following file in Wolvenkit:

tutorial\amm_props\template_no_variants\template_no_variants.ent

You add props by putting meshes directly into the components array:

Root entity

One entity file per prop, one entry in AMM's prop browser (e.g. cube). After spawning it, you can toggle its appearances (white, black, glowing) the same way you do it with NPCs.

Edit this kind of prop by opening the following file in Wolvenkit:

tutorial\amm_props\template\template.ent

Instead of adding items directly via the components array, we link appearances to an .app file. The only component we keep in the root entity is the targeting component for the CET cursor: this way, it will be added to each appearance in the .app file.

Appearance file

This file holds a list of appearances. Inside each appearance, you can define any number of things to be loaded (components) and specify or override their behaviour.

template_textured.mesh

A pre-configured mesh for a textured material. Uses the following files in the subfolder textures:

• template_01_d.xbm: A diffuse (albedo) map, colouring the mesh

• template_01_n.xbm: A normal (bump) map, adding depth to the object.

You can learn more about textured materials here. This is not necessary for the purpose of this guide.

template_multilayered.mesh

A pre-configured mesh for a multilayered material. Uses the following files in the subfolder textures:

• 6_layers.mlsetup: A multilayer setup with colour properties

• 6_layers.mlmask: A multilayer mask, determining which parts of the mesh are affected by which layer of the mlsetup. In this case, it just contains six blank layers.

• template_01_n.xbm: A normal (bump) map, adding depth to the object.

You can learn more about multilayered materials here. This is not necessary for the purpose of this guide.

Diagram

Okay, now that we've gone through the theory, let's have a quick overview how everything hangs together:

Without variants

With variants

Using other meshes

You can point the prop at a different mesh by changing the depot path of the component. If you have no idea how to do that, read on!

With variants

1. Open the appearance file tutorial\amm_props\template\template.app

2. Find the array appearances at the top of the file

3. For each appearance, open the components array

4. Click on the first component amm_prop_slot1. In the panel to the right of the tree, change the following properties:

   • mesh -> DepotPath. Put the relative path to your .mesh (right-click on the file)

   • mesh -> meshAppearance. Put something that actually exists in your file, otherwise the first appearance from the list will be used as default.

1. If you want to use more than one mesh, repeat the process for the other components. If you want to use more than 4, check #why-only-4-components below.

2. Repeat the process for the other appearances.

3. Save the file and start the game. If you've done everything right, you will now see your new mesh.

Without variants

1. Open the mesh entity tutorial\amm_props\template_no_variants\template_no_variants.ent

2. Find the components array and open it

3. Click on the first component amm_prop_slot1. In the panel to the right of the tree, change the following properties:

   • mesh -> DepotPath. Put the relative path to your .mesh (right-click on the file)

   • mesh -> meshAppearance. Put something that actually exists in your file, otherwise the first appearance from the list will be used as default.

1. If you want to load more than one mesh, repeat the process for the other components. If you want to use more than four, read #why-only-4-components

2. If you don't want to load more than one mesh, select amm_prop_slot2 and delete the depotPath. Otherwise, you'll see your prop and a floating cube.

3. Finally, change the defaultAppearance to a valid appearance in your .mesh file. If no appearance with this name can be found, the prop will be invisible when it spawns.

Why only 4 components?

Currently (October 31 2023), AppearanceMenuMod can only scale objects by targeting their components by name. For that reason, yours have to be named as they are.

If you use more than 4 components or change their name, then your prop will no longer scale.

Creating another prop

If you want to create another prop, here's the fastest non-script way to go about it (tried and tested by manavortex).

1. In Windows Explorer, duplicate the template folder

2. Rename the new folder (template - Copy) to the name of your prop (e.g. baseball).

1. Rename all files inside of the folder: replace template with the name of your prop (e.g. baseball). Not all files will have template in their names; just ignore the ones that don't.

2. Switch to the raw tab in Wolvenkit and open your json files in Notepad++

3. Via Search and Replace in Files (Ctrl+Shift+F), replace template with the name of your new prop and folder (e.g. baseball). Replace it in all files, using Match case:
4. Optional: If you have changed the folder structure (e.g. moved your folder from the subfolder stuff to the subfolder misc), run another Search and Replace in Files (Ctrl+Shift+F) to adjust your file paths.

5. In the project browser's raw section, right-click on the folder and select Convert from json. This will have updated the relationships between the files to your renamed files.

6. Delete the files / appearances that you don't need. Save and close the mesh file.

7. Import your meshes and textures over the ones from the template. For a guide on how to do that, check here.

9. To register the prop with AMM, add another entry to the props array in your LUA file:

    {
      name = "Baseball (customizable)",
      path = "tutorial\\amm_props\\baseball\\baseball.ent",
      category = "Misc",
      distanceFromGround = 1,
      appearances = {
          "baseball_textured",
          "baseball_multilayered",
      }
    }, 

1. Save the LUA file.

2. Install and launch the game

3. Spawn your new prop Baseball (customizable) with AMM.

If everything went well, you should see something like this now:

If not, it is time to hit up the troubleshooting.

The final touches

Before you can share your custom props, you have to change the folder structure and file paths. Otherwise, two people overwrite tutorial.lua, and one of the mods stops working.

You can find a step-by-step guide on the process here.

Troubleshooting

This section will only cover troubleshooting steps for this guide. For anything related to mesh imports, see here. For general 3d model troubleshooting (including import errors), see here.

My prop doesn't even list in AMM!

The problem is in your .lua file. Use this tool to check the syntax and make sure that there are no errors - usually, it is missing/extra commas and/or missing/extra braces.

If the syntax is okay and your prop still doesn't show up, double-check your category and make sure that it is one of the existing ones.

My prop won't spawn!

... and I can't target it!

AMM can't find your .ent file. Make sure that your .lua points to the correct path in your archive (right-click -> copy relative path and paste it to your lua file.

... it all looks good, but there is no prop!

Toy around with the scaling. Sometimes, your prop doesn't show because it's the size of Johnny's ego and hovers somewhere above your city block – or the opposite, it's microscopically tiny. Don't be afraid to change it by the factor 10 or even 100 and see if that does anything.

If that's not it and if you have a customizable prop (with a root entity), try adding an appearance default to the mesh. The game will fall back to that one if there are issues with your custom appearances.

My prop spawns, but something about it is weird!

In general, your answer is probably in the guide on AMM: Textured items and Cyberpunk Materials using Custom Props, section 2 (processing the mesh) – check that guide's troubleshooting section.

Summary

Published: Feb 09 2024 by Last documented edit: Feb 11 2024 by

This page will show you how to add a light component to AMM props.

Wait, this is not what I want!

For a quick overview on lights and their properties, check Cheat Sheet: Lights (currently WIP)

For an explanation about light, check Lights explained (currently WIP)

Adding lights to AMM props

This is as easy as finding the right component, adding it to your prop (either in the root entity or in each appearance in the .app file) and naming it Light:

This enables the AMM light panel in the target tools.

Placing your light components

Your lights will be anywhere relative to your prop. How can you position them relative to the actual object?

1. Add an Empty in Blender (Viewport, Hotkey: Shift+A -> Empty -> Plain Axes)

2. Move the empty to the position where you want your light to be

3. Switch to the Object tab and see its location transform:

Now that you have the relative position, switch back to Wolvenkit: we need to add it to our entSlotComponent.

1. Open the slots array and select your first entSlot

2. Find the relativePosition property in the box on the right

3. Copy the values from the "Transform" field in Blender (Screenshot above) to the corresponding fields under relativePosition (screenshot below)

1. Save and see your effect changing positions!