Last updated: 23 Nov 20 17:05:15 (UTC)

Recording Game play data in Twine

…to Google Spreadsheets Notes on my attempts are below (oldest at the bottom).

Ongoing: keeping track of variables, and where to add them:

For each new variable:
- Add its name to a column in the google spreadsheet.
- Add its reset value to the Start passage (<><<set $var to “”>><>).
- Add it to the list of vars to collect on the variables passage, so that it can be copied later into all the relevant end passages. (This refers to You and CO2 - if there are not multiple endings, or the game will come to a single passage in the end, just put it in the one ending passage.)

ACTUAL INSTRUCTIONS THAT WORK AS OF 21 FEB 2019, WITH TWINE 2.0 SUGARCUBE 2.21.0

FIRST, you have to have the variables you want to record; it doesn’t record clicks or anything by default. I wanted to record choices, and those fall into three categories for the You and CO2 Twine game: ordinary links (in which there are multiple navigation links available on a passage - no need to record basic links); cycling links; and demographic data, such as names and pronouns chosen.

Ordinary links:
1. Use the passage name plus “OL" for the variable name. E.g., if the passage title is “transport”, use “$transportOL" as the variable name. It makes the spreadsheet easier to parse - you can see the passage name as the column header, and the choices made in the data.
2. On the Start passage (or a passage that will restart on replays), silently set the variables for all ordinary links. Doing this on the Start passage resets ALL OL variables on replays. I tried first setting the variables on the passage where they first appear - but then if the player replays the game immediately, the variables on the paths they chose the FIRST time are still set the SECOND time they play, and get recorded on the next data set, which confuses the play path.
  - <>
  - <<set $transportOL to “”>>
  - <<set $lunchOL to “”>>
  - <>
3. For each link, use setter notation to define the variable. So if the “transport” passage has links “lunch” and “skiving”, code the links as:
  - [[lunch][$transportOL to “lunch”]]
  - [[skiving][$transportOL to “skiving”]]
Cycling links:
1. Because I am already counting choices in these links in the You and CO2 project as points, they already have variables. These should be reset in the Start passage (as in Step 2 for Ordinary Links) as well (there will be cycling links on passages that are optional, and thus all need to be reset to avoid confusion).
  - To set a cycling link as a variable, name it using variable notation ($) right after calling the cyclinglink macro (in this case, $transportCL):
  - <<cyclinglink “$transportCL" “trot off on foot” “jump a monorail” “snag a solo-port”>>
  - Note that the cycling link macro javascript should be in the Twine file’s javascript sheet!

cyclinglink-macro.min.js

2. Use the passage name plus “CL" for the variable name. E.g., if the passage title is “transport”, use “$transportCL" as the variable name. It makes the spreadsheet easier to parse - you can see the passage name as the column header, and the choices made in the data - and cycling links are differentiated from ordinary links.

Demographic data:
1. Because these already call for variables, they’re defined. For You & CO2, at the moment, they have to reset these each time they play (or, I’m going to return them to a point just AFTER they’ve set them, in which case, they’ll stay the same for a whole replay session…actually, that’s what I’ll prefer), so no need to reset. Data sets will be differentiated by timestamps.

Now, the spreadsheet set-up:

Create or open an existing Google Sheet. This will serve as the database and will be public to the internet. Do not put private information in this database. It’s okay to set the Spreadsheet to editable by anyone with the link - it doesn’t need to be publicly editable to work.
Rename the sheet to “DATA”. This makes the rest easier.
Open the Script Editor. This can be found under Tools –> Script Editor.
Replace any existing code with Code.gs contents. *(From Dan’s site, or from the txt file below.) *This will provide the necessary server backend to updating cells.
- CodeGS.txt
If you did not rename the sheet “DATA”, replace the name of the sheet in the CodeGS to use in the SHEET_NAME variable. By default, the first sheet will be called “Sheet1”. Following these direction, replace the string “DATA” with “Sheet1” in the code.
- // 1. Enter sheet name where data is to be written below
- var SHEET_NAME = “DATA”;
Click the save icon.
Run the setup function. In the Script Editor, go to Run –> Run Function –> setup. This will prepare the code.
Publish the web app. In the Script Editor, go to Publish –> Deploy as web app. This will open the dialog box for deploying the script as a web app.
**Fill in the project version, select to execute the app as “Me…”, and select “Anyone, even anonymous” as the access level. **Add in a project version and select to execute the app and who has access. Be sure to select “Anyone, even anonymous” or the code will not be able to accept incoming requests.
Click Publish to finish.
Copy the provided URL and click “OK” to close. The code will now be deployed and ready.
Return the Google Sheet and add in column names and verify the sheet name.The data passed to the server-side function MUST match existing column names or it will be ignored. In order to accept incoming data, add column names.
- The column names, ideally, should match the variable names. So if you have a “points” variable, name a column “points”.
- Note: This code adds a Timestamp column if one is not found. As part of the code, it will record changes and when they happened.
I HAD TO CHANGE THE NEXT STEP FROM DAN’S TUTORIAL, PULLING FROM JOHN STEWART’S TUTORIAL, because nothing happened when I tried. So…
Create or open an existing Twine file in the editor view. In a passage designed for the purpose of sending data, copy the code. This will call the jQuery $.ajax() function to send the data to the Google Sheet. If no errors have occurred, the new value will appear in the sheet within seconds of the call.
- The Passage: should be near the end, or at least a passage that appears after all variables have been set. It needs to be one that “completes” the playthrough - putting the code on Ending1 if they get to Ending3 won’t record the data.
- The code:

CallVarstoGS.txt

- Under “var sendData”, the items in quotation marks are the *column headings*. These need to match the column headings in the Google Spreadsheet.
- Likewise, for each “state.active.variables”, replace the final bit with the name of the variable to go in that column. E.g., for the “NickName” column, put the NickName variable.
- Down under the “$.ajax”, for url, paste in the web app URL copied in step 14 above.

And that should do it. Test the Twine file via “Play” or local file to browser to see if there are any bugs. The data will NOT RECORD to the spreadsheet unless hosted on a server. It’s easier to test for bugs before it’s on the server, though. So once it’s running smoothly on play/local file, upload it to server and test. The Spreadsheet should almost instantly populate with data.

OLD ATTEMPTS THAT DIDN’T WORK (just for the record…)

Okay, take 2 (below tutorial didn’t work…maybe because it’s harlowe? Trying Dan Cox’s tutorial now…https://videlais.com/2018/05/16/working-with-google-sheets-in-twine/

TAKE 1

Starting with this tutorial: https://www.johnastewart.org/coding/twine-game-data-to-google-sheets-via-javascript-version-2/

Follow the instructions. It says to "reference the jquery library in the head of your file” (part of step 2), but it’s not clear on how to add anything to the html head, since Twine doesn’t natively allow it. So, add this to the Javascript sheet:

A passage, not linked to anything, called “headAppend”.
Inside, put the script to go in the header:

THEN: Establishing variables to record:

The tutorial isn’t really clear on how to set variables, just that the system will record the variables. So the variables I might want to record could be:

Names filled in, genders selected
Each link clicked in a passage where there is a choice
Cycling link variables

So while my cycling link variables currently change the overall score, they don’t necessarily record what value was settled on. Likewise, ordinary passage links don’t have variables, so wouldn’t be recorded. Thus, I have to go through and set each thing I want to record with its specific variable (which then must be duplicated in the spreadsheet column headers). As follows:

Ordinary links to passages:
- In the passage, set a variable to the passage name: <<set $PassageName to “x”>>
  - The x is the default - if it records, that means the passage wasn’t visited.
- For each link, use setter notation to reset the variable. So if the “PassageName” passage has links “Passage1” and “Passage2”, code the links as:
  - [[Passage1][set $PassageName to “Passage1”]]
  - [[Passage2][set $PassageName to “Passage2”]]
- As a result, on the spreadsheet, each passage should be represented on the column headers, and the cell for each playthrough row will show which link was clicked.
  - Perhaps considering using special notation for link variables vs cycling link variables vs names, for ease of ordering. Passage name first, so the spreadsheet can be grouped by passage name?
    - Demographic data: $dd-variablename
    - Ordinary links: $passagenameOL
    - Cycling links: $passagenameCL

Pronoun $Pronoun$ F1Pronoun F2Pronoun $F2Pronoun$ F3Pronoun NickName $NickName$ Friend1 Friend2 $Friend2$ Friend3 link $link$ points transport $transport$ three $four