Today we look at how to extend our functions beyond the Update loop by allowing them to pause and resume execution using “Coroutines”. We also take our first look at Unity’s UI system, and use these together to create a “Get Ready” state to prepare our players for gameplay. Get Ready!!!
Part 1: Coroutines
In past discussions, I have mentioned that Unity runs through it’s objects and their scripts sequentially. It is a very linear process. When the “awake” message is sent out, Unity goes down the list of objects that it maintains (and that you will not control) and one by one passes it the “awake” message. That message is passed to each one of that object’s components, and if that object has an Awake( ) function it is executed, line by line. Once every object has received the “awake” message, the “start” message is called prior to rendering the next frame, and Unity again goes down the list, object by object, component by component, and any corresponding function will execute.
When a function is called, it must run until it is completes every line (or until it encounters a “return”, which is a type of completion). If another function is called during that original function, then THAT new function must run to completion before moving to the next line in the original, and so forth and so on.
Using this method, it can be difficult or cumbersome to create functions that execute periodically (such as a timed event), or to occur across a span of time and across many frames (such as a fading transition). Creating and maintaining internal timers can be tricky, and it requires a lot of extra calls.
A coroutine is a function that lets us break out of this pattern by allowing us to pause it’s execution, hand control back to Unity, and then resume later and pick back up where it left off after some measure.
In our game, we would like to create a new state to let the player “get ready” to begin a round. A moment between when the ball is reset, and the action begins. For our first co-routine, we are going to make this moment last for 3 seconds.
We create our function by declaring an IEnumerator. This function will wait for three seconds, and then call the StartBall( ) function.
public IEnumerator GetReady()
{
// tell the engine to come back in three seconds
yield return new WaitForSeconds(3.0f);
// resumes after the pause
StartBall();
}
Next we call this by replacing the StartBall( ) function call in InitRound( ) with the StartCoroutine( ) function, passing our coroutine’s call as the parameter.
private void InitRound()
{
// Reset Ball
ResetBall();
// start the coroutine
StartCoroutine(GetReady());
}
Now when we run this, our ball sits there for three seconds and then begins to move.
Part 2: Basic UI
Three seconds can be a long time, and we don’t want our player to get confused, so first we should build a message to the player letting them know that now is the time to Get Ready!!!
To do this, we create a new text object by going to Game Object > UI > Text or Create > UI > Text.
When you do this, you will see a few new objects appear in your scene, including a Canvas object, and an EventSystem object. We will cover the UI system more in a future lesson, for now just know that the Canvas is the two-dimensional space where UI elements live, and renders as an overlay for the active camera.
One change you will definitely want to make now is in the Canvas object. Look for the Canvas Scaler component and change the UI Scale Mode to Scale with Screen Size. This ensures that your UI elements will fill the same proportions of the screen whether it is in the Game window or full screen.
Select the text object that you have created and change the name. We used myOverlayTextObject (because we will use this for more than one message). In the Text component, change the Text field (a longform text area, and yes, text inside text is redundant) to read something besides “New Text”. I chose “Hello World”. Set your Alignments to “Center” and “Middle”, and set your Horizontal and Vertical overflow values to Overflow. Finally, adjust the font size until you have something that looks good to you.
Next, go to the EasyPing script, and add a Text object variable to hold a reference to our text object. UI elements have their own Unity library, which we have to call first by adding the following line to the “using” commands at the very top:
using UnityEngine.UI;
Without this line, your calls to get and set text objects will return errors because Unity does not recognize that you will be using them.
Next, create the text object to hold the message text, and use our drag-and-drop method in the Unity editor to assign the text object to this field.
// define text objects public Text overlayMessage;
Now inside of the Start( ) function, we set our text message to read “Get Ready!!!”, and then set the enabled property to false so that it will not display until we tell it to.
// set the text message to read "Get Ready!!!" overlayMessage.text = "Get Ready!!!"; overlayMessage.enabled = false;
We want to make our message display while the GetReady coroutine is running, and turn off again when the stage is over and we move into the Playing state. We do this by adjusting the text object’s enabled property like so:
public IEnumerator GetReady()
{
overlayMessage.enabled = true // turn the message visibility on
// tell the engine to come back in three seconds
yield return new WaitForSeconds(3.0f);
overlayMessage.enabled = false // turn the message visibility off
// resumes after the pause
StartBall();
}
Now we should see the message appear for 3 seconds, then disappear as the ball starts moving.
Part 3: Using the Renderer
Three seconds still feels like a long time, doesn’t it? Players might still think our game is broken or stalled. And just when they let their guard down, the ball shoots off!
Let’s help show our players that something is happening, and help them anticipate the beginning of the round. We will do this by making the ball and the message blink.
To achieve this, you might be tempted to the enabled property of the ball object, but don’t do that! Making the ball inactive can destroy the connections, and reactivating it will run the Start( ) command all over again. Instead, we want to manipulate only the visibility of the ball, which we do by enabling and disabling the Mesh Renderer component.
In our EasyPing declarations, we create a new private variable of the type Renderer, like so:
private Renderer ballRender;
… then in our Start( ) method we assign the Renderer component like this:
ballRender = ballObject.GetComponent<Renderer>();
Finally, we modify our GetReady( ) script to enable and disable the Renderer component, alternated with our overlay message. We will display one configuration for a half second, and then the other for another half second. The use of a for loop lets us cycle through this three times. Once the loop completes, StartBall( ) is called and our Coroutine ends.
public IEnumerator GetReady()
{
for (int i=0; i <3; i++)
{
// turn on the message
overlayMessage.enabled = true;
// turn off the ball
ballRender.enabled = false;
yield return new WaitForSeconds(0.5f);
// turn off the message
overlayMessage.enabled = false;
// turn on the ball
ballRender.enabled = true;
yield return new WaitForSeconds(0.5f);
}
StartBall();
}
Now our ready message and ball alternate in quick half-second blinks that let the player get a good sense of the timing that is coming.
With the extra time leftover at the end of class, we also added a “none” state, and changed the initial message to “Press ‘S’ to Start”. We made sure that the Update loop only responded to the S key when in the “none” state, and from there called InitRound( ).
Now we’ve covered everything that is needed to complete Assignment #2!
EasyPing.cs
using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using UnityEngine.UI;
public enum GameState { none, setup, getReady, playing, gameOver};
public class EasyPing : MonoBehaviour
{
public GameObject ballObject;
private Rigidbody ballRigidbody;
private Renderer ballRender;
public float force;
public Vector3 direction;
// declare my state variable and set a value
public GameState myState = GameState.none;
// score tracking
private int playerOneScore;
private int playerTwoScore;
private int MAX_SCORE = 3;
// get my ui text values
public Text overlayMessage;
// Start is called before the first frame update
void Start()
{
// fetch the rigidbody & renderer
ballRigidbody = ballObject.GetComponent<Rigidbody>();
ballRender = ballObject.GetComponent<Renderer>();
// initialize the score
playerOneScore = 0;
playerTwoScore = 0;
// set the text message to Get Ready!!!
overlayMessage.text = "Press \"S\" to start...";
overlayMessage.enabled = true;
}
// Update is called once per frame
void Update()
{
if (myState == GameState.none) {
if (Input.GetKeyDown(KeyCode.S))
{
// Initilize Round
InitRound();
}
}
}
private void InitRound()
{
// set the game state
myState = GameState.setup;
// reset the ball
ResetBall();
// start the coroutine
StartCoroutine(GetReady());
}
public IEnumerator GetReady()
{
// set the get ready message
overlayMessage.enabled = false;
overlayMessage.text = "Get Ready!!!";
myState = GameState.getReady; // set the gamestate to get ready
for (int i=0; i<3; i++)
{
// turn message on, and ball off
overlayMessage.enabled = true;
ballRender.enabled = false;
yield return new WaitForSeconds(0.5f); // wait 1/2 second
// turn message off, and ball on
overlayMessage.enabled = false;
ballRender.enabled = true;
yield return new WaitForSeconds(0.5f); // wait 1/2 second
}
// start the ball
StartBall();
}
private void ResetBall()
{
// make sure we control the ball, not physics
ballRigidbody.isKinematic = true;
// move the ball to the start position
ballObject.transform.position = Vector3.zero;
}
private void StartBall()
{
// turn kinematics off
ballRigidbody.isKinematic = false;
// normalize the directional vector
direction.Normalize();
// launch the ball
ballRigidbody.AddForce((direction * force), ForceMode.VelocityChange);
// update the gamestate
myState = GameState.playing;
}
public void RegisterScore(int playerNumber)
{
// stop the action
ballRigidbody.isKinematic = true;
// who scored?
if (playerNumber == 1)
{
playerOneScore++;
} else if (playerNumber == 2)
{
playerTwoScore++;
} else
{
Debug.Log("Unassigned player number was submitted");
}
// display the score
Debug.Log("The Score is " + playerOneScore + "-" + playerTwoScore);
// gamestate is no longer playing
myState = GameState.setup;
// start a new round
InitRound();
}
}