Return to the Cyberball 5 page
___________________________________________________________________________________________________________________

											Cyberball Version 5
___________________________________________________________________________________________________________________

Script Author:	David Nitz for Millisecond Software, LLC
Date:			08-02-2021
Date:			08-02-2021
Last updated:	08-02-2021 by David Nitz for Millisecond Software, LLC

Script Copyright © 08-02-2021 Millisecond Software, LLC

For questions about this script, please contact support@millisecond.com.
___________________________________________________________________________________________________________________
BACKGROUND INFO
___________________________________________________________________________________________________________________
This script implements Kip Williams's Cyberball game (version 5) used in research on ostracism, social exclusion, 
rejection, bullying, or discrimination.

References for Cyberball:
Cyberball 5 Manual, App version 5.4.0.2, Manual version 1.3, last updated 1/9/2019. 
Retrieved from https://www.empirisoft.com/cyberball/Manuals/Manual_for_Cyberball_5_v5402.pdf.

Cyberball App version 5.4.0.2 source code retrieved from https://www.empirisoft.com/cyberball.aspx.

Announcement page for Cyberball 5. https://www3.psych.purdue.edu/~willia55/Announce/cyberball.htm

Literature:
Williams, K. D., Cheung, C. K. T., & Choi, W. (2000). CyberOstracism: Effects of being ignored over the Internet. 
Journal of Personality and Social Psychology, 79, 748-762.

Williams, K. D., & Jarvis, B. (2006). Cyberball: A program for use in research on ostracism and interpersonal acceptance. 
Behavior Research Methods, Instruments, and Computers, 38, 174-180.

Hartgerink, C. H. J., van Beest, I., Wicherts, J. M., & Williams, K. D. (2015). The ordinal effects of ostracism: 
A meta-analysis of 120 Cyberball studies. PloSONE, 10. e0127002. doi: 10.1371/journal.pone.0127002

****NOTE****
Due to technical limitations, chat/message functionality is NOT available in this implementation.

___________________________________________________________________________________________________________________
TASK DESCRIPTION
___________________________________________________________________________________________________________________
Cyberball is a virtual ball-tossing game that can be used in research on ostracism, social exclusion, or rejection. 
It has also been used to study discrimination and prejudice (in these instances, Cyberball ball toss choices are 
used as Dependent Variable).

___________________________________________________________________________________________________________________
DURATION 
___________________________________________________________________________________________________________________
Duration will depend substantially on the chosen parameters, chiefly the total number of throws.
You can assume roughly 5 to 6 seconds per throw, i.e. a game consisting of 30 throws will take about 3 minutes to 
complete.

___________________________________________________________________________________________________________________
DATA FILE INFORMATION 
___________________________________________________________________________________________________________________
The default data stored in the data files are:

(1) Raw data file: 'cyberball5_raw*.iqdat' (a separate file for each participant)

inquisit.version, inquisit.build:	The specific Inquisit version used (the 'build') used to collect the data.
computer.platform:					The platform the script was run on (win/mac/ios/android).
date, time, 						Date and time script was run
subject, group, session				with the current subject id/group number/session number.

parameters.showavatars: 			Whether avatar images should be shown. Default is false. 
									Avatar images can be customized under item.playeravatars.
parameters.showstats: 				Whether basic on-screen throw statistics should be shown 
									(throws taken and made by the human player, total throws).
									Default is false.
parameters.nplayers: 				Number of players in the given game. Default is 3.
									The script supports 3- to 9-player games.
parameters.nthrows: 				Number of throws to be made during the game.
parameters.spectate: 				Whether the human player should only "watch" the game being played.
									When set to true, the computer takes over controlling player 2, 
									making random throws to the other players. A "spectate" condition is often 
									used as a control condition. Default is false.
parameters.scheduletype: 			Whether the script should administer an "ostracize", "include", or "custom"
									schedule.
parameters.ostracism_target: 		Applies when running an "ostracize" schedule. Number of the player being 
									excluded by the other players. Default is 2 (human player).
parameters.ostracism_mode: 			Applies when running an "ostracize" schedule. Determines the degree to which 
									the target is ostracized.
									0 = target receives 0 throws from the NPCs.
									1 = target receives 1 throw from the NPCs, early in the schedule.
									2 = target receives 2 throws frm the NPCs, early in the schedule.
									You may set higher values. Make sure to increase parameters.nthrows commensurate 
									with the chosen setting. E.g. for a schedule comprising only 10 throws, it may 
									not be possible to actually achieve two throws to the target early on. Achieving 
									5 throws to the target would be downright impossible and would also make the 
									schedule something that is not actually an ostracism schedule.
parameters.customschedulenumber:	Index number of the custom schedule; applies when parameters.scheduletype is set to "custom".
									Default is 1. For information on how to assign different custom schedules to different 
									between-subjects conditions, see section SCHEDULING LISTS and the example expt elements 
									#4 and #5 in this script.
parameters.throwmode:				"speed" or "duration"
									"speed" => ball travels at constant speed: 
									A throw will take longer between two players that are farther apart than between two 
									players that are closer together, since the ball will have to travel a longer (relative) 
									distance.
									"duration" => ball travels with constant duration:
									Throws between players that are farther apart take the same amount of time as throws between 
									two players that are closer togehter, i.e. the ball will travel at higher relative speed 
									between the two more distant players.
									Defaults is "duration".
parameters.throwspeed:				Relative speed of the ball when parameters.throwmode is set to "speed".
									Expressed as fraction of horizontal display area traversed per second.
									0.25 => quarter of horizontal screen aread traversed in one second.
									0.5 => half the horizontal screen area traversed in one second.
									1 => entire horizontal screen area traversed in one second.
									Default is 0.45.
parameters.throwduration:			Constant duration of a throw when parameters.throwmode is set to "duration".
									Given in milliseconds. Default is 900.

blocknum, blockcode:				The number and name of the current block (built-in Inquisit variable).
trialnum, trialcode: 				The number and name of the currently recorded trial (built-in Inquisit variable).
									Note: trialnum is a built-in Inquisit variable; it counts all trials run; even those
									that do not record data to the data file such as feedback trials. Thus, trialnum 
									may not reflect the number of main trials run per block.
response:							The participant's response (player selection).
latency: 							The response latency in milliseconds.

values.received_from: 				Whom the current ballholder received the ball from.
values.ball_at: 					The current ballholder.
values.throw_to: 					Whom the current ballholder chose to throw the ball to.
expressions.throwdistance_mm:		Distance covered by the current throw in mm.
expressions.throwduration_s:		Duration of the current throw in seconds.
expressions.throwspeed_mm:_s		Realized throw speed in mm/s.
values.delay: 						Delay after which the throw was executed.
values.player2received:				Running count of times player 2 (human) received the ball.
values.player2thrown:				Running count of times player 2 (human) threw the ball.
values.throwcount: 					Running count of realized throws.
values.deprecated: 					Running count of deprecated throws.
values.generatedThrowSchedule: 		A text string recording the generated throw schedule, or -- in the case of custom 
									schedules -- the experimenter-entered custom schedule. 
									For details, see section SCHEDULING LISTS.
values.realizedThrowSchedule: 		The realized throw schedule, including the choices maded by the human player, across 
									the progression of the game.
expressions.width_mm				Width of the used screen area in mm.
expressions.height_mm				Height of the used screen area in mm.

(2) Summary data file: 'cyberball5_summary*.iqdat' (a separate file for each participant)

inquisit.version, inquisit.build:	The specific Inquisit version used (the 'build') to collect the data.
computer.platform:					The platform the script was run on (win/mac/ios/and).
script.startdate:					Date script was run.
script.starttime:					Time script was started.
script.subjectid:					Assigned subject id number.
script.groupid:						Assigned group id number.
script.sessionid:					Assigned session id number.
script.elapsedtime:					Time it took to run script (in ms); measured from onset to offset of script.
script.completed:					Whether the script was completed or terminated prematurely.
									0 = script was not completed (prematurely aborted). 
									1 = script was completed (all conditions run).
parameters.showavatars: 			Whether avatar images should be shown. Default is false. 
									Avatar images can be customized under item.playeravatars.
parameters.showstats: 				Whether basic on-screen throw statistics should be shown 
									(throws taken & made by the human player, total throws).
									Default is false.
parameters.nplayers: 				Number of players in the given game. Default is 3.
									The script supports 3- to 9-player games.
parameters.nthrows: 				Number of throws to be made during the game.
parameters.spectate: 				Whether the human player should only "watch" the game being played.
									When set to true, the computer takes over controlling player 2, 
									making random throws to the other players. A "spectate" condition is often 
									used as a control condition. Default is false.
parameters.scheduletype: 			Whether the script should administer an "ostracize", "include", or "custom"
									schedule.
parameters.ostracism_target: 		Applies when running an "ostracize" schedule. Number of the player being 
									excluded by the other players. Default is 2 (human player).
parameters.ostracism_mode: 			Applies when running an "ostracize" schedule. Determines the degree to which 
									the target is ostracized.
									0 = target receives 0 throws from the NPCs.
									1 = target receives 1 throw from the NPCs, early in the schedule.
									2 = target receives 2 throws frm the NPCs, early in the schedule.
									You may set higher values. Make sure to increase parameters.nthrows commensurate 
									with the chosen setting. E.g. for a schedule comprising only 10 throws, it may 
									not be possible to actually achieve two throws to the target early on. Achieving 
									5 throws to the target would be downright impossible and would also make the 
									schedule something that is not actually an ostracism schedule.
parameters.customschedulenumber:	Index number of the custom schedule; applies when parameters.scheduletype is set to "custom".
									Default is 1. For information on how to assign different custom schedules to different 
									between-subjects conditions, see section SCHEDULING LISTS and the example expt elements 
									#4 and #5 in this script.
parameters.throwmode:				"speed" or "duration"
									"speed" => ball travels at constant speed: 
									A throw will take longer between two players that are farther apart than between two 
									players that are closer together, since the ball will have to travel a longer (relative) 
									distance.
									"duration" => ball travels with constant duration:
									Throws between players that are farther apart take the same amount of time as throws between 
									two players that are closer togehter, i.e. the ball will travel at higher relative speed 
									between the two more distant players.
									Default is "duration".
parameters.throwspeed:				Relative speed of the ball when throwmode is set to "speed".
									Expressed as fraction of horizontal display area traversed per second.
									0.25 => quarter of horizontal screen aread traversed in one second.
									0.5 => half the horizontal screen area traversed in one second.
									1 => entire horizontal screen area traversed in one second.
									Default is 0.45.
parameters.throwduration:			Constant duration of a throw when throwmode is set to "duration".
									Given in milliseconds. Default is 900.
values.player2received:				Count of times player 2 (human) received the ball.
values.player2thrown:				Count of times player 2 (human) threw the ball.
values.throwcount: 					Count of realized throws.
values.deprecated:					Count of throw deprecations during the administration of the schedule.
values.generatedThrowSchedule: 		A text string recording the generated throw schedule, or -- in the case of custom schedules -- 
									the experimenter-entered custom schedule (plus potential padding). 
									For details, see section SCHEDULING LISTS.
values.realizedThrowSchedule: 		The realized throw schedule, including the choices maded by the human player, across 
									the progression of the game.
parameters.player1label to
parameters.player9label:			Labels assinged to players 1 to 9. Default is "Player 1" to "Player 9".
expressions.width_mm				Width of the used screen area in mm.
expressions.height_mm				Height of the used screen area in mm.
___________________________________________________________________________________________________________________
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________
(1)  Task:
- Participants engage in a ball-toss game with between 2 to 8 other (virtual) players.
- The virtual players' behavior can be configured in numerous ways, e.g. to exclude the participant or any of the 
virtual players, to include all players, and anything in between.

(2) End of Task:
- The task ends when the configured number of ball tosses has been reached.

(3) Instructions
- Instructions can be easily changed under EDITABLE INSTRUCTIONS.
- Some stimuli can be easily changed under EDITABLE STIMULI.

(4) Dependent Variables/Scores:
Data files record who threw the ball to whom, including the choices made by the human participant and 
computer-controlled players (NPCs), how long each throw was delayed, as well as general game settings and the 
type of schedule administered.

Typically, Cyberball is used as an independent variable, i.e. experimental manipulation to induce varying 
degrees of social inclusion or exclusion (ostracism). As such, it does not have traditional scores or dependent 
variables to report. 

When used as a dependent variable in studies of empathy, altruistic behavior, prejudice or discrimination, the 
variable of interest is the human player's throwing behavior (cf. Williams & Jarvis, 2006, p. 177).
___________________________________________________________________________________________________________________
INSTRUCTIONS 
___________________________________________________________________________________________________________________
Instructions are as provided in the original Cyberball 5 application.
Instructions can be easily changed under section EDITABLE INSTRUCTIONS.

___________________________________________________________________________________________________________________
EDITABLE CODE 
___________________________________________________________________________________________________________________
Check below for (relatively) easily editable parameters, stimuli, instructions etc. 
Keep in mind that you can use this script as a template and therefore always "mess" with the entire code 
to further customize your experiment.

The parameters you can change are:
/nplayers: 							Number of players in the given game. Default is 3.
									The script supports 3- to 9-player games.
/nthrows: 							Number of throws to be made during the game. Default is 30.
/spectate: 							true or false. Whether the human player should only "watch" the game being played.
									When set to true, the computer takes over controlling player 2, 
									making random throws to the other players. A "spectate" condition is often 
									used as a control condition. Default is false.
/scheduletype: 						Whether the script should administer an "ostracize", "include", or "custom"
									schedule.
/ostracism_target: 					Applies when running an "ostracize" schedule. Number of the player being 
									excluded by the other players. Default is 2 (human player).
/ostracism_mode: 					Applies when running an "ostracize" schedule. Determines the degree to which 
									the target is ostracized.
									0 = target receives 0 throws from the NPCs.
									1 = target receives max. 1 throw from the NPCs, early in the schedule (1st 25% of throws).
									2 = target receives max. 2 throws from the NPCs, early in the schedule (1st 25% of throws).
									You may set higher values. Make sure to increase parameters.nthrows commensurate 
									with the chosen setting. E.g. for a schedule consisting of only 10 or 15 throws, it may 
									not be possible to actually achieve two throws to the target early on. Achieving 
									5 throws to the target would be downright impossible, apart from transforming the 
									schedule into something that is not actually an ostracism schedule.
/custom_schedulenumber: 			Applies when running a "custom" schedule. The script can support multiple, different 
									custom schedules used in different between-subjects condition. When multiple custom 
									schedules are present, this parameter must be set to the appropriate schedule number
									/onexptbegin in the given between-subjects condition. See section SCHEDULING LISTS and
									the example expt elements #4 and #5 in this script.
/throwmode:							"speed" or "duration"
									"speed" => ball travels at constant speed: 
									A throw will take longer between two players that are farther apart than between two 
									players that are closer together, since the ball will have to travel a longer (relative) 
									distance.
									"duration" => ball travels with constant duration:
									Throws between players that are farther apart take the same amount of time as throws between 
									two players that are closer togehter, i.e. the ball will travel at higher relative speed 
									between the two more distant players.
/throwspeed:						Relative speed of the ball when parameters.throwmode is set to "speed".
									Expressed as fraction of horizontal display area traversed per second.
									0.25 => quarter of horizontal screen aread traversed in one second.
									0.5 => half the horizontal screen area traversed in one second.
									1 => entire horizontal screen area traversed in one second.
									Default: 0.4
/throwduration:						Constant duration of a throw when parameters.throwmode is set to "duration".
									Given in milliseconds. Default: 900
/showavatars: 						true or false. Whether avatar images should be shown. Default is false. 
									Avatar images can be customized under item.playeravatars.
/showstats: 						true or false. Whether basic on-screen throw statistics should be shown 
									(throws taken & made by the human player, total throws).
									Default is false.
/player1label to
/player9label:						Labels for players 1 to 9.

/player1labelColor to
/player9labelColor: 				Colors of the labels for players 1 to 9.