> For the complete documentation index, see [llms.txt](https://wiki.redmodding.org/cyberpunk-2077-modding/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/items-equipment/adding-new-items/archivexl-dynamic-variants/dynamic-appearances-understanding-the-process.md). # Dynamic appearances: Understanding the process How does the ancient magic work? ## Summary This page explains the files from [ItemAdditions: Dynamic Appearances](/cyberpunk-2077-modding/modding-guides/items-equipment/adding-new-items/archivexl-dynamic-variants.md) -> [ItemAdditions: Dynamic Appearances](/cyberpunk-2077-modding/modding-guides/items-equipment/adding-new-items/archivexl-dynamic-variants.md#generated-files), what they do, and how they do it. {% hint style="info" %} You will be able to change the template project just by following the steps, but if you want to make your own mods, then you're going to want to understand this. Depending on how you learn best, you can also fuck around and try to understand the connections yourself. In that case, check [#exercise-1-create-more-records](#exercise-1-create-more-records "mention") at the end of the section. {% endhint %} ### The .mesh files These files contain the item's **geometry**, its **materials**, and the **armature** it is rigged to. They are pulled into your mod by [#the-mesh\_entity](#the-mesh_entity "mention"). You can delete meshes that you aren't using – make sure to remove the corresponding components from the mesh entity. For more information on .mesh files, check the following pages: * [3d objects: .mesh files](/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/3d-objects-.mesh-files.md#whats-a-mesh) * [Submeshes, Materials and Chunks](/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/3d-objects-.mesh-files/submeshes-materials-and-chunks.md) ### The yaml For a general explanation of what the yaml file does, check [/pages/ogzonZ0xI3ppkRsdTaEO#the-control-file-yourmodname.yaml](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/items-equipment/adding-new-items/archivexl-dynamic-variants/pages/ogzonZ0xI3ppkRsdTaEO#the-control-file-yourmodname.yaml "mention"). This section will only cover the differences between a dynamic and a regular yaml. {% hint style="info" %} This file contains the biggest part of the dynamic magic. {% endhint %} This is your dynamic project's yaml file, minus any properties that aren't influenced by the dynamic appearances: ```yaml Items.manavortex_my_custom_shirt_$(base_color)_$(secondary): $base: Items.TShirt $instances: - {base_color: black, secondary: samurai} - {base_color: black, secondary: witcher} - {base_color: black, secondary: galaxy} - {base_color: white, secondary: samurai} - {base_color: white, secondary: witcher} - {base_color: white, secondary: galaxy} - {base_color: red, secondary: samurai} - {base_color: red, secondary: witcher} - {base_color: red, secondary: galaxy} appearanceName: my_custom_shirt_!$(base_color)+$(secondary) entityName: my_custom_shirt_factory_name localizedDescription: LocKey#my_custom_shirt_i18n_desc displayName: LocKey#my_custom_shirt_i18n_$(base_color)_$(secondary) quality: Quality.Legendary icon: atlasResourcePath: manavortex\my_archive_xl_item\my_custom_shirt\my_custom_shirt_icons.inkatlas atlasPartName: my_custom_shirt_$(base_color)_$(secondary) statModifiers: - !append Quality.IconicItem - !append Character.ScaleToPlayerLevel appearanceSuffixes: [] statModifierGroups: - !append-once Items.IconicQualityRandomization placementSlots: OutfitSlots.TorsoInner ``` This section will explain how that works - except for the appearanceName, you will find that in [#the-root\_entity](#the-root_entity "mention"). #### Record names TweakXL will generate one record per entry in `$instances`, according to the rules that you're using in the item name. This happens via **property interpolation**. The example above will generate three item entries by **substituting** `$(property_name)` with the value of the property from the entry. If that isn't clear enough, check the example and the resulting item codes at the end of the line. ```yaml Items.manavortex_my_custom_shirt_$(base_color)_$(secondary): $instances: - {base_color: black, secondary: samurai} # Items.manavortex_my_custom_shirt_black_samurai - {base_color: black, secondary: witcher} # Items.manavortex_my_custom_shirt_black_witcher - {base_color: black, secondary: galaxy} # Items.manavortex_my_custom_shirt_black_galaxy - {base_color: white, secondary: samurai} # Items.manavortex_my_custom_shirt_white_samurai - {base_color: white, secondary: witcher} # Items.manavortex_my_custom_shirt_white_witcher - {base_color: white, secondary: galaxy} # Items.manavortex_my_custom_shirt_white_galaxy - {base_color: red, secondary: samurai} # Items.manavortex_my_custom_shirt_red_samurai - {base_color: red, secondary: witcher} # Items.manavortex_my_custom_shirt_red_witcher - {base_color: red, secondary: galaxy} # Items.manavortex_my_custom_shirt_red_galaxy ``` If you [install and launch](https://wiki.redmodding.org/wolvenkit/wolvenkit-app/menu/toolbar#install-and-launch) your project, you can immediately spawn them in Cyberpunk via Cyber Engine Tweaks: ``` Game.AddToInventory("Items.manavortex_my_custom_shirt_black_samurai") Game.AddToInventory("Items.manavortex_my_custom_shirt_black_witcher") Game.AddToInventory("Items.manavortex_my_custom_shirt_black_galaxy") Game.AddToInventory("Items.manavortex_my_custom_shirt_white_samurai") Game.AddToInventory("Items.manavortex_my_custom_shirt_white_witcher") Game.AddToInventory("Items.manavortex_my_custom_shirt_white_galaxy") Game.AddToInventory("Items.manavortex_my_custom_shirt_red_samurai") Game.AddToInventory("Items.manavortex_my_custom_shirt_red_witcher") Game.AddToInventory("Items.manavortex_my_custom_shirt_red_galaxy") ``` #### Display names Like the record names, the `displayName` property is also generated for each entry: ```yaml displayName: my_custom_shirt_i18n_$(base_color)_$(secondary) $instances: - {base_color: black, secondary: samurai} # my_custom_shirt_i18n_black_samurai - {base_color: black, secondary: witcher} # my_custom_shirt_i18n_black_witcher - {base_color: black, secondary: galaxy} # my_custom_shirt_i18n_black_galaxy - {base_color: white, secondary: samurai} # my_custom_shirt_i18n_white_samurai - {base_color: white, secondary: witcher} # my_custom_shirt_i18n_white_witcher - {base_color: white, secondary: galaxy} # my_custom_shirt_i18n_white_galaxy - {base_color: red, secondary: samurai} # my_custom_shirt_i18n_red_samurai - {base_color: red, secondary: witcher} # my_custom_shirt_i18n_red_witcher ``` These entries have been auto-generated in your [localization file](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/items-equipment/adding-new-items/archivexl-dynamic-variants/pages/ogzonZ0xI3ppkRsdTaEO#the-.json-file-custom-texts-i18n). #### Icons The icon name in the record is also generated for each entry. They are all using the same [inkatlas](/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/game-icons-the-inkatlas-file.md), but you can generate that as well if you want - I've done it for the [Netrunner suits](https://www.nexusmods.com/cyberpunk2077/mods/9314), since I needed more than 100 icons. ```yaml icon: atlasResourcePath: manavortex\my_archive_xl_item\my_custom_shirt\my_custom_shirt_icons.inkatlas atlasPartName: my_custom_shirt_$(base_color)_$(secondary) $instances: - {base_color: black, secondary: samurai} # my_custom_shirt_i18n_black_samurai - {base_color: black, secondary: witcher} # my_custom_shirt_i18n_black_witcher - {base_color: black, secondary: galaxy} # my_custom_shirt_i18n_black_galaxy - {base_color: white, secondary: samurai} # my_custom_shirt_i18n_white_samurai - {base_color: white, secondary: witcher} # my_custom_shirt_i18n_white_witcher - {base_color: white, secondary: galaxy} # my_custom_shirt_i18n_white_galaxy - {base_color: red, secondary: samurai} # my_custom_shirt_i18n_red_samurai - {base_color: red, secondary: witcher} # my_custom_shirt_i18n_red_witcher ``` You can see that the generated names are identical to the ones in the section [#display-names](#display-names "mention") above. That is because the key to generate them (`atlasPartName`) has the same pattern as `displayName` . {% hint style="info" %} If you want to make gendered icons, please check [Gendered preview icons](/cyberpunk-2077-modding/modding-guides/custom-icons-and-ui/adding-items-preview-images/gendered-preview-icons.md) -> [Gendered preview icons](/cyberpunk-2077-modding/modding-guides/custom-icons-and-ui/adding-items-preview-images/gendered-preview-icons.md#does-this-work-with-dynamic-variants) {% endhint %}
Exercise 1: Create more records {% hint style="info" %} This is outdated and needs to be re-worked to consider the new generated structure {% endhint %} With clever hook-ups in the mesh entity, you can set up your items so that they can be changed **with a simple `.yaml` edit** — that means, the user can switch out the ribbon colour without ever starting Wolvenkit! We'll use that here to enable "hidden" appearances. I have hooked up the example project to support two base colours: * black * white and three ribbon colors: * red * blue * green By editing the `$instances` block in the `.yaml`, you should be able to spawn 6 different shirt in the game without touching any of the additional files!
### The root\_entity For a general explanation of the root entity, check [/pages/ogzonZ0xI3ppkRsdTaEO#root\_entity.ent](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/items-equipment/adding-new-items/archivexl-dynamic-variants/pages/ogzonZ0xI3ppkRsdTaEO#root_entity.ent "mention"). This section will only cover the differences between a dynamic and a regular root entity. {% hint style="info" %} This is where you **enable** the feature by adding the tag **`DynamicAppearance`** to the `visualTagsSchema` (the last entry in the file): {% endhint %}

It's DynamicAppearance, without S.

{% hint style="warning" %} For dynamic appearances, your `root_entity` file will contain **one entry**. You can give every item [its own root entity](https://github.com/CDPR-Modding-Documentation/Cyberpunk-Modding-Docs/blob/main/for-mod-creators/files-and-what-they-do/entity-.ent-files#root-entity), or share a file across the mod. {% endhint %} The appearance name in the root entity corresponds to the `appearanceName` property in the `.yaml` without the variant:
You can leave the `appearanceName` blank. In that case, ArchiveXL will look for an appearance with the same name as the `name` attribute. ### The .app For a general explanation of the .app file, check [/pages/ogzonZ0xI3ppkRsdTaEO#appearance.app](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/items-equipment/adding-new-items/archivexl-dynamic-variants/pages/ogzonZ0xI3ppkRsdTaEO#appearance.app "mention"). This section will only cover the differences between a dynamic and a regular .app file. {% hint style="danger" %} For dynamic variants, components in the .app file will be **ignored**. You **have** to use a mesh entity. {% endhint %} #### .app file: Conditional switching {% hint style="info" %} You can find more about this under [Dynamic Appearances: fine-tuning visibility conditions](/cyberpunk-2077-modding/modding-guides/items-equipment/adding-new-items/archivexl-dynamic-variants/dynamic-appearances-fine-tuning-visibility-conditions.md). {% endhint %} You can define appearances for different circumstances by changing the appearance names. This will let you influence the mesh entity even further by e.g. hiding parts of the mesh via [Components](/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/components.md#chunkmask). And the best part is: you don't even need to touch your root entity. In the context of our example project, this means that you can define your **appearances** like this:
Appearance nameExplanation
app_file_dynamic_appearanceYour regular appearance. Is displayed when none of the conditional ones apply.
app_file_dynamic_appearance&camera=tppThis is only active in third person perspective. The item will be completely invisible in first person.
app_file_dynamic_appearance&camera=fppThis becomes active whenever you are in first person perspective. You'll usually want this to remove the mesh from your face via partsOverrides.
app_file_dynamic_appearance&gender=maleYou shouldn't do this — instead, use #substitutions in the mesh file path.
### The mesh\_entity Unless you are using [#app-file-conditional-switching](#app-file-conditional-switching "mention"), this file contains **the entire magic**. This section will explain how you tell the .ent file to load different meshes. You can use either [#substitutions](#substitutions "mention") or (not recommended) [#ent-file-conditional-switching](#ent-file-conditional-switching "mention"). #### Wait, this is not what I want! * For a picture of the difference between substitutions and conditional switching, check [#the-diagram](#the-diagram "mention") 's bottom left corner * For a general explanation of the mesh entity, check [/pages/ogzonZ0xI3ppkRsdTaEO#mesh\_entity.ent](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/items-equipment/adding-new-items/archivexl-dynamic-variants/pages/ogzonZ0xI3ppkRsdTaEO#mesh_entity.ent "mention") * To learn more about dynamic appearances, check the [ArchiveXL documentation](/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl.md#dynamic-appearances) #### How it works Per default, all components in the mesh entity are active and will be added to the player when you equip your item. Which parts of them are visible is determined by their [chunk masks](/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/3d-objects-.mesh-files/submeshes-materials-and-chunks.md#chunkmasks-partially-hiding-meshes) (set everything to visible, then use the .app's [partsOverride](/cyberpunk-2077-modding/modding-guides/items-equipment/influencing-other-items.md#partsoverrides-changing-other-meshes) to hide parts of them). #### Substitutions {% hint style="info" %} Check [ArchiveXL: Suffixes and Substitutions](/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl/archivexl-suffixes-and-substitutions.md#which-substitutions-exist) for a full list of your options. {% endhint %} Substitutions in path names will be switched out by ArchiveXL at runtime. For example, `p{gender}a` becomes `pwa` if your V has a female body gender, and `pma` if they don't. To enable substitution, your depot path must begin with an asterisk `*`. Each substitution needs to be enclosed in braces, e.g. `{gender}`.\ All generated paths will already be dynamic.
{% hint style="info" %} [File validation](https://wiki.redmodding.org/wolvenkit/wolvenkit-app/file-validation) can help you spot errors in your paths. {% endhint %} #### .ent file: conditional switching {% hint style="warning" %} This is only documented because it's possible, not because it's good practice: ArchiveXL will create **all** components, hiding those that aren't matched by your current conditions. If possible, use [#substitutions](#substitutions "mention") together with [#app-file-conditional-switching](#app-file-conditional-switching "mention") and [Influencing other items](/cyberpunk-2077-modding/modding-guides/items-equipment/influencing-other-items.md#partsoverrides-changing-other-meshes). {% endhint %}
Click to expand (DO NOT USE THIS, check the box above) Just like in the .app file, you can apply conditional switching to component names. It works exactly like [#app-file-conditional-switching](#app-file-conditional-switching "mention"):
Components can also be selected by variant, this currently cannot be broken down by variant parts (eg variant.1, variant.2 etc) but it uses the full variant after the ! in the yaml. ```yaml $instances: - { base_color: white, ribbons: red } - { base_color: black, ribbons: red } - { base_color: black, ribbons: blue } appearanceName: root_entity_dynamic_appearance_!$(base_color)+$(ribbons) ``` In this above example you can create filtered components by instance as follows. The one without the ! will be used by default if the variant is not in the list (eg black\_pink). ``` entSkinnedMeshComponent: MyJacketDecals!white_red entSkinnedMeshComponent: MyJacketDecals!black_red entSkinnedMeshComponent: MyJacketDecals!black_blue entSkinnedMeshComponent: MyJacketDecals ``` This is what your compontent can look like; in this example a different light is used based on the variant.
## The diagram Now let's look at what we just did and check the diagram. You'll see that the control files are almost identical to the[ vanilla variants](/cyberpunk-2077-modding/modding-guides/items-equipment/adding-new-items/archive-xl-item-structure-explained.md#the-final-result), but that the rest of the files has gotten a lot more manageable:
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/items-equipment/adding-new-items/archivexl-dynamic-variants/dynamic-appearances-understanding-the-process.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.