Some help please on uploading to IF Archive and "play online" for HTML games

Some help please on uploading to IFDB and “play online” for HTLP games.

Following DanF’s suggestion of using curl. this:

curl \
    -F \
    -F "name=Jkj Yuio" \
    -F "" \
    -F $'filedesc=Escape From Skuggar\n\nAuthor: Jkj Yuio\nVersion:1.01' \
    -F "rights=author" \
    -F "directory=games/html" \
    -F "tos=on" \
    -F "tuid=blb52egcxg07ub23" \

It appears to upload. But then how to enable the “play online” ?

Presumably something like this:

Some questions:

  1. When you upload a zip, is that zip available for download? If so, this zip wont help anyone play it in their local web browser because the HTML needs to be served. So where to explain this?

  2. Where does IFDB unpack the files? in the curl above, should it actually have a directory for the game itself,

    -F "directory=games/html/skuggar"

    Otherwise how to point the link at index.html

  3. When a new zip uploaded, do i have to wait for mods to make it live, or does this go in right away. Presumably I don’t update the play online link once it works originally.


Yeah, I think it might have been clearer to use the web UI the first time, and then using curl to automate the process in the future. When you use the web UI, it prints a message when the upload finishes:

Note that your files will not appear in the unprocessed folder immediately. A human moderator will usually move your files to the “unprocessed” folder within a few days, and then move them to their final destination some time after that. For more information on the upload process, see this post.

… which is to say, at first, when you upload, the files aren’t immediately visible on the archive. It can take days, but these days it’s usually just hours.

As for unzipping, it’s actually IF Archive that does the unzipping, not IFDB. For example, here’s the html directory on the archive.

Those zips have a “View contents” link, where you you can browse the contents of the file and play them. For example, here’s the “View contents” link for

That link is to the IF Archive “unboxing service,” aka “unbox.” It shows a list of all of the files in the zip, which you could download individually, but there’s a big button at the top, “Open index tellers.html” which opens the game itself on a separate domain:

Back on you’ll see that Beached Prelude also has a link to its IFDB entry. And there you can see that the “Play Online” link is configured to point at which redirects to

If you Edit the page and edit the external link, you can see how the link is set up in IFDB.

IFDB is smart enough to interpret those settings to mean that “Play Online” should point to unbox and request that unbox redirect us to the index tellers.html file, making it playable.


Fantastic! Thanks a lot for the detailed explanation. I hadn’t realized it works by dynamic unboxing.

Actually I did see a report returned from curl. But it just dumped the HTML at me. That’s what I get, i guess :slight_smile:

So basically, all i do is:

  • upload the zip
  • point the “external link” to the zip

And it automatically creates the “play online” link via unboxing.

The only remaining question is over updates. If I’m going to next upload sounds like this would be a bad naming convention. I should simply use the same zip name each time (eg otherwise the link needs to update.

I shall give it a go!

If necessary, volunteers will rename the new file so the link doesn’t break. Using the same file name will save us a few seconds, but it’s not a problem either way.



On a related question, is there a file naming convention for files uploaded to IF Archive? Are files case-sensitive? Are spaces permitted? Are special characters permitted? What happens if you have multiple html-based games (specifically Adventuron games) that are all named index.html? Should they be renamed?

When I upload my own files to itch or GitHub, I use the customary web naming convention of all lower case with hyphens separating words. Would this be okay for IF Archive?

Just for context, I’ll be uploading all the entries from Text Adventure Literacy Jam 2024 in the next day or two (everyone gave consent - yay!) and I want to make things as easy as possible for the IF Archive volunteers.

1 Like

The only real file naming convention is to not include version numbers in the game file name, as otherwise all the links would change for a new version. Beyond that, we usually keep it however the uploader puts it, though ALL_CAPS_LOOKS_ANNOYING so we might rename that. If the upload is updating a file already in the archive we’ll generally keep the same filename as the earlier version, again to avoid breaking links.

File names are case sensitive and spaces are permitted. Special characters are okay within reason: if you name a file using Unicode Linear-B characters we are not likely to accept that. Lowercase with hyphen separators is valid.

HTML games in the archive are always stored in zip files. This is a security measure as well as a convenience for HTML games that have subsidiary files: such games can be accessed via the unboxing service, which acts to isolate the domain that the game is served from from the rest of So for HTML games all called “index.html” the easiest thing is to zip each one up into a separate archive, each named appropriately.

1 Like

Thanks for the response. That makes it pretty clear what to do.

@Warrigal Yes, as i understand it for HTML, the files all remain in a ZIP. So each game is a zip and each zip has a top HTML file (eg index.html). Then there no conflict.

At the mo’, I’ve been uploading zips with version numbers in their names. I might stop this and just keep to the same filename. To make the link easier. I guess the only problem with this is that i won’t know when it goes live.

The zip unboxing is interesting, but I’m wondering if it will get slow for large zips with a lot of files. Will see.

1 Like

I’m pretty sure it does, as I was looking at a zip file the other day that had lots of files in it. Mind you, I didn’t download the zip file to check.

1 Like

A volunteer should email you when the upload has been processed, so you don’t need to keep checking.

1 Like

There’s some caching on the unbox server. So if several people are playing a game, it will be fast for most of them, most of the time.


@Keltena is right that the archive team will email you, but I think you’ll also find it helpful to include the version number in the “About this file” filedesc description, so you can see visually on which version is being served.

1 Like