This is a legacy document; the project has migrated to Github.

Requirements

You need a web server or a web host with a database for the game and the scripts that record the transcripts. These instructions assume that you know how to upload files to the server and create database tables. The bundled scripts are set up for MySQL. Using other databases shouldn't be a problem, but will require some modification of the scripts.

• parchment-transcript.(version).client-bundle.zip is a Parchment installation with the recorder pre-installed
• parchment-transcript.(version).server-tools.zip has PHP scripts for saving and viewing transcripts

Files can be downloaded from the project download page (http://code.google.com/p/parchment-transcript/downloads/list). Choose the latest version of both packages (top two links).

If you use an existing installation of Parchment it must be a version from July 2011 or later so that it has the hooks required for the plugin to attach itself to.

Server scripts

Upload and unpack the server tools to the server so that they can be accessed from the Internet.

If you are using PHP version 5.1 or lower you may need to install the JSON extension to PHP. Otherwise a plain PHP installation should be enough.

Same origin policy

Due to browser security measures you have to have the script that records the transcripts in the same domain as your Parchment installation. If your game is at www.mydomain.com, you can't have the game send transcripts to www.example.com.

Parchment installation

Upload the contents of the client-bundle zip package and the game file to the server and edit transcript.settings.js with information where the game file and the transcript recording script are located.

If you have a Parchment installation already running, follow the instructions on a separate page.

Database setup

The database structure is included in http://parchment-transcript.googlecode.com/svn/trunk/doc/database.sql.

The PHP scripts have the database configuration in the tools/include/db.php file. Add the SQL username/password and other information there.

Player opt-out

If the game URL includes option "feedback=0" the transcripts won't be recorded. This functionality is provided so that the game author can provide a link to a version that doesn't collect private data without having to install two versions of Parchment.

For example, if you have installed Parchment to http://www.example.com/game/index.html you'd provide a link to http://www.example.com/game/index.html?feedback=0. If you already have other parameters in the URL the separator is an ampersand: http://www.example.com/game/index.html?story=game.zblorb&feedback=0.

Troubleshooting

Transcripts aren't saved to the database

• Make sure that the server script is in the same domain as the Parchment installation.

• Verify that the server script works by navigating to the script with a web browser. If the message is "POST data not found", the database connection works.

• Install FireBug for Firefox or some similar debugging tool to see what the script responds when the transcripts are being sent. The script should respond "ok" if everything worked as expected.

The transcript viewer shows links to empty transcripts

• The game is probably in Glulx format. The transcript recorder doesn't support Glulx yet, but records that a Glulx game has been started.

• Parchment may have encountered an error loading or starting the game and halted before the game could begin.