Cyberball 4.0: User Manual


User Manual for Cyberball 4.0

[beta]

January, 2012

Kipling D. Williams

David Scott Yeager

Christopher K.T. Cheung

Wilma Choi

Citation:

Williams, K.D., Yeager, D.S., Cheung, C.K.T., & Choi, W. (2012). Cyberball 4.0 [Software]. f

Contact information:

Kipling Williams:

David Yeager:

Help with Cyberball 4:

Overview

Cyberball 4.0 is a program designed to study ostracism. It can be downloaded here:

A history of the program can be found here:

Cyberball 4.0was designed to create a “future proof” version of theCyberball 3 program. It runs using HTML5. Just like any other website, it first needs to be saved on a web server that you control. Then it will run in a browser on any web-enabled device, including any computer (Mac, PC, Linux, etc), any smartphone (such as the iPhone) and any tablet (such as the iPad). It has the capability of every previous version of Cyberball, including the ability to:

-Play with 3 or 4 players, with all of the setting files that appeared in Cyberball 3

-Change the names and pictures of the players

-Save log files of every throw in the game, with time stamps

It also adds new features, such as:

-Settings (names, pictures, conditions) that are set in a URL, so that they can be passed on from software that randomly assigns parameters, such as MediaLab or Qualtrics.

-An optional chat box, with comments logged in a log file

-A “spectate” version that allows a player to watch Cyberball being played

-The participant can click anywhere on another player to throw the ball

-Other features that are in development…

For an example of an installed version, see:

Cyberball 4 is free and open source, with the stipulation that this manual is cited in publications.

For more background, see:

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.
Contents of User Manual

File structure on the Server

Contents and function of each folder/file

URL Parameters

Event Timing

Merging the Logs

Running the Cyberball Program

Changing the settings files......

Installing Cyberball on a PHP-enabled Server

Installing on a web host so it runs as a website (preferred method)

Installing on your own computer

File structure on the server

The file structure on the web server should be as follows in order for the game to work. The blue boxes represent files. The others represent directories/folders.


Contents and function of each folder/file

The contents and function of each folder is as below:

  • Images – Contains images used in the game.
  • spriteImages – Contains the images needed for Players and the ball. It also contains javascript files needed to animate them.
  • Js – Contains javascript files needed for jQuery, easelJS and Tweening.
  • Css – The css stylesheets for the game.
  • Logs – All the user logs are uploaded to this folder after the game is over. It also contains the following files other than csv logs. The PHP server process needs to have write permissions to this folder in order to be able to save the logs.
  • Merge.php – This file is used to merge all the logs currently present into a single .csv file.
  • Schedules – Contains the Schedule files which will be used by the computer players for each setting of the game. These schedules are the same as Cyberball v3.0. The files are:
  • all include 3.txt
  • all include 4.txt
  • change of heart 4.txt
  • just one 3.txt
  • just one 4.txt
  • ostracize other 3.txt
  • ostracize other 4.txt
  • ostracize subject 3.txt
  • ostracize subject 4.txt
  • two against two 4.txt
  • Settings – Contains the Settings files that are to be used for each type of game. The game uses only the values of Total Throws and Schedule from these files. The game ends after the ball has been thrown for the number of times specified by Total Throws. The value of Schedule if used to fetch the Schedule file from the server. The settings files are:
  • 3pl - all include.txt
  • 3pl - just one.txt
  • 3pl - ostracize other.txt
  • 3pl - ostracize subject.txt
  • 4pl - all include.txt
  • 4pl - change of heart.txt
  • 4pl - just one.txt
  • 4pl - ostracize other.txt
  • 4pl - ostracize subject.txt
  • 4pl - two against two.txt
  • saveLog.php – This file is used to send user log data from flash to the server. It saves the log data to the logs directory in the format <userid_timestamp>.csv
  • index.htm – Used as the title/intro screen (this can be edited to suit your own settings files)
  • cyberball.htm – Used to embed and play the game. Title screen links to this file.

URL Parameters

The various parameters used in the URL are as follows:

No. / Parameter / Valid Value(s) / Invalid Values / Description
1 / userid / Any string of characters. / This value will be used to create the log csv file.
2 / settings /
  1. 3plall
  2. 3pljo
  3. 3ploo
  4. 3plos
  5. 4plall
  6. 4plcoh
  7. 4pljo
  8. 4ploo
  9. 4plos
  10. 4pltat
/ Any other / The game will fetch the respective settings and schedule from the server
(Note: the names of the settings parameterson the left correspond to the settings and schedule files listed above in the same order)
3 / pics / true / Any other / If set to true, the game will display images besides the player cartoons.
4 / pic1 / Any valid image URL / The URL of the image to be displayed besides player one’s cartoon
5 / pic3 / Any valid image URL / The URL of the image to be displayed besides player three’s cartoon
6 / pic4 / Any valid image URL / The URL of the image to be displayed besides player four’s cartoon
7 / chat / true / Any other / If set to true, the game will display a chat box in which the user can enter messages.
8 / p1name / Any string of characters / This value will be shown as the name of player one
9 / P2name / Any string of characters / This value will be shown as the name of player two
10 / p3name / Any string of characters / This value will be shown as the name of player three
11 / p4name / Any string of characters / This value will be shown as the name of player four
12 / spectate / true / Any other / If set to true, the game will start in spectator mode [schedule will play; player will throw randomly]

Event Timing

Various timed events in the game are:

  1. The “Connecting to other Players” screen is displayed for a random number of seconds between 5 and 7.
  2. Player One sends the chat message “Hey!” after a random number of seconds between 3 and 5 after the game starts.
  3. The computer players throw the ball after a random number of seconds between 0 and 4 once they have the ball in hand.

Merging the Logs

To merge the logs, make sure that the file named merge.php is in the logs folder as stated previously and then enter its URL in the browser’s address bar. For example:

All the log files will be merged and a single file will be provided as a download.

Running the Cyberball Program

Open the URL (such as in the browser.

You will be presented with the following screen.

Click on the “Start Playing Now” link. The game will now start and will connect to other online players playing cyberball.

Once connected, you will be taken to this screen.

The actual screen you see may vary depending on the server settings and the game version.

You can send messages to other players using the chat box.

The ball can be thrown to any other player by clicking on their image or on their cartoon.

Changing the settings files

In order to randomly assign participants to the settings that you are interested in studying, you will change the settings in the URL.

You can change the settings files by editing the link in the “start playing now” text on the index.htm file (e.g., in Dreamweaver) saved on your server. Then when participants click the “start playing now” link it will take them to the setting that you want.

Or if you want participants to skip the index “welcome” page, you can edit the URL directly and then assign participants to the desired URL.

For instance, this version of a three-player ostracism setting has a chat box:

This version of a three-player ostracism setting set the chat box to “false” and has no chat box:

And this version has no chat box and is the three player “inclusion” condition:

You can make analogous changes to any of the parameters outlined above on page 5.

Installing Cyberball(on a PHP-enabled Server)

Cyberball 4 is designed to run as a website that is hosted on a server, but it can run on a local computer. “Installing” it just requires copying the files to a folder, just like any other website. There is no “installation” program.

However, in order to function properly, Cyberball needs to be run from a PHP-enabled server or computer. This is because the “merge logs” and “save logs” functions use PHP code.

Installing on a web host so it runs as a website (preferred method)

To install Cyberball, copy all the files to a folder (e.g. cyberball) on your web server.

The web host must support hosting PHP files. If you are at a university or a business, email your IT guy to see if your server runs PHP. If they say “no” ask how you can get access to one.

Installing on your own computer

Cyberball can also be run from your local machine, but it requires some software installation. To install Cyberball, copy all the files to a folder on your computer.

Your computer must support PHP files.

PHP can either be installed into Apache or IIS depending on whether the local machine is running Linux or Windows. PHP installation instructions can be found at:

Other out of the box solutions are also available for major platforms. They are:

  1. LAMP - Linux
  2. WAMP - Windows
  3. XAMPP – Cross platform

Page 1 of 12