CCXL: Creating a Switcher

Summary

This page will demonstrate the ability to create additional switchers in the Character Creator with ArchiveXL.

Why would I want to do that?

Creating new switchers allows us to add new options to the character creator without occupying existing switchers.

Examples include:

• Create switchable tattoo additions that can be toggled alongside the game's vanilla facial tattoos and body tattoos (Beginner)

• Control left and right eye color independently using overlay meshes (Intermediate)

• Give V switchable hairstyles for feet (Expert)

Requirements

• A WolvenKit project

• A .xl file referencing at least one .inkcharcustomization file

• All necessary meshes, materials, textures, and .app files for your addition

• A .json file for your translation entries, if applicable

What are switchers?

Switchers are the switches shown in the character creator that allow us to change V's physical appearance. There are two different types of visible switcher: those that cycle through text-labeled options such as hairstyles and tattoos—and those that use icons generally depicting color options. Switchers are defined within separate .inkcharcustomization files for each gender.

Types of switcher

Type 1: Cyclic switchers

There are two types of cyclic switcher—one consists of a gameuiSwitcherInfo that defines index and options and two or more gameuiAppearanceInfo's that contain the corresponding option parameters (the first one usually being the off appearance):

gameuiSwitcherInfo

The other type of cyclic switcher consists of a gameuiMorphInfo with morph names as its options. The chest size switcher for Female body V is an example of this:

gameuiMorphInfo

Type 2: Icon switchers

The hair color switcher acts as a cyclic switcher but has icons instead of names:

It can be expanded to show selectable icons.

The icon switcher does not require a gameuiSwitcherInfo but consists of a single gameuiAppearanceInfo, with its options defined as definitions—appearance definitions within a .app file:

Nested switchers

A switcher can have other switchers as options. These are known as a nested switchers:

The uiSlot and uiSlots parameters are what make this possible—each switcher or option can occupy one uiSlot, and every uiSlot can have only one active option:

This means that every hairstyle has its own hair color switcher. Since each hair color switcher occupies uiSlot 'hair_color' only one hair color switcher can be active at any time.

Switcher attributes

A switcher has multiple attributes that make them behave in a certain way:

Putting it all together

Knowing how a switcher works is important when it comes to creating new switchers with CCXL. Now that we are familiar with the inner workings of a switcher, we can get started.

Be sure you have a WolvenKit project with a file structure following this format:

Create a .xl file

In order to build a switcher, we need a .xl file so ArchiveXL knows where to find it.

You can create one in WolvenKit. See these steps to do so:

This will create an empty .xl file that ArchiveXL uses to locate our custom switcher. It can be modified in a text editor like Notepad++. We'll do that once we add our other files but for now, be sure to stick the .xl in the resources folder of your project:

Create the .inkcharcustomization files

Follow the same steps as last time for the .inkcharcustomization file, but—

• Create one for each gender if applicable (add _pwa and _pma respectively when naming)

• Put them in the mod folder of your project

Your project structure should look something like this:

Now that we have the base files for a switcher, let's go ahead and edit our .xl file.

Modifying the .xl

Open the .xl file in your preferred text editor, and you should have a blank document. Add the following:

customizations:
  male: your_modder_name\ccxl\your_mod_name\your_mod_pma.inkcharcustomization
  female: your_modder_name\ccxl\your_mod_name\your_mod_pwa.inkcharcustomization

Ensure these paths match the relative paths to your .inkcharcustomization files, and save.

If you want to use translation entries, be sure to add these in the .xl also. See the wiki about it for more info.

Modifying the .inkcharcustomization files

Now we can start building our switcher. The easiest way to do this is to start with one .inkcharcustomization file, then copy everything over once we know it works.

Open a .inkcharcustomization file to get started:

First we must determine which group our switcher belongs to. A good way to figure this out is knowing where the camera should focus in the character creator when using our switcher (arms, head, or body).

Create a cyclic switcher

Click on headCustomizationOptions (or whichever category you want to use) and then "Add New Element":

Then, click "gameuiSwitcherInfo" and Create:

You should now have an empty switcher:

Minimum Attributes:

At minimum, we should change the following attributes to have a working switcher:

• editTags (we have to be able to use this switcher somewhere!)

• localizedName (not required, but helps to identify our switcher in-game)

• name (will be used to identify our switcher in headGroups later on)

• options (must have at least 2 options; 'OFF' can be one)

• uiSlot (must occupy a slot)

• uiSlots (give our options slots to occupy)

You should reference the table above to learn more about each attribute.

With the minimum requirements met, your switcher should look something like this:

Now, let's define our switcher options:

For our options, they should be indexed to determine their order in the switcher. The names will reference those of our gameuiAppearanceInfo's, while the localizedNames will display as our option names in-game.

Now we need a gameuiAppearanceInfo for each option in our switcher. Follow the same steps you used to create your gameuiSwitcherInfo, but select "gameuiAppearanceInfo" and create, then duplicate it:

Based on the options in our gameuiSwitcherInfo, our first gameuiAppearanceInfo should look like this:

Our second should look like this:

The only thing changing right now is our name, to match the ones referenced in our gameuiSwitcherInfo options.

We can add our resource (path to a .app file) and definitions (appearance definitions in said .app file) now, or come back to it later.

Right now, we still need to add our switcher and appearances to our groups.

Groups

For most appearance additions, the following groups will suffice:

headGroups

If your switcher is in headCustomizationOptions, you'll want to use these four headGroups:

• FPP

• TPP

• TPP_photomode

• character_customization

bodyGroups

If your switcher is in bodyCustomizationOptions, you'll want to use these three bodyGroups:

• FPP_Body

• TPP_Body

• character_creation (not to be confused with 'character_customization' in headGroups)

Adding your switcher and appearances to headGroups should look like this:

Once this is done, you can save your .inkcharcustomization file (Ctrl + S) and install this mod to test your switcher. If done correctly, you should have a new switcher at the top of the character creator, with two options:

Of course, if you didn't add any path to resource or include any definitions in your gameuiAppearanceInfo, then this switcher won't do much.

Attaching an appearance

I've borrowed some files to use in this demonstration, in order to give our switcher a purpose:

For a detailed explanation on how these will work together, see CCXL: Body Tattoos.

Going back to our gameuiAppearanceInfo, let's add our .app file to the resource path:

We'll need to add an appearance definition to the definitions slot, but we need to know what they are. Those will be found in our .app file:

You'll want to add the one for whichever gender you are working on to the definitions of your gameuiAppearanceInfo:

Once this is done, we can save with Ctrl + S, install our mod again, and launch. If your resource and definitions were done correctly, you should now have a fully-functional switcher:

Referencing the table above, now is a good time to make any additional customizations to your switcher (index, localizedName, add additional options, etc.)

Once that's done, you can copy everything over to the other .inkcharcustomization file. Be sure to change the definitions of the gameuiAppearanceInfo to correspond with the correct gender when doing so.