CCXL Theory: Switchers

Summary

Published: September 3rd 2025 by icxrus Last documented edit: September 3rd 2025 by icxrus

This page explains how switchers work with the character creator and ArchiveXL. It is currently a work in progress.

Originally separated from CCXL: Creating a Switcher.

Wait, this is not what I want!

To create your own switcher, check CCXL: Creating a Switcher .

For existing vanilla and modded switchers, check ArchiveXL: Character Creator additions .

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 generally defined within separate .inkcharcustomization files for each gender.

Types of switchers

Type 1: Cyclic switchers

The hairstyle switcher contains text-labeled options. It requires cycling through options

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

'Options' within the gameuiSwitcherInfo create the options for the switcher, with names pointing to gameuiAppearanceInfo's

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

The chest size switcher has three options, defined by the morph names.

The second option has no morphName, and is the 'Default' option.

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:

Vanilla eye color switcher consists of gameuiAppearanceInfo with 71 appearance definitions as selectable options. It does NOT have a default 'OFF' option.

Each appearance definition references a definition within the .app file attached as a resource in the gameuiAppearanceInfo

Nested switchers

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

The hairstyle switcher controls multiple hair_color switchers which also function as appearance options

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:

The hairstyle switcher occupies a uiSlot and controls multiple uiSlots

This hairstyle occupies the hair_color uiSlot

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:

Attribute	Found in	Function	Value type
censorFlag	gameuiSwitcherInfo gameuiAppearanceInfo gameuiMorphInfo	Listens for active censor, like nudity
censorFlagAction	gameuiSwitcherInfo gameuiAppearanceInfo gameuiMorphInfo	Activate/Deactivate switchers based on censorFlag
defaultIndex	gameuiSwitcherInfo gameuiAppearanceInfo gameuiMorphInfo	Index of default switcherOption / morphName / appDefinition	int
editTags	gameuiSwitcherInfo gameuiAppearanceInfo gameuiMorphInfo	Dictates where a switcher can be used in-game	NewGame, HairDresser, Ripperdoc
enabled	gameuiSwitcherInfo gameuiAppearanceInfo gameuiMorphInfo	Determines whether switcher is active or inactive by default	bool
hidden	gameuiSwitcherInfo gameuiAppearanceInfo gameuiMorphInfo	Hides switcher in character creator	bool
index	gameuiSwitcherInfo gameuiAppearanceInfo gameuiMorphInfo	Determines order of switchers in Character Creator	int
link	gameuiSwitcherInfo gameuiAppearanceInfo gameuiMorphInfo	Allows a switcher to control the state of other switchers	string
linkController	gameuiSwitcherInfo gameuiAppearanceInfo gameuiMorphInfo	The switcher will control other switchers with the same link value	bool
localizedName	gameuiSwitcherInfo gameuiAppearanceInfo gameuiMorphInfo	The name, usually a translation entry, that will be shown in-game	string
name	gameuiSwitcherInfo gameuiAppearanceInfo gameuiMorphInfo	The name of a switcher or appearance, referenced by switcher options	string
onDeactivateOptions	gameuiSwitcherInfo gameuiAppearanceInfo gameuiMorphInfo	Activate/Deactivate other switchers/options when switcher is deactivated
options	gameuiSwitcherInfo	Creates options for the switcher, referencing names of appearance infos	string
definitions	gameuiAppearanceInfo	Appearance definition to be referenced in .app file	string
morphNames	gameuiMorphInfo	Defines the available morphtargets, match these to the values in your .morphtarget	cName
resource	gameuiAppearanceInfo	Path to .app file	path
randomizeCategory	gameuiSwitcherInfo gameuiAppearanceInfo gameuiMorphInfo	The category of a switcher in the randomizer
switchVisibility	gameuiSwitcherInfo	(More info needed)	bool
uiSlot	gameuiSwitcherInfo gameuiAppearanceInfo gameuiMorphInfo	The slot which a switcher or option will occupy. Allows only one active option at a time	string
uiSlots	gameuiSwitcherInfo	The slot(s) a switcher's options will occupy	string

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)

armGroups

If your switcher is in armsCustomizationOptions, you'll want to use these armGroups:

Female V:

• holstered_default_tpp

• holstered_default_fpp

• holstered_strong_tpp

• holstered_strong_fpp

• unholstered_strong

• holstered_nanowire_tpp

• holstered_nanowire_fpp

• unholstered_nanowire

• holstered_launcher_tpp

• holstered_launcher_fpp

• unholstered_launcher

• holstered_mantis_tpp

• holstered_mantis_fpp

• unholstered_mantis

• nails

• character_customization

Male V:

• holstered_default

• holstered_strong

• unholstered_strong

• holstered_nanowire

• unholstered_nanowire

• holstered_launcher

• unholstered_launcher

• holstered_mantis

• unholstered_mantis

• nails

• character_customization

Each of these holstered and unholstered definitions links to a certain arm cyberware, or none, being equipped by the player. Many of these also have different positioning to each other.