Having already seen spaces in a previous tutorial, we will now talk about a component that only appears on space objects: the TimeSpace.

Learning Objectives

TimeScale
Pausing

Level Setup

Command : New Project
Create a new project using the {nav icon=clone, name=Empty 2D Project} template
Command : CreateSprite
In the Properties Window
Add Component : RigidBody
Add Component : BoxCollider
Under RigidBody
Set name=DynamicState,icon=list to Static
Under Transform
Set Scale to [25,1,1]
Command : CreateSphere
In the Properties Window
Under Transform
Set Translation to [-10,5,0]
Under RigidBody
Set Velocity to [10,0,0]

What is the TimeSpace?

The TimeSpace component allows for developer control over time in the space it is attached to. Time in that space can be slowed or even stopped. Let's see what the demo looks like right now to get a frame of reference.

Command : PlayGame

control

Command : StopGame

The ball falls, bounces, and rolls at a normal pace for the values it was initialized with.

TimeScale

A common dramatic effect is to slow down time during some in-game event. Slow motion effects are typically implemented via the TimeScale property, which is a scalar for the rate at which time passes. There are also some times where running your project at a slower speed will allow you to debug issues more easily. Let's take a look at how to change TimeScale using the UI.

(NOTE)Space Selection: The Space can be selected via the Select menu, by clicking in the viewport and then pressing Shift + S, by pressing Ctrl + Shift + S with any window in focus, or by using the SelectSpace command.

Command : SelectSpace
In the Properties Window
Under TimeSpace
Set TimeScale to 0.5
Command : PlayGame

halfspeed

Demo running half speed with 0.5 TimeScale

Command : StopGame

Now we can see that the time scale directly affects the rate of time without affecting the framerate.

Command : SelectSpace
In the Properties Window
Under TimeSpace
Set TimeScale to 1.0

Adjusting TimeScale In Script

Command : Add Resource
Create a NadaScript resource using the Component template template and name it TimeControl
Update the TimeControl script to the following:

class TimeControl : NadaComponent
{
  [Property]
  var IncreaseRateKey : Keys = Keys.Up;
  
  [Property]
  var DecreaseRateKey : Keys = Keys.Down;
  
  [Property]
  var TimeScaleRateOfChange : Real = 0.1;
  
  function Initialize(init : CogInitializer)
  {
    Zilch.Connect(this.Space, Events.LogicUpdate, this.OnLogicUpdate);
  }

  function OnLogicUpdate(event : UpdateEvent)
  {
    if(Zilch.Keyboard.KeyIsPressed(this.IncreaseRateKey))
      this.ScaleTime(this.TimeScaleRateOfChange);
      
    if(Zilch.Keyboard.KeyIsPressed(this.DecreaseRateKey))
      this.ScaleTime(-this.TimeScaleRateOfChange);
  }
  
  function ScaleTime(rateChange : Real)
  {
    var newTimeScale = this.Space.TimeSpace.TimeScale + rateChange;
    this.Space.TimeSpace.TimeScale = Math.Clamp(newTimeScale, 0.0, 2.0);
    Console.WriteLine("TimeScale: `this.Space.TimeSpace.TimeScale`");
  }
}

Select : LevelSettings object
In the Properties Window
Add Component : TimeControl
Command : Console
Command : PlayGame
Adjust the time scale using the up and down keys

controlled

TimeScale being adjusted up and down

Command : StopGame

Above we can see the demo progressing slower and then faster as the TimeScale is adjusted using the keyboard.

Pausing

Add the following property to the TimeControl script:

  [Property]
  var PauseKey : Keys = Keys.Space;

Add the following function to the TimeControl script:

  function TogglePause()
  {
    if(this.Space.TimeSpace.Paused)
    {
      Console.WriteLine("Game was paused, unpausing now");
      this.Space.TimeSpace.Paused = false;
    }
    else
    {
      Console.WriteLine("Game was not paused, pausing now");
      this.Space.TimeSpace.Paused = true;
    }
  }

Add the following block to the end of the OnLogicUpdate function in the TimeControl script:

    if(Zilch.Keyboard.KeyIsPressed(this.PauseKey))
      this.TogglePause();

Command : PlayGame
Press Space to pause the game and then press Space again to attempt to unpause the game

stopped

Command : StopGame

You probably noticed that the game will not unpause. This is because when the TimeSpace is paused, Keyboard, listening for the KeyDown event, or to poll the keyboard input on FrameUpdate.

Update the Initialize function in TimeControl to the following:

  function Initialize(init : CogInitializer)
  {
    Zilch.Connect(Zilch.Keyboard, Events.KeyDown, this.OnKeyDown);
  }

Replace the OnLogicUpdate function in TimeControl with the following:

  function OnKeyDown(event : KeyboardEvent)
  {
    if(event.Key == this.IncreaseRateKey)
      this.ScaleTime(this.TimeScaleRateOfChange);
      
    if(event.Key == this.DecreaseRateKey)
      this.ScaleTime(-this.TimeScaleRateOfChange);
    
    if(event.Key == this.PauseKey)
      this.TogglePause();
  }

Command : PlayGame
Press Space to pause the game and then press Space again to attempt to unpause the game

pausing

Pausing with and unpausing in reaction to the KeyDown event

Now we can see the game being paused and unpaused successfully.

Command : StopGame

Manual

Reference

Commands

Classes

Events

Development Tasks

{T1178}

Table of Contents