Support Home Game Builder How To

How To: Game Builder

  • Overview
  • Getting Access
  • Scenes
  • Introduction
  • Storyboarding
  • Creating Scenes
  • Scene Editor
  • Adding Objects
  • Positioning Objects
  • Configuring Components
  • Adding a Backdrop
  • Adding Spawnables
  • Spreadsheets
  • Spreadsheets
  • Editing Spreadsheets
  • Binding to the spreadsheet
  • Spreadsheet randomisation
  • Using multiple spreadsheets
  • Stimuli
  • Stimuli
  • Settings
  • Manipulations
  • Store
  • Subsystems
  • Metrics
  • Multiplayer
  • Animation
  • Animation Tool
  • Creating Animation
  • Previewing Clips
  • Triggering Animations
  • Scripts
  • Scripts

Overview


The Game Builder allows you to create simple games to use in behavioural research studies. It's designed to support both gamified versions of more 'traditional' cognitive tasks, as well as more open ended experiences. Like Task Builder 2, you can incorporate text, image, video or audio stimuli, and collect participant responses in a variety of ways (mouse, keyboard etc). However, in the Game Builder, we use animation to control how elements appear and move. This allows you to create a much richer and more engaging experience, while maintaining all the rigorous scientific control required for research studies.

Importantly, you do not have to touch a single line of code. All the layout and animation can be designed using visual tools.

Read on to see what each part of the tool does, and follow our step-by-step guide to build your first game and learn the tools quickly.

Getting Access to the Game Builder Tools


The Game Builder is a new tool that is available to all Gorilla users. It's free to start building your Game Builder tasks and preview them. You can create a Game Builder task from inside any of your projects and you can also contact the Support Desk if you have any questions about Game Builder!

shopbuilder setup

To add your Game Builder tasks to an experiment and start collecting data, you'll need a licence.

Visit our pricing page for more information.

Introduction


The Scenes tab is where you configure all the different scenes used in your task. In the Game Builder, there are three different types of scene:

  1. Scenes represent a single part of your task. This might be an instructions screen, or a trial, or a break screen.
  2. Backdrop is a special scene that is always visible. Use this to create a background for your task (for example, this could be a forest or a space station).
  3. Spawnables are special scenes that you can make dynamically appear. Use these for effects such as explosions or puffs of stars.

As an example of how these three might be used together, consider a simple game where the player controls a space rocket that shoots asteroids with its laser:

Schematic example of two scenes within a game. The first scene illustrates a rocket firing a laser. The second scene shows the laser hitting an exploding asteroid.

The stars and planet, which are always visible, would be in the Backdrop scene. The main Scene would show the rocket, laser and asteroid. The explosion effect would be a Spawnable, which we would spawn when the asteroid explodes. The image below shows how this example can be broken down into the different types of scenes:

Schematic display broken down into three scenes. The first shows the backdrop of planets and stars. The second shows the scene with the rocket sprite shooting a laser at an asteroid. The third shows the asteroid exploding as a Spawnable scene.

Storyboarding


A good approach to building your game is a process we call storyboarding. This means planning out the different interactions that should happen on the screen. Storyboards can be created on paper, or by using a program such as PowerPoint. For example, a storyboard for our rocket game might look something like this:

A storyboard of 6 different scenes. Scene 1 starts in space with a background of a planet and stars. Scene 2 shows a rocket flying in from offscreen. Scene 3 shows 'Get Ready' text appearing. Scene 4 is where the asteroid will fly in across the screen. Scene 5 shows a laser animation starting if a participant reacts in time, and the asteroid explodes. Scene 6 shows the asteroid continuing to fly offscreen if the participant responds too slowly.

The storyboarding phase is a great time to start gathering images you will be using as part of your game. You can find a wide range of free (or very cheap) artwork to use in your games on sites such as Pixabay , Pexels , Unsplash and Canva .

Once you're happy with the storyboard, you can put each part together within the Game Builder. Most of the time, you'll do this using animation.

Scene Editor


You can create any of the three types of the Scenes by clicking '+ New Scene' on the right:

A screenshot of the Game Builder Scene Editor. An arrow points to the red button labelled 'New Scene'.

When you add a new scene, a menu will prompt you to choose either a Scene, Backdrop or Spawnable.

A screenshot of the pop-up menu after clicking New Scene. Three options are presented: either a Scene, Spawnable, or Backdrop

Once you select an option and click Create, you will be taken to the Scene Editor. The scene editor is split into three main sections:

Screenshot of the Scene Editor in Game Builder. The screen is split into three sections. On the left, the Scene preview is labelled and highlighted in yellow. In the middle, the object list is labelled and highlighted in blue. On the right, the object editor / screen tab / debug tab is labelled and highlighted in green.

Scene Preview


The Scene Preview panel (the largest section highlighted in yellow above) shows you a live preview of your scene.

In the bar across the top, you can use the first four buttons to click between different screen dimensions to see how your screen will look at those resolutions. Hover over each icon to see what device it represents. The in-editor preview tests four 'common' resolutions: Large Montor (1920 x 1080); Small Monitor (1280 x 1024); Laptop (1440 x 900); Tablet (1024 x 768). These are just the common measurements and won't be indicative of all possible devices. The previews can be used as a guide to make sure things will approximately display correctly. Therefore, for most participants, if it looks okay in these previews it should be okay for them. However, you should continue to test and pilot your experiment across different devices and use all of the available scene space when creating your game. Have a look at this video walkthrough for viewing your game at different screen sizes using the developer tools.

The Play and Reload buttons allow you to preview the sequence of events in your scene from start to finish. Press Play to preview the scene, and Reload to start the preview again from the beginning. Clicking the Play button again will take you back to edit mode, where you can make further changes to your scene.

The final button, View Source, allows you to view the underlying code that controls the objects and their components in the scene. If you prefer, you can edit the source directly to add or edit objects and components as well as adjust their settings, instead of using the graphical user interface. The Source also provides an easy way to way to copy entire scenes between Games. You can copy the Source in a screen from one game and paste this in the Source of another. Clicking 'Back to Tools' at the top-left of the Source will return you to the standard view of the Scene Editor.


Object List


The Object List (shown in blue) shows a list of all the objects on your screen. When you first add a Scene or Spawnable scene, this list will appear empty until objects are added. If you are adding a Backdrop Scene, three objects will appear by default: the background, stage and foreground. You can read more about adding Backdrop scenes later in this guide.

You can reorder objects in the Object List by clicking and dragging them up and down. This is useful for controlling which visual components are displayed in front of or behind other visual components. Here, you can also drag objects diagonally to become children of Containers. You can read more about this in the Positioning Guide.


The panel on the right (highlighted in green) has three functions, depending on which tab above it is highlighted in red: OBJECTS, SCREEN, or DEBUG.' The Object List is only visible when OBJECTS is selected from the panel on the right.


Objects Tab


When OBJECTS is selected, this panel functions as the Object Editor. Clicking on an object in the Object List will open its configuration options and components here:

A screenshot of a Christmas Same / Different game, with two present images on the Scene. The left present is selected in the Objects list, and the configuration settings and Animator component are shown in the Objects Tab on the right of the screen.

Screen Tab


When SCREEN is selected, this panel functions as the Screen Tab. Here, you can add special components to implement things that apply to the entire screen. For example, adding a timelimit to the screen, accuracy scoring or saving responses to use later in your game or experiment.

A screenshot of a Christmas Same / Different game. The Screen Tab is selected from the panel on the right-hand side. The Time Limit and Scorer are shown in the Screen Tab.

Debug Tab


When DEBUG is selected, this panel functions as the Debug Tab. The Debug Tab will automatically open when you press the Play button in the Scene Preview. Here, you can select specific trials from specific spreadsheets to show on the scene preview by using the dropdown menus. Press Play to preview the sequence of events in your scene (including non-visible events like responses).

A screenshot of a Christmas Same / Different game. The debug tab is selected on the right-hand side. The spreadsheet and row 2 are selected in the debug settings. The sequence of screen progression is recorded with the response received and response processed recorded.

Adding Objects


Click the Add Object button to add a new object to your scene:

Screenshot of the Objects list in the Game Builder. An arrow points to the Add Object button in the tab.

This will open the Object Builder menu, where you can choose the components you would like to add to your object:

Screenshot of the object builder in game builder. The menu shows a scrollable list of components and a search bar to browse available components. A text box to name the object appears on the left.

Objects are made up of components, which allows you to combine different bits of behaviour together. You can also use Prefabs, such as 'Animated Sprite'. Prefabs are pre-made bundles of 2 or more components that work together to create specific functionality. For example, the Animated Sprite prefab consists of 2 components: Sprite and Animator. This means you can add your custom animations created within the Animator to the Sprite. Read more about how the Object-Component System enables greater flexibility in your game.

Use the search bar on the top left of the Object Builder to search for components and prefabs to add to your object. You can also browse the categories to the right of the search bar (Renderable, Positioning, Response etc.) to bring up lists of relevant components and prefabs. Finally, clicking one of the dark buttons at the top of the Object Builder will immediately create an object that is frequently used. For a full list of components and their settings, see the Game Builder Components Guide.

You can combine prefabs and components flexibily to create the functionality you want. For example, you could start with an Animated Sprite then swap the Sprite for some Text to create Animated Text instead:

Note: One restriction to combining components is that each object can only contain one Renderable component. Renderable components are usually visual components that you can see within the scene, for example Sprite, Text and Quad components. The only case where a Renderable component will not be visible, is if you are using a Hotspot component (but the case remains that you can only have one Hotspot per object). If you try to add a Renderable component (or prefab containing a Renderable component) to an object that already contains one, the Object Builder will swap in the new Renderable to replace the old one. For example, in the video above, the orignial Sprite component is swapped for the new Text component. If you need to combine multiple Renderable components, you will have to add these to your scene as separate objects.

In the Object panel on the right of the Object Builder, you can rename your object using the Object Name field. You can also remove components by clicking the bin icon on the right of each component.

Screenshot of the Object Builder menu. One arrow highlights the field where object can be named on the right. A second arrow highlights the bin icon to the right of each component.

Once you are happy with the object you have built, click Done. This will return you to the Scene Editor. Your new object will now appear in the Object List, and its components and configuration settings will appear in the Object Editor on the right. You can add or change any components in your object by clicking on Add Component, this will open the Object Builder with any existing components in this object.

You can create a copy of an object by clicking the Duplicate button in the top-right of the Object Editor:

A screenshot of the Object Editor within the Game Builder. An arrow highlights the icon used to duplicate object in the right-hand corner of the tab.

You can also copy and paste an object's properties and components into another existing object by using the three-dots menu in the Object Editor. On the object you want to copy, click the three-dots menu and select 'Copy'. Then, click on the object you want to paste into, and select 'Paste' from the three-dots menu. Note: this will overwrite any existing components and settings on that Object.

You can even copy and paste objects across games! Simply open each game in a separate tab, and then copy and paste the objects between the games in the same way as explained above.


Positioning Objects


If you add an Object that contains a visual component, it will be placed by default in the centre of the scene (0,0). You can move it by clicking and dragging around the scene, or by changing the X and Y Position values under the visual component in the Object Editor. For most Renderable components (except Text and Particles), you can choose to specify the position using pixels (the ruler icon), which are the raw coordinates of the screen, or you can define the position as a percentage (the % icon) of the screen size:

You can also control the back-to-front display ordering of these objects by dragging them up and down in the Object List to change their order. Objects that are lower in the Object List will be displayed in front of objects that are higher. Read more about the layout of scenes in the Positioning Guide.


Configuring Components


Click on an object in the Object List to configure its components:

A screenshot of the game builder. The sprite object is selected, revelaing it's configuration settings. An arrow highlights the selected object from the list. A second arrow highlights where the configuration settings can be seen on the right of the screen.

The settings available depend on the components that the object has. You can find a full list of components and their settings in the Game Builder Components Guide.

Click the Add Component button to add a component to an object:

A screenshot of the game builder. An arrow highlights the Add Component button in the Object Editor panel.

This will then open the Object Builder. Search or browse for a component, and then click Add to add it to your object. Click done when you are happy with the component(s) you have added:

A screenshot of the Object Builder in the game builder. An arrow highlights the Done button to finish building object

To remove a component, go to the three-dots menu at the top right of the component and select 'Remove Component':

A screenshot of the game builder object editor panel. An arrow highlights the three-buttons menu to the right of the component. The menu is open and shows the options to remove or copy the component.

You can also use the three-dots menu to copy a component by selecting 'Copy Component'. Click the object where you want to paste your copied component and select 'Paste' from the three-dots menu at the top of the object:

The exact effect this has will vary depending on the components the object already has. If the object already has a component of the same type (e.g., you are pasting an Animator component into an object that already has an Animator component), then the settings from the pasted component (e.g. animations you have created) will overwrite the settings of the existing component. If the object already has a component that is not the same type, but fulfils the same function (e.g., you are pasting Sprite component into an object that already has a visual component, such as Text), then the pasted component will replace the existing component. Otherwise, the pasted component will simply be added to the object's list of components, as in the video example above.

As you change the settings, the Scene Preview panel will update live:


Adding a Backdrop


Backdrop scenes will be present in all of the other scenes within the game, so you don't have to recreate it every time. To add a Backdrop to your game, click '+ New Scene', select 'Backdrop' from the menu and click Create:

A screenshot of the new scene pop-up in the game builder. The backdrop option is selected.

This will take you directly to your new Backdrop scene. There will be three objects pre-populated in your Backdrop scene: background, stage and foreground:

A screenshot of a new backdrop scene in the game builder. The objects list is prepopulated with the background, foreground and stage

The main scenes created in your game will be added to the stage.

Anything added to the background will be shown behind any scenes added to the stage.

Anything added to the foreground will be shown in front of any scenes you add to the stage.

This creates a layering effect of scenes illustrated below:

A diagram of three squares layered on top of one another. The square at the back is labelled background, the middle square is labelled stage and is shown in front of the background. The final square is labelled foreground and is at the front, on top of the stage.

To add an image you would like to use as a background, you should first add an Object to the Scene with a Sprite component. You can set the texture of this Sprite to be the background image you would like to use. This image can be chosen from previously uploaded stimuli, or uploaded directly from your files, by clicking +New:

A screenshot of the Choose File screen in the game builder. The preview shows uploaded files to the Stimuli tab. An arrow highlights the New button in the top right corner

Set the size of the background to be 100% for both x and y, so that the image will fill the screen regardless of the device type:

A screenshot of the game builder. The Sprite containing the background image as been set to be 100%.

Finally, drag the Sprite to be a child of the background in the Object List. Doing this will ensure the background image appears behind any other scenes you add to your game. Children of objects will appear indented in the Object List:

You can create richer and more complex backdrop scenes by creating Objects to be children of the foreground, too. The backdrop scene created will be displayed in all scenes you create in the game.


Adding Spawnables


Spawnable Scenes are special scenes that you can trigger to dynamically appear within other scenes of your game. As previously mentioned, they are great for when you would like to create effects within your game. In this example, we will use a Spawnable scene to make a firework explode!

First, you will need to add a new Spawnable scene. Click '+New Scene' and select Spawnable from the menu. Give your spawnable a name, it is best practice to give your spawnables meaningful names so you can later identify them within your scenes. Click Create:

 A screenshot of the New Scene menu in the game builder. The Spawnable option is selected and has been given the name 'FireworkExplode'.

Then, you will need to upload any images you would like to use to the Stimuli Tab.

In this example, the Particle component is used to create the spawnable explosion. You only need to upload a single image, which will be multipled to create the effect. The configuration settings on the right can be adjusted to manipulate the effect created.

Use the Play button in the preview panel to see how your Spawnable will look:

Once you have created a Spawnable you are happy with, use a Spawn animation to trigger the appearance of the Spawnable.

Navigate to the scene where you would like to trigger the Spawnable. Here, there is a Sprite of a firework that we would like to control the appearance of the Spawnable. Add an Animator component to the Sprite object and open the Animation Tool to create an Animation. Add the Spawn animation, and configure the settings by entering the name of your Spawnable scene in the 'Spawn' field and attach it to 'Self'. In this example the Die animation is also added, so that the firework Sprite disappears once the Spawnable has been triggered. You can then preview how your Spawnable appears in the main Preview by setting the animation to Play on Start and using the Play button:

Using a Particle component in a Spawnable Scene is the most common use-case, but they are by no means limited to this! You could create Spawnables that use text and sprites - anything you wish to make dynamically appear within your main scenes.


Spreadsheets


The actual order that your scenes are shown in is defined in a Spreadsheet. Each row represents a time step in the game. One column specifies the scene that participants should see, and the remaining columns define the stimuli and other settings that are used in that scene. The game will progress through each row in the spreadsheet one after the other until the game is complete.

For example, consider the example rocket game from earlier:

/rocket example

Let's say that during each trial, the player has to decide whether or not to shoot the asteroid. We want to show the instructions first, then do two practice trials, twenty real trials, and then the debrief at the end. Each of the practice trials and real trials uses different stimuli. Your spreadsheet may then look like the following:

/spreadsheet example

When defining your scenes, there are many configuration settings (e.g. which image to display or what the correct answer is) which you can set to be controlled by a specific spreadsheet column. We call this process binding - you bind certain settings to the spreadsheet so that they take their value from the row that we're currently on. You can find more information about how to do this in the Binding to the spreadsheet section of this guide.


Editing Spreadsheets


To create a spreadsheet, click the New Spreadsheet button within the Spreadsheet Tab:

A screenshot of the Spreadsheet Tab within the Game Builder. The spreadsheet icon is highlighted with a black square surrounding it on the left of the screen. The red New Spreadsheet button in the top-right corner is highlighted with an arrow pointing to it.

Enter a name for your spreadsheet and click Create. You will then have a choice of launching the Spreadsheet Builder, or alternatively starting with an empty spreadsheet, or file upload, or copying one of your existing spreadsheets:

A screenshot of the New Spreadsheet display in the Game Builder.

Creating an empty spreadsheet


If you create an empty spreadsheet, by default it will contain only a single column, which is the scene.

Use the corner menu to reorder existing columns or add a new column. You can also use either this menu or the +Add Row button at the bottom of the spreadsheet to add a new row:

A screenshot of the spreadsheet menu in the Game Builder. The options 'Reorder Columns', 'Add Column' and 'Add Row' are shown.

Click on a spreadsheet cell to edit it. In the scene column, enter the name of one of your scenes:

A screenshot of a cell of the spreadsheet being edited. The word 'Practice' is entered into the scene column of the spreadsheet.

The cell will show a green background if it matches either a scene name, or the name of one of your uploaded stimuli. This makes mistakes easy to spot:

A screenshot of an example spreadsheet. The cells with 'Practice' and 'Trial' are highlighted in green. The cell with 'TRial' entered, is not highlighted in green.

While being able to specify a few rows directly in the spreadsheet editor is useful for stubbing out your game quickly, or fixing individual cells, it is generally easier to download a template spreadsheet and perform larger-scale edits in your spreadsheet editor of choice (e.g. Excel). You might find it helpful to first use the Spreadsheet Builder to create the basic structure of your spreadsheet.


Using the Spreadsheet Builder


To use the Spreadsheet Builder, click the 'Launch Spreadsheet Builder' from the New Spreadsheet screen, or click the 'Open Spreadsheet Builder' button at the top of the spreadsheet tab. When you open the Spreadsheet Builder, click the button to add a block to your game:

Screenshot of the opening screen of the Spreadsheet Builder, with a + button to add the first block of trials.

Select a scene and enter the number of times it should be repeated:

A screenshot of the Spreadsheet Builder 'Select a Scene' menu. There is a dropdown to select the Scene and a text field to enter the 'Count' of this scene.

In the example above, the 'Trial' scene will be presented 10 times.

If you have already set up binding to the spreadsheet on any scenes, the Spreadsheet Builder will detect this and display the relevant rows and columns for you to fill in. In this example, in the Trial scene there is a Sprite component that binds to the Stimulus column in the spreadsheet:

Screenshot of a Trial block in the Spreadsheet Builder, showing the Stimulus column for filling in with stimulus filenames.

You can either fill in the relevant details here, or finish blocking out the spreadsheet within the Spreadsheet Builder and then download the spreadsheet to fill in offline and re-upload it.


Uploading a pre-made spreadsheet


To upload a pre-made spreadsheet, click 'Upload from File' and then 'Create' from the New Spreadsheet screen:

Screenshot of the New Spreadsheet screen. 'Upload From File' is selected and highlighted with an arrow.

To download a template spreadsheet first, create an empty spreadsheet or use the Spreadsheet Builder, then use the 'Download File' button at the top of the spreadsheet tab:

Screenshot of an empty spreadsheet containing columns 'scene' and 'Stimulus'. 'Download File' at the top is highlighted with an arrow

You can then edit the file locally, and then upload it using the Upload File button:

Screenshot of an empty spreadsheet containing columns 'scene' and 'Stimulus'. 'Upload File' at the top is highlighted with an arrow.

To rename or remove a column in your spreadsheet, click the pencil button in the column header:

Screenshot of the column menu in the Spreadsheet tab, showing options 'Rename Column' and 'Remove Column'.

To add a column to your spreadsheet, use the corner menu at the top left of the spreadsheet and select 'Add Column'. A column will automatically be added whenever you bind a setting on one of your scenes to the spreadsheet. You can also add columns by downloading your spreadsheet, adding the column in Excel or similar, and reuploading your spreadsheet. This is the best way to add metadata columns, such as information about trial types that is useful for analysis but not required for the functioning of the game itself.


Binding to the spreadsheet


When you create your scenes, you have the option to bind certain settings - for example, Sprites, text and correct answers - to the spreadsheet. This means that this information will be populated from the spreadsheet, which is useful for things that you want to vary from trial to trial.

Bindable settings will have a link button - click this to open the binding window:

Screenshot of the Sprite settings in the Game Builder. An arrow highlight the binding button on the right-hand side.

You can bind settings to various sources, as explained in our Binding Guide, but most of the time you'll be using the spreadsheet. Ensure Spreadsheet is selected at the top of the binding window. Then, pick the column you want to bind to. Early on, you'll likely be creating new columns, but once created they'll appear in the dropdown list:

A screenshot of the binding window in the Game Builder. The dropdown list shows opetions of existing columns in the spreadsheet and the option to create a new spreadsheet column.

Click Bind to apply the binding. Your setting will change to show that it's now bound - the green S indicates that it is bound to the spreadsheet:

Screenshot of the Sprite settings in Game Builder now that it is bound to the spreadsheet. The field reads 'Stimulus' with a greeen S to the left

To change your binding, click the link button again. You can then unbind the setting, or change it to be bound to a different value. Finally, if you go back to the spreadsheet tab, you'll see that any new columns now appear.

You would then fill in this column with the appropriate data: for example, filenames of the stimuli that you want your bound component to display on each trial. You can see an example of this at the end of the Stimuli section of this guide.

You can find more information about binding to the spreadsheet in our Binding Guide.


Spreadsheet randomisation


To add randomisation to your spreadsheet, click the 'Add Radnomisation' button at the top of the spreadsheet tab:

A screenshot of the spreadheet tab in the Game Builder. An arrow highlights the 'Add Ranomdisation' button on the right.

A randomiser panel will appear on the right. Click 'Add Component' to add a randomisation component. There is information about the different types of randomisation you can implement below.

Once you have added your randomisation component(s), you can preview how your randomised spreadsheet might look for one participant by clicking the Preview Randomisation button (dice icon) at the top of the spreadsheet tab:

A screenshot of the spreadsheet tab in the Game Builder. There is a ranomisation component added on the right. An arrow highlight the dice icon in the Randomisation button, used to preview randomisation.

Gorilla will show you one possible randomised version of the spreadsheet under the constraints you have selected:

A screenshot of the spreadsheet tab. The randomisation button is highlighted in green, indicating preview mode. The spreadsheet shows an example of the randomisation.

You can view more possible randomised versions by repeatedly clicking the Preview Randomisation button. When you have finished previewing, click the 'Stop Randomisation Preview' button to return to displaying your original spreadsheet:

A screenshot of the spreadsheet tab in randomisation preview mode. An arrow highlights the Stop Randomisation Preview button.

To remove a randomisation component, click the three-dots menu to the right of the specific component and select Remove Component. You can also use the menu to copy a randomisation component:

A screenshot of the spreadsheet randomisation tab. The three dots menu on the right has been opened, and displays the options to copy component or remove component.

To paste a randomisation component, click the three dots menu at the top of the randomiser tab and select 'Paste Component'. This enables you to copy randomisation settings from one game to another:

A screenshot of the spreadsheet randomisation tab in the Game Builder. The three dots menu in the randomisation tab is open and displays the options to Add New Component or Paste Component.

To remove all randomisation from your spreadsheet, click the 'Remove Randomisation' button (bin icon) at the top of the spreadsheet tab:

A screenshot of the spreadsheet randomisation. An arrow highlights the Remove Randomisation button.

Randomisation Types

You can apply the following types of randomisation to your spreadsheet:


Randomise Trials by Column

This will randomise sets of rows in your spreadsheet, where the sets are defined by having matching values in the selected column.

To set up this type of randomisation, create an additional column in your spreadsheet. Leave this column blank for any rows that you do not want to be randomised. Enter matching values in any rows that you want to be treated as a set for the purposes of randomisation. For example, if you want to randomise easy and hard trials independently, create a column that defines these trial types, entering one value in all rows that define one set (e.g. 'easy') and a different value for all rows that belong to another set of trials (e.g. 'hard'). Then, select this column in the dropdown when you configure your randomisation component.

For example, imagine you want to present participants with alternating easy and hard trials. However, you want the order of the specific easy and hard trials within these constraints to be randomised so that the exact stimuli is shuffled. The screenshot below shows how you would set this up using a Difficulty column that defines trial type and a Randomise Trials by Column component:

A screenshot of the spreadsheet within the Game Builder. Trials in the 'Difficulty' column alternate 'easy' and 'hard' trials.

Clicking the Preview Randomisation button shows one possible randomisation of the spreadsheet under these constraints:

A screenshot of the spreadsheet within the Game Builder. The preview randomisation is in action. Trials in the Difficulty column have been randomised within the 'easy' nad 'hard' trial constraints.

Randomise Blocks

This will randomise the order of blocks of rows in your spreadsheet. To apply this randomisation type, you will need to create a column that defines your blocks. In this column, fill in the same number in all rows that belong to the same block. For example, fill in a 1 for all rows in block 1, a 2 for all rows in block 2, a 3 for all rows in block 3 etc. Then, select this column in the dropdown when you configure your randomisation component. This will cause the order of blocks to be shuffled, but the order of the trials within each block to be preserved (or alternatively, controlled by another randomisation component).

A screenshot of the spreadsheet within the Game Builder. Trials in the 'block' column are assigned to either block 1 or 2.

Clicking the Preview Randomisation button shows one possible randomisation of the spreadsheet under these constraints:

A screenshot of the spreadsheet in the Game Builder. Trials have been randomised by Block in the Preview.

Randomise Within Column

This will randomise the contents of one column, independently of all other columns. For example, applying Randomisation Within Column to the Stimulus column will randomise the assignment of stimuli to trials, while keeping all other trial information as specified in the original spreadsheet:

A screenshot of the spreadsheet in the Game Builder. The Randomise Within Columns is set to the Stimulus column of the spreadsheet.

Clicking the Preview Randomisation button shows one possible randomisation of the spreadsheet under these constraints. Rows that are empty in the selected column will not be randomised:

A screenshot of the spreadsheet within the Game Builder. The randomisation preview shows randomised content within the Stimulus column.

Randomise Between Columns

This will randomise content between two or more columns, on a per-row basis. For example, if you have three consistent response buttons across your trials, but want to randomise the order in which these appear from trial to trial, you could do this with the following setup:

A screenshot of the spreadsheet within the Game Builder. The Randomise Between Columns component has been added, and the columns 'button1', 'button2' and 'button3' have been selected for randomisation.

Clicking the Preview Randomisation button shows one possible randomisation of the spreadsheet under these constraints:

A screenshot of the spreadsheet within the Game Builder. The columns selected within the component have been randomised across the trial rows.

Select Randomised Subset

This will select a randomised subset of rows in the spreadsheet, based on the constraints you define. For example, imagine your spreadsheet contains a total of 6 easy and 6 hard trials, but you only want to present a random subset of 3 easy and 3 hard trials to each participant. To do this, you would add two subsets: Column = Difficulty, Value = easy, Number = 3; and Column = Difficulty, Value = hard, Number = 3, as shown in the screenshot below:

A screenshot of the spreadsheet within the game builder. Trials are assigned to either 'easy' or 'hard' difficulty.

Clicking the Preview Randomisation button shows one possible randomisation of the spreadsheet under these constraints:

A screenshot of the spreadsheet in the game builder. Three trials from each Difficulty classification have been selected.

Combining Randomisation Components

To achieve more complex types of randomisation, you can add multiple randomisation components to your spreadsheet. For example, imagine you have 2 blocks of trials, a block of easy trials and a block of hard trials, and you would like to randomise the order the blocks are presented as well as the order of trials within each block. You can do this by adding a 'Randomise Trials by Column' component and a 'Randomise Blocks' component:

A screenshot of the spreadsheet in the game builder. The trials are split into Easy and Hard blocks and numbered 1 or 2. Two randomisation component have been added to the randomiser tab

Clicking the Preview Randomisation button shows one possible randomisation of the spreadsheet under both these constraints:

A screenshot of the spreadsheet in game builder in the randomisation preview. Both the trials and blocks have been randomised.

Using multiple spreadsheets


You can add as many spreadsheets to your game as you wish. To add a new spreadsheet, click the 'New Spreadsheet' button at the top-right of the spreadsheet tab. Enter a name for your new spreadsheet, and click 'Create'. You can then launch the Spreadsheet Builder, start with an empty spreadsheet, copy an existing spreadsheet, or upload a file.

The name of the spreadsheet you are currently viewing is displayed at the top of the Spreadsheet Tab:

A screenshot of the spreadsheet in the game builder. An arrow highlights the name of the spreadsheet name, 'spreadsheet1' at the top of the screen.

To toggle which spreadsheet you are viewing, click the name of the current spreadsheet. This will open a dropdown menu containing all your spreadsheets for this game. Select the spreadsheet you want to view:

A screenshot of the spreadsheet in the game builder. The dropdown menu is open, and showing the two spreadsheets in the game 'Spreadsheet1' and 'test'.

You can also use this menu to rename or remove the spreadsheet you are currently viewing.

When you preview your game, you can select which spreadsheet you want to use. Simply click Preview at the top-right of the Game Builder window and select the spreadsheet you want to use from the dropdown menu:

A screenshot of the pop-up window when the preview button is clicked. The dropdown menu shows the spreadsheet options in the game.

Stimuli


Stimuli are any media files (images, audio, videos, etc.) which you will present to participants during your game.

You can add, delete, and manage stimuli in the Stimuli tab. To add stimuli, click Add Stimuli at the top right:

A screenshot of the Stimuli Tab in the game builder. An arrow highlights the red 'Add Stimuli' in the top-right of the screen.

Browse the files on your computer and select the stimuli you want to upload. Once the stimuli have uploaded, you will see a preview of each stimulus. Stimuli are shown 10 to a page. To navigate between pages, use the arrows at the top of the Stimuli tab. Click 'Remove' next to a stimulus to delete it from your task:

A screenshot of the stimuli tab in the game builder. Two stimuli are shown, one image and one audio. There are two arrows, one highlights thee 'Remove' button and the other highlights the arrows to move between pages of stimuli.

You can search for specific stimuli by typing part of the filename in the Search box in the top-left. You can also filter stimuli by type (image, audio, video, and document) using the Filter icons at the top of the Stimuli Tab. Active Filters are displayed in red, while inactive filters are displayed in black. Toggle whether a filter is active or inactive by clicking it.

There are two main ways to incorporate stimuli in your game. If you need the same stimulus to display for all trials and for all participants (e.g. in an instructions scene), create an object in that screen with the appropriate component (e.g. Sprite component), and then 'choose...' dialogue to pick the stimulus you want to display:

If on the other hand, you want the stimulus to change trial by trial, you will instead need to bind the component you have created to a column in the spreadsheet. You would then fill in this column with the filenames of the stimuli you want to show on each trial:

A screenshot of the spreadsheet tab within the Game Builder. The cells are highlighted green and contain the names of stimulus filenames.

Manipulations


Manipulations allow you to change setting on your game from within the experiment tree. You can use manipulations to implement between-participant conditions in your experiment.

To add a manipulation, navigate to the task setting you want to manipulate. For example, imagine you want to use a manipulation to vary the time limit on a scene between participants. Go to the relevant scene and click the Screen tab to find the Time Limit component. Then click Bind :

Screenshot of a Time Limit component. The Bind button (link icon to the right of the Time Limit setting) is highlighted

Click Manipulation. From the dropdown menu, select 'Create new...' Type a name for your manipulation into the box that appears:

Screenshot of binding to a new manipulation called 'TimeLimit' in the binding dialogue in Game Builder

Click Bind to apply the binding. Your setting will change to show that it's now bound - the blue M indicates that it is bound to a manipulation:

Screenshot of the Time Limit setting after binding, with the text 'TimeLimit' and a blue M icon

You can find more information about binding to manipulations, including how to configure manipulations in the Experiment Tree, in our Binding Guide.

To view all manipulations set up on your game, go to the Settings tab on the left and click Manipulations. Here, you can delete any manipulations you are no longer using by clicking the bin icon on the left of each manipulation. You can also add a description for your manipulation, set its Label and Key, define Options, and set up a default value.

Screenshot of the Settings tab, with Manipulations selected. Below are the settings for the TimeLimit manipulation

Label: This is the name of your manipulation, as it will appear in all configuration menus.

Description: Use this to add a description of your manipulation and its possible values.

Key: This is the name of your manipulation, as it will be referred to in Gorilla's underlying code. By default, the Key is identical to the Label. You will need to use the Key if you refer to your manipulation within a script.

Default: Use this to set a default value for your manipulation. This value will be used if you do not set a value manually within the Experiment Tree.

Options: Here, you can define options for the values of your manipulation. If you define options, these options will show up as a dropdown menu when you set up your Game in the Experiment Tree. If you do not define options, then you will enter the value of the manipulation in a free text field when you set up your Game in the Experiment Tree.


Store


The Store is a place to save participant data that you want to use later in the game or the experiment: for example, responses and accuracy scores. Each piece of data that you save in the Store will be saved in a named Field, so that you can retrieve it and use it later. If you're already familiar with Gorilla's older tools, this is analogous to what was previously called embedded data.


Saving data to the Store


For example, imagine that you want to save participants' number of correct responses during a game. Navigate to the scene where you collect participants' responses and click the Screen tab. The first step would be to set up a Scorer component so that participants' responses can be marked as correct or incorrect. Once your Scorer component is set up with the correct answers, click Add Component, select Save Accuracy (under Response Handling), and click 'Choose'. Click +Add next to Destinations. Under Attribute, select which aspect of participant accuracy you want to save. In this case, the accuracy of Correct responses are stored. When you have selected an attribute, under 'Field', click 'Set...' Create a new Field, give it a name, and click 'Bind'. Repeat this for any other attributes of accuracy you want to save. In the screenshot below, the Save Accuracy component is set up to save the participant's number of correct responses in the Store field 'Correct', and the participant's total number of trials in the Store field 'Total' - the orange F indicates that each is bound to a field in the Store.

In the example above, we have left the Tag fields blank. Tags are most useful when you have scenes with more than one response. You can read more about Response Tagging in the Response Processing guide.


Retrieving data from the Store


Now, navigate to the scene where you want to retrieve and display the values of these Store fields. You can directly bind a component to a Store field. You can see another example of how to do this in the Binding Guide.

In the example below, a series of Text components have been used to show participants the number of trials they got correct:

If you preview the task, you can see how this will display to a specific participant:

Screenshot of the participant's view when previewing the game. Text reads: 'You scored 5 out of 8.'

To view all Store fields currently being saved in your game, go to the Settings tab on the left and click Store in the top bar:

Screenshot of the Settings tab with Store selected, showing Store fields with 'Local' switch set to off

Here, you can view and change the names of your Store fields. You can also delete any Store fields you are no longer using by clicking the bin icon on the left of each one. Finally, you can toggle whether fields are stored locally to the game, or globally to the experiment. This distinction matters if you are using the same Game node multiple times within an Experiment Tree. If you want accuracy to be counted up separately for each version of the game, then you should select 'Local' for the relevant Store fields. By default, all fields are stored globally. This setting is appropriate for most cases.

You can find more information about binding to the Store in our Binding Guide.


Subsystems


The Subsystems tab contains information on which subsystems are currently enabled for your game. Subsystems are features that make use of browser hardware (e.g. audio, microphone, camera) that often require some explicit permission for the user to activate. Enabling a subsystem ensures that the system is correctly initialised and that any required permissions have been granted before starting your game.

When you add a component involving one of these subsystems (e.g. an Audio Clip) to your game, Gorilla will automatically enable the corresponding subsystem. You should therefore only need to visit this tab to disable subsystems that you are no longer using in your game. For example, if your game previously used audio, but you have now deleted all Audio Clip components and no longer require this subsystem, you can disable it here to avoid participants being asked for permissions that are no longer required.

Update (Jan 2024): Subsystem checks will now run only once per participant within an experiment. Previously, subsystem checks would run before every task that required that subsystem, and again if the page was reloaded, which was repetitive and frustrating for participants. Now, the initial subsystem check requiring user input will run once, at the beginning of the first task that has that subsystem enabled. Following this, when the participant enters another task or reloads the page, Gorilla will perform subsequent subsystem checks silently in the background; if these checks are successful, the participant will not have to repeat the full subsystem check.

A screenshot of the Subsystems tab within the Game Builder. The Audio subsystem is shown to be switched off.
Warning

For participants using the Safari browser, the fullscreen subsystem sometimes does not recognise when the participant has entered fullscreen mode. This means there is no way to progress the game beyond the initial screen when this subsystem is enabled. We are investigating this issue; in the meantime, we advise that you test your fullscreen game thoroughly across browsers, and consider either screening out participants using affected browsers or asking participants to trigger fullscreen mode manually.


Metrics


The Metrics tab can only be used in conjunction with scripting. A guide to scripting in Game Builder is coming soon!


Multiplayer


Coming Soon!

This is where you can activate Multiplayer mode in your game, allowing several participants to take part interactively. Read more about Multiplayer in our Multiplayer Guides.


Animation Tool


Animation is the main way to create movement in the Game Builder. You can animate any objects in the Game Builder that have an Animator component added to them. The Animator component can be found in the Object Builder Menu under the 'Animation tab', or by using the search bar:

The Object builder menu is open in the Game Builder, within the Animation Tab. The components Animate On Response, Animate on Response Accuracy and Animator can be seen. The animator component has been added to the object.

Once the Animator component has been added to an Object, you can start creating animations by clicking 'Open Animation Tool':

A screenshot of the Objects tab in the Game Buider. The object has Sprite and Animator components. An arrow highlights the red Open Animation Tool button within the Animator component.

The animation tool is divided into three sections:

A screenshot of the animation tool in the game builder. The three sections of the tool are highlighted in yellow, green and blue.

Clip Panel


The Clip Panel highlighted in yellow above shows your list of clips. You can also add new clips to your Animations by clicking the '+ Add Clip' button in this panel. The selected clip will be highlighted in red:

A screenshot of the Animation tool in the Game Builder. The selected clip 'MovingRocket' is highlighted in red.

Timeline Editor


The Timeline Editor, the green section above, shows all the Animation Channels and individual Animations that make up the selected clip. To add more animations, click the '+ Add Animation' button in this panel. These animations are arranged in a timeline, which show the sequence of animated events. Within the Timeline editor, you can rearrange the position of the individual animations within the timeline. To do this, click and drag the grey section of the animation you would like to move. You can also add Channels here, which allow multiple animations to play simultaneously. To delete Animations or Channels, click the bin icon. These features are shown in the video below:

Note the grey bars beneath each animation. These are visual representations of the duration of the animations; animations will be laid out horizontally according to their duration. This is particularly useful if you have multiple channels, making it easier to visualise if each animation lines up correctly. Read more about animations with multiple channels in the next section of this guide. You can change the duration of animations in the Animation Editor panel.

To remove an entire clip from the Animation Tool, click the three-dots menu next to the animation name. You can also rename clips in this way, too:

A screenshot of the animation tool in the game builder. The three-dots menu has been clicked, and displays the options to remove or rename the clip. An arrow highlights this three-dots menu.

Animation Editor


The Animation Editor is highlighted in blue at the top of this page. Here, you can configure the currently selected animation. Choosing an animation from the Timeline Editor will bring up its configuration options in this panel. You can read more about how to configure the Animations in the Animation Guide.


Creating Animation


Animation is organised into clips, where each clip is a sequence of individual animations. To start creating a new clip, open the Animation Tool, click '+ Add Clip' and type a name for the animation. In this example, the animation will be called 'MovingRocket'. It is good practice to give your animations meaningful names, so you can easily identify different animations you create. Click Confirm to start adding animations:

A screenshot of the Animation Tool in the Game Builder. A pop-up window shows where to name the animaiton. An arrow highlights the 'Add Clip' button on the left.

Then, you can start building your animation by clicking '+ Add Animation':

A screenshot of the Animationtool in the game builder. An arrow highlights the red 'Add Animation' button in the middle.

A scrollable window will then show you all the available animations within the Game Builder. When an animation is clicked on, a short description of the animation appears on the right-hand side. Once you have found an animation you would like to use, click Choose:

A screenshot of the animation window. All animations are listed on the left hand side, the Delay animation is selected, with a short description shown on the left.

When you have choosen the animation, it will appear in the Animation Tool.

In this example, an animation is created that makes the rocket sprite Delay, then Move to a Position in the scene, and then Pulse in size. Once these animations have been added and configured, you can view the sequence of events in the Animation Tool:

A screenshot of the animation tool, the animations shown are Delay, Move to Position, Pulse.

When previewed, the above animation will look like this:


Using Multiple Channels

A clip can contain multiple channels which will be played simultaneously - this is useful if you want multiple animations to take place at the same time. In this example, we would like the Sprite to move and spin at the same time. To do this, click the 'Add Channel' button in the Animation Tool and add your second channel of animations:

A screenshot of the animator tool, there are two channels in the animator. An arrow highlights the Add Channel button at the bottom of the window.

The above animation with multiple channels will look like this in the Game Builder:


Previewing Clips


Once you have created a clip, close the Animation Tool and click the little Play button in the Object Editor. This will trigger the animation to play.

A screenshot of the Object Editor in the game builder. The play button next to the MovingRocket animation in the Animator in the Animation component, is highlighted with an arrow.

To make changes, open the Animation Tool again, tweak, and then preview the animation again to see your changes.

You can also preview the entire scene, including animations by selecting the animation to 'Play on Start' from the dropdown menu within the Object Editor. Then, you can use the Play button in the Screen preview to view the entire scene:

A screenshot of the game builder. An arrow highlights the 'Play on Start' field within the Animation component. ANother arrow highlights the Play button at the top of the screen preview.

Triggering Animations


There are several ways to trigger animations in the Game Builder:

On Start


All Animator components have a 'Play on Start' setting. You can select the name of a clip here from the dropdown menu. In doing this, the animation will play as soon as the screen starts.

A screenshot of the game builder. An arrow highlights the 'Play on Start' field within the Animation component.

When a response is submitted


Animate on Response

When a response is submitted, you can trigger an animation based on the specific response given by a participant, by adding an Animate on Response component to Objects with Animators. Use the 'Response' field to state a specific response, or use the bind icon to bind the response to the spreadsheet (or other source).

A screenshot of the game builder. The Animate on Response component is added to the Object. An arrow highlights the binding icon to the left of the component

Animate on Response Accuracy

Alternatively, you may want to trigger an animation when a correct or incorrect response is submitted by participants. To do this, you can add an Animate on Response Accuracy component to the Object instead. Using this component, you can set different animations to be triggered depending on whether a correct or incorrect response is submitted. Choose the animation from the dropdown menus. By setting the 'Self Only' configuration setting, the animations will only be triggered if the response was generated by another component within the same object containing the animation.

A screenshot of the game builder. The Animate on Response Accuracy component is added to the Object. The drop downmenus to animate on correct / incorrect responses are highlighted with arrows.

When triggered by another animation


You can also trigger an animation clip on a different object from the one that is currently animating. Use this to 'daisy-chain' animations together, so that one object animation can trigger the animation of another. Unlike the previous ways of triggering animations, this method is controlled from within the Animation Tool, rather than by additional components. To create a 'chain' of reactions in this way, open the Animation Tool and add a 'Trigger Animation' animation. In the example below, another animation will be triggered once the Pulse animation has finished. From the 'Target' dropdown, you can select which Object in the scene you would like to animate, and use the 'Clip' dropdown to choose the animation. Please note that the dropdown menu will only present Objects with an Animator component of their own, and clips that have been created in these Animators.

A screenshot of the animation tool in the game builder. The trigger animation has been added. Two arrows higlight the Target and Clip dropdown menus in the Animation Editor panel.

There is also an animation called Delay which you can use to insert time delays in your animation sequences. This is often useful to choreograph animations to work together, or to simply space out sequences.


Scripts


A guide to scripting in the Game Builder is coming soon!