Chapter 6: Dice Group Roller

In 2.1: Dice Group, you created a DiceGroup which simulates rolling groups of like sided dice (e.g. 3d6 or 2d4 or 1d20). In this chapter, you will create a simple scene that allows the player to specify a DiceGroup using Dice Notation and roll that DiceGroup. This is the first step in creating a Dice Analyzer.

When you have completed this chapter, you will have a scene that is similar to the one below.

01. Create a Dice Analyzer Scene

1. Create a new Scene in your Scenes folder and call it Dice Analyzer
2. Open the new Scene

If you need a refresher on creating and opening a Scene, check out 1.2.01: Create a Scene

02. Add and Configure a Canvas

Before adding UI components to the Scene, it is a good idea to add and configure a Canvas to scale properly with the screen.

Challenge: Add UI Components

In this Scene, you will add 4 UI components:

1. Title: A Text element for the Title
2. Dice Group Input: An Input Field to allow the user to specify the DiceGroup to roll
3. Dice Info: A Text element to display information about the rolls made by the DiceGroup
4. Roll Button A Button to simulate rolling the current DiceGroup

Add, rename, and size these 4 components into your Hierarchy. When you’re finished your Canvas should contain at least 4 Game Objects. However, you may find it helpful to add additional Game Objects with Layout components to position your elements the way you would like.

Here is what my Hierarchy and Scene looked like after I had finished:

If you need help adding a specific component to your Scene, click on a section below to see instructions.

03. Create a DiceGroupController Script

Next, you will create a MonoBehaviour called DiceGroupController. This script will allow us to create a GameObject that controls a DiceGroup as well as provide UnityEvents that other GameObjects can listen to and update themselves accordingly.

1. In your Scripts/Controller folder create a script called DiceGroupController
2. Open the DiceGroupController script
3. It should be apart of the AdventureQuest.Dice name space
4. You won’t need an Update() or Start() method
5. The script will use the UnityEngine and UnityEngine.Events name spaces

If you’ve set up the class properly, your DiceGroupController.cs file should look like this:

using UnityEngine;
using UnityEngine.Events;

namespace AdventureQuest.Dice
{
    public class DiceGroupController : MonoBehaviour
    {

    }
}

04. Properties and Methods of a DiceGroupController

Think about what purpose a DiceGroupController will serve in this Scene.

• Based on the UI components, what methods will the DiceGroupController need?
• What parameters will those methods accepts?
• How will those parameters be validated?
• What events does a DiceGroupController need to communicate with the UI components?
• What properties and private fields will the DiceGroupController have to manage the state of a DiceGroup?

Think about the questions above, then expand the section below.

/// <summary>
/// The <see cref="DiceGroup"/> that is being controlled (or null if no _diceGroup has
/// been initialized).
/// </summary>
private DiceGroup _diceGroup;

/// <summary>
/// This event is invoked each time a new <see cref="DiceGroup"/> is 
/// initialized.
/// </summary>
[field: SerializeField]
public UnityEvent OnDiceGroupInitialized { get; private set; }

/// <summary>
/// This event is invoked each time a Roll event occurs with the 
/// value of that roll.
/// </summary>
[field: SerializeField]
public UnityEvent<string> OnRoll { get; private set; }

/// <summary>
/// This event is invoked if an error occurs reporting a message to be
/// reported to the user.
/// </summary>
[field: SerializeField]
public UnityEvent<string> OnError { get; private set; }

/// <summary>
/// Attempts to initialize a <see cref="DiceGroup"/> using the specified
/// <paramref name="diceNotation"/>. If the <paramref name="diceNotation"/> was
/// not a valid <see cref="DiceGroup"/> an error is generated and no dice is initializd.
/// </summary>
public void InitializeDiceGroup(string diceNotation)
{
    // TODO
}

/// <summary>
/// Rolls the <see cref="DiceGroup"/>. If no <see cref="DiceGroup"/> has been initialized,
/// an error is generated and no dice are rolled.
/// </summary>
public void Roll()
{
    // TODO
}

Add a DiceGroupController GameObject to the Scene

With the DiceGroupController script outlined, you’re ready to attach it to a GameObject in the Scene.

1. Right click in the Hierarchy
2. Select Create Empty
3. Rename the new object DiceGroupController
4. Select the DiceGroupController object in the Hierarchy
5. In the Inspector click Add Component
6. Search for DiceGroupController and add it.

05. On Edit End Event

With the DiceController events in place, it is time to connect it to the UI components.

The Input Field has several events. In our case, we would like to invoke the DiceGroupController’s InitializeDiceGroup method when the user is finished entering a value into the Dice Group Input.

1. Select Dice Group Input in the Hierarchy
2. In the Inspector find the TextMeshPro - Input Field component
3. Within this component, locate the On End Edit (String) event
   • You will likely need to scroll to access it

1. Click the + icon to add a listener to the event
2. Drag Dice Group Input into the listener
3. Select the DiceGroupController.InitializeDiceGroup method from the Function dropdown.

This event triggers after the user enters a value and clicks out of the Input Field.

To test that it is connected, you can update your DiceGroupController.InitializeDiceGroupMethod:

public void InitializeDiceGroup(string diceNotation)
{
    Debug.Log($"The user entered: '{diceNotation}'");
}

Run the Scene, enter a value, and click away from the input box. You should see the string you entered displayed in the console.

Challenge: Connect Dice Info to the OnError event

When the user enters a string that cannot be formatted, you will need to display an error message. To do this, you can connect the Dice Info component to the DiceGroupController’s OnError event.

To test that it is properly connected, update the InitializeDiceGroup method to invoke the OnError event:

public void InitializeDiceGroup(string diceNotation)
{
    OnError.Invoke($"The user entered: '{diceNotation}'");
}

If all went well, your scene should act similar to the one below:

07. Disable the Roll Button

When the user enters a valid DiceGroup value, the Roll Button should be clickable. This means, that before that happens, it should be disabled. This can be done in the Inspector.

1. Click the Roll Button in the Hierarchy
2. In the Inspector find the Button component
3. Uncheck the Interactable flag

The button in the Scene should appear greyed out. Attempting to click on it will not fire the OnClick event.

Challenge: Connect Roll Button to OnDiceGroupInitialized

Can you connect the Roll Button to the DiceGroupController’s On Dice Group Initialized event?

To test that it is properly connected, update the InitializeDiceGroup method to invoke the OnDiceGroupInitialized event:

public void InitializeDiceGroup(string diceNotation)
{
    OnError.Invoke($"The user entered: '{diceNotation}'");
    OnDiceGroupInitialized.Invoke();
}

If everything is working, your scene should act similarly to the one below:

Challenge: Connect DiceGroupController to the Roll Button

Clicking the Roll Button should invoke in the DiceGroupController’s Roll() method. Can you add the DiceGroupController to the Roll Button?

To test that it is properly connected, update the Roll() method to display a message to the console.

public void Roll()
{
    Debug.Log("Roll clicked!");
}            

If everything is working, you should see a message in your console when you click the roll button.

Challenge: Connect DiceInfo to the OnRoll event

When the DiceGroup is rolled, the results should be displayed to the user. Can you connect the Dice Info component to the DiceGroupController’s OnRoll method?

To test that it is properly connected, update the Roll() method to invoke8* the OnRoll **event.

public void Roll()
{
    OnRoll.Invoke("Dice rolled! Result was 42!");
}

If all went well, you should see the message displayed on the screen when the roll button is clicked.

08. DiceGroup.IsParseable

Before implementing the InitializeDiceGroup(string diceNotation) method, it would be convenient to add two static methods to the DiceGroup class to help with parsing the users input into a DiceGroup.

• Add the following static method to your DiceGroup class:

/// <summary>
/// Checks if the specified <paramref name="diceNotation"/> string is in
/// a <see cref="DiceGroup"/> format. If it can be parsed, returns true
/// and false otherwise.
/// </summary>
public static bool IsParseable(string diceNotation)
{
    if (diceNotation == null) { return false; }
    string trimmed = diceNotation.Trim();
    string[] tokens = trimmed.Split("d");
    if (tokens.Length != 2) { return false; }
    if (!int.TryParse(tokens[0], out int amount)) { return false; }
    if (amount < 1) { return false; }
    if (!int.TryParse(tokens[1], out int sides)) { return false; }
    if (sides < 2) { return false; }
    return true;
}

Challenge: Implement DiceGroup.Parse

Next, you must implement the DiceGroup.Parse method:

1. Validate that the incoming string is in the correct format. If it is not, throw a System.FormatExcpetion
2. Split the string into tokens (use diceNotation’s Split method)
3. Parse the tokens into amount and sides (use int.Parse)
4. construct and return a new DiceGroup(amount, sides)

/// <summary>
/// Given a <paramref name="diceNotation"/> string, parses it and returns a new <see cref="DiceGroup"/>.
/// </summary>
/// <exception cref="System.FormatException">If <paramref name="diceNotation"/> is not a DiceGroup notation.</exception>
public static DiceGroup Parse(string diceNotation)
{
    int amount = int.Parse("1");
    int sides = int.Parse("2");
    return new DiceGroup(amount, sides);
}

[Test, Timeout(5000), Description("Tests the Parse method against 3d6 and 1d20")]
public void TestParse()
{
    DiceGroup group3d6 = DiceGroup.Parse("3d6");
    Assert.AreEqual(3, group3d6.Amount);
    Assert.AreEqual(6, group3d6.Sides);
    Assert.AreEqual(3, group3d6.Min);
    Assert.AreEqual(18, group3d6.Max);

    DiceGroup group1d20 = DiceGroup.Parse("1d20");
    Assert.AreEqual(1, group1d20.Amount);
    Assert.AreEqual(20, group1d20.Sides);
    Assert.AreEqual(1, group1d20.Min);
    Assert.AreEqual(20, group1d20.Max);
}

[Test, Timeout(5000), Description("Tests the Parse method throws a format exception on invalid input")]
public void TestParseFormatException()
{
    Assert.Throws<System.FormatException>(() => DiceGroup.Parse("d4"));
    Assert.Throws<System.FormatException>(() => DiceGroup.Parse("d6"));
    Assert.Throws<System.FormatException>(() => DiceGroup.Parse("d8"));
    Assert.Throws<System.FormatException>(() => DiceGroup.Parse("1d-6"));
    Assert.Throws<System.FormatException>(() => DiceGroup.Parse("0d1"));
    Assert.Throws<System.FormatException>(() => DiceGroup.Parse("-1d5"));
    Assert.Throws<System.FormatException>(() => DiceGroup.Parse("banana"));
    Assert.Throws<System.FormatException>(() => DiceGroup.Parse("d5"));
}

[Test, Timeout(5000), Description("Tests the IsParseable method")]
public void TestIsParseable()
{
    Assert.True(DiceGroup.IsParseable("1d4"));
    Assert.True(DiceGroup.IsParseable("3d6"));
    Assert.True(DiceGroup.IsParseable("20d8"));
    Assert.True(DiceGroup.IsParseable("2d12"));
    Assert.True(DiceGroup.IsParseable("7d20"));
    Assert.True(DiceGroup.IsParseable("1d17"));

    Assert.False(DiceGroup.IsParseable("d4"));
    Assert.False(DiceGroup.IsParseable("d6"));
    Assert.False(DiceGroup.IsParseable("d8"));

    Assert.False(DiceGroup.IsParseable("1d-6"));
    Assert.False(DiceGroup.IsParseable("0d1"));
    Assert.False(DiceGroup.IsParseable("-1d5"));
    Assert.False(DiceGroup.IsParseable("banana"));
    Assert.False(DiceGroup.IsParseable("d5"));
}

Challenge: Implement DiceGroupController.InitializeDiceGroup

With these two methods in place, try to implementing the InitializeDiceGroup method.

1. Check if diceNotation can be parsed using the DiceGroup.IsParseable method
   • If it cannot be parsed, invoke OnError
2. If it can be parsed:
   • use DiceGroup.Parse(diceNotation) to parse a DiceGroup and set _diceGroup
   • Invoke OnDiceGroupInitialized

You can test that your method works be entering an invalid input. This should display an error message and the roll button will remain disabled.

Entering a valid input should enable the button.

public void InitializeDiceGroup(string diceNotation)
{
    if (!DiceGroup.IsParseable(diceNotation))
    {
        OnError.Invoke($"Error: \"{diceNotation}\" is not a valid dice group. Expected d.");
        return;
    }
    _diceGroup = DiceGroup.Parse(diceNotation);
    OnDiceGroupInitialized.Invoke();
}

Challenge: Implement DiceGroupController.Roll

Finally, can you implement the Roll() method? Clicking Roll should roll the _diceGroup and invoke the OnRoll method reporting the results.

When you’re finished, your Scene should act similar to the one below:

Good Time to Commit

If you have not already done so, now would be a good time to make a commit and merge. You just finished a feature. More specifically, you implemented a basic Dice Group Roller.

This commit adds a Die class which models a multi-sided die providing an
interface with 2 properties: `Sides` and `LastRolled`. Additionally, it provides
a single method: `Roll()` which "rolls" the die and randomly selecting one of
the sides.

Additionally, added unit tests to test the Die class specification.

What’s Next?

Hopefully, you are becoming more comfortable with Unity’s UI elements and connecting them with UnityEvents is beginning to feel easier.

With a DiceGroup class in place, you are ready to move on to [3.0 Character Creator] where you will create a Character Creation Scene.

That said, there is quite a bit more you can do with Dice Notation. If you would like to continue creating additional classes to specify more interesting combinations of dice, you can do so in [2.3 Dice Pool].

Join the Discussion

If you're stuck, have questions, or want to provide feedback, you can do so below. However, I ask that you please refrain from posting complete solutions to any of the challenges.

Before commenting, you will need to authorize giscus. Alternatively, you can add a comment directly on the GitHub Discussion Board.