This Page is Under Construction.

We’re currently working on it. May be inconsistent or outdated.

If you have questions about the code/blueprints that aren’t clear from this page, feel free to email the programmer Elizeon at software@elizeon.com

This guide is for a more in-depth exploration of the blueprints and C++ code in the character creator, for advanced users that want to learn how the system works and modify it.

Common Questions when Developing Changes

Can you summarise how the In-Editor char creator works?

BP_XandraCharacterCustom is the main blueprint for a customisable character with the system. With this blueprint, the custom appearance is set by setting the ‘Appearance’ field to one of the premade characters you have customised.

When a new character appearance is created in the Lvl_CharacterCreator_InEditor scene, the new character appearance will become available in the ‘Appearance’ drop-down field (enum selector) on the BP_XandraCharacterCustom blueprint.

To create your own Actor which uses this custom appearance, create an actor that inherits from BP_XandraCharacterCustom then choose a value in the Appearance field.

Behind the scenes, the character information has been saved as a text file (.xchar), and the C++ code has added a value to the enum E_CharsEnum which refers to that file.

If you make further changes to the appearance in the character creator, you will need to re-compile any blueprints using that appearance for them to be updated.

Can you explain the flow of code the In-Editor char creator?

· First, the appearance is loaded in ConstructionScript of BP_XANDRACharacterCustom after any default values are initialised. It reads the config from the .txt file (FillConfigFromFile) then loads the char from that config (LoadCharFromConfig).

· In LoadCharFromConfig it first sets the body appearance (Male, Female) because this deletes and replaces the XANDRA character child class. Then, it goes through the rest of the fields reading them from config and applying them to the XANDRA character. Finally, it calls CustomisationSetup which refreshes the appearance of the XANDRA character. If the body mesh has changed, then CustomisationSetup will re-apply all field changes from the config to the new mesh.

How does character get loaded as an actor in editor time? For example how does it load the appearance in the editor when a character is placed in a scene?

The construction script is actually run in editor time, and this is utilised in CustomisableCharacter to initialise the character’s appearance from the selected enum in this event.

There’s also an EditorTick event implemented in CustomisableCharacter that could be used for future editor-time character functionality but is not used yet.

How are default values (e.g. skin color, hair texture) set?

See InitDefaultCharValues

Why do you have a dynamically changing Enum for the list of characters? How does that work?

We dynamically create an enum so that you can select a dynamically created character (referencing a text config file on disk) in a user-friendly drop down in a blueprint.

Also, this means that the enum is accessible to a Packaged game which does not have access to Editor files.

We edit CharEnum enum uasset at runtime and at editor-time (On Construct). Because of this, some things to be aware of:

· You can NOT use a FOR EACH on Char Enum. When it compiles the values in the enum are fixed. If we change the enum after compile time (which we do allow by the character creator), the for each can cause intermittent crashes.

· If you see an issue where you are having trouble changing an enum or other in-editor/ in BP_CustomisableCharacter blueprint Construct at editor-time stuff that’s hard to debug, try putting a breakpoint in functions like GetFileNameFromEnumToString that are used in Construct, and then launch the editor through the debugger. You may be able to find what’s going on.

· There is a known issue where character appearance saves must not have spaces in them or they cannot be selected in blueprints, I believe it’s to do with the enum/character file system.

Adding a New Customisable Field

1. Add Enum: Generate and open the .sln file to edit C++ code and add a value in E_FieldNames (CharCreatorEnums.h). The Display Name should not be changed once set because it’s the field name used to read and write the field. Compile the changes.

2. Add ‘set’ and ‘get’ methods for the new field:

• Update ISet<type> method based on the field type (e.g. ISetMesh, ISetFloat) in BP_Character_Custom (under Interfaces methods) so that the config value can be loaded from a string to the character in LoadCharFromConfig.
  • Make sure not to add these get and set methods to BP_XANDRACustomCharacter or it will override the parent BP_Character_Custom methods and break the system.
• Update IGet<type> method in BP_Character_Custom so that the character appearance value can be exported to a string in config with WriteCharToConfig.
  • Note that these Set and Get methods reference the enum as a string, so that the BP Character Custom does not have to depend the character creator C++ code (for example in standalone Xandra characters)

5. Follow these final steps depending on the type of field being added

Slider (Float)

A. Add the slider to CharCreatorWidget_Common (There is a separate child blueprint for each menu – e.g. WBP_CCMenu_Face – you’ll need to edit the one where you want to add the slider).

Mesh or Enum Picker

C. Add a GenericPicker (custom type) to the UI.

D. Add GetMeshes or GetEnumPickerValues (depending on type) for the new picker field in Constants

E. Open NotifyOfAppearanceChange interface method in CharCreatorWidget_Common and ensure it updates the character from changes to your picker

F. In InitialiseGenericPickers, add your new picker to the GenericPickerList which will fill in the Names for the new picker.

Color

G. Create an instance of ColorPicker widget inside CharCreatorWidget_Common

H. In CharCreatorWidget_Common UpdateColors set the color based on the new ColorPicker’s value

Add Character Creator Menu (e.g. Face, Body…)

1. Add to Menu enum

2. Add method like ShowFaceMenu in CharCreatorWidget_Common

3. Call your new method On Click for the menu switching button

4. Select the menu item and click Bind next to Behaviour – Visibility and create binding.

5. In the binding, return visible if the variable set in showFaceMenu is true, otherwise return hidden. (See the other menus for reference)

Where is the Animator set?

BP Character Custom implements the ‘Set Body Type’ method from the BPI Character Custom interface.

Open BP Character Custom and open the Set Body Type method, and you will see how the male and female animators are set.

Adding the Character Creator UI to your own game

If you place the BP_UISpawner_InEditor (for ‘editor’ .xchar file characters) or BP_UISpawner_InGame (for ‘in-game’ save file characters) blueprint into a scene, it will spawn the character creator including the cameras at the location where you have placed that blueprint. The CameraManager is a variable in WBP_UI_Common if you need to change the camera’s location directly during runtime.

Understanding UI Blueprints

You may want to make some visual changes to the character creator UI to match your own game.

Main UI Blueprints

The main blueprints controlling the UI are

BP UI Common (Shared between the Editor and In Game UI)

• Contains the main windows – body, face, etc, their layout and the code to initialise them.

BP UI In Game (In Game only)

• Contains button to start the game
• Links to the code that saves and load character from a save game – not an .xchar file

BP UI Editor (Editor only)

• Contains Exit and Tutorial
• Contains Save and Load character .xchar files

Other UI blueprints:

• WBP_FloatSlider: Displays a slider that controls a float value such as Eye Height. Change Field to the CCFloatField you want this slider to edit. The values for CCFloatField are defined in C++ code. There are blueprint Interface methods on Xandra’s main blueprint ‘BP Character Custom’ called Get Float and Set Float which get these blend shapes directly from the model. WBP FloatSliderWithText is a variant that includes a title.
• WBP_WardrobeItemButton: Displays text buttons that can be clicked to select a wardrobe item, e.g. for clothing items.
• WBP_WardrobeItemButton Image: Displays image buttons that can be clicked to select a wardrobe item, in particular for hairstyles and faces.
• WBP GenericItemPicker: Under the hood this is the element controlling ‘on change’ events for every wardrobe item.
• WBP Texture Option Slider: A slider that slides between a number of texture options. Used for makeup, eyebrows, etc.
• WBP 2D Color Picker: The window used for picking a color. WBP ColorPicker is the button you click that displays the current color and opens the 2D color picker.

Understanding Main Character Save/Load/Config Functionality in Blueprints and C++

BP Character Custom (Visuals): Xandra’s base customisable character.

BP_XANDRACustomChar (Communicates between Visuals and Config/Save data): The main Actor class for an actor using an appearance created in the character creator. This class talks to the BP Character Custom (through the interface BPI Char Creator Fields) which lets it set and get all the visual changes to a Xandra character. It also contains an ACXandraCustomiser to help it access field values from the code. By controlling both the config with the character visuals it is the main class which manages the general appearance and config of a custom character.

• BP Xandra Custom Char contains some utility method for setting fields and reloading the character. These are used by the keyboard shortcuts in the in-game demo to change outfits in-game. For example, Set Mesh Field And Reload Character.
• BP Xandra Custom Char contains some utility method for setting fields and saving those changes to config, which are used by the character creator UI.
• BP Xandra Custom Char contains methods to interpret some of the current field values based on how the character visually looks. For example, GetFieldMeshFromCharDirectAppearance. This is used by the UI.
• BP Xandra Custom Char contains some methods to access current field values saved in the config as their understood types (for example as a float or enum even if they are saved as a simple string). For example, GetConfigFloat to get a float value like Eye height. Or Get Field Body Type to get the body type.

ACXandraCustomiser (Config/Save data): This is an ‘Actor Component’. It inherits from the C++ class ‘CPP Custom Char Actor Comp’. The purpose of this class is to let BP Xandra Custom Char talk to the C++ code which manages loading and saving character config, and read the string config values for the character. BP Xandra Character Custom contains an ACXandraCustomiser.

• AC Xandra Customiser contains low level methods to set current field values saved in the config. This is used by the BP XANDRA Custom Char and generally shouldn’t need to be used directly.

Saving and Loading characters

If you plan on making changes to the way characters are saved or loaded be aware there’s a significant difference between the in-editor (the main system) and in-game character creator (example demo).

In the underlying system a save is understood as a map of field names to values, saved as strings.

This map is saved in ‘CustomCharConfig’ of CPP_CustomCharActorComp (c++ class)

For example Torso: T-shirt 1

In-Editor Character Creator (Main System)

• Saves characters to text files (named .xchar files) which are made up of a list of field:value pairs
• Wardrobe items and meshes are referenced by ID in these field:value pairs.
• For example the file may contain hairstyle:bob01, eyeheight:0.7
• An enum dynamically created by the code lets you select these .xchar configs as the Appearance in blueprints.

In-Game Character Creator (In-Game Example)

• Saves the player character to Unreal’s ‘Save Game’ format in the BP_DemoSaveGame blueprint
• Inside the BP_DemoSaveGame blueprint, the CharacterAppearanceConfig variable stores a map of string field: values in the same underlying format used to save to the .xchar files in the main system.