# ArchiveXL: Dynamic conversion guide

## Summary

**Published:** June 30 2024 by [mana vortex](https://app.gitbook.com/u/NfZBoxGegfUqB33J9HXuCs6PVaC3 "mention")\
**Last documented update:** June 30 2024 by [mana vortex](https://app.gitbook.com/u/NfZBoxGegfUqB33J9HXuCs6PVaC3 "mention")

This page will teach you how to convert your existing ArchiveXL mod to the "new" system.

## Prerequisites

* An ArchiveXL mod that you want to convert

We will go through the process step-by-step. I'll explain what I'm doing as I go along.

## Step 0: The .yaml

Instead of one entry per **item variant**, we only need one entry per **item**.

Our variants are defined via `$instances` and generated via substitutions. Let's take a look at this:

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-43ae745dfdb7672049a913e128cfab058621c7b8%2Farchivexl_conversion_yaml_before_after.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
You'll notice that the `displayName`s are different now. I could prevent that by writing `my_shirt_localization_name_$(shirt)_$(ribbons)`, but this is a great chance to clean up the historically-grown mess.
{% endhint %}

### What did we do here?

* We **deleted** the `appearanceSuffixes` (we'd only need them for [gendered-preview-icons](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/custom-icons-and-ui/adding-items-preview-images/gendered-preview-icons "mention"), and we can't be arsed with that)
* We defined a list of `$instances`, which will generate all of our different appearances
* We replaced all parts that are different with the corresponding key from `$instances`. The rest will be magic.

### And that !+ stuff?

Defines the variants — you'll get a gold star for paying attention, but we're getting to that later ([#step-3-the-mesh-entity](#step-3-the-mesh-entity "mention"))

## Step 1: The root entity

Instead of one entry **per variant and gender**, we only need one entry **in total**.

Our appearance's `name` must still match the `.yaml`, but only up to the variant separator: we're going with `appearance_root_entity_`.

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-3f7e20625349bf527eb0892fe2c08dd776361ea7%2Farchivexl_conversion_root_entity_before_after.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
By leaving the `appearanceName` blank, we're telling ArchiveXL to re-use `name`. If you want to use a specific appearance name (or if you don't want `appearance_root_entity_` in your .app), you can put something different here.
{% endhint %}

### What did we do here?

* We added the `DynamicAppearance` tag to enable the feature
* We deleted all appearances but one
* We deleted everything variant-related from the appearance
* We deleted the appearanceName, so that ArchiveXL will re-use `name` for the .app

## Step 2: The .app

Instead of one appearance per **variant and gender**, we will squash everything down so that we have only one appearance per gender. In [#lets-simplify-this-even-further](#lets-simplify-this-even-further "mention"), I will teach you how to reduce that even further, but for now, we'll be going step by step.

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-53882137c5e84e1ac68e5a8efe712e126afdb602%2Farchivexl_conversion_app_file_before_after.png?alt=media" alt=""><figcaption></figcaption></figure>

### What did we do here?

* We deleted all but one appearance per gender
* We added the condition `&gender=w` and `&gender=m`
* We deleted the `partsOverrides`

Gender matching now happens via condition. The different meshes for male and female body gender are loaded in the different mesh entity files.

{% hint style="info" %}
For a full list of conditions, see [archivexl-suffixes-and-substitutions](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl/archivexl-suffixes-and-substitutions "mention")
{% endhint %}

### But that will always load the default appearance!

Right! You've been paying attention! Let's take a look at that next.

## Step 3: The mesh entity

We will only change a single field (`meshAppearance`).

Before, it was `mesh_white_red` (the default appearance), and each appearance overwrote it via `partsOverride`. We're now changing it to `dynamic`:

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-2388dbb34445b3c15536663edccb041a36074b6c%2Farchivexl_conversion_mesh_entity.png?alt=media" alt=""><figcaption></figcaption></figure>

Old: `mesh_white_red`\
New: `*mesh_{variant.2}_{variant.1}`

{% hint style="info" %}
This is where file validation currently stops working (as of June 2024). If you make any mistakes here, you will always see the first mesh appearance.
{% endhint %}

{% hint style="warning" %}
This assumes that the appearance names inside the mesh start with the prefix `mesh_`. If yours don't, you need to adjust accordingly.
{% endhint %}

### What did we just do?

* By adding a leading `*`, we told ArchiveXL that this field is involved in magic (substitution in this case)
* By replacing `white` with `{variant.2}`, we're using the second parameter from the yaml's `appearanceName` (shirt).
* By replacing `red` with `{variant.1}`, we're using the first parameter from the yaml's `appearanceName` (ribbons).

### Parameters? Variants? What?

Let's unpack this.

In this example, we have the following mesh appearances:

* `mesh_white_red`
* `mesh_black_red`
* `mesh_black_blue`

By using `!` in the `appearanceName`, we're telling ArchiveXL that everything after is part of the mesh appearance definition:

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-ee6fe828dcb7c14c50d3bb1f1da27de6c991ae3b%2Farchivexl_conversion_guide_variants.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
This is the reason why we've used only `appearance_root_entity_` as the appearanceName, and not the whole ordeal.
{% endhint %}

The `+` in the `variant` allows you to reference each substitution by its index. In this case, `variant.1` is the first element (before the `+`), `variant.2` (after the `+`), and if you wanted more substitution variables, you could add more `+` and reference `variant.3`, `variant.4`, etc.

#### What if I don't use +?

Let's compare our setup ( `*mesh_{variant.2}_{variant.1}`) to the alternative.

yaml:

```yaml
appearanceName: appearance_root_entity!$(shirt)_$(ribbons)
```

Our `meshAppearance` would be `*mesh_{variant}`.

{% hint style="info" %}
Without the split, there's no way to reference the individual substitutions.
{% endhint %}

## Recap

Unless you got hopelessly lost, this should have taken no more than ten minutes, and your mod just works(tm).

You now have one `root_entity` entry, two `appearanceAppearanceDefinition`s in your `.app`, and one `mesh_entity` per body gender.

## Let's simplify this even further.

Currently, we have two mesh\_entities:

```
tutorial\torso\my_custom_shirt\mesh_entity_pwa.ent
tutorial\torso\my_custom_shirt\mesh_entity_pma.ent
```

Each of them points at a different mesh:

```
tutorial\torso\my_custom_shirt\meshes\t1_custom_shirt_pwa.mesh
tutorial\torso\my_custom_shirt\meshes\t1_custom_shirt_pma.mesh
```

Delete one of the mesh entities and rename the other:

```
tutorial\torso\my_custom_shirt\mesh_entity.ent
```

### The .app file

Delete one of your appearances, and strip the suffix name from the other, leaving only `appearance_root_entity_`.

Change the path of your `partsValue` to the only remaining mesh entity, and save the file.

{% hint style="info" %}
This will only load one body gender (the one you defined in the `mesh_entity`).
{% endhint %}

## The mesh\_entity: Round 2

### Method 1: Conditional Components

{% hint style="danger" %}
You should use the other approach where possible; this is only documented here for the sake of completeness.
{% endhint %}

Just like with appearances, you can also use [#conditions](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl-suffixes-and-substitutions#conditions "mention") with component names.

**Pro:** Especially with many body mods, you can just put all the logic into the components

**Cons:** All of these components will be added to the player entity, even if half of them will be hidden. This is bad for performance, especially if everyone does it.

{% hint style="info" %}
If you want several different body mods or feet state to use the same mesh, you can use [archivexl-resource-linking](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl/archivexl-resource-linking "mention") instead.
{% endhint %}

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-0abdf71e3cc8b51ece82d4b0a1dc102fb975b65c%2Farchivexl_conversion_conditional_components.png?alt=media" alt=""><figcaption></figcaption></figure>

### Method 2: Component substitution

The best way of dealing with multiple meshes is to have a single component and let ArchiveXL handle all the heavy lifting by using substitutions in the path:

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-b16b0b6d8e76ab939593724636fb66105e5af93c%2Farchivexl_conversion_path_substitution.png?alt=media" alt=""><figcaption></figcaption></figure>

This is our mesh's depot path:

```
*tutorial\torso\my_custom_shirt\meshes\t1_custom_shirt_p{gender}a.mesh
```

At runtime, ArchiveXL will substitute `{gender}` with `w` or `m`, so depending on your V's body gender, the game will load one of these paths:

```
tutorial\torso\my_custom_shirt\meshes\t1_custom_shirt_pwa.mesh
tutorial\torso\my_custom_shirt\meshes\t1_custom_shirt_pma.mesh
```

You can find a full list of component substitution on [archivexl-suffixes-and-substitutions](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl/archivexl-suffixes-and-substitutions "mention").

<details>

<summary>Instead of body gender, you can also use this for <strong>body mods</strong>:</summary>

<pre><code><strong>*tutorial\torso\my_custom_shirt\meshes\t1_custom_shirt__{body}.mesh
</strong></code></pre>

becomes

```
tutorial\torso\my_custom_shirt\meshes\t1_custom_shirt__base_body.mesh
tutorial\torso\my_custom_shirt\meshes\t1_custom_shirt__lush.mesh
tutorial\torso\my_custom_shirt\meshes\t1_custom_shirt__ebbwtfbbq.mesh
...and many more
```

</details>

{% hint style="info" %}
Wolvenkit ≥ 8.16.2 lets you convert paths to dynamic from editor panel's context menu (to the right of the tree view)
{% endhint %}

#### That's it!

By using substitutions, your mesh path will auto-adjust to the current circumstances, and simply load the correct mesh.

{% hint style="info" %}
If you want to avoid mesh duplication, check out the page about [archivexl-resource-linking](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl/archivexl-resource-linking "mention")
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl/archivexl-dynamic-conversion-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.