.ent files: Suffixes

Suffixes: what they are (and whether you need them)

Summary

This page explains how to

If you already know the theory and just want to pick the right combination, check "which suffixes exist" below.

What are suffixes?

In a root_entity file, you can give the game a list of appearances and have them mapped to an .app file by entry name. While that's pretty good already, have you ever wanted to be more specific — for example, "for a male character, use this appearance, but for a female use this other one?"

This is where suffixes come in. You append them to an appearance's name in the root_entity, and the game will pick the correct appearance (and the correct app file, and the correct mesh!) based on the best match.

If you are registering an item via ArchiveXL, you can define suffixes via appearanceSuffixes: [ … ] in the .yaml file.

Your item will inherit the suffix setup from the $base component. In the example of Items.GenericHeadClothing, that will be

appearanceSuffixes: [ 
  itemsFactoryAppearanceSuffix.Gender, 
  itemsFactoryAppearanceSuffix.Camera ]  

What can possibly go wrong?

These bad beans can be the reason why your item is invisible!! You can and should disable the suffixes if you don't need them.

To do so, add an empty array to the yaml entry:

appearanceSuffixes: []

Which suffixes exist?

For a full list, see For a more in-depth list, check (TODO: Psi's github?)

For clothing items, the following suffixes are relevant:

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

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!