-
Notifications
You must be signed in to change notification settings - Fork 13
IFComp Game file management
This document describes how the IFComp web app receives and prepares uploaded game files.
The primary source for this information is the app's source code, particularly the modules IFComp::Schema::Result::Entry (the object class for entries) and IFComp::Controller::Entry (the web application's controller for the author entry form). You don't need to read or understand those modules to understand the information presented below, but if you'd like to dive deeper, there you go.
-
sword: The IFComp server, as of 2017. Runs under IFTF auspices.
-
the app: The web application that runs all the services on ifcomp.org. Perhaps it should have a punchier name. Well, it doesn't.
-
entry: An IFComp entry with representation in the comp database. It needn't necessarily exist beyond this database row. For purposes of this document, mere intents (with no uploaded files) count as entries, as do fully finished games.
Per the instructions it gives to authors, IFComp expects every entry upload to comprise a single file. This effectively means that the file is one of these three things:
-
A playable game, in a single file. May be a HTML file (if a text-only Twine game), a .blorb file (if created with Inform), a Windows executable, et cetera.
-
An HTML file acting as a static web page linking to the actual entry, running elsewhere on the web.
-
An archive in zip format, which in turn might contain anything at all.
As of 2017, the IFComp website restricts the total size of upload files to be 25 megabytes. I (jmac) chose this number in 2014 because I wanted some limit, so looked at the size of the disk-largest IFComp game so far, and picked a number slightly larger than that.
This pseudo-rule exists more for logistical reasons than technical ones. Concerns of storage space and processing efficiency to one side, nothing within IFComp's entry-processing software prevents it from working with larger uploads.
All entries' files exist on the filesystem within a single entry directory. By default, this directory is named entries, and exists under the IFComp app's root folder. (Therefore, in 2017, this directory exists at /home/ifcomp/ifcomp/IFComp/entries on sword.)
The remainder of this document refers to this directory as the entries directory.
The entries directory contains a number of subdirectories, each named after the database ID of an IFComp entry. Practically speaking, this is an integer. Thus, if you list the contents of the entries directory, you'll often see a whole bunch of folders whose names are mere numbers. This is normal.
Within every such ID-named directory, you will find the following subdirectories:
-
main: Contains, at most, one file. If the file exists, then it is the game file uploaded most recently by this entry's author.
The archived version of a given IFComp entry is based on this file, as is the direct-download link that the web app offers during the judging period.
-
content: Can contain any number of files or sub-directories. The contents of the "main" directory, after being processed by the app. See below for information on what this process entails.
The app's "Play Online" feature, available from the ballot page, depends on the contents of this directory.
-
cover: Contains, at most, one file. If the file exists, then it is the cover-image file uploaded most recently by this entry's author.
-
walkthrough: Contains, at most, one file. If the file exists, then it is the walkthrough file uploaded most recently by this entry's author.
Typically, this file is either a plain-text file, or an HTML page. In practice we allow authors to upload whatever they want as the walkthrough.
When an author uploads a game file, these things happen, in this order:
-
The app creates the directory and subdirectories for this entry, if it does not already exist on the filesystem.
-
The app deletes the contents, if any, of the main and content directories for this entry.
-
The app copies the author-uploaded file into main, and modifies that copy no further.
-
If the file now in main is a zip file, then the app copies all its contents, expanded, into content. Otherwise, the app simply copies the single file into content.
-
The app subjects the contents of this entry's content directory to the processing described below.
Once it has populated an entry's content directory based on the steps listed above, the app might further modify them depending upon the nature of the entry's content.
If the entry content is a single, Inform-generated file, such as a .z8 or a .gblorb file, then the app creates a new file called index.html and places it in the content directory.
This file, when opened in a browser, will launch a local copy of the Parchment interpreters located in root/static/ (relative to the app's own root directory). Z-code files will use the ZVM interpreter; Glulx files will use Quixe. The app will also set up server-side transcription support, using GlkOte's native transcription feature.
If the entry content is a complete website based on Parchment or Quixe, then the app modifies its play.html file (if present) to set up server-side transcription support, adding the appropriate script invocation or configuration to the file.
The app used to replace the interpreter files with local versions; this no longer happens, so if an author uploads an old version of Parchment or Quixe then if there are any bugs in those interpreters it is the author's responsibility to update their entry.
If play.html is not present, then these modifications do not occur.
If the entry does not meet any of the above criteria, then the app makes no further modifications to the content of the entry's content directory.