Character Creation Framework

From Multiverse

User Interface Development

Overview  •  Managing Widgets  •  Event Handling  •  Using Widget Templates  •  Customizing Key Bindings  •  Localizing UI Text  •  Character Creation Framework  •  Minimap Component  •  Scripting Avatar Appearance

Reference

Widgets  •  Property Elements  •  Imageset Files

Tutorials

Hello World  •  Creating a Button  •  Creating a Menu  •  Creating a Help Dialog  •  Using Radio Buttons

Contents 1 Overview 1.1 Implementing character creation 2 User interface and 3D assets 2.1 User interface files 2.2 Imageset and image files 2.3 3D asset files 3 Client scripts 3.1 Model information 3.2 Customization 3.3 Character creation class 3.4 Character selection class 4 Server scripts

Overview

The character creation framework actually consists of two parts:

• Character creation, in which player creates a new character avatar
• Character selection, in which a player selects from a list of previously-created character avatars.

On initial login (with a new account ID), a player sees the character selection screen, for example as shown at right. Initially, the player must click on Create to create a new character, since he does not have an existing character to select. This action brings up the character creation screen, for example as shown in the screenshot below. In this screen, the player enters a name for the character, selects a gender, and selects a model.

NOTE: Sampleworld provides only one model of each gender, but the framework enables you to provide many.

On subsequent logins, a player sees the character selection screen displaying a list of all the characters they have previously created. Clicking on the name of an existing character displays that character.

Clicking the Create button displays the character creation screen again, where they can create a new character, up to the default limit of six characters. Clicking Quit exits the Client, and clicking Play logs in to the world with the selected character.

Implementing character creation

The best way to implement character creation/selection in your world is to start with the implementation in Sampleworld and modify it to suit your world. The files in the Sampleworld implementation are:

• User interface and 3D asset files in the asset repository Interface/FrameXML/, Interface/Imagesets/ and Imagefiles/ directories. See the User Interface section below for a full list of these files.
• A Client script file: Scripts/SampleCharacterCreation.py
• A server script file: mv-home/config/world/character_factory.py

To incorporate character creation/selection in your world, add these files to your asset repository and modify as desired.

NOTE: If you customized the character creation code in a previous release, you must merge your changes with the new character creation framework as illustrated in Sampleworld. See Upgrading to Version 1.0.

User interface and 3D assets

To use character creation/selection, all of the files listed below (or the equivalents for your world) must be in your asset repository. Often, a good starting point is to copy the files from the Sampleworld asset repository, and then modify them for your world.

User interface files

These files are all in the Interface/FrameXML/ directory of the asset repository:

• startup.toc is the UI theme file that lists the files required for the character creation and selection interface.
• startup_bindings.txt contains the key bindings to use for the initial character creation and selection interface. Typically, this will just be an empty file (with no key bindings), because you don't want any key bindings in the character creation/selection screens.
• MvCharCreation.xml sets up the layout of the character creation and selection interface. Change this to provide different options or a different look from the sample.
• MvCharCreation.py contains some basic logic for handling character creation and selection. There are also two variables, createContext and selectContext, that are instantiations of the custom classes for creation and selection. In Sampleworld, these are instances of SampleCharacterCreationContext and SampleCharacterSelectionContext. See Character creation class and Character selection class for more information.

Imageset and image files

Interface/Imagesets/MvCharCreation.xml is the XML file that defines the position of component images within the texture used for the sample character creation and selection interface graphics.

Imagefiles/MvCharCreation.tga is the texture that contains the graphics for the various buttons, frame borders, etc. that are used in the character creation and selection interface.

3D asset files

The SampleCharacterFactory requires a number of new media files for the initial scene:

For the gazebo in which the character stands:

• Meshes/creation_gazebo.mesh
• Materials/creation_gazebo.material
• Textures/BlankTexture512x512_normals.dds
• Textures/BlankTexture512x512_specular.dds
• Textures/creation_gazebo.dds
• Physics/creation_gazebo.physics

For the sky cylinder used as the backdrop:

• Meshes/creation_gazebo_skycyl.mesh
  
• Materials/creation_gazebo_skycyl.material
  
• Textures/creation_skycyl.dds
  
• Physics/creation_gazebo_skycyl.physics
  

Client scripts

When the Client starts, it runs Scripts/Startup.py. This file imports and runs the code in each each module (script file). Do not place world initialization code in Startup.py. Instead, put the code in an external file and import it, as illustrated for Sampleworld.

Scripts/SampleCharacterCreation.py is an example character creation and selection script. Rename this file and the classes it defines for your world, and make the corresponding change in Startup.py.

SampleCharacterCreation.py defines the 3D models available and two Python classes:

• SampleCharacterCreationContext for character creation.
• SampleCharacterSelectionContext for character selection.

Model information

Some initial code in SampleCharacterCreation.py defines the meshInfo dictionary that contains information on the 3D models available for avatars (characters). The following statement defines the base models:

meshInfo = { "human_female.mesh" : [[ "bodyShape-lib.0", "human_female.skin_material" ],
                                   [ "head_aShape-lib.0", "human_female.head_a_material" ],
                                   [ "hair_bShape-lib.0", "human_female.hair_b_material" ]],
            "human_male.mesh" : [[ "bodyShape-lib.0", "human_male.skin_material" ],
                                 [ "head_aShape-lib.0", "human_male.head_a_material" ]] }

Then, these statements add clothes to the models:

meshInfo["human_male.mesh"].extend([[ "cloth_a_bootsShape-lib.0", "human_male.cloth_a_material" ],
                                   [ "cloth_a_shirtShape-lib.0", "human_male.cloth_a_material" ],
                                   [ "cloth_a_pantsShape-lib.0", "human_male.cloth_a_material" ]])
meshInfo["human_female.mesh"].extend([[ "leather_a_beltShape-lib.0", "human_female.leather_a_material" ],
                                     [ "leather_a_pantsShape-lib.0", "human_female.leather_a_material" ],
                                     [ "leather_a_bootsShape-lib.0", "human_female.leather_a_material" ],
                                     [ "leather_a_tunicShape-lib.0", "human_female.leather_a_material" ]])

Modify these lines to reference your models and the corresponding clothes.

Customization

The number of characters the user can create (and select from) is determined by the value of MaxNumChars in Interface/FrameXML/MvCharCreation.py. To reduce the number of character slots, set MaxNumChars to a value less than six (6). To increase the number of character slots, set MaxNumChars to a larger value and add some XML to Interface/FrameXML/MvCharCreation.xml under the MvCharSelectionFrame Frame, to make additional buttons.

NOTE: This technique will change the number of character slots, but is not secure, because it is entirely client-side. You must add some server logic to make it secure.

To set the number of character slots, add the following XML snippet, and replace n with the appropriate number. Numbering of buttons starts with zero, so MvCharSelectionFrameButtonCreate0 is the first button and MvCharSelectionFrameButtonCreaten is the n+1^th button. Add buttons by using the XML below and replacing n and n-1 with the actual numbers. For example, to create the seventh button, use the above XML sample and replace n with 6 and n-1 with 5.:

 <Button name="MvCharSelectionFrameButtonCreaten"
         inherits="MvCharSelectionCreateButtonTemplate" 
         text="create" 
         id="n">
   <Anchors>
     <Anchor point="TOP" relativeTo="MvCharSelectionFrameButtonCreate(n-1)" relativePoint="BOTTOM">
        <Offset>
           <AbsDimension x="0" y="-4"/>
        </Offset>
     </Anchor>
   </Anchors>
   <Scripts language="python">
     <OnClick>MvCharSelectionCreate_OnClick(this, n)</OnClick>
   </Scripts>
 </Button>

The file Interface/Imagesets/MvCharCreation.xml contains the image assets for decorating the character creation and selection widget:

• screen_edge defines the edge and corner images for decorating the entire character creation and selection widget.
• screen_edge_top defines the box up top that shows whether you are currently in character creation or character selection mode.
• basic_frame_edge defines the edge and corner images for decorating the various frames inside the character creation and selection widget.
• female_button_up and female_button_down define the images for the female selection with _up and _down being the different push states.
• male_button_up and male_button_down define the images for the male selection with _up and _down being the different push states.
• left_arrow and right_arrow define the images for the previous and next buttons in the selection widget.

Character creation class

The SampleCharacterCreationContext class handles character creation. This class extends the CharacterCreation.CharacterCreationContext class.

To customize it, edit the following methods:

• __init__()
• GetValidAttributteValues()
• _setAttributes()
• OnAttributesUpdated()

The __init__(self) method is the constructor that sets the initial attributes for the CharacterCreationContext object. In the sample, this sets the model attribute to human_male.mesh. Change this to the name of your default character model. Provide a complete set of initial attributes for the character to be shown.

The GetValidAttributeValues(attr) method gets the possible attribute values for the parameter attribute, given the state of the other attributes in the internal attribute dictionary.

The _setAttributes(primaryAttribute, attributes) method is the internal method for setting attributes. Use this method to update any other attributes that are not valid with the selection. For example, if the user has selected one hairstyle, but then changes the sex of the avatar, you might need to change the hairstyle attribute as well. This method returns True if no attributes needed to be modified, or False if the attributes needed to be modified.

The OnAttributesUpdated method is called whenever the character's attributes are changed. Typically, this will update the displayed avatar to match the information in the character's attribute dictionary.

Character selection class

The SampleCharacterSelectionContext class handles character selection. This class extends the CharacterCreation.CharacterSelectionContext class. To customize it, modify the following methods:

• OnSelectionUpdated()
• BuildInitialScene()

The OnSelectionUpdated method is called whenever the selected character changes to update the displayed avatar based on the information in the character's displayContext attribute.

Modify the BuildInitialScene method to create and populate the temporary character creation/selection "world". In Sampleworld, this method creates a gazebo, a sky cylinder, some lights, and the initial avatar. The sample version requires the asset files described in 3D asset files.

Server scripts

There are server character creation/selection scripts in multiverse/config/common/character_factory.py and multiverse/config/sampleworld/character_factory.py. The login server reads the world-specific script after the common script, so the world-specific script takes precedence.

The SampleFactory.createCharacter(self, worldName, uid, properties) method creates an override template for the character, and generates the character object, a dictionary object. This properties dictionary contains information from the client that to use when creating a character. In the sample, the client provides the characterName attribute as well as the sex attribute. The sample decides what to put in the display context based solely on the sex attribute, but you can use a combination of other fields if desired. If the character is successfully created, this method returns the object ID of the newly created object.

This method should also validate fields, checking that names are unique and that the combination of attributes is valid. If there is an error in this process, this method can set the errorMessage attribute in the properties dictionary; the dictionary is passed to the Client, which can then display an error dialog.