Unity Character Creator UI Basics

1. Understanding the UI Toolkit

If you've used Unity's legacy UI system (Canvas, GameObjects, etc.), UI Toolkit might feel a bit different. It's modeled after web technologies and breaks a UI down into three parts:

• UXML (.uxml): An XML-based language that defines the structure and layout of the UI. This is similar to HTML.
• USS (.uss): A stylesheet language, similar to CSS, that controls the appearance (colors, fonts, spacing) of the UI elements.
• C# Scripts: These provide the functionality, handling user input and manipulating the UI elements.

This separation makes UIs more modular, maintainable, and easier to style. To get a quick overview of these concepts, let's watch the beginning of a helpful video.

Following the video's guidance, go ahead and create a new UI Document in your Unity project. I suggest creating a UI folder to keep things organized. Name the new file CharacterCreator.uxml. Double-click it to open the UI Builder window.

2. Designing the Layout with Flexbox

With the UI Builder open, our next task is to lay out the structure of our character creator. We need fields for all the data we defined in Rust.

UI Toolkit uses a powerful layout system called Flexbox to arrange elements. If you've done any web development, this will be familiar. The key is to understand how parent containers arrange their children along a main axis (either a row or a column).

Now, let's apply this. We'll create a vertical layout for our form. In the UI Builder's Hierarchy panel, start by dragging elements from the Library panel to create the following structure:

1. A root VisualElement: This will be our main container. By default, its flex-direction is column, which is what we want.
2. A TextField: For the character's name.
3. A DropdownField: For selecting the age stage.
4. Six Slider elements: For the HEXACO personality dimensions.
5. A few Toggle elements: For selecting traits.
6. A Button: To create the character.

For now, just drag these elements into the hierarchy. Don't worry about their appearance yet. Here's a visual example of what a finished character creator might look like in-game:

3. Configuring the UI Elements

Now let's configure each element in the Inspector panel within the UI Builder.

Name Field (TextField)

• Give it a name in the Inspector, like character-name. This is crucial for accessing it from our C# script later.
• Set its label to "Name".

Age Stage (DropdownField)

• Set its name to age-stage-dropdown.
• Set its label to "Age Stage".
• In the Inspector, find the "Choices" list and add our four age stages: Child, Teen, Adult, and Elder.

Personality Sliders (Slider)
For each of the six sliders:

• Set its label to one of the HEXACO dimensions: Honesty-Humility, Emotionality, Extraversion, Agreeableness, Conscientiousness, Openness to Experience.
• Set its name accordingly (e.g., honesty-slider).
• Set the low-value to 0 and high-value to 1. This will make the slider output a float between 0.0 and 1.0, matching our Rust Personality struct.

You can find more details on configuring sliders in the Unity documentation.

Traits (Toggle)

• Create three or four Toggle elements.
• Give each one a label for a sample trait, like "Creative", "Ambitious", or "Bookworm".
• Give each a unique name (e.g., creative-trait-toggle).

Create Button (Button)

• Set its name to create-character-button.
• Set its text to "Create Character".

4. Styling with USS

With the structure in place, let's add some basic styling to make it look less plain. We'll do this using a USS stylesheet.

1. In the UI Builder's StyleSheets panel, create a new stylesheet and save it as CharacterCreator.uss.
2. Now you can add style rules. For example, to give your form some breathing room, you could select the root VisualElement and add some padding in the Inspector. This will automatically create a new style rule in your USS file.
3. Try adding some styles yourself:
   • Give the create-character-button a background color.
   • Add some margin below each element to space them out.
   • Increase the font size for the labels.

Experiment with the properties in the Inspector. This is the fastest way to learn what's possible with USS.

5. Hooking Up Logic with C#

Our UI looks good, but it doesn't do anything yet. The final step is to write a C# script to read the player's input when they click the "Create Character" button.

Now, let's apply this to our scene.

1. In your main Unity scene, create an empty GameObject and name it UI Controller.
2. Add the UI Document component to it. In the Source Asset field, assign your CharacterCreator.uxml file. You should now see your UI in the Game view.
3. Create a new C# script named CharacterCreatorController and add it to the UI Controller GameObject.
4. Open the script and add the following code:

using UnityEngine;
using UnityEngine.UIElements;
using System.Collections.Generic;

public class CharacterCreatorController : MonoBehaviour
{
    private UIDocument uiDocument;

    private TextField characterName;
    private DropdownField ageStage;

    // Sliders for HEXACO
    private Slider honestySlider;
    private Slider emotionalitySlider;
    private Slider extraversionSlider;
    private Slider agreeablenessSlider;
    private Slider conscientiousnessSlider;
    private Slider opennessSlider;
    
    // Toggles for traits
    private Toggle creativeTrait;
    private Toggle ambitiousTrait;
    private Toggle bookwormTrait;

    private Button createButton;

    void OnEnable()
    {
        uiDocument = GetComponent<UIDocument>();
        var root = uiDocument.rootVisualElement;

        // Query for all the elements by name
        characterName = root.Q<TextField>("character-name");
        ageStage = root.Q<DropdownField>("age-stage-dropdown");

        honestySlider = root.Q<Slider>("honesty-slider");
        emotionalitySlider = root.Q<Slider>("emotionality-slider");
        extraversionSlider = root.Q<Slider>("extraversion-slider");
        agreeablenessSlider = root.Q<Slider>("agreeableness-slider");
        conscientiousnessSlider = root.Q<Slider>("conscientiousness-slider");
        opennessSlider = root.Q<Slider>("openness-slider");

        creativeTrait = root.Q<Toggle>("creative-trait-toggle");
        ambitiousTrait = root.Q<Toggle>("ambitious-trait-toggle");
        bookwormTrait = root.Q<Toggle>("bookworm-trait-toggle");

        createButton = root.Q<Button>("create-character-button");

        // Register a callback for the button click
        createButton.RegisterCallback<ClickEvent>(evt => OnCreateCharacterClicked());
    }

    private void OnCreateCharacterClicked()
    {
        Debug.Log("--- Character Creation Data ---");
        Debug.Log($"Name: {characterName.value}");
        Debug.Log($"Age Stage: {ageStage.value}");

        Debug.Log("--- Personality ---");
        Debug.Log($"Honesty-Humility: {honestySlider.value}");
        Debug.Log($"Emotionality: {emotionalitySlider.value}");
        Debug.Log($"Extraversion: {extraversionSlider.value}");
        Debug.Log($"Agreeableness: {agreeablenessSlider.value}");
        Debug.Log($"Conscientiousness: {conscientiousnessSlider.value}");
        Debug.Log($"Openness: {opennessSlider.value}");

        List<string> selectedTraits = new List<string>();
        if (creativeTrait.value) selectedTraits.Add("Creative");
        if (ambitiousTrait.value) selectedTraits.Add("Ambitious");
        if (bookwormTrait.value) selectedTraits.Add("Bookworm");
        
        Debug.Log($"Traits: {string.Join(", ", selectedTraits)}");
        Debug.Log("-----------------------------");
    }
}

Run the scene, fill out the form, and click the "Create Character" button. You should see all the data you entered printed neatly in the Unity console.

Conclusion

Excellent work! You've successfully built a functional character creation screen using Unity's modern UI Toolkit. You've structured the layout with UXML, applied styles with USS, and captured user input with a C# script.

Key Takeaways:

• UI Toolkit separates UI into UXML (structure), USS (style), and C# (logic).
• Flexbox is the primary system for creating flexible and responsive layouts in UI Toolkit.
• UI elements are created in the UI Builder and configured in the Inspector, where you assign them a unique name.
• C# scripts access UI elements using root.Q<ElementType>("element-name").
• User interactions like button clicks are handled by registering callbacks (e.g., RegisterCallback<ClickEvent>).

Right now, our captured data only exists in the Unity console. In the next lesson, we will take the next critical step: passing this character creation data from Unity to our Rust backend via the FFI for validation. This will be the first time our frontend and backend truly communicate with complex, structured data.