Documentation improvements

[Screwtapello]

Recently I acquired a copy of the MS-DOS port of Lancelot, which I wanted to play with a modern interpreter (Specifically, I was using Gargoyle, but its Level 9 terp is based on this one, and most of the problems I've encountered are also present in the standalone GtkLevel9 terp).

What I started with:

• a bunch of files named 1.PIC through 30.PIC, plus a PALETTE.PIC
• files named GAMEDAT1.DAT through GAMEDAT3.DAT
• files named MENU.TXT and MENU.EXE

I wanted to know exactly which files I needed to make the game work with Gargoyle/GtkLevel9, but that information was difficult to come by. The included level9.txt talks about what files were used by the original terps, which was interesting, but it wasn't clear to me whether Gargoyle/GtkLevel9 required exactly the same files and filenames.

My first attempt was just to point Gargoyle at GAMEDAT1.DAT, but that failed because Gargoyle doesn't recognise that file as a Level 9 game. GtkLevel9's "File → Open" dialog also doesn't recognise that file, because it's only looking for *.dat, not *.DAT.

Poking around the Gargoyle source tree, I discovered it seemed to associate *.l9 and *.sna files with Level9. I didn't know what "sna" was, but "l9" seemed appropriate. level9.txt suggested that game files could be named just about anything, so long as they contained the volume-number in the right place, so I renamed my files to lancelot1.l9 through lancelot3.l9, and then I could launch the game with Gargoyle and have it run.

The next problem was that the included pictures were not displayed. Searching the Level9 source suggested that it should try both upper-case and lower-case extensions, but in retrospect I think that's only for a single-file picture archive (i.e. LANCELOT.DAT → LANCELOT.PIC). At any rate, once I renamed the images to 1.pic through 30.pic (i.e. with a lower-case extension) images started appearing.

Lastly, I tried opening lancelot2.l9 and lancelot3.l9 instead of just the first one. Loading lancelot3.l9 took me to the final part of the game, which made sense, but loading lancelot2.l9 gave me a weird error in Gargoyle:

Next disk file: lancelot2.l1

[ Lancelot, pt. 2 (Amiga/PC *USA*)

Unable to load: lancelot2.l1

The game has exited.

In GtkLevel9, the result is even stranger - it loads the title-screen image, but does not write any messages to the text window, and just beeps when I press a key.

I guessed that perhaps the game couldn't start from the middle, and it was trying to decrement an integer in the filename to find the first part of the game, and failing. Sure enough, if I renamed the game files to lancelot1.sna through lancelot3.sna, everything started working perfectly.

From this experience, I respectfully suggest a few changes that would have made this more straightforward:

• Coordinate with Gargoyle about what the ideal file-extension for Level 9 games should be
  • .DAT and .dat are traditional but too generic
  • .sna works everywhere but apparently is supposed to be a "Spectrum snapshot" which isn't appropriate
  • .l9 would be great except that it breaks the "automatically switch between game segments" feature
• Check for PC images with upper-case and lower-case extensions
• Consider writing a step-by-step guide for verifying what format a game is in, and how to convert it into a convenient form for use with the Level9 terp (descriptive filenames, a distinctive file extension that can be associated with an executable, etc.)
  • I am willing to help with this, if I have access to games I can try to convert.

[cibersheep]

A couple of things (careful, I might be wrong):

• .sna there indeed for Spectrum memory snapshots so, nothing to do with the .dat format (level 9 portable game code)
• .DAT is the extension used in the original games for MS-DOS. They are numbered 1-3 parts. The interpreter will try to find the first/next part of a game, that's why you get the error with .l9 extension. Unable to load: lancelot2.l1 is looking for the «first part of [gamename.l]9
• I didn't know about case issues. That is something that we might want to file as a separate issue
• If you .tar the files from older games (llike Silicon Dreams) the interpreter will find the image file but not with the more modern. I don't know if that's something the developer want to look into as it would be really useful feature

[Screwtapello]

The Blorb resource archive specification reserves a code for Level 9 games, so I can imagine a tool (perhaps based on l9cut) that collects game data and bundles it into a .blorb file (.lblorb?) for portability. However, that would require development work and project management work (getting matching changes into Gargoyle, etc.), and I expect writing up "how to get it working" documentation would be a good first step.

[cibersheep]

Oh, I didn't know that. Blorb it could be very interesting indeed. And work.

[Screwtapello]

As I mentioned "coordinate with Gargoyle", I also filed an issue over there: https://github.com/garglk/garglk/issues/365

Since my original post, I've found another awkwardness: I started playing Lancelot on the Android IF terp Fabularium, and because there's three files with the same extension, they show up as three individual games in the game list. For the sake of game-cataloguing apps, it'd be nice if the extra game files could be distinguished by extension instead of a number in the filename. For example:

Lancelot.l9
Lancelot.l9b
Lancelot.l9c

Still three files, still in an obvious order, but only the first one would have the file-type association with a terp, only the first one would show up in generic front-ends like Fabularium, etc.

[DavidKinder]

It's taken a long time for me to get round to looking at this issue, sorry ...

The case sensitivity of the ".PIC" / ".pic" file extension definitely needs addressing, but it already exists as a separate issue, https://github.com/DavidKinder/Level9/issues/10

Sorting out file extensions makese sense, but I think the most complete solution is to support Level 9 games in Blorb files, and just have a set of Blorb files available to download. That is also a separate issue, https://github.com/DavidKinder/Level9/issues/8

Co-ordinating with other projects like Gargoyle just isn't going to happen, I'm afraid. I've too little time free for that, and it's not really how I want to spend what free time I have.

Given the above, I'm going to close this issue, as I think anything that might actually change is covered in separate issues.