After many years I have finally sort-of finished the massive task of documenting the current version of Dave Platt’s A-code (developed for writing his Adventure 3, a.k.a. Adv550), as enhanced by myself for Adventure4+ (a.k.a. Adv660) and then for Adv770.
I know that I am far too close to the subject matter to make a proper assessment, so I would be very grateful to anybody willing to cast an eye on the result of my efforts and tell me whether it actually makes sense. All constructive comments are welcome (including typo reports, of course!), though if anybody feels that the lot needs re-casting, all I can say – if you are prepared to help, than maybe.
I realise that few people have ever heard of A-code, but Adv550, at least has some historic significance (as does Mike Goetz’s Adv580), and I have a distinct impression that it had a strong influence on Malmberg’s Adv1000.
There are still some bits that need adding. The debugging section still needs to be written and the styles document finished off. Ideally, I should also add lots more code snippets and maybe even a simple tutorial. But the bulk is done and I would very much welcome an outside view.
Thanks in advance to anybody willing to offer a view.
I agree with the need for tutorial games. Writing games with machine language is a rather difficult task. Also, a single file PDF format, if available, would be nice.
There is a heavily commented A-code implementation of Roger Firth’s “Cloak of Darkness” nano-adventure. You can find it on the Adventure downloads page at mipmip.org and it is, of course, also on Roger Firth’s Cloak of Darkness page (now gone from the net, but I retrieved a copy from the Way Back Machine – see Interactive Fiction Rescue.
A-code is not any sort of machine language. It is a language developed originally by Dave Platt specifically for writing Adventure-style games. Far more readable than a lot of other authoring systems (IMHO, of course – I am biased! :-)).
As for a single PDF… I’d say it is far too complex for that.
Oh, I thought it would be as easy as doing pandoc html to pdf conversion. Any multiple pdfs can be merged with pdfmerge utility. I guess not everyone is on Linux. Never mind, then.
You are right and I was half-wrong – cibersheep has already kindly constructed rough-and-ready versions of both PDF and an ePub derived from my HTML. I am about to add them to the website. But what I really meant was that the documentation is a tree of documents and some serious thought would be required to serialise it into a single document with some logical flow to it. 'Fraid this is not something anywhere near my current priority list, but if you feel it would help – please feel free to have a go.
BTW, I am on Linux (Mandrake → Mandriva → Manjaro). Haven’t used anything else for decades (except some VM-based testing of my software on Windows and Macs). But document handling has never been something I needed to look into.
A new version of documentation, correcting a few glaring errors, is now at A-code documentation, including updated pdf and epub versions , thanks to @cibersheep. The pdf and epub files now feature their publication date in their names. Both are linked from the index page. Any further updates will be published in a similar manner.
I have created a git repo with a basic script to get a basic chain to create the epub and pdf.
It needs a way of fixing the TOC (I remake it in Sigil). While I find a way of automate that, I will keep updating them by hand
I’m sure the code has bugs and maybe @ramstrong has an alternative to Calibre to build the docs with pandoc. Feel free to send your changes and fixes:
An updated version of the A-code documentation (March 12) is now available from the A-code tools and documentation page A-code documentation
It adds the section on debugging, corrects the name and use of the minor directive for dumping game data (formerly DUMP, corrected to DUMPDATA) and fixes a few typos.
It removes the redundant “Rule 5” in the upward compatibility section, replacing it with a brief explanation of the use of the PROMPTED flag in the section describing the CONTEXT mechanism.
It also adds rounds off notes on historical development in the styles section and fixes some more typos.
As far as I am concerned, that completes A-code documentation, as it currently stands. I confess that I had no idea what a massive task it was going to turn out when I started on it a few years ago. Any comments (including typo reports and other criticisms ) are welcome.
Thanks for pointing out the runaway link. Have fixed and uploaded the corrected version.
Agree about examples, assuming there is any interest in the documentation, other than as a historical document and an aid for anybody looking at sources of existing A-code games. One of my reasons for posting here was to find out whether it was worth the additional effort. So far, the lack of feedback is not encouraging.
If I were to add examples of use of individual directives, how to you think it should be slotted it? I think it could be a mistake to overload the language section. Possible options might be a separate document (with links into it from the language document), or pop-ups resulting from clicking on a directive’s name or… Any suggestions? And would you be willing to look at work in progress to offer constructive criticisms?
ROTFL! My apologies, I missed the obvious due to interpreting IFGE as “Interactive Fiction [something] [something]” – as in e.g. Gender Equality. Yes, you are quite right, the IFGE directive does exist but I somehow managed to drop it from the list of minor directives. Have fixed – thanks!
Re options. I am not after technical advice, but after a reader’s point of view. And also, whether it is actually worth doing at all.
Thanks for willingness to check anything that might or might not come to being. As programmers tend to do, I am not good at documenting systems and writing that documentation took way more effort than I’d bargained for. If there is an interest, that would be a spur, but otherwise, nothing will happen in a hurry, if ever.
As a Windows user, I would have liked to have seen more information on how to set everything up for that platform.
I am guessing that installing MSYS2 would be one option, but am not sure how that would compare with using Cygwin or WSL instead.
I would also have liked it to have been clearer whether “ANSI C” means C89 or one of the many later standards and what the minimum system requirements might be for the target platforms. Could it be used with an 8-bit cross compiler such as SDCC or z88dk for example?
Finally, is there an equivalent of switch or select case available? It seems a little long winded to use multiple IF statements to compare the same variable with different values.
Bear in mind that I am (and have been for decades) a Unix/Linux user with zilch knowledge of Windows. I used to build the Windows versions of Adv770 under Cygwin before switching to MSYS2. But these days I use gcc cross-compiler on Linux. WSL would work too, of course. But I expect you need none of that, as long as you have a Windows C compiler. There are no complicated build structures for either the acdc translator or for translated code. Just compile and link all acdc sources and a working acdc runfile should result. Then run acdc with the main .acd file as the argument, and .acd it will spit out .c and .h sources. Compile and link them together with the kernel .c and .h files – you now have the basic version of the game runfile.
ANSI C – good point. AFAIK C89 and any subsequent ones will do. My main experience is with gcc and clang and over the years I never had to specify a particular version – the default always worked. Sorry, cannot help with 8-bit cross-compilers. But chances are those should work too. I know it got built by others on 8-bit platforms back in 1990s. Whether that is at all relevant, I have no idea. Try it and if there are problems, I’ll try to fix them (or gratefully accept fixes! :-))
At present there is no SWITCH or CASE. Until trying to emulate Adv350 and Adv440 dwarf movements, I never came across a compelling use case for one (and clearly neither had Dave Platt). I expect something like SWITCH… CASE… CASE… ENDSWITCH could be implemented easily enough.
P.S. Come to think of it, the original ANSI C 1983, as described in the 2nd edition of the Kernighan/Ritchie “The C Programming Language” should also work. The current implementation was originally built using that and I have not added anything that would require other C features since then.
I recently reinstalled Windows, so I don’t currently have any compilers on my system.
MSYS2 is likely to be my best option, as I will need to install that to also test Nelua (a version of Lua that compiles to C). It should also allow me to use the A-code bash script.
My main reason for wanting to use a switch statement was to potentially save memory by using literal strings. I am hoping to be able to create games for computers with 64Kb of memory or less, so having data in memory twice (once for the line of code assigning the value and again in the memory locations storing the value) would not be good.
At this point, I haven’t seen how the final C source is structured, so I don’t know if that would be an issue yet.
One final question: is the produced C code human readable? I am not very familiar with C and would like making any needed changes (to cater for obscure systems) to be as painless as possible.
The C code produced by languages such as Nim and Blitz Max seems especially hard to follow.
