intfiction.org

Another new idea, what about using one of the unicode control characters as delimiters? The Inform 7 docs say they don't support characters less than 32, but I'm sure we can work around that.

I've been contacted recently by several people expressing interest in the transcript-saving Parchment so I'd like to start the conversation again. I'd like to actually make a Parchment fork with transcript collection capabilities from where it could eventually be merged into the official branch.

I've made some changes to Dannii's original proposal: I've dropped everything that would require changes in the Z-machine standard (tagging library messages) and moved some stuff around. The idea is to start with the bare minimum and expand later if needed. The original proposal was meant as a standard for any interpreter that would support it and I've kept that in mind whenever possible, but my immediate goal is to implement this in web interpreters.


The transcript protocol

The data is sent as JSON over HTTP POST requests.

The handshake

Firstly, the interpreter sends a message to the server giving the details of the story file. Either an IFID or a URL must be sent, with an IFID being strongly preferred. The other items are all optional, though as much information should be given as is possible.



(Note that I've moved the session variable creation from the server to the interpreter, and added a "parent-session" variable; the motivation for this relates to saving/restoring. More on this later.)

The server replies with HTTP code 200 and content "OK". Any other HTTP code or content means the server does not support transcript logging and the game should not send them.

Sending transcripts

Again, the client sends transcripts over HTTP POST requests, but after the handshake, it does not need to listen to the response.



(I've made a couple of changes: The library message classifications are removed, turn count is included, and the interpreter sends only one turn at a time. Turn count is required because the log is sent asynchronously and there's a small but nonzero chance that the server receives the requests in the wrong order. It can also tell the server that some commands have not been received if the turn count doesn't add up. Note that turn count is more accurately the input count and it's not the same as the turn count the game keeps track of.)

A client first sends its session ID, followed by the logged commands. Time stamps are sent in the following ISO 8601 format: YYYY-MM-DDTHH-MM-SS. If timestamps are not sent then the server should do its best to keep commands in order, and may use the time of the HTTP request instead.


Closing the transcript

(The following is my addition:)

When the interpreter detects that the player has stopped playing (in case of Parchment, the game ends or the player closes the page) it sends the following:



This lets the server know that it should not expect any more input for this play session and it can more accurately calculate the total play time.


Saving and restoring

This is the part where things could get messy. What happens if the player saves the game, closes the interpreter and restores later? Ideally the interpreter would save the session number and its own turn count and on restore inform the server that it's continuing from a restore.

This is where the "parent-session" variable in the handshake comes in: the interpreter generates a new session after the restore and informs the server what was the original session that was restored. With this information the server can link sessions together.

(I don't know how Parchment handles save/restore, but I assume this would be doable.)


Changes to Parchment

There should be an option to opt out from sending the transcripts. This could be done with a URL GET parameter called "feedback" where value 0 would mean no transcripts are sent. For example "http://example.com/parchment.html?story=zork.z8&feedback=0" would disable transcript collection. The author could then provide this link for people who wish to opt out.

Also there should be options in Parchment for the author to define the transcript collecting server's URL and other stuff, but those are minor details.


So there it is, comments are most welcome.

Should we name the "turn" filed as something else, so as not to conflict with the game's turn count? I'd prefer something like "input-count" so we don't have to keep explaining that "turn" in the transcript protocol is different from the game turn.

Other than that, I think this looks great!

I like the changes, and agree with input-count, or perhaps input-id. I still think that including the server url in the blorb is the way to go... it's just so easy to extract, and shouldn't be hard to add either.

I suggest that the session id and input count be included in the QUETZAL so that they can be continued at a later time.

Ah, I missed that part. Yes, url in the blorb would be the best option, but there should also be a Parchment option for games that don't provide their own url.