Official AGI Documentation

[lance.ewing]

It would seem that that wasn't all though. According to his resume:

KINGS QUEST I Development team member. Helped design and produce graphics and animation utilities, game logic compiler, later to become known as Adventure game development system AGDS. Substantially contributed to game design and story line. Built game screen graphics and animated characters. Developed game AI logics and user response messages.

So certainly the pictures and views, but also the logic scripts and tools.

[lance.ewing]

That resume has an email address, and Greg appears to still be the owner of the domain name, even though it is nearly 20 years after the date on the resume. It might just still work.

[lance.ewing]

Found this as well:

https://www.experts-exchange.com/members/SurferJoe.html

I suppose I should try that email address and see where we get to.

[lance.ewing]

I received a reply back from Al Lowe earlier today. He says he has never heard of GAL, and had never heard of AGDS either, that is until he heard of the Russian AGDS tools much later on, in the 90s. He says that right back when he was working on Black Cauldron in 1983, they always called it AGI. I've responded by pointing him at Greg Rowland's resume, and the text on all those AGI game title screens. Waiting to hear back what he says. We obviously know from that AGDS.DOC file that there was at least someone at Sierra that called it AGDS. Perhaps the author of that particular document? We should try to track down Greg Rowland if we can.

Rather amusingly, after laying out some of the evidence for the name, Al acknowledges that the title screens don't lie, and he now thinks that he might have been the source of the AGDS name. But he has no memory of anyone at Sierra actually referring to it by that name. They always referred internally to AGI and SCI, from his memory. - It actually makes sense if Al is the source of it, because he was involved in all of the games that I listed previously that mention Adventure Game Development System on the title screen. Games that didn't involve Al don't seem to have it (although I'd love to be proven wrong).

So Greg is unlikely to be the author of the doc if Al thinks that he himself might have been the source of the name (despite no longer recalling it). But it's interesting that Greg remembered the AGDS name well enough in 1997 to mention it in his resume.

I just sent an email to that old email address for Greg. Waiting to hear back on what he remembers about King's Quest, whether it was an AGI game, what AGDS was, what the distinction between AGI and AGDS was.

Edit:

Just noticed that Al Lowe and Greg Rowland worked on Police Quest together:

http://www.mobygames.com/game/dos/police-quest-in-pursuit-of-the-death-angel

[lance.ewing]

I've been thinking a bit more about the AGI.pdf, mainly because I've been studying it a bit as part of writing the C# AGI interpreter. One thing that is quite obvious, but I don't think we've pointed out yet, is that it is missing quite a few of the AGI commands. I guess we've all assumed it was written at a time when those commands didn't exist, and I think that is probably quite likely. Something I've noticed this evening though is that the final AGI command covered in the AGI.pdf document doesn't exist any more. The name is max.drawn. The command is described in the document, and the AGI saved game format has a field for storing the max drawn value, but it would seem we no longer have a way of setting it. The AGI.pdf document states that the default value is 15, and sure enough in the saved game files I've been studying, the value of the field is 15. So I guess in the interpreter code, that field is still set to the default of 15.

The only reference I can find to MAXDRAWN in the fragments of AGI interpreter source code that we have are from the memory map of the section of memory that is saved as part of the AGI saved game file. It isn't mentioned anywhere else in the fragments that we have. Obviously there must have been more references to it since the inclusion in the memory map means that there was a variable with this name. The references must be in one of the parts we don't have the source for.

As far as I can tell, for those commands that it does include, the AGI.pdf document lists the AGI commands in their correct AGI v2 and AGI v3 order. As has already been discussed previously, AGI v1 had a lot of the same commands but they appeared in a different order (i.e. they had different byte/op code numbers). What this seems to suggest to me is that perhaps the AGI.pdf document represents AGI v2 in its very earliest form. I say this because according to the AGI specs, version 2.089 had 155 commands. The AGI.pdf document does not list this many. It stops at max.drawn, which I assume would have been at number 143 (since script.size appeared immediately before it and is at number 142). For most AGI v2 and v3 games that we're familiar with, command 143 is set.game.id. This does not appear in the AGI.pdf document. One possible conclusion about why it only has 143 commands is that AGI.pdf represents a time prior to version 2.089. Perhaps it represents the 2.001 that DDP apparently used. And if that is the case, does that version of DDP use the max.drawn command? If not then what games did use it?

Edit : I had one further thought about this. HWM's interpreter list says that the 2.001 version of Donald Duck's Playground had an OBJECT file that didn't have the header, which I take to mean the first three bytes. If this is the case then it would not have contained the "number of animated objects" value that is the third byte in the OBJECT file. Perhaps that was what max.drawn was originally intended to be used to set. I wonder this because from having taken a look across a few of the standard AGI v2 games (KQ1/2/3, SQ1/2, and PQ1), the "num of animated objects" value in the OBJECT file ranges between 16 and 20, which is very similar to the default value stated for max drawn.

[Collector]

If the document is that early (2.001 or 2.0890)  I wonder if Omer has any later ones that he can share. Given that int 2.917 is one of the most commonly used interpreters it would be great to have documentation that included that version. Then what about 3?

[OmerMor]

I don't have another version of this document.

I do however have the source code for Donald Duck's Playground from July 1986, and this version (1) does not use the max.drawn command, and (2) uses the set.game.id command.
The game defines 169 commands, 18 tests, 26 vars, and 16 flags.

[lance.ewing]

I doubt that that is the AGI v2.001 version of DDP then. 169 commands is in the 2.4XX range.

NewRisingSun mentions in the message below that there is an extremely rare v2.440 version of DDP:

http://sciprogramming.com/community/index.php?topic=1690.msg10345#msg10345

This is probably what you have the source for then. A shame it wasn't the original DDP version. That would have been very interesting.

When I get a chance, I might study the original DDP game disk. The image is on that retrograde page.

[lance.ewing]

...and DP v1.0Q (AGI v2.001) additionally requires set.game.id to have a NUM instead of a MSGNUM argument.

I was just reading back through the above topic again and noticed the text I've quoted. I'm wondering if that set.game.id that requires a NUM instead of a MSGNUM is actually max.drawn. The AGI.pdf implies it was in the same bytecode position as what set.game.id later became, so its a bit suspicious that DDP with AGI v2.001 requires a NUM for that command.

[lance.ewing]

Does anyone know if it is possible to save your game in Donald Duck's playground? I'm trying to do so in the original AGI 2.001 version running in dosbox but I can't seem to find an option for saving.

The reason I'm curious to try this is because the AGI.pdf states that the save.game command does this:

save.game()
    Prompt the player for a letter between 'a' and 'z' under which to
    save the current game, then save it.

This describes how the saved game mechanism worked in the pre-AGIv2 games, but certainly from AGI 2.272, there was a proper slot selection and game description included. I'm guessing that the original AGI v2 version (perhaps used by DDP) had the same save.game mechanism as the pre AGI v2 games, but it looks like DDP doesn't provide save game support. I guess we could always hack it to turn one of the controllers to call save.game, in fact I'm going to try that tonight.

I don't have the 2.089 AGI interpreter used by the original SQ1, so I'm not sure how the saved game mechanism worked in that one. I did have it once upon a time. Does anyone have that version to give it a try?

[lance.ewing]

I guess we could always hack it to turn one of the controllers to call save.game, in fact I'm going to try that tonight.

I replaced the version() call for Alt-D with a call to save.game()

[HWM]

If I recall correctly, you could get the save (or restore?) game screen to appear by teleporting to room 100 using the debug mode; I discovered this by accident back in the days. Never sure why this worked, as there is no logic 100 resource. The v2.089 interpreter has the same save game mechanism as the later v2 interpreters.

I fully agree with your suggestion that the AGI documentation in question represents AGIv2 in its earliest form.

[lance.ewing]

If I recall correctly, you could get the save (or restore?) game screen to appear by teleporting to room 100 using the debug mode; I discovered this by accident back in the days. Never sure why this worked, as there is no logic 100 resource.

I've just tried that and you're right, in fact it seems to go in to some sort of loop. If I ESC out of the save screen, it shows the game screen again for a few seconds and then shows the save screen again. Perhaps there was one of those broken LOGDIR entries in the data. I've come across those when decoding DIR resources in the past, where an entry points to somewhere that either doesn't exist (e.g. a VOL file that doesn't exist or beyond the end of a VOL), or to a location in an existing DIR file that isn't a resource (or if it is then maybe the wrong type). The games wouldn't care about this because they just follow what is in their scripts, so they'll never try to load those garbage entries. An editor like AGI Studio, etc., checks all of the entries to form a list of resources to choose from. - So perhaps doing a tp 100 is making it load LOGDIR entry 100 and that happens to point to somewhere on the disk that isn't a logic resource and its interpreting random commands after that. I'm guessing the game probably hangs if you try to tp to other non-existant logics. I've tried a couple but the game told me that those logics don't exist, so it would have to be one of these unused DIR entries that has junk data in it.

The v2.089 interpreter has the same save game mechanism as the later v2 interpreters.

Thanks for checking that. Yeah, DDP has always been stated as being somewhat of an AGIv1/v2 hybrid, so it doesn't surprise me that it was the only one with that save game mechanism.

I fully agree with your suggestion that the AGI documentation in question represents AGIv2 in its earliest form.

I wonder if we can list AGI v2.001 as having 143 commands then. It doesn't currently appear in the lists that compare the number of commands across AGI versions. I suppose someone could examine the interpreter code to confirm.

[HWM]

I've just tried that and you're right, in fact it seems to go in to some sort of loop. If I ESC out of the save screen, it shows the game screen again for a few seconds and then shows the save screen again. Perhaps there was one of those broken LOGDIR entries in the data. I've come across those when decoding DIR resources in the past, where an entry points to somewhere that either doesn't exist (e.g. a VOL file that doesn't exist or beyond the end of a VOL), or to a location in an existing DIR file that isn't a resource (or if it is then maybe the wrong type). The games wouldn't care about this because they just follow what is in their scripts, so they'll never try to load those garbage entries. An editor like AGI Studio, etc., checks all of the entries to form a list of resources to choose from. - So perhaps doing a tp 100 is making it load LOGDIR entry 100 and that happens to point to somewhere on the disk that isn't a logic resource and its interpreting random commands after that. I'm guessing the game probably hangs if you try to tp to other non-existant logics. I've tried a couple but the game told me that those logics don't exist, so it would have to be one of these unused DIR entries that has junk data in it.

It's most likely something along those lines. It seems a bit as if the interpreter has an issue with bounds checking in regard to DIR entries, given the rather erratic results.

I wonder if we can list AGI v2.001 as having 143 commands then. It doesn't currently appear in the lists that compare the number of commands across AGI versions. I suppose someone could examine the interpreter code to confirm.

I did some testing and AGI v2.001 seems to have one additional command (144) not mentioned in the documentation. It requires one argument, which corresponds with the log command. However I'm not sure if it's actually has the same functionality, since the AGIDATA.OVL equivalent is missing the references to the log file functionality.

Command 143 indeed seems to be max.drawn instead of set.game.id. It is set to 25 in the game script and changing it to anything lower than 3 will get the game to run out of memory at the intro (as Huey, Dewey and Louie make their appearance there). However if you remove the command, the intro will work normally, so the interpreter also has a default value already set apparently.

[lance.ewing]

have.key()
True if a key is waiting to be read. Note that if a 'prevent.input()' has not been done, the likelyhood of this being true is minimal -- virtually all input will go to the input line.

The above from the original AGI documentation (which we believe to represent version 2.000) appears not to be true of the later AGI 2 versions. I've done testing with accept.input active and the have.key command still evaluates to true. What you seem to get is the character being added to the user input line but have.key also tests as true. So this would seem to suggest that it isn't about a key press waiting to be read but rather that a key was already read in the current cycle. The original AGI source seems to support this. The code for have.key shows that it will evaluate to true if var 19 (i.e. the LAST_CHAR variable) is not zero. Var 19 holds the last character to have been read. So if have.key is checking the value in that variable as its first check, then it obviously isn't telling us that there is a key waiting to be read. If var 19 is 0 then the code for have.key goes on to check if there is a keypress waiting, but then it sets var 19 to the value of the key press that is waiting to be read before returning true, which means that it is no longer waiting to be read. It's all about a key that has already been read and prevent.input/accept.input has no impact on this at all.

I wonder if the behaviour of this test command changed over time, perhaps when var 19 was introduced.