Entity: .ent files

All the dirty detes on entity files

Definition

Serves as the top-level container for entities and their properties within the game. Most things that you can see, touch, or interact with have an .ent file somewhere in their hierarchy. Examples are player equipment, weapons, NPCs, interactables (doors, vending machines…)

For the purpose of modding, we distinguish between two different kinds of entity files.

To see a minimal example in action, see the guide for creating custom props.

Mesh/Component entity (simple entity)

The minimal way of adding something (e.g. meshes) to the game. This entity can be directly spawned (e.g. via AMM) or referenced from within Appearance: .app files.

This entity adds four physical mesh components, which will appear when it is spawned. It does not reference an .app file and does not have appearances.

For player equipment (weapons and armour), you can use mesh entities to encapsulate parts of your item. You load such .ent files via partsValues, which will be added to the corresponding appearance as if the components had been in the .app file itself.

As of April 2023, partsValues will be ignored for anything but player equipment.

This is good practice to avoid repetition, and also to make it easy on yourself if you want to change paths later in your project (imagine having defined 20 appearances with 5 components each, and then wanting to rename your mesh folder…)

Root entity

The entry point for the game to display an NPC or prop. This kind of entity only defines those components that are shared among all appearances. Meshes are defined in the app file, where they can be assigned different properties (e.g. materials) per appearance.

From ArchiveXL item additions, this kind of file is usually called a root entity.

• An entity file can define multiple appearances, which can point to different .app files.

• For creating props, root entities are used as the defining key (one entity => one item, which can have multiple appearances)

• Names support suffixes, allowing you to load different appearances based on body gender or camera mode. These are only used for player equipment and look like &FPP

• How you split your .app files is largely a matter of taste. At CDPR, they usually shove everything into one file.

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.

Find step-by-step walkthrough on using suffixes in the ArchiveXL item addition guide.

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!