Playground: Reference Guide

1. Movement Scripts

This category of scripts is all about moving GameObjects around, whether they are the player, hazards, or non-player characters.

Being that the Playground is all based on physics, almost all GameObjects require a Rigidbody2D component to produce movement, and will also need some type of Collider2D component if you want the object to be able to interact with others.

Auto Move

Requirements: Rigidbody2D component

The AutoMove script applies a continuous force to a GameObject. It is a useful script for things such as rockets, arrows, and other self-propelled objects.

The direction of the force applied to a GameObject is expressed through a Vector2 and also includes the strength of the force. The force can be absolute or relative to the object's rotation.

In the Scene view, a green arrow gizmo represents the direction of the push, while the size of the arrow represents the strength of the force.

Note: If you are considering using this script on a prefab created with the help of the Object Shooter script, remember that Object Shooter already applies a force to objects when shooting them. In case of a non self-propelled object (like a rock fired from a catapult), you don't need Auto Move on the projectile.

Auto Rotate

Requirements: Rigidbody 2D component

The AutoRotate script applies a continuous rotation to a GameObject on the Z axis. This script can be used to add movement to a decorative object, but can also create rotating obstacles in conjunction with the ConditionCollision script (referenced below). You can specify the speed of the rotation, and setting a negative speed makes the object rotate counter-clockwise.

In the Scene view, a green arrow gizmo represents the direction of the rotation.

Camera Follow

Requirements: Camera component

Use the CameraFollow script on a GameObject that has a Camera component. This script is useful for action adventure games where the camera is centered on the player. Assign a moving GameObject in the scene as the Target.

Note: Add this script to the Camera, not to the object being followed!

If you enable the Use Bounds property, you will be able to constrain the movement of the Camera to a rectangle.

You can adjust the values of the bounds through the Inspector or in the Scene view with the yellow rectangle gizmo:

Follow Target

Requirements: Rigidbody2D component

Adding the FollowTarget script to a GameObject forces the GameObject to follow a specified target indefinitely.

Enabling Look at target allows you to set whether the object orients itself to look at the target or not. See the Move script (referenced below) for more information.

Tip: You can assign this script to an enemy and use the player as a target to create a constant threat, or you can create a queue of characters by chaining them to each other with a series of FollowTarget scripts.

Jump

Requirements: Rigidbody2D component and a Collider component (to be able to land!)

The Jump script is a simple script that propels an object upwards when a specific key is pressed. From the Key property dropdown you can select the keyboard key that is used to perform the jump.

To stop the player from jumping in the air, enable Check ground and select a tag from the Ground tag dropdown. Then, you need to tag anything you want to consider ground with that same tag. As soon as the GameObject collides with the ground, it is able to jump again.

If Check ground is not enabled, the player is able to jump multiple times in the air. This might be useful to create an effect more like a wing flap than a jump.

Tip: You can tune the Jump Strength property together with the Friction property of the Rigidbody2D component to obtain exactly the jump dynamics that you want.

Move

Requirements: Rigidbody2D component

The Move script applies a constant force to a GameObject on two axes.

The Type of Control property assigns which control scheme the script uses (either the arrow keys or WASD). You can have two Move scripts in the scene and assign one to each player to create multiplayer games that can be played on the same keyboard.

The Movement Type property allows you to restrict the movement of a GameObject to only one axis. You can think of this as if the object is moving along a rail, but you can also combine this more limited range of motion with other movement scripts to create more refined movement. For instance, you can create a platformer controller by using the Move script and forcing it to use only the horizontal axis in conjunction with a Jump script.

Note: Keep in mind that even if the force you apply to a GameObject uses only one axis, nothing is stopping the object from moving on the other axis as a result of a collision. If a GameObject is hit by another one, for example, this might disrupt gameplay. To account for this, enable Freeze Position for the appropriate axis on the Rigidbody2D component.

The Orient to direction property gives you control over whether the object rotates to face the direction of travel. This is useful for vehicles (spaceships, cars, boats, etc.) and more generally, sprites that are seen from the above.

If you enable Orientation to direction, you can choose which side is used as the forward direction with the Look Axis dropdown. This depends on how the sprite has been drawn.

In the image above, for instance, you would set the Look Axis to Up for the spaceship, Down for the fish, while you wouldn’t enable Orient to direction for the bee because it’s framed from the side and not from the top, so rotating the sprite would look strange.

Patrol

Requirements: Rigidbody2D component

The Patrol script allows you to have an object move along a path made up of waypoints. These waypoints are organized in a list (Stops), so you can add, remove, or reorder them easily. The Reset Waypoints button clears the list of waypoints and adds one default stop.

The GameObject returns to the starting point once it has traveled to all of the set waypoints. Once the GameObject reaches its starting position, it restarts on the path.

As with other Movement scripts, enable Orient to direction to control which way the sprite faces while it moves. See the Orient to direction description in Move for move information.

When you create a waypoint, its position is visualized in the Scene view as a Transform handle. You can change the location of these waypoints by moving their handles around in the Scene view or by changing their position values in the Inspector.

A green ghost sprite connected to four waypoints in the Scene view. A little blue arrow marks the direction of movement the ghost will follow on its path from one waypoint to another

Push

Requirements: Rigidbody2D component

The Push script applies a continuous force in one direction to a GameObject when you hold a specific key on the keyboard. This script is useful when you need to create a controller for vehicles, and you can use it in combination with a Rotate script (discussed below) to allow for better steering.

In the Scene view, a green arrow gizmo shows you the direction and strength of the force.

By setting the Axis property, you can control in which direction the push moves the object (Y means up, X means to the right). To achieve a push in the opposite direction, simply set Push Strength to a negative value.

In conjunction with Axis, the Relative Axis property controls whether the push rotates with the GameObject or whether it is applied in absolute terms. For example, with Relative Axis enabled, rotating the object by 90 degrees clockwise also rotates the relative direction of the push by 90 degrees clockwise. With Relative Axis disabled, the direction of the push stays the same, no matter how the object is moved. There is no change in the gizmo if the object has no rotation.

The tooltip below the option reflects the change that enabling or disabling the property will have. Generally, it’s a good idea to enable Relative Axis so that the object moves in a forward direction, no matter which way it is pointing.

Rotate

Requirements: Rigidbody2D component

The Rotate script applies a torque - that is, a rotation on the Z axis, to an object. Like the Move script, this movement is controlled with the arrows keys or WASD keys. You can use a Rotate script together with a Push script to create a vehicle-like controller, where you can steer and move forward in the direction the vehicle is pointing in.

Wander

Requirements: Rigidbody2D component

With the Wander script added, a GameObject randomly moves around in short bursts. The movement speed is controlled by the Speed property, which as usual goes together with the Friction property in the Rigidbody2D component to make the movement feel realistic.

The Direction Change Interval property controls the amount of time that passes (in seconds) before the object changes direction.

If the Keep Near Starting Point property is enabled, the GameObject performs a check every now and then, and if it strays too far from its original location, the object heads back to its initial point in its next movement.

Note: If you set the Speed too high or there’s not enough Friction on the Rigidbody2D component, the object might still be able to wander off very far, even if the Keep Near Starting Point property is enabled!

As with other Movement scripts, the Orient to direction property gives you control over how the sprite orients itself while it is moving. Check out the description of this property in the Move script section for move information.

2. Gameplay Scripts

Gameplay scripts are a miscellaneous category of scripts that produce gameplay effects. These scripts act on their own, meaning they don’t require conditions to activate them.

ObjectCreatorArea

Requirements: BoxCollider2D component

The ObjectCreatorArea script generates new objects from a prefab in a rectangular area. To work, this script requires a BoxCollider2D component (which is applied automatically when the script itself is applied) that defines the area where the instances appear.

The Prefab To Spawn property can be used to spawn an object from the scene, but it’s good practice to assign a prefab instead. If you assign a normal GameObject from the scene, the component displays a warning.

The Spawn Interval property determines how often (in seconds) an object is generated.

ObjectShooter

Requirements: N/A

The ObjectShooter script allows you to propel or shoot a prefab when you press a certain key. You can use this script to create weapons that shoot lasers, a tennis ball machine, or any kind of item that propels something out repeatedly. This script works in conjunction with the BulletAttribute script (discussed below).

Most of the time, you’ll want to assign this script to an empty GameObject, make that object the parent of another GameObject, and use the child as a spawning point for the projectiles. That way you can control exactly where the projectile is emitted from.

You can select an object from the scene in the Prefab to Spawn property, but it’s good practice to create a prefab and select that instead. If you select a normal GameObject from the scene, the component displays a warning.

The Creation Rate property controls the interval between shots (in seconds). The Shot Speed property determines the speed of each shot, and the Shot Direction property controls the direction of the shot as a Vector2.

The Relative to Rotation property allows the direction of the shot to be rotated with the GameObject, so if (for instance) you use this script on an object like a spaceship that rotates, the shooting direction rotates as well. Disabling this property means the shooting direction is in World Space.

When you apply this script to an object, a green arrow gizmo appears in the Scene view.

The size of the arrow is not connected to the strength of the shot.

Note: You can also set the Shot Speed to 0. This way the player can leave behind objects as they move. Don’t get fooled by the name of the script: the generated object doesn’t need to be a projectile!

Finally, the ObjectShooter script also has the ability to assign a player ID to the projectiles. This works in conjunction with the BulletAttribute script (referenced below), which needs to be assigned to the projectile prefab that you want to shoot out. Doing so means that if the projectile hits another object that has the DestroyForPointsAttribute script (referenced below), points are assigned to the correct player.

To make sure the ObjectShooter script assigns the correct ID, you need to tag the GameObject as Player or Player2.

Note: If you don’t tag the GameObject, the projectile is considered as coming from Player1, so for single-player games you don’t need to worry about tagging.

PickUpAndHold

Requirements: N/A

The PickUpAndHold script is used to give a character the ability to pick up (and drop) something, such as a ball in a sports game. Coupled with clever use of a ConditionArea script (referenced in Playground conditions), you can create gameplay that revolves around picking up an object and delivering it to a specific area.

To be able to pick up an object, you need to assign that object the Pickup tag and give it a Collider2D component of any kind. You’ll also probably want to make the Collider a trigger, otherwise the object collides with the player and is harder to pick up. If the object has a Rigidbody2D component, it is made kinematic and any forces are stopped before being parented to the character.

The Pickup Key and Drop Key properties define which key needs to be pressed to pick up and drop an item. These keys are the same by default, but they don’t have to!

The Pick Up Distance property defines the maximum distance in meters that the object can be from the player while still being able to be picked up. If multiple objects tagged with Pickup are present, the closest one is picked up when the Pickup Key is pressed.

TimedSelfDestruct

Requirements: N/A

The TimedSelfDestruct script is a utility script that can be used to get rid of objects that are no longer needed in the scene after a certain time. The Time to Destruction property controls the lifespan (in seconds) of an object. Once that time has been reached, the object disappears!

Use this script on any generated object, like projectiles for example, to make sure the scene doesn’t get too cluttered. Also, if your game generates a lot of objects, over time the performance of the game might slow down. Putting the TimedSelfDestruct script on those objects - even if the Time to Destruction is high - will help the game run better.

3. Playground Attributes

Attributes are a category of scripts that don’t do much on their own: they define qualities that objects have, and then another script acts on those qualities. Attributes have a role similar to Tags, but being scripts they can come with extra data.

BulletAttribute

Requirements: Collider2D of any shape

The Bullet script has no functionality on its own, but it holds a reference to which Player launched a projectile. This number (playerID in the code) can be 0 (player 1) or 1 (player 2).

The playerID is automatically set by the ObjectShooter script (referenced in Gameplay scripts) when the projectile is launched.

Note: If for any reason you want to set the playerID property in the Inspector, open the BulletAttribute script and remove the attribute [HideInInspector] from the property. This could be useful in case the projectiles are created by a script that is not ObjectShooter.

CollectableAttribute

Requirements: Collider2D of any shape

The CollectableAttribute script awards a point to any player who touches the object that has this script added to it. As such, this script requires a Collider2D component to function properly marked as a Trigger.

The Points Worth property allows you to assign a different value to each object.

Note: To display the total score on screen, a UI prefab needs to be present in the scene. Refer to the Getting Started manual for more information on the UI prefab.

DestroyForPointsAttribute

Requirements: N/A

The DestroyForPoints script is good for targets and enemies in shooting games. This script destroys the GameObject on collision with another object, but only if this second object has the Bullet script. Also, the DestroyForPoints script awards points to the Player who originally launched the projectile.

Check out the sections on the Bullet and ObjectShooter scripts for more information on how IDs are assigned to projectiles.

Note: To display the total score on screen, a UI prefab needs to be present in the scene. Refer to the Getting Started manual for more information on the UI prefab.

HealthSystemAttribute

Requirements: N/A

The HealthSystemAttribute script can be added to characters, enemies, or objects. This script allows GameObjects to take damage and potentially be removed from the game if their health falls to 0 - which in the case of the Player might mean game over!

This script works in conjunction with the ModifyHealthAttribute script (discussed below), which is necessary even for projectiles. Similarly, an object with the ModifyHealthAttribute script will not affect an object that doesn’t have the HealthSystemAttribute script.

The HealthSystemAttribute script doesn’t require the presence of a Collider2D component, but it’s recommended to have one if you are relying on collisions to subtract health from your player.

Note: To display the player’s health on screen, a UI prefab needs to be present in the scene. Refer to the Getting Started manual for more information on the UI prefab.

ModifyHealthAttribute

Requirements: Collider2D component of any shape

The ModifyHealthAttribute script makes any object capable of subtracting or adding health to any object that has the HealthSystemAttribute script. This script is useful for projectiles, hazard zones, and other damaging objects, but can also be used for things that can heal, like medical kits, food, and more!

When the Destroy When Activated property is enabled, the object is removed from the scene the first time it produces its effects. Enable this property for projectiles, consumables, and anything else that only acts once.

The Health Change property indicates the change in health that the object produces. If property is negative, then the object is a damaging one. If the property is positive, the object adds health. The text (and color of the text) below this property changes depending on whether the object damages, heals, or has no effect.

ResourceAttribute

Requirements: Collider2D component of any shape, SpriteRenderer component

The ResourceAttributes script, together with ConsumeResource, allows resources and an inventory to be added to games made with Playground. Touching an object that has this script removes the object from the scene and adds it to an inventory displayed by the UI.

The ResourceAttributes script requires a SpriteRenderer component since the sprite is used to display an icon in the lower-left corner of the scene, alongside a number representing the number of that resource the player has.

Picking up more resources of the same type increases the number in the UI. A ConsumeResource script can then be used to make use of the collected resources. Check out the description of the ConsumeResource script for more information.

With resources, you can create a crafting system (that is, use a certain number of collected resources to create a new resource) or a simple door and key system, where the player needs to have the right key to open each door.

Defining resource types

The Type of Resource property allows you to define which type a resource belongs to, and you can optionally specify an Amount (useful for coins and money). This will effect what is visible in the UI.

To define a resource type, select the Add/Remove types button. Defining a resource focuses the Editor on a ScriptableObject called InventoryResources. In the Inspector for InventoryResources, a list of strings defines all the available types of resources in the game.

Several types have already been added for your convenience, but you can add more or remove existing ones to better suit your game. Once you add a resource type, be sure to go back to the object that has the ResourceAttribute script and assign it the correct type.

Note: Resource types are shared between all scenes, so if you remove the base types (Coin, Star, etc.) some Example scenes like Roguelike will stop working.

Moving the location of the InventoryResources object will also break the system.

4. Playground Conditions

Conditions are very similar to If Statements in programming, meaning that they act as a gateway to other behaviors. If the condition is verified, then the attached Actions are executed. See Action scripts for more details on what Conditions can execute.

Condition scripts have a purple if tag at the top-left corner of their icon.

All Condition scripts have some common properties, which are described below.

Gameplay Actions

The Gameplay Actions property is a list of Action scripts that are executed when the requirement of the Condition script is met. Once the requirement is met, Unity executes the Actions in this list until one of them fails (only a few Actions can fail). If the Action doesn’t fail, then the next one is executed. At the end of the list, Custom Actions (if present) are carried out.

A list of empty Actions looks like this:

Selecting the Add (+) button reveals a list of the Actions available to add:

The list items correspond exactly to the scripts in the Action folder. If you select any of these items, the script is added as a component and automatically connected to the list.

Note: Action scripts need to be connected in the Gameplay Actions list to work. Simply adding an Action script to a GameObject will not execute it.

Tip: At the bottom of the dropdown, there is an option to add an empty slot. Having an empty slot is really useful when you want to connect an Action present on another GameObject to your current GameObject. This way you can break your logic into parts, which makes the logic easier to manage. To see this in practice, open the Roguelike example game and select the InvisibleTrigger object. Notice how 2 of the Actions are on separate objects parented to this one.

Custom Actions

Similarly to Gameplay Actions, Custom Actions are executed when the requirement of the Condition script is met. It’s not necessary to use Gameplay Actions, so if the Use custom actions property is disabled, no custom action is executed.

Enabling the Use custom actions property reveals a list of Unity Events. Here,you can connect anything you would normally use an UnityEvent for.

Custom Actions allow you to expand the gameplay aspect of your game: if you know programming, you can write a simple script and expose a public function, and then connect it in the list of Unity Events. That way your script can be called by one of the default Condition scripts of the Playground. This is a great way for teachers to quickly extend the functionality of the Playground during a workshop.

Another use of Custom Actions is to connect standard Playground public functions in the list of Unity Events. A good example is the UI Script script and its GameWon and GameOver functions. By wiring one of these functions into the Custom Actions list of a Condition, you can, for instance, create a win condition when an object collides with something else or enters an area.

ConditionArea

Requirements: Collider2D component set as Trigger

The ConditionArea script requires a Collider2D component set as Trigger. The Event Type property determines when the event occurs: on entering the area, on leaving it, or while staying inside (if you select Stay Inside, a Frequency property appears that allows you to determine how often the event happens).

Because you probably don’t want just any object to trigger an event, the Filter by Tag property allows you to select the specific category of objects that trigger the event when they enter the area. It is common to use the Player tag for this, but you can use whatever you like!

If the Happen Only Once property is enabled, the condition will be ignored after the event has happened once.

Gameplay Actions and Custom Actions are common to all Conditions, so you can find more info in the general sections: Gameplay and Custom.

ConditionCollision

Requirements: N/A

The ConditionCollision script is a simple condition that makes something happen when an object collides with the object that has this script. As with other conditions, you can filter which type of object actually produces the event by setting a tag in the Filter by Tag property.

If the Happen Only Once property is enabled, the condition will be ignored after the event has happened once.

Gameplay Actions and Custom Actions are common to all Conditions, so you can find more info in the general sections: Gameplay and Custom.

ConditionKeyPress

Requirements: N/A

The ConditionKeyPress script is a generic way of binding an Action to a key press. In addition to being able to choose which key activates the event with the Key to Press property, you can also choose which type of key event triggers the event with the Event Type property: Just Pressed (similar to GetKeyDown), Released (GetKeyUp) or Kept Pressed (GetKey). As with other continuous actions, the Kept Pressed option has a Frequency property.

If the Happen Only Once property is enabled, the condition will be ignored after the event has happened once.

Gameplay Actions and Custom Actions are common to all Conditions, so you can find more info in the general sections: Gameplay and Custom.

ConditionRepeat

Requirements: N/A

To make a programming comparison, the ConditionRepeat script is more like a WHILE than an IF. The script executes the list of Actions repeatedly without user input or interaction. The script has a Frequency property that controls how often (measured in seconds) an event happens, and an Initial Delay property that determines how long after a condition is met (also measured in seconds) for the event to trigger.

Gameplay Actions and Custom Actions are common to all Conditions, so you can ffind more info in the general sections: Gameplay and Custom.

5. Playground Actions

Actions are scripts that don’t work on their own, but need to be executed by Conditions. The Action is only executed if the Condition is verified. Action scripts because they have a little yellow then tag at the top-left corner of their icon.

Action scripts all feature the concept of success. This means that some actions can fail, and if they do, the Condition that triggers them will interrupt the chain of Actions and stop the event.

Adding and removing Actions

Actions can be added like any other component, but on their own they won’t do anything - they always need to be connected to a Condition.

For this reason, it’s best practice to add Actions via a Conditions' Gameplay Actions property and not the Add Component button in the Inspector or by dragging the script into the chosen GameObject, Adding Actions with the Gameplay Actions property of a Condition both adds the Action component to an object and connects the Action to the Gameplay Actions list. Similarly, the Remove (-) button both removes the item in the list and the component from the GameObject.

If you want to add an Action to another object that has the same Condition, simply add the Action to the object as a regular component, then set the Gameplay Actions property to Empty Slot. Finally, drag the GameObject that has the Action onto the list slot that you just added.

Check out the Gameplay Actions section of Conditions for more information.

ConsumeResource Action

Requirements: N/A

The ConsumeResource script is an event that is only triggered if the following condition is met: the player must have a certain number of objects in their inventory that have the same tag as the Type of Resource property of the script, and the number of objects must be equal to or greater than the quantity selected in the script’s Amount Needed property.

If the condition is met, that number of resources is consumed and any specified following Action is executed.

If the condition is not met, then no resource is consumed and the list of Actions is stopped (meaning any following Action is not executed).

Like in the ResourceAttribute script (found in the Playground Attributes section), the Add/Remove types button allows you to define resource types.

CreateObject Action

Requirements: N/A

The CreateObject script generates a new object from a prefab. The object that is created can be selected using the Prefab to Create property.

To decide where the new object is created, you can use the New Position property, which initially is in world space (meaning 0,0 is the origin). When the Relative to this Object property is enabled, the New Position property can be considered local space.

DestroyAction

Requirements: N/A

The DestroyAction script can be used to remove objects from the game.

The Target property can have two values: This Object, which destroys the object that the script is added to upon collision, and Object That Collided, which destroys the object that collided with the object the script is added to upon collision. When using the latter value, this Action needs to be connected to either a ConditionArea script or a ConditionCollision script, or it will fail.

You can also set the Death Effect property, which generates another object when the Target object is destroyed. This Death Effect object could be a particle system, or other objects (like debris, a broken version of the object that was destroyed, etc.).

DialogueBalloon Action

Requirements: N/A

The DialogueBalloon script allows you to put simple dialogues into a game. An example of this script in action can be found in the Roguelike example scene.

The first set of properties, Text to Display, Background Color, and Text Color are pretty self-explanatory.

If the Target Object property is enabled, the chosen text appears above a character or object. If this property is disabled, the text appears in the middle of the screen.

The Disappear Mode property has two options to choose from: Button Press and Time. Selecting Button Press requires the user to press a key (set with the Key to Press property) to remove the dialogue, while selecting Time means that the dialogue will disappear after the number of seconds specified by the Time to Disappear property.

Regardless of how the dialogue is removed, you can connect another DialogueBalloon script in the Following Text property to create a continuous dialogue.

You can connect several DialogueBalloon scripts together and set the Target Object property to different objects to create conversations between two or more characters.

Tip: Use chained DialogueBalloon scripts with no target and set the Disappear Mode property to Button Press to create small tutorials for your game!

LoadLevel Action

Requirements: N/A

The LoadLevel script gives you the ability to load Unity scenes from Conditions.

From the Scene to load property, you can select all of the scenes that have been added to the Build Settings menu (File > Build Settings…). In order to load a scene using the LoadLevelAction script, add the scene to the Scenes in Build list and enable it.

The RELOAD LEVEL menu item in the Scene to load property dropdown reloads the current scene. This is useful if you want to reset the state of the game after a game over.

OnOffAction

Requirements: N/A

The On-Off script is used to turn an object on or off, meaning that the object’s Active flag is set to either true or false. You need to select the target in the Object to Affect property in order for this script to work.

The Just Make Invisible property allows you to turn a SpriteRenderer on or off instead, meaning the object is still part of the gameplay, including any collision events it might have.

The OnOffAction script always sets the Active flag to its opposite position. This means the second time the Action is executed on the same object, the script restores the object’s previous state, and so on.

Tip: If you want to set an object on or off in an absolute way (meaning the second time there will be no effect), you can use a regular UnityEvent (enable Custom Actions on the Condition and select SetActive on the target GameObject).

TeleportAction

Requirements: N/A

The Teleport script moves an object to a new location instantly. If nothing is assigned in the Object to Move property, the object that has the script added to it is teleported. The New Position property is in world space.

For objects that have a Rigidbody2D component, if you enable the Stop Movements property, in addition to being teleported to the new location, the object is also stopped, meaning the object’s speed and torque are zeroed, which is good for resetting the game state (for instance, after scoring in a sports game).