Community

AGI Programming => AGI Community How To's & Tutorials => Topic started by: OmerMor on April 25, 2016, 05:49:28 AM

Title: Official AGI Documentation
Post by: OmerMor on April 25, 2016, 05:49:28 AM
I don't think this was ever leaked before...
Enjoy!  8)

(Documents are dated 1986-05-30)
Title: Re: Official AGI Documentation
Post by: Kawa on April 25, 2016, 08:00:40 AM
Oh goddammit he's at it again.

*downloads, studies*
Title: Re: Official AGI Documentation
Post by: MusicallyInspired on April 25, 2016, 08:32:55 AM
Too good. It's a shame it's taken this long to get this stuff out, so long after the games (not to mention the engine) mean nothing to most people.
Title: Re: Official AGI Documentation
Post by: Collector on April 25, 2016, 10:32:16 AM
Guess I'll have to put this on the Wiki. Now if I could only find someone to help with the logic backend of my AGI IDE.
Title: Re: Official AGI Documentation
Post by: gumby on April 26, 2016, 06:17:57 PM
I know I left you in the middle of development of your project Collector and I am sorry about that.  What's left to complete?
Title: Re: Official AGI Documentation
Post by: Collector on April 27, 2016, 02:47:01 AM
Outside of the sound editor the GUI for all of the editors are done. Mostly it is the logic backend and a compiler. Save functionality in the backend for the object file also needs to be finished. It will load an existing object file. That would make the IDE usable for actual game development. To be complete the Visual AGI sound editor would need to be ported to C#, but a user could probably just use the existing editor outside of the IDE or use no sounds.

I am not sure how many would make use of it these days, but all of the existing AGI IDEs have problems on modern Windows.
Title: Re: Official AGI Documentation
Post by: Collector on May 16, 2016, 04:57:02 PM
I hope that the to do list for the new AGI IDE didn't chase off Gumby. Anyway it was as much his project as mine.
Title: Re: Official AGI Documentation
Post by: Collector on May 30, 2016, 05:56:12 PM
A little off topic, but I have been talking to Damon Slye about the early Dynamix engines. Sadly he said that not much documentation survives, but he may have some printed source to a version of 3-Space. It would be interesting to see it, though I would be more interested in DGDS.
Title: Re: Official AGI Documentation
Post by: Brandon on May 30, 2016, 06:57:34 PM
For those contacting Sierra/Dynamix alumni, I would certainly appreciate your assistance in the efforts of the Sierra Museum. The Sierra Museum's website is currently in alpha and I'm working hard to get it to a beta stage.

The Sierra Museum has arisen from the Art of Sierra project and my long involvement with trying to preserve and archive Sierra's history, back to the early days of SierraGamers.com (Ken's website, not the Facebook group), and I welcome and seek donations (or loans) of anything related to Sierra. The Art of Sierra team has created goodwill with many Sierra and Dynamix alumni in the course of our work, and the Museum curates the largest physical collection of original Sierra materials. It's my belief that the physical preservation of as much Sierra material as posssible, bringing Sierra's scattered history back into one place, is just as important as the digital preservation of those materials.

If in the course of contacting alumni you would consider mentioning the Museum, it would be most appreciated. The more physical documents and other physical items that enter the care of the Museum, the greater the awareness of the Museum as the best place to trust with those materials. Items that make their way to the Museum can then be archived and shared according to the wishes of the person donating the materials.
Title: Re: Official AGI Documentation
Post by: OmerMor on May 31, 2016, 02:59:15 AM
A little off topic, but I have been talking to Damon Slye about the early Dynamix engines. Sadly he said that not much documentation survives, but he may have some printed source to a version of 3-Space. It would be interesting to see it, though I would be more interested in DGDS.

3-Space was used for the Tank Simulator in Heart of China (https://youtu.be/UujHRfDHJV8?t=14).

If you can get a copy of that documentation - please share it! The ScummVM guys might be able to use that when they decide to support DGDS games.
Title: Re: Official AGI Documentation
Post by: OmerMor on May 31, 2016, 03:01:41 AM
For those contacting Sierra/Dynamix alumni, I would certainly appreciate your assistance in the efforts of the Sierra Museum. The Sierra Museum's website is currently in alpha and I'm working hard to get it to a beta stage.

The Sierra Museum has arisen from the Art of Sierra project and my long involvement with trying to preserve and archive Sierra's history, back to the early days of SierraGamers.com (Ken's website, not the Facebook group), and I welcome and seek donations (or loans) of anything related to Sierra. The Art of Sierra team has created goodwill with many Sierra and Dynamix alumni in the course of our work, and the Museum curates the largest physical collection of original Sierra materials. It's my belief that the physical preservation of as much Sierra material as posssible, bringing Sierra's scattered history back into one place, is just as important as the digital preservation of those materials.

If in the course of contacting alumni you would consider mentioning the Museum, it would be most appreciated. The more physical documents and other physical items that enter the care of the Museum, the greater the awareness of the Museum as the best place to trust with those materials. Items that make their way to the Museum can then be archived and shared according to the wishes of the person donating the materials.

Definitely a worthy cause Brandon!
I'll be sure to raise awareness with my contacts.

Title: Re: Official AGI Documentation
Post by: gumby on June 04, 2016, 03:04:32 PM
I hope that the to do list for the new AGI IDE didn't chase off Gumby. Anyway it was as much his project as mine.

Nope, just haven't had any spare time - which has been getting really, really old.
Title: Re: Official AGI Documentation
Post by: lance.ewing on October 15, 2016, 10:32:07 AM
I know it's been a while, but it doesn't look like I left a comment on this thread. I did see it at the time you posted it Omer, but was incredibly busy work wise at the time. Quite a find.

I thought I'd bump this topic again mainly in relation to the discussion about what we mean by AGI. It turns out that at one point in time, they may have referred to the whole thing, and even specifically to the language, as AGDS. If this is official Sierra AGI documentation, then this is what it has to say:

Quote
AGDS - Adventure Game Development System

AGDS was developed as a fast means to implement adventure games using a
machine portable language. It outwardly resembles the programming
language "C".

AGDS is a specialized set of commands which help manipulate objects on a
3-D plane. Before looking at the commands, it is important to understand
some basic terminology.

There is only one reference in that document to AGI, and that is simply to reference the other AGI.DOC documentation. The implications of this reference are quite interesting though. It seems to suggest that both AGDS and AGI coexisted as different terms. If you read both documents, the terminology isn't consistent though. One is about the "Actions, Tests and Flags" in the Adventure Game Interpreter. The other has 10 references to AGDS and uses the term to refer to various things, three of the references already listed above, and the rest listed below:

Quote
AGDS works like traditional cartoon animation

AGDS cells are cycled at the rate of 9 per second

Each cell contains the specific bit-maps AGDS displays on-screen.

AGDS determines which LOOP is displayed, based on the direction of an object.

AGDS always automatically loads, and executes ROOM 0.

AGDS pictures are composed of a picture screen, and a priority screen.

To accomplish this, AGDS scans directly down the control priority until it finds some "non-control" priority.

So AGDS is used above to refer to the whole system, and in relation to the VIEWs, PICTUREs, and LOGIC. For example, "AGDS cells", "AGDS pictures", "AGDS is a specialized set of commands".

Hmmm. Maybe AGDS was the original name and they changed it to AGI later on?

(off now to locate that HWM topic with the original AGI interpreter source code in it, with the purpose of doing further terminology investigation)

Edit:

Direct link below:

http://sciprogramming.com/community/index.php?topic=1418.msg6446#msg6446
[it's attached at the bottom of that post]

I couldn't find any references to AGDS in there, but it does reference AGI quite a bit, mainly to say its for the AGI.EXE file (e.g. "Memory Map for AGI.EXE 10/07/87"), but it also says this:

Quote
** Routines for handling menus in AGI


Edit Edit:

What is even more bizarre about the AGDS name is that that is what was used here:

http://www.ifarchive.org/indexes/if-archiveXprogrammingXagi.html
http://wiki.scummvm.org/index.php/AGIWiki/AGDS
http://www.agidev.com/articles/agispec/agispecs-11.html#agds

...for the Russian set of tools that were created years ago for building AGI games. AGDS in that particular case apparently stood for "Adventure Game Design System", which is very similar but appears to be complete coincidence.
Title: Re: Official AGI Documentation
Post by: lance.ewing on October 15, 2016, 11:57:27 AM
I've been playing Apple II AGI games. Take a look at the name of the system in this screen shot (attached)::
Title: Re: Official AGI Documentation
Post by: Collector on October 15, 2016, 12:29:47 PM
Would development of the port have anything to do with it? Perhaps from the tools for Apple?
Title: Re: Official AGI Documentation
Post by: Kawa on October 15, 2016, 12:33:34 PM
Again, I am reminded of the whole SCUMM/SPUTM stuff.
Title: Re: Official AGI Documentation
Post by: lance.ewing on October 15, 2016, 12:53:47 PM
Would development of the port have anything to do with it? Perhaps from the tools for Apple?

I wondered whether it was something to do with the relationship with Walt Disney. Perhaps they used a different name for the system in relation to the games they built that were associated with Disney, such as Black Cauldron and Donald Duck's playground. I also wondered whether maybe the AGDS name was a wider external name for the system, for use with any external partner, i.e. not just for Disney, and AGI was perhaps the internal name. - Just some thoughts I had. - I guess Al Lowe would remember. He was the Disney dev guy, right? Might send him an email.

Omer, without necessarily revealing your sources, can you tell us if there is any suggestion that the AGDS document was associated with a Disney game or Disney games?

Edit:

Email just sent to Al. We'll see what he remembers. I asked him about GAL as well.
Title: Re: Official AGI Documentation
Post by: lance.ewing on October 15, 2016, 03:26:49 PM
Reference to AGDS by a former Sierra On-Line employee:

http://www.sierranet.net/~pgr/resume.htm

...where Greg Rowland (a developer of the original Kings Quest game) says:

Quote
Helped design and produce graphics and animation utilities, game logic compiler, later to become known as Adventure game development system AGDS.

So there we go. Both the official documentation and a former employee refer to the graphics and animations utilities, and game logic compiler, as AGDS.
Title: Re: Official AGI Documentation
Post by: lance.ewing on October 15, 2016, 04:11:39 PM
The more I look, the more I see it. It would appear that it's not only in Black Cauldron the Apple II version, but also the PC version of BC. Greg Rowland mentioned King's Quest 1, as we saw in his resume above, but I can't find it mentioned in the game. LSL1, PQ1, and KQ3 all refer to Adventure Game Development System though. I just hadn't noticed it was so prominent before:

http://policequest.wikia.com/wiki/PQ1EGA_transcript

I've been searching the net for "Adventure Game Development System" and turned up the above page. It's a dump of messages from PQ1. I then looked a bit closer at a few other games and can see it in LSL1 and KQ3. Still looking...    Also in Donald Duck's Playground.

http://sarien.net/policequest

http://sarien.net/kingsquest3

I guess whenever I saw that in the past, I probably thought of it more as a description of the system rather than its name. I always thought it was called AGI, and certainly there are games that say "Adventure Game Interpreter" in the credits and opening screens, and there are files names that use AGI and packaging that mentioned AGI, and books, etc., etc. But AGDS also seems to have been a name that they used for it.
Title: Re: Official AGI Documentation
Post by: NewRisingSun on October 15, 2016, 04:30:42 PM
I would say that any 2-D game development system would need to include:In the case of the "Adventure Game Development System", there's the "Picture Editor" and "Object Editor" for 1., the "Sound Editor" for 2., "CG - the game compiler" for 3., and "AGI", the "Adventure Game Interpreter" for 4. Therefore, the whole thing is the AGDS, and AGI is Part 4 of it.  ;D
Title: Re: Official AGI Documentation
Post by: lance.ewing on October 15, 2016, 04:40:39 PM
Yeah, you're probably right, in that that is probably how it started out. AGDS was probably the whole development package of tools, and AGI the interpreter.

More links to easily verifiable screens that mention "Adventure Game Development System":

https://archive.org/details/msdos_donald_ducks_playground_1984_sierra

https://archive.org/details/msdos_Leisure_Suit_Larry_1_-_Land_of_the_Lounge_Lizards_1987

https://archive.org/details/msdos_Black_Cauldron_The_1986

(Those runnable DOS games on archive.org are quite cool really).
Title: Re: Official AGI Documentation
Post by: NewRisingSun on October 15, 2016, 05:23:58 PM
Quote
(Those runnable DOS games on archive.org are quite cool really).
I find them to be nightmares, as the underlying emulators are badly configured, the game versions mislabeled, and the aspect of openly offering thousands of games for free stretching the meaning of "preservation" to a ludicrous level. But maybe that's just me.  ;)
Title: Re: Official AGI Documentation
Post by: lance.ewing on October 15, 2016, 05:48:57 PM
I don't disagree with any of that. I was thinking more of the underlying technology of running DOS games in a browser using Javascript, at seemingly full speed.
Title: Re: Official AGI Documentation
Post by: Kawa on October 15, 2016, 06:15:43 PM
I don't like it.

Sure, it's impressive, but that's just not what webpages are for, know what I'm saying? Webpages are for downloading a DOSBox from and the games to run on it with a nice description on how to run it 'n shit, not for hosting a DOSBox in-place holy shit no wonder people[who?] say web browsers are operating systems onto their own. It's shit like JS having grown faster than Tetsuo on crack that makes all these web browsers basically the same two or three cores in different coats of user-unfriendly paint.

</rant>

Still, gotta love availability and hidden gems.
Title: Re: Official AGI Documentation
Post by: lance.ewing on October 15, 2016, 06:51:19 PM
I've written a few emulators, and a couple of HTML5 games, ....so I love machine emulation, and I love HTML5, and DOS was the best thing Microsoft has done in a while. So running LSL3 in the browser at full screen without any issues definitely ticks all my boxes. I like it when something just works in the browser. I'm a Java developer with 18 years experience and I spent an hour earlier today tearing my hair out trying to work out how to get my Firefox installation to run a Java applet so that I could run an Apple II emulator in the browser. HTML5 is the way of the future. Java is so broken and dead in browsers these days, its embarrassing.    :-[
Title: Re: Official AGI Documentation
Post by: lskovlun on October 15, 2016, 07:40:52 PM
Again, I am reminded of the whole SCUMM/SPUTM stuff.
And SCI, what with the language being called Script, the compiler being called SC, the interpreter being called SCI(V) etc.
Title: Re: Official AGI Documentation
Post by: OmerMor on October 16, 2016, 12:06:17 PM
On a related note, here's what Robert (Bob) Heitman (http://www.mobygames.com/developer/sheet/view/developerId,2200/) wrote to me once:
Quote
Whenever I hear of people writing a modern version of SCI I ask myself a fundamental question and that question is: Just exactly what do they think SCI was?
 
SCI was a marketing invented "name" for a generation of Sierra's development environment that consisted of a proprietary scripting language (.SC files), several proprietary asset file formats (view, pic, sound, font), and a executable file that functioned both as the interpreter of the script files but also provided all of the graphics, input, sound, and resource management functions required to "play" the game.
 
The idea of someone needing to do anything to "reverse engineer" the engine assumes that there is a complicated master data structure underneath all of it. There is not. A SCI game is written completely in a procedural manner. There is no SCUMM-like data being interpreted. At best there is core set of low level functions to handle the heavy listing but everything else was glued together in the scripting language itself.
 
Given the existence of all sorts of DOS emulators, and the fact that you can still run Sierra games today (as long as you can accommodate the faster clock speeds), it just doesn't seem like that much of a challenge.
 
So, what am I missing?
 
It seems like the real challenge of the day is to recreate ANY development environment that empowers fans of the old fashioned graphics adventure games to create new games in a seamless manner.
 
For the record it took Jeff and myself approximately 8 months to create the core of the development environment and get to first scripting of the 16 color version. He wrote the language and the language interpreter and I wrote the animation editor (VE), the picture editor (PE), the resource manager, the initial text parser, and all I/O routines. I only mention this as it seems like a perfect project for a slightly larger group to have knocked out in a couple months.


Omer, without necessarily revealing your sources, can you tell us if there is any suggestion that the AGDS document was associated with a Disney game or Disney games?

I got the AGDS document with some files related to Donald Duck's Playground.

As for the AGDS/AGI question - I agree with NewRisingSun's assertion of System vs. Interpreter.
Title: Re: Official AGI Documentation
Post by: lskovlun on October 16, 2016, 12:43:43 PM
On a related note, here's what Robert (Bob) Heitman (http://www.mobygames.com/developer/sheet/view/developerId,2200/) wrote to me once:
Quote
For the record it took Jeff and myself approximately 8 months to create the core of the development environment and get to first scripting of the 16 color version. He wrote the language and the language interpreter and I wrote the animation editor (VE), the picture editor (PE), the resource manager, the initial text parser, and all I/O routines.
And Pablo Ghenis wrote the parser, and Stuart Goldstein wrote the music system.
Title: Re: Official AGI Documentation
Post by: lance.ewing on October 18, 2016, 01:05:36 PM
Email just sent to Al. We'll see what he remembers. I asked him about GAL as well.

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.
Title: Re: Official AGI Documentation
Post by: lskovlun on October 18, 2016, 01:56:07 PM
We should try to track down Greg Rowland if we can.
He was the graphic artist according to the title screen, not a programmer. The programmers were (again, according to the title screen) Charles Tingley, Ken McNeill and Chris Iden. I've only ever heard of Tingley in the context of this game, oddly. Chris Iden does not appear in the credits for the PCjr version, so one might assume he was the one who ported the game to the ordinary PC?
Title: Re: Official AGI Documentation
Post by: lance.ewing on October 18, 2016, 05:46:41 PM
It would seem that that wasn't all though. According to his resume:

Quote
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.
Title: Re: Official AGI Documentation
Post by: lance.ewing on October 18, 2016, 05:53:19 PM
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.
Title: Re: Official AGI Documentation
Post by: lance.ewing on October 18, 2016, 06:02:12 PM
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.
Title: Re: Official AGI Documentation
Post by: lance.ewing on October 18, 2016, 06:43:55 PM
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
Title: Re: Official AGI Documentation
Post by: lance.ewing on February 18, 2017, 05:49:44 PM
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.
Title: Re: Official AGI Documentation
Post by: Collector on February 18, 2017, 11:29:42 PM
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?
Title: Re: Official AGI Documentation
Post by: OmerMor on February 19, 2017, 03:34:56 PM
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.
Title: Re: Official AGI Documentation
Post by: lance.ewing on February 19, 2017, 05:53:24 PM
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.
Title: Re: Official AGI Documentation
Post by: lance.ewing on February 22, 2017, 04:44:39 PM
...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.
Title: Re: Official AGI Documentation
Post by: lance.ewing on February 24, 2017, 02:09:44 PM
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:

Quote
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?
Title: Re: Official AGI Documentation
Post by: lance.ewing on February 24, 2017, 02:46:42 PM
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()
Title: Re: Official AGI Documentation
Post by: HWM on February 24, 2017, 09:03:43 PM
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.
Title: Re: Official AGI Documentation
Post by: lance.ewing on February 25, 2017, 05:10:05 AM
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.
Title: Re: Official AGI Documentation
Post by: HWM on February 25, 2017, 10:00:46 AM
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.
Title: Re: Official AGI Documentation
Post by: lance.ewing on April 09, 2017, 03:39:30 PM
Quote
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.
Title: Re: Official AGI Documentation
Post by: Collector on April 09, 2017, 06:38:30 PM
Given that most of the template and fan games are late AGI2 it seems that the documentation focus on those interpreters.
Title: Re: Official AGI Documentation
Post by: lance.ewing on April 12, 2017, 04:42:35 PM
Yeah, that is exactly right. I wrote quite a lot of the fan made AGI specs, and from memory I think it was based mainly on 2.9XX and above. I don't remember ever having the DDP game at that time, which is our closest match to the official Sierra AGI doc.
Title: Re: Official AGI Documentation
Post by: Collector on March 28, 2018, 09:19:45 PM
I finally got around to Adding this to the AGI Wiki.

http://agiwiki.sierrahelp.com/index.php?title=Official_AGDS/AGI_Documentation
Title: Re: Official AGI Documentation
Post by: AGKorson on March 29, 2018, 02:44:52 AM
I think you should clearly indicate that the information is for 2.001 (or whatever version you think it is). There is a significant amount of difference between these specs and what we see in the most commonly used versions for fanmade games. I'm mostly done a full decompile on v2.917 and will be sharing what I've learned in the WinAGI help files. Lots of interesting things I've found by going through all the code.
Title: Re: Official AGI Documentation
Post by: Collector on March 29, 2018, 09:13:53 AM
Good point. It would be nice if you could contribute what you have found to the Wiki
Title: Re: Official AGI Documentation
Post by: AGKorson on March 29, 2018, 10:12:08 AM
I will add that to my list of things to do. Hopefully I'll be able to get to that in next couple of months.
Title: Re: Official AGI Documentation
Post by: Collector on March 29, 2018, 07:10:38 PM
Thanks for any contribution that you might be able to make. I don't believe you currently have an account on the Wiki. When you are ready let me know and I'll add one for you. You probably contributed to the original AGI Wiki. A lot of the current Wiki is reconstructed from the original one via the Wayback. If you get a chance you could look through the Wiki and see what might need attention or correction.