ArchiveXL: Suffixes and Substitutions

How suffixes and substitutions work

Summary

Published: ??? by manavortex Last documented update: Feb 18 2024 by manavortex

This page will teach you about conditional appearance switching in Cyberpunk and give you an overview of existing suffixes and substitutions.

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.

Wait, that's not what I want!

• For a hands-on guide to Adding new items, check the corresponding pages under Modding Guides.

• Dynamic appearances have their own guide (see ItemAdditions: Dynamic Appearances)

• There is an own page for Influencing other items

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…).

Since 1.5, psiberx has made it possible to use conditionals via dynamic appearances, 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.

Conditional hiding

To conditionally hide items or parts of items, check Influencing other items or ArchiveXL: Tags (especially the section about Root entity tags)

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, which can then be used for suffixes and for substitutions in dynamic variants. To learn more about this, check ArchiveXL: body mods and refits.

You can check the current foot state by running the following command from CET:

print(Game.GetScriptableSystemsContainer():Get("PuppetStateSystem"):GetBodyTypeSuffix(ItemID.new(), GetPlayer(), nil))

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 mode	FPP	substitution
First Person Perspective	&FPP	fpp
Third Person Perspective	&TPP	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
None	&BaseArms	base_arms
Mantis Blades	&MantisBlades	mantis_blades
Monowire	&Monowire	monowire
Projectile Launcher	&ProjectileLauncher	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.

You can check the current foot state by running the following command from CET:

print(Game.GetScriptableSystemsContainer():Get("PuppetStateSystem"):GetArmsStateSuffix(ItemID.new(), GetPlayer(), nil))

Foot states

To achieve gender equality in regard to foot states, you need to use Toggleable Feet. The substitution key for dynamic appearances is feet.

Character	Footwear	Suffix/Tag	Substitution: feet=
Female	Unequipped	&Flat	flat
Female	Equipped (default)	&Lifted	lifted
Female	Equipped with HighHeels tag	&HighHeels	high_heels
Female	Equipped with FlatShoes tag	&FlatShoes	flat_shoes
Male	Any	(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.

You can check the current foot state by running the following command from CET:

print(Game.GetScriptableSystemsContainer():Get("PuppetStateSystem"):GetFeetStateSuffix(ItemID.new(), GetPlayer(), nil))

Which suffixes exist?

For ArchiveXL dynamic item additions, you don't need to bother with suffixes at all – they will have

Suffix	Explanation
itemsFactoryAppearanceSuffix.Gender	This item is gendered When resolving the appearance name via rootentity.ent, the game will look for appearanceName&Female and appearanceName&Male.
itemsFactoryAppearanceSuffix.Camera	This 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.Partial	If the current item has hide_T1part part and slot OuterChest is not hidden, will search rootentity.ent for&Full or &Part
itemsFactoryAppearanceSuffix.HairType	Defines 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:

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. 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

For a tutorial about this, check ItemAdditions: Dynamic Appearances

If you are a mod user and want to dynamically recolour an item, check the Recolours and Refits guide -> sub-page Emissive -> Switching existing colours

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. (Please update the wiki if that happens!)

Substitution will only become active if the property name starts with an asterisk (*).

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 from customization, e.g. 03_senna
{hair_color}	hair color name from customization. e.g. black_liquorice

Substitution load order

For Dynamic appearances, you can conditionally switch out components or entire appearances by name. You can switch use any of the entries from Which substitutions exist?

The order works as follows:

Appearance/Component	Priority	Description
my_item!variant&camera=tpp	1	Has the highest priority because it requires a specific variant and one state condition.
my_item!variant	2	Has second priority because it requires a specific variant.
my_item&gender=w&camera=tpp	3	Has third priority because it has two state conditions.
my_item&camera=tpp	4	Has fourth priority because it has one state condition.
my_item	5	Has the lowest priority and will be used when no other elements match the criteria.