User Manual: Inquisit Pizza Game


___________________________________________________________________________________________________________________	

											*Pizza Game*
___________________________________________________________________________________________________________________	

Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
Date: 03-07-2022
last updated:  07-22-2022 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 07-22-2022 Millisecond Software

Millisecond Software thanks Dr. Jan Keil for his ample support in creating this script!
Any mistakes and errors that this script may contain, however, are Millisecond's alone.

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________	

The 'Pizza Game' is a virtual public goods game to assess cooperative behavior in children and adolescents
(Keil et al, 2017). The 'Pizza Game' is not a true multi player game but simulates the behavior of coplayers
with computer algorithms while pretending that participants play against real people.
The original 'Pizza Game' app runs in German and was initially programmed in e-prime.
It was later re-programmed by [programmer name]. This updated version of the Pizza Game - 
used by the lab of Dr. Jan Keil- incorporates a selfie-app to increase the real-life validity of the task.
For more information regarding the original Pizza Game implementation contact 
Dr. Keil at jan.keil@medizin.uni-leipzig.de.

This specific script implements an Inquisit version of the 'Pizza Game'.
It can be played with real participant images - however this implementation does not incorporate a selfie-app.
More information on how to incorporate real player images see below.


Reference:
Keil, J., Michel, A., Sticca, F. et al. The Pizzagame: A virtual public goods game to assess cooperative behavior 
in children and adolescents. Behav Res 49, 1432–1443 (2017). 
https://doi.org/10.3758/s13428-016-0799-9

___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________	

The basic game setup is as follows:
Participant are told that they play a game with 2 fellow players that evolves around collecting
slices of pizzas: The more slices of pizza the better.
Each player receives 9 slices of pizza at the start of each new game round. 
Each player then has to decide how many slices of pizza to keep (safely)
at home and how many slices of pizza to contribute to a 'public share plate' at school.

Home: pizza is 'safe' (home pizza slices cannot be taken away) 
School: slices of pizza are pooled and teacher contributes half of the collected slices.
The total number of slices of pizza are then divided up amongst the three players
=> depending on how many slices of pizza are contributed by all the players, each player can end up with
more, fewer or the same number of pizza slices compared to the start amount (9)

Examples:
1) None of the players contribute ('non-cooperative' or 'selfish')
school: 3*0 = 0; 0/2 = 0 (0+0)/3 = 0 
=> each player receives 13.5 pizza slices from school => 9 (home) + 0 (school) = 9 (9-9 = 0 => no gain, no loss)

2) 2 players contribute 0 slices of pizza and one player contributes 9 slices. ('exploitative' or 'divergent')
school: 1*9 = 9; 9/2 = 4.5; (9+4.5)/3 = 4.5 
=> each player receives 9 pizza slices from school 
=> cooperative player: 0 (home) + 4.5 (school) = 4.5 (4.5-9 = -4.5 => loss)
=> exploitative players: 9 (home) + 4.5 (school) = 13.5 (13.5-9 = 4.5 => net gain)

3) All players contribute 9 slices of pizze ('cooperative').
school: 3*9 = 27; 27/2 = 13.5; (27+13.5)/3 = 13.5 
=> each player receives 13.5 pizza slices from school => 0 (home) + 13.5 (school) = 13.5 (13.5-9 = 4.5 => net gain)


Participants play 3 games with 4 rounds each. Each game is played with different 'players'.
The first game is run with cooperative players, the second one is run with uncooperative players,
and the third game is run with one exploitative player.

___________________________________________________________________________________________________________________	
DURATION 
___________________________________________________________________________________________________________________	
the default set-up of the script takes appr. 15-20 minutes to complete
___________________________________________________________________________________________________________________	
DATA FILE INFORMATION 
___________________________________________________________________________________________________________________		
The default data stored in the data files are:

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

build:							The specific Inquisit version used (the 'build') that was run
computer.platform:				the platform the script was run on (win/mac/ios/android)
date, time: 					date and time script was run 

subject: 						current subjectid
								Note: to run script with player images
								1) use subjectids that start with 'i' (Example: i_102)
								2) the player images need to be added to the script folder 
								as '*.png' files with the subjectid as the name BEFORE start of the script

group:							group1 = runs generic avatar setup
								group2 = runs female, agegroup1 stimuli
								group3 = runs female, agegroup2 stimuli
								group4 = runs male, agegroup1 stimuli
								group5 = runs male, agegroup2 stimuli


session:						with the current session id

blockcode, blocknum:			the name and number of the current block (built-in Inquisit variable)
trialcode, trialnum: 			the name and number 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 store data to the data file. 
										
//built-in DVs (record for any data recording trial)
response:						the participant's response
correct:						accuracy of response: 1 = correct response; 0 = otherwise (if applicable)
latency: 						the response latency (in ms); measured from: onset of trial


//Demo Data: 
correctResponse_q1:				stores the correct response for q1 (0 = none, 1 = button1, 2=button2, 3=button3, A = All)
q1_rsp:							stores the selected response for q1
q1_ACC:							see trialcode 'compQuestions_end': 1 = comprehension question 1 answered correctly; 0 = otherwise

correctResponse_q2:				stores the correct response for q2 (0 = none, 1 = button1, 2=button2, 3=button3, A = All)
q2_rsp:							stores the selected response for q2
q2_ACC:							see trialcode 'compQuestions_end': 1 = comprehension question 2 answered correctly; 0 = otherwise

correctResponse_q3:				stores the correct response for q3 (0 = none, 1 = button1, 2=button2, 3=button3, A = All)
q3_rsp:							stores the selected response for q3
q3_ACC:							see trialcode 'compQuestions_end': 1 = comprehension question 3 answered correctly; 0 = otherwise


//Test Game Data (see trial.test_decision)
game:							1, 2 or 3 
gameCondition:					"cooperative", "selfish", "divergent"

roundCount:						counts the number of rounds per game (1-4)

coplayer1_image:				the image presented for coplayer1 (on the left)
coplayer1_name:					the name selected for coplayer1
start_player1:					the number of pizza slices at the start of the round
school_player1:					the number of pizza slices that coplayer1 takes to school
home_player1:					the number of pizza slices that coplayer1 keeps home

coplayer2_image:				the image presented for coplayer2 (on the right)
coplayer2_name:					the name selected for coplayer2
start_player2:					the number of pizza slices at the start of the round
school_player2:					the number of pizza slices that coplayer2 takes to school
home_player2:					the number of pizza slices that coplayer2 keeps home

participant_image:				the image presented for participant (in the middle)
participant_name:				the name used for participant
start_participant:				the number of pizza slices at the start of the round
school_participant:				the number of pizza slices that participant takes to school
home_participant:				the number of pizza slices that participant keeps home


schoolcontribution:				the sum of the all the pizza slices brought to school
teachercontribution:			the number of pizza slices the teacher contributes
totalpizza:						the combined number of pizza slices (teacher contribution + slices brought in by the kids)
takehomepizza:					the number of pizza slices that each kid can take home

final_player1:					the total number of pizza slices for player1 (home + takehomepizza) at the end of the current round
final_player2:					the total number of pizza slices for player2 (home + takehomepizza) at the end of the current round
final_participant:				the total number of pizza slices for participant (home + takehomepizza) at the end of the current round

//the collected number of pizza slices (participant) by game and round
game1_r1: 						the collected number of pizza slices in round1 of game1 ('cooperative')
game1_r2: 						the collected number of pizza slices in round2 of game1
game1_r3: 						the collected number of pizza slices in round3 of game1
game1_r4: 						the collected number of pizza slices in round4 of game1

game2_r1: 						the collected number of pizza slices in round1 of game2 ('selfish')
game2_r2: 						the collected number of pizza slices in round2 of game2
game2_r3: 						the collected number of pizza slices in round3 of game2
game2_r4: 						the collected number of pizza slices in round4 of game2

game3_r1: 						the collected number of pizza slices in round1 of game3 ('divergent')
game3_r2: 						the collected number of pizza slices in round2 of game3
game3_r3: 						the collected number of pizza slices in round3 of game3
game3_r4: 						the collected number of pizza slices in round4 of game3


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

inquisit.version:				Inquisit version run
computer.platform:				the platform the script was run on (win/mac/ios/android)
startDate:						date script was run
startTime:						time script was started

subjectid: 						current subjectid
								Note: to run script with player images
								1) use subjectids that start with 'i' (Example: i_102)
								2) the player images need to be added to the script folder 
								as '*.png' files with the subjectid as the name BEFORE start of the script

groupid:						group1 = runs generic avatar setup
								group2 = runs female, agegroup1 stimuli
								group3 = runs female, agegroup2 stimuli
								group4 = runs male, agegroup1 stimuli
								group5 = runs male, agegroup2 stimuli
								
sessionid:						assigned session id number
elapsedTime:					time it took to run script (in ms); measured from onset to offset of script
completed:						0 = script was not completed (prematurely aborted); 
								1 = script was completed (all conditions run)
								
compACC:						comprehension accuracy: proportion correctly responded comprehension questions (out of 9)								
																
//the collected number of pizza slices (participant) by game and round
game1_Condition:				cooperative
game1_r1: 						the collected number of pizza slices in round1 of game1 ('cooperative')
game1_r2: 						the collected number of pizza slices in round2 of game1
game1_r3: 						the collected number of pizza slices in round3 of game1
game1_r4: 						the collected number of pizza slices in round4 of game1

game2_Condition:				selfish 
game2_r1: 						the collected number of pizza slices in round1 of game2 ('selfish')
game2_r2: 						the collected number of pizza slices in round2 of game2
game2_r3: 						the collected number of pizza slices in round3 of game2
game2_r4: 						the collected number of pizza slices in round4 of game2

game3_Condition:				divergent
game3_r1: 						the collected number of pizza slices in round1 of game3 ('divergent')
game3_r2: 						the collected number of pizza slices in round2 of game3
game3_r3: 						the collected number of pizza slices in round3 of game3
game3_r4: 						the collected number of pizza slices in round4 of game3								
							
							
* separate data files: to change to one data file for all participants (on Inquisit Lab only), go to section
"DATA" and follow further instructions

___________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________	

(1) Game Loading: the script 'loads' the game page for a random 2-10s while playing some music

(2) Game Startup Page: the startup page presents 4 buttons: a tutorial button and three game buttons.
At the start of the game, only the tutorial button is activated.

(3) Tutorial: the tutorial plays
(a) Instructions
(b) 3 demo scenarios: the scenarios are played in a fixed order
Demo1: shows non-cooperative players
Demo2: shows an exploitative player
Demo3: shows cooperative players
After each demo, participants are asked 
(i) Which player has more slices of pizza 
(ii) Which player has fewer slices of pizza 
(iii) Which player has the same amount of pizza
participants do not receive accuracy feedback for their choices

(c) A practice ('User Interface') Scenario (a game round without actual slices of pizza and actual coplayers)
After the practice, the first game button is activated

(4) Game #1
-Game #1 starts with a 'fake' module loading page (with music overlay) to simulate finding players etc.
-Then the players get introduced
-Then the decision page comes up: how many slices of pizza to share at school (this trial is followed by a 'wait' trial with music)
-Then the school situation is played out, the slices of pizza divided
-At the end of the round, the participant gets feedback of this particular round and an overview
of how many slices of pizzas were won during game1
After game #1 is over (4 rounds), the player returns to the startpage and game button 2 is activated
(game button#1 is de-activated)

(5) Game #2
see Game #1 with new players

(6) Game #3
see Game #1 with new players

(7) Final Feedback about slices of pizza won by all 7 players
An overview page that displays all pizza slices won during each game round
(participant always ends up being the second highest winner,
the remaining numbers are calculated based on an fixed algorithm - see script 'pizzagame_ranksoverview.iqx')

___________________________________________________________________________________________________________________
SELFIES: ADDITIONAL INFORMATION
___________________________________________________________________________________________________________________

The original pizza game (Keil et al, 2017) is played with selfies and images for the coplayer. 
Co-players were originally matched in gender and agegroup.

This Inquisit implementation of the pizza game provides the following options:

//Co-players://
- script played with groupnumner 1 (generic game): all players use avatars (participant can choose avatar and avatar name)


- script played with groupnumber 2: female co-players, age 9-12 (images taken from the NIMH-chEFS database Neutral-direct gazes)
Each coplayer image gets a name randomly assigned (see file 'pizzagame_coplayers_f_agegroup1.iqx)

- script played with groupnumber 3: female co-players, age 13-16 (images taken from the NIMH-chEFS database Neutral-direct gazes)
Each coplayer image gets a name randomly assigned (see file 'pizzagame_coplayers_f_agegroup2.iqx)

- script played with groupnumber 4: male co-players, age 9-12 (images taken from the NIMH-chEFS database Neutral-direct gazes)
Each coplayer image gets a name randomly assigned (see file 'pizzagame_coplayers_m_agegroup1.iqx)

- script played with groupnumber 5: male co-players, age 13-16 (images taken from the NIMH-chEFS database Neutral-direct gazes)
Each coplayer image gets a name randomly assigned (see file 'pizzagame_coplayers_m_agegroup2.iqx)




//Participant://
- groupnumber 1 (default): participant can choose avatar and name (as can all the fellow players - presumably)

- script played with groupnumber 2 to 5: if an image (PNG) of a participant can be taken and cropped 
(you can use 'pictureframe.png' - provided with this script- to 'crop' the image.
pictureframe.png requires a square image of 800x800 pixels. It can be copied on the selfie as a second layer e.g. in
Paint.net. The second layer is then merged down and the image should be saved)
The image should then be added to the folder that contains all pizza game scripts and images/soundfiles.
IMPORTANT: The SUBJECTID of the participant should start with an "i" (examples: i_participant1, i102, i_s203) 
and the filename of the image should be the same (e.g i_participant1.png, i102.png, i_s203.png). 
The image needs to be a *.png file as otherwise the script won't find it.

If the game is played without a subjectid that starts with an 'i', the game will automatically use a generic
participant avatar for the game.



___________________________________________________________________________________________________________________
STIMULI
___________________________________________________________________________________________________________________
provided by Millisecond Software - can be edited under section Editable Stimuli
The images were taken from 'https://pixabay.com/' (license: free for commercial use)
soundfiles were taken from 'https://www.free-stock-music.com'  (license: free for commercial use with attribution)
as well as 'https://freesound.org/ (creative commons 0 license)

photo images: NIMH-chEFS database Neutral-direct gazes

Note: avatar images used for group1 can be replaced by your own (just keep the original filenames)

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________	
The instructions are based on the original German Pizza game instructions shared by Dr. Jan Keil.
The audio files were professionally generated by Millisecond Software.

___________________________________________________________________________________________________________________	
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: