ItemAdditions: Dynamic Appearances
An item addition with dynamic appearances, and what you can do for this
PreviousItemAdditions: File structure explainedNextDynamic Appearances: fine-tuning visibility conditions
Last updated
An item addition with dynamic appearances, and what you can do for this
Last updated
Published: 29 Oct. 2023 by Last documented update: Jul 05 2024 by
This guide will cover a sub-case of Adding new itemsvia ArchiveXL (added in 1.13). Dynamic variants are both easier and more flexible. Unless you don't need different appearances, you will want to default to this approach.
If you are an absolute beginner who has never done this before, check out Adding new items. The guide will tell you when to switch over.
You can find the technical documentation for dynamic variants on ArchiveXL's github.
If you want to create an Atelier store, see Your own Atelier Store
To quickly generate instances with up to two keys, check out W's generator (Codepen.IO)
You need at least the following tools and versions (get the most recent):
WolvenKit >= 8.11.0 (you should have it )
TweakXL >= 1.4.4
ArchiveXL >= 1.5.0
Red4ext >= 1.17.0
Cyber Engine Tweaks (for spawning items)
You define an appearance as dynamic by adding the DynamicAppearance tag to the visual tags in its root entity.
If you don't know what that means yet, read on — it will hopefully become clear soon.
TL;DR: It just is, source: trust me bro. Proceed to the next section.
With vanilla item additions, you need one entry in the root entity per suffix. This gets out of hand quickly. When making stockings, there are four feet states (flat, flat_shoes, lifted and high_heels), and two body genders (Male and Female) . That leads to 4x2 entries for a single item.
For 15 appearances (colour variants) per mesh, I (manavortex) ended up with
120 entries in the root entity (4*15 per body gender)
120 entries in the .app file, (4*15 per body gender)
six mesh_entity files (flat, lifted, and heels for each body gender. I used the same for flat and flat_shoes, or I'd have ended up with eight.)
The most frustrating part was that everything was just duplication. Each set of entries in the .app file would only differ by name (_pwa and _pma to select it from the root entity), and the mesh entity path in partValues. Everything else was virtually identical, but I had to copy-paste and maintain 120 entries.
I cried to psiberx, who went and made the problem go away.
Dynamic variants put the logic into the mesh entity file. Instead of defining appearances with suffixes, I can conditionally define which component gets loaded, and ArchiveXL does the rest.
number of root_entity entries
120
1
number of .app entries
120
1
number of mesh entity files
6
1
number of components per mesh entity
2
5
If you still aren't convinced, go to Adding new items and start duplicating entries. Everyone else, to the batmobile!
This guide contains the minimal amount of fluff and will link background information rather than giving it. Any links will tell you what you're supposed to read.
For that reason, you shouldn't skip or skim unless the section tells you that it's optional.
That being said, make sure to check the section
This guide assumes that you have access to the prepared example project, so go and grab it.
Find the template project on Nexus.
Download it and extract the files to your project's root folder, so that the source directory merges with the existing one.
You will be able to change the template project just by following the steps, but if you want to make your own mods, then you're going to want to understand this.
Depending on how you learn best, you can also fuck around and try to understand the connections yourself. In that case, check Exercise 1: Create more records at the end of the section.
This file contains the biggest part of the dynamic magic.
This is your dynamic project's yaml file, minus any properties that aren't influenced by the dynamic appearances:
This section will explain how that works - except for the appearanceName, you will find that in The root_entity.
TweakXL will generate one record per entry in $instances, according to the rules that you're using in the item name. This happens via property interpolation.
The example above will generate three item entries by substituting $(property_name) with the value of the property from the entry. If that isn't clear enough, check the example and the resulting item codes at the end of the line.
Like the record names, the displayName property is also generated for each entry:
All you need to do is to make sure that such an entry exists in your localization file.
The icon name in the record is also generated for each entry. They are all using the same inkatlas, but you can generate that as well if you want - I've done it for the Netrunner suits, since I needed more than 100 icons.
The only important thing here is that the naming follows your inkatlas file's slot definitions.
With clever hook-ups in the mesh entity, you can set up your items so that they can be changed with a simple .yaml edit — that means, the user can switch out the ribbon colour without ever starting Wolvenkit!
We'll use that here to enable "hidden" appearances.
I have hooked up the example project to support two base colours:
black
white
and three ribbon colors:
red
blue
green
By editing the $instances block in the .yaml, you should be able to spawn 6 different shirt in the game without touching any of the additional files!
This is where you enable the feature by adding the tag DynamicAppearance to the visualTagsSchema (the last entry in the file):
For dynamic appearances, your root_entity file will contain one entry. Each item should have its own root entity.
The appearance name in the root entity corresponds to the appearanceName property in the .yaml without the variant:
You can leave the appearanceName blank. In that case, ArchiveXL will look for an appearance with the same name as the name attribute.
Since the appearance in the .app is called app_file_dynamic_appearance for clarity, and there is no root_entity_dynamic_appearance_ in the .app, this will not work for the example project.
For dynamic variants, components in the .app file will be ignored. You have to use a mesh entity.
In the context of our example project, this means that you can define your appearances like this:
app_file_dynamic_appearance
Your regular appearance. Is displayed when none of the conditional ones apply.
app_file_dynamic_appearance&camera=tpp
This is only active in third person perspective. The item will be completely invisible in first person.
app_file_dynamic_appearance&camera=fpp
app_file_dynamic_appearance&gender=male
Unless you are using .app file: Conditional switching, this is where the magic happens.
Like appearance definition names, components in the mesh entity support .ent file: conditional switching. On top of that, they also support Substitutions.
Check The diagram's bottom left corner for a demonstration of both, or read up the ArchiveXL documentation on how they work.
In your mesh entity, you can use substitutions in path names to load different meshes. This is better than .ent file: conditional switching because it won't create extra components.
To enable substitution, your depot path must begin with an asterisk *. Each substitution needs to be enclosed in braces, e.g. {gender}.
ArchiveXL will create all components, hiding those that aren't matched by your current conditions. If possible, use Substitutions instead.
Just like in the .app file, you can apply conditional switching to component names. It works exactly like .app file: Conditional switching:
Now let's look at what we just did and check the diagram. You'll see that the control files are almost identical to the vanilla variants, but that the rest of the files has gotten a lot more manageable:
And that's it! With this and the original guide, you should hopefully be able to add items to your heart's content!
I have written a Python script to auto-generate display names, you can find it on my github. If you don't know how to use this, check Running Python Scripts.
Create a
For a general explanation of what the yaml file does, check . This section will only cover the differences between a dynamic and a regular yaml.
If you your project, you can immediately spawn them in Cyberpunk via Cyber Engine Tweaks:
If you want to make gendered icons, please check Gendered preview icons ->
For a general explanation of the root entity, check . This section will only cover the differences between a dynamic and a regular root entity.
For a general explanation of the .app file, check . This section will only cover the differences between a dynamic and a regular .app file.
You can define appearances for different circumstances by changing the appearance names. This will let you influence the mesh entity even further by e.g. hiding parts of the mesh via . And the best part is: you don't even need to touch your root entity.
This becomes active whenever you are in first person perspective. You'll usually want this to via .
You shouldn't do this — instead, use in the mesh file path.
For a general explanation of the mesh entity, check . This section will only cover the differences between a dynamic and a regular mesh entity.
For a list, check
can help you spot errors in your paths.
Please see the original guide's section.
DynamicAppearance, without S.
