# ArchiveXL: Suffixes and Substitutions ## Summary **Published:** ??? by [mana vortex](https://app.gitbook.com/u/NfZBoxGegfUqB33J9HXuCs6PVaC3 "mention")\ **Last documented update:** Feb 18 2024 by [mana vortex](https://app.gitbook.com/u/NfZBoxGegfUqB33J9HXuCs6PVaC3 "mention") This page will teach you about conditional appearance switching in Cyberpunk and give you an overview of existing suffixes and substitutions. {% hint style="info" %} ArchiveXL did not invent suffixes. In fact, they are CDPR's solution to a problem, and they are annoying to use. psiberx has found ways to make this less painful. This page documents these ways. {% endhint %} ### Wait, that's not what I want! * For a hands-on guide to [adding-new-items](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/items-equipment/adding-new-items "mention"), check the corresponding pages in the Modding Guides section * Dynamic appearances have their own guide (see [archivexl-dynamic-variants](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/items-equipment/adding-new-items/archivexl-dynamic-variants "mention")) * There is an own page for [influencing-other-items](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/items-equipment/influencing-other-items "mention") * To conditionally hide items or parts of items, check [influencing-other-items](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/items-equipment/influencing-other-items "mention") or [archivexl-tags](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl/archivexl-tags "mention") (especially the section about [#root-entity-tags](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl-tags#root-entity-tags "mention")) ## Why are suffixes? Sometimes, you want to load different meshes/appearances under different circumstances. Before ArchiveXL 1.5, the only way to do that were suffixes — registering them in the `.yaml`, then adding one appearance for each variation in the root entity (so for 2 suffixes, you'd have 4 entries, for 3 suffixes, you'd have 8…). {% hint style="warning" %} Suffixes are **outdated**! Do yourself a favour and use [dynamic appearances](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/items-equipment/adding-new-items/archivexl-dynamic-variants)! {% endhint %} Since 1.5, psiberx has made it possible to use **conditionals** via [dynamic appearances](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/items-equipment/adding-new-items/archivexl-dynamic-variants), which require a lot less of an overhead. (Personally, I've gone from 96 entries in the root entity down to 9!) But while the solution has changed (and improved), the problems remain and require handling. {% hint style="info" %} You can use **dynamic path substitution** in **clothing items**, or in any [#entgarmentskinnedmeshcomponent](https://wiki.redmodding.org/cyberpunk-2077-modding/files-and-what-they-do/components/documented-components#entgarmentskinnedmeshcomponent "mention")s loaded via mesh.ent, as long as the depot path is set to `Soft` {% endhint %} ### Body genders There are two body genders with different proportions, and you can't make them wear the same shirt (at least not without clipping). To solve that, you can do what CDPR did and have one variant per rig. The suffix for the body is `Male` / `Female`, the ArchiveXL string substitution is `{gender}` and resolves to `m` or `w`. ### Body types ArchiveXL allows body modders to [register a custom body tag](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl/archivexl-body-mods-and-refits), which can then be used for suffixes and for substitutions in dynamic variants. To learn more about this, check [archivexl-body-mods-and-refits](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl/archivexl-body-mods-and-refits "mention"). {% hint style="info" %} You can check the current foot state by running the following command from CET: ``` print(Game.GetScriptableSystemsContainer():Get("PuppetStateSystem"):GetBodyTypeSuffix(ItemID.new(), GetPlayer(), nil)) ``` {% endhint %} ### Camera modes Sometimes, you need to hide parts of the item in first person. – for example helmets, since you don't want to have half a helmet floating in front of your face (unless you consider that immersive; most people don't).
Camera modeSuffixSubstitutionCondition
First Person Perspective&FPPfpp&camera=fpp
Third Person Perspective&TPPtpp&camera=tpp
### Arm states The arm states represent the different cyberware. For example, since you can't hire the forearms for mantis blades, you can roll up the sleeves just for this. The definitions are: | Cyberware | Suffix | Substitution | Conditional | | ------------------- | --------------------- | --------------------- | --------------------------- | | None | `&BaseArms` | `base_arms` | `&arms=base_arms` | | Mantis Blades | `&MantisBlades` | `mantis_blades` | `&arms=mantis_blades` | | Monowire | `&Monowire` | `monowire` | `&arms=monowire` | | Projectile Launcher | `&ProjectileLauncher` | `projectile_launcher` | `&arms=projectile_launcher` | If the arm states aren't working as expected, check if the table above is outdated by comparing the names with the [source code](https://github.com/psiberx/cp2077-archive-xl/blob/027aab7139689ee8d14163682ab6d506fbccea2a/src/App/Extensions/PuppetState/System.cpp#L72). {% hint style="info" %} You can check the current foot state by running the following command from CET: ``` print(Game.GetScriptableSystemsContainer():Get("PuppetStateSystem"):GetArmsStateSuffix(ItemID.new(), GetPlayer(), nil)) ``` {% endhint %} #### Foot states To achieve gender equality in regard to foot states, you need to use [Toggleable Feet](https://www.nexusmods.com/cyberpunk2077/mods/7049). The substitution key for dynamic appearances is `feet`. {% hint style="warning" %} Feet states for male-rigged V are not supported by the base game. You need to install either a body mod, or [Toggleable Feet](https://www.nexusmods.com/cyberpunk2077/mods/7049). {% endhint %}
CharacterFootwearSuffix/TagSubstitutionCondition
FemaleUnequipped&Flatflat&feet=flat
FemaleEquipped (default)&Liftedlifted&feet=lifted
FemaleEquipped with HighHeels tag&HighHeelshigh_heels&feet=high_heels
FemaleEquipped with FlatShoes tag&FlatShoesflat_shoes&feet=flat_shoes
MaleAny(empty)
If the foot states aren't working as expected, check if the table above is outdated by comparing the names with the [source code](https://github.com/psiberx/cp2077-archive-xl/blob/027aab7139689ee8d14163682ab6d506fbccea2a/src/App/Extensions/PuppetState/System.cpp#L89). {% hint style="info" %} You can check the current foot state by running the following command from CET: ``` print(Game.GetScriptableSystemsContainer():Get("PuppetStateSystem"):GetFeetStateSuffix(ItemID.new(), GetPlayer(), nil)) ``` {% endhint %} ### Sleeve states Via the [`hide_T1part` tag](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl-tags#base-game-tags), you can configure an item to hide parts of your sleeves. The substitution for dynamic appearances is `{sleeves}` .
Sleeves modeSuffixSubstitutionCondition
Full sleeves&Fullfull&sleeves=full
Partial sleeves&Partpart&sleeves=part
## Conditions Conditions are a feature of **dynamic appearances** . They can be used in two places: #### In your .app file Inside your `.app` file for `appearanceAppearanceDefinition.name`:
This lets you to select a different appearance based on body gender, camera state... (see the tables above). By using conditional appearances, you can still make use of `partsOverrides` to use [chunkmask hiding](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/3d-objects-.mesh-files/submeshes-materials-and-chunks). {% hint style="info" %} For a hands-on example, see [archivexl-dynamic-conversion-guide](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl/archivexl-dynamic-conversion-guide "mention") -> [#step-2-the-.app](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl-dynamic-conversion-guide#step-2-the-.app "mention") {% endhint %} #### In your mesh\_entity.ent file {% hint style="info" %} It is generally considered better practice to use gendered appearances, as the components for the inactive gender will still be added to the player entity. {% endhint %} Inside your `mesh_entity.ent` for `component.name`:
{% hint style="info" %} For a hands-on example, see [archivexl-dynamic-conversion-guide](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl/archivexl-dynamic-conversion-guide "mention") -> [#method-1-conditional-components](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl-dynamic-conversion-guide#method-1-conditional-components "mention") {% endhint %} ## Substitutions Substitutions are a feature of **dynamic appearances** . They can only be used inside your `mesh_entity.ent`. Substitutions allow ArchiveXL to **load a different mesh** based on different circumstances.
{% hint style="info" %} For a hands-on example, see [archivexl-dynamic-conversion-guide](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl/archivexl-dynamic-conversion-guide "mention") -> [#method-2-component-substitution](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl-dynamic-conversion-guide#method-2-component-substitution "mention") {% endhint %} ## Which suffixes exist? {% hint style="warning" %} Do yourself a favour and don't use suffixes! They are outdated - use [dynamic item additions](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl/..#dynamic-appearances) instead. {% endhint %} For a list of active suffixes, check the tables above.
SuffixExplanation
itemsFactoryAppearanceSuffix.GenderThis item is gendered
When resolving the appearance name via rootentity.ent, the game will look for appearanceName&Female and appearanceName&Male.
itemsFactoryAppearanceSuffix.CameraThis item has special rules for first and third person camera
When resolving the appearance name via rootentity.ent, the game will look for appearanceName&FPP and appearanceName&TPP.
itemsFactoryAppearanceSuffix.PartialIf the current item has hide_T1part part and slot OuterChest is not hidden, will search rootentity.ent for&Full or &Part
itemsFactoryAppearanceSuffix.HairTypeDefines how your item will look if a certain hair type is loaded (e.g., hide the back half of a bandana for long hair).
When resolving the appearance name via rootentity.ent, the game will look for &Short, &Long, &Dreads, &Buzz, &Bald
### Disabling Suffixes You can disable suffixes by adding the following line to your .yaml entry: ```yaml appearanceSuffixes: [] ``` ### Suffix load order 1. the base appearance (with no suffix) 2. the most specific suffix collection it can find #### Example: V has a female body gender and you're in photo mode (third person camera). Your base appearance is called `appearance_`. | full appearance name | | | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | `appearance_` | Found first, then ignored because a more specific appearance exists. | |

appearance\_\&Male
appearance\_\&Male\&FPP
appearance\_\&Male\&TPP

| Ignored: V's body gender isn't male | | `appearance_&Female` | ignored: a better match exists | | `appearance_&Female&FPP` | ignored: you are not in first person camera | | `appearance_&Female&TPP` | best match! The game will use this one! | ## Which substitutions exist? Since 1.8.0, ArchiveXL supports substitutions for [#dynamic-appearances](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl/..#dynamic-appearances "mention"). You can use them in two places: * inside `mesh entity` components in the fields `name`, `depotPath` and `appearance` * in the `.app` appearances for the field `name` {% hint style="success" %} For a tutorial about this, check [archivexl-dynamic-variants](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/items-equipment/adding-new-items/archivexl-dynamic-variants "mention") If you are a mod user and want to dynamically recolour an item, check the [recolours-and-refits](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/items-equipment/recolours-and-refits "mention") guide -> sub-page Emissive -> [#switching-existing-colours](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/items-equipment/recolours-and-refits/r-and-r-emissive#switching-existing-colours "mention") {% endhint %} Any placeholders will be **interpolated** at run-time (replaced with the correct value for your current state)! If any of the placeholders aren't working the way you expect them, check if the table below is outdated by referring [directly to the source](https://github.com/psiberx/cp2077-archive-xl/blob/027aab7139689ee8d14163682ab6d506fbccea2a/src/App/Extensions/GarmentOverride/Dynamic.cpp#L29). (Please update the wiki if that happens!) {% hint style="info" %} Substitution will only become active if the property name starts with an asterisk (`*`). {% endhint %} | Placeholder | Substitution | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `{camera}` | `fpp` or `tpp` | | `{gender}` | `m` or `w` | | `{body}` | `base_body` or body mod name in snake case | | `{arms}` | `base_arms`, `mantis_blades`, `monowire`, `projectile_launcher` | | `{feet}` | `flat`, `lifted`, `high_heels`, `flat_shoes` (empty for mascV!) | | `{sleeves}` | `full`, `part` | | `{skin_color}` | [skin color name](https://wiki.redmodding.org/cyberpunk-2077-modding/references-lists-and-overviews/cheat-sheet-head#skin-tones-by-index) from customization, e.g. `03_senna` | | `{hair_color}` | [hair color name](https://wiki.redmodding.org/cyberpunk-2077-modding/references-lists-and-overviews/cheat-sheet-head/hair#colour-in-files-by-index) from customization. e.g. `black_liquorice` | ### Substitution load order For [#dynamic-appearances](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/archivexl/..#dynamic-appearances "mention"), you can conditionally switch out components or entire appearances **by name**. You can switch use any of the entries from [#which-substitutions-exist](#which-substitutions-exist "mention") The order works as follows:
Appearance/ComponentPriorityDescription
my_item!variant&camera=tpp1Has the highest priority because it requires a specific variant and one state condition.
my_item!variant2Has second priority because it requires a specific variant.
my_item&gender=w&camera=tpp3Has third priority because it has two state conditions.
my_item&camera=tpp4Has fourth priority because it has one state condition.
my_item5Has the lowest priority and will be used when no other elements match the criteria.
--- # 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-suffixes-and-substitutions.md?ask= ``` 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.