From a534ed39371593b4a6aa7863429b77292fcf78d9 Mon Sep 17 00:00:00 2001 From: Jason Self Date: Fri, 22 Mar 2024 20:45:21 -0700 Subject: [PATCH] Publish first version of ZIL Programming for Interactive Fiction: A Technical Guide --- COPYING | 674 ++++++++++++++++++ guide.md | 2052 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 2726 insertions(+) create mode 100644 COPYING create mode 100644 guide.md diff --git a/COPYING b/COPYING new file mode 100644 index 0000000..f288702 --- /dev/null +++ b/COPYING @@ -0,0 +1,674 @@ + GNU GENERAL PUBLIC LICENSE + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The GNU General Public License is a free, copyleft license for +software and other kinds of works. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. We, the Free Software Foundation, use the +GNU General Public License for most of our software; it applies also to +any other work released this way by its authors. You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you have +certain responsibilities if you distribute copies of the software, or if +you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + + Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + + Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the manufacturer +can do so. This is fundamentally incompatible with the aim of +protecting users' freedom to change the software. The systematic +pattern of such abuse occurs in the area of products for individuals to +use, which is precisely where it is most unacceptable. Therefore, we +have designed this version of the GPL to prohibit the practice for those +products. If such problems arise substantially in other domains, we +stand ready to extend this provision to those domains in future versions +of the GPL, as needed to protect the freedom of users. + + Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and +modification follow. + + TERMS AND CONDITIONS + + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public License. + + "Copyright" also means copyright-like laws that apply to other kinds of +works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this +License. Each licensee is addressed as "you". "Licensees" and +"recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of an +exact copy. The resulting work is called a "modified version" of the +earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work based +on the Program. + + To "propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + + To "convey" a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user through +a computer network, with no transfer of a copy, is not conveying. + + An interactive user interface displays "Appropriate Legal Notices" +to the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work +for making modifications to it. "Object code" means any non-source +form of a work. + + A "Standard Interface" means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + + The "System Libraries" of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +"Major Component", in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + + The Corresponding Source need not include anything that users +can regenerate automatically from other parts of the Corresponding +Source. + + The Corresponding Source for a work in source code form is that +same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + + You may make, run and propagate covered works that you do not +convey, without conditions so long as your license otherwise remains +in force. You may convey covered works to others for the sole purpose +of having them make modifications exclusively for you, or provide you +with facilities for running those works, provided that you comply with +the terms of this License in conveying all material for which you do +not control copyright. Those thus making or running the covered works +for you must do so exclusively on your behalf, under your direction +and control, on terms that prohibit them from making any copies of +your copyrighted material outside their relationship with you. + + Conveying under any other circumstances is permitted solely under +the conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + + When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such circumvention +is effected by exercising rights under this License with respect to +the covered work, and you disclaim any intention to limit operation or +modification of the work as a means of enforcing, against the work's +users, your or third parties' legal rights to forbid circumvention of +technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these conditions: + + a) The work must carry prominent notices stating that you modified + it, and giving a relevant date. + + b) The work must carry prominent notices stating that it is + released under this License and any conditions added under section + 7. This requirement modifies the requirement in section 4 to + "keep intact all notices". + + c) You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable section 7 + additional terms, to the whole of the work, and all its parts, + regardless of how they are packaged. This License gives no + permission to license the work in any other way, but it does not + invalidate such permission if you have separately received it. + + d) If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has interactive + interfaces that do not display Appropriate Legal Notices, your + work need not make them do so. + + A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +"aggregate" if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms +of sections 4 and 5, provided that you also convey the +machine-readable Corresponding Source under the terms of this License, +in one of these ways: + + a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that product + model, to give anyone who possesses the object code either (1) a + copy of the Corresponding Source for all the software in the + product that is covered by this License, on a durable physical + medium customarily used for software interchange, for a price no + more than your reasonable cost of physically performing this + conveying of source, or (2) access to copy the + Corresponding Source from a network server at no charge. + + c) Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, and + only if you received the object code with such an offer, in accord + with subsection 6b. + + d) Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to the + Corresponding Source in the same way through the same place at no + further charge. You need not require recipients to copy the + Corresponding Source along with the object code. If the place to + copy the object code is a network server, the Corresponding Source + may be on a different server (operated by you or a third party) + that supports equivalent copying facilities, provided you maintain + clear directions next to the object code saying where to find the + Corresponding Source. Regardless of what server hosts the + Corresponding Source, you remain obligated to ensure that it is + available for as long as needed to satisfy these requirements. + + e) Convey the object code using peer-to-peer transmission, provided + you inform other peers where the object code and Corresponding + Source of the work are being offered to the general public at no + charge under subsection 6d. + + A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means any +tangible personal property which is normally used for personal, family, +or household purposes, or (2) anything designed or sold for incorporation +into a dwelling. In determining whether a product is a consumer product, +doubtful cases shall be resolved in favor of coverage. For a particular +product received by a particular user, "normally used" refers to a +typical or common use of that class of product, regardless of the status +of the particular user or of the way in which the particular user +actually uses, or expects or is expected to use, the product. A product +is a consumer product regardless of whether the product has substantial +commercial, industrial or non-consumer uses, unless such uses represent +the only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, +procedures, authorization keys, or other information required to install +and execute modified versions of a covered work in that User Product from +a modified version of its Corresponding Source. The information must +suffice to ensure that the continued functioning of the modified object +code is in no case prevented or interfered with solely because +modification has been made. + + If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + + The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or updates +for a work that has been modified or installed by the recipient, or for +the User Product in which it has been modified or installed. Access to a +network may be denied when the modification itself materially and +adversely affects the operation of the network or violates the rules and +protocols for communication across the network. + + Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + + When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders of +that material) supplement the terms of this License with terms: + + a) Disclaiming warranty or limiting liability differently from the + terms of sections 15 and 16 of this License; or + + b) Requiring preservation of specified reasonable legal notices or + author attributions in that material or in the Appropriate Legal + Notices displayed by works containing it; or + + c) Prohibiting misrepresentation of the origin of that material, or + requiring that modified versions of such material be marked in + reasonable ways as different from the original version; or + + d) Limiting the use for publicity purposes of names of licensors or + authors of the material; or + + e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified versions of + it) with contractual assumptions of liability to the recipient, for + any liability that these contractual assumptions directly impose on + those licensors and authors. + + All other non-permissive additional terms are considered "further +restrictions" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + + If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; +the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + + However, if you cease all violation of this License, then your +license from a particular copyright holder is reinstated (a) +provisionally, unless and until the copyright holder explicitly and +finally terminates your license, and (b) permanently, if the copyright +holder fails to notify you of the violation by some reasonable means +prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + + Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or +run a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + + An "entity transaction" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + + You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's "contributor version". + + A contributor's "essential patent claims" are all patent claims +owned or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, "control" includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + + Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + + In the following three paragraphs, a "patent license" is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To "grant" such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + + If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. "Knowingly relying" means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + + A patent license is "discriminatory" if it does not include within +the scope of its coverage, prohibits the exercise of, or is +conditioned on the non-exercise of one or more of the rights that are +specifically granted under this License. You may not convey a covered +work if you are a party to an arrangement with a third party that is +in the business of distributing software, under which you make payment +to the third party based on the extent of your activity of conveying +the work, and under which the third party grants, to any of the +parties who would receive the covered work from you, a discriminatory +patent license (a) in connection with copies of the covered work +conveyed by you (or copies made from those copies), or (b) primarily +for and in connection with specific products or compilations that +contain the covered work, unless you entered into that arrangement, +or that patent license was granted, prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey a +covered work so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you may +not convey it at all. For example, if you agree to terms that obligate you +to collect a royalty for further conveying from those to whom you convey +the Program, the only way you could satisfy both those terms and this +License would be to refrain entirely from conveying the Program. + + 13. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the GNU Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new versions of +the GNU General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + + Each version is given a distinguishing version number. If the +Program specifies that a certain numbered version of the GNU General +Public License "or any later version" applies to it, you have the +option of following the terms and conditions either of that numbered +version or of any later version published by the Free Software +Foundation. If the Program does not specify a version number of the +GNU General Public License, you may choose any version ever published +by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future +versions of the GNU General Public License can be used, that proxy's +public statement of acceptance of a version permanently authorizes you +to choose that version for the Program. + + Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY +OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM +IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF +ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS +THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE +USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF +DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD +PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), +EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF +SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + +Also add information on how to contact you by electronic and paper mail. + + If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + Copyright (C) + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, your program's commands +might be different; for a GUI interface, you would use an "about box". + + You should also get your employer (if you work as a programmer) or school, +if any, to sign a "copyright disclaimer" for the program, if necessary. +For more information on this, and how to apply and follow the GNU GPL, see +. + + The GNU General Public License does not permit incorporating your program +into proprietary programs. If your program is a subroutine library, you +may consider it more useful to permit linking proprietary applications with +the library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. But first, please read +. diff --git a/guide.md b/guide.md new file mode 100644 index 0000000..97486dc --- /dev/null +++ b/guide.md @@ -0,0 +1,2052 @@ +# ZIL Programming for Interactive Fiction: A Technical Guide + +# Introduction + +This document provides a structured approach to learning ZIL, catering +to a technical audience. Each chapter builds upon the previous ones, +gradually introducing more complex concepts and techniques. This guide +aims to equip readers with the knowledge and skills necessary to +create their own interactive fiction games using ZIL. + +# Copyright & Licensing + +Copyright (C) 2024 Jason Self + +You can redistribute and/or modify ZIL Programming for Interactive +Fiction: A Technical Guide under the terms of the GNU General Public +License as published by the Free Software Foundation, either version 3 +of the License, or (at your option) any later version. + +This book is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this book. If not, see + +# Chapter 1: Introduction to ZIL and Interactive Fiction + +Welcome to the world of ZIL programming and interactive fiction (IF)! +This chapter will introduce you to the fundamental concepts of IF and +the role ZIL plays in creating these unique narrative experiences. +We'll explore the basic structure of ZIL code and key elements that +form the foundation of IF games. Additionally, we'll examine the +relationship between ZIL, the interpreter, and the game world, +providing a comprehensive overview for your journey into ZIL +programming. + +## What is Interactive Fiction? + +Interactive fiction is a genre of computer games where players +experience a story through text-based interaction. Unlike traditional +novels, IF allows players to influence the narrative by typing +commands and making choices that affect the story's direction and +outcome. This creates a dynamic and engaging experience where players +actively participate in shaping the narrative. + +## ZIL: The Language of Interactive Fiction + +ZIL (Zork Implementation Language) is a specialized programming +language designed specifically for creating IF games. Developed by +Infocom in the early 1980s, ZIL offers a powerful and flexible toolset +for crafting intricate narratives with rich interactivity. + +While ZIL shares some similarities with other programming languages, +it has unique features tailored to the needs of IF development. These +include: + + Object-oriented structure: ZIL revolves around objects + representing rooms, items, and characters within the game world. + + Action routines: Objects have associated action routines that + define how they respond to player interaction. + + Parser and syntaxes: ZIL includes a sophisticated parser that + interprets player input and maps it to specific actions and + objects. + + Event handling: ZIL allows for time-based events and dynamic + responses through interrupts and other mechanisms. + +By leveraging these features, ZIL empowers developers to create +immersive and responsive IF experiences. + +## The Z-Machine and the Interpreter + +ZIL code is compiled into a machine-independent format called Z-code, +which is then executed by a virtual machine known as the Z-machine. +This means that ZIL games can be played on various platforms without +requiring platform-specific modifications. The Z-machine interpreter +acts as the bridge between the Z-code and the player, reading the +compiled code and presenting the game world to the player through text +descriptions and responses to their input. + +## Key Concepts in ZIL Programming + +As you delve deeper into ZIL, you'll encounter several key concepts +that are crucial for understanding how IF games are built: + + Objects: These represent the fundamental building blocks of the + game world, including rooms, items, and characters. + + Properties: Objects have properties that define their + characteristics, such as descriptions, synonyms, and flags. + + Routines: These are sub-programs that perform specific tasks, + such as handling player actions or describing objects. + + Parser: The parser interprets player input and identifies the + verb, direct object, and indirect object. + + Action routines: These routines are associated with objects and + handle player interaction based on the parser's output. + + Events: Events are time-based occurrences or dynamic responses + triggered by specific conditions. + +This chapter has provided a foundational understanding of ZIL and its +role in creating interactive fiction. By understanding these core +concepts, you'll be well-equipped to start building your own +interactive fiction games using ZIL. + +In the following chapters, we'll explore each of these concepts in +greater detail, equipping you with the knowledge and skills necessary +to become a proficient ZIL programmer. + +# Chapter 2: Data Types and Expressions in ZIL + +This chapter dives into the core of ZIL programming: data types and +expressions. We'll explore the various types of data ZIL uses to +represent different elements of the game world and how you can +manipulate them through expressions. By understanding these +fundamental building blocks, you'll be able to construct the logic and +mechanics of your interactive fiction game. + +## ZIL Data Types + +ZIL utilizes a relatively small set of data types, each serving a +specific purpose in representing and manipulating information within +the game: + +1. FORM: + + A FORM is a fundamental structure in ZIL, representing a + collection of objects enclosed within balanced angle brackets + (< >). + + It's used to perform operations, either built-in subroutines or + user-defined routines. + + The first element of a FORM specifies the operation, while the + remaining elements are arguments. + +Example: + + <+ 5 3> ; This FORM adds the integers 5 and 3. + +2. FIX (Integer): + + FIX represents integers within the range of -32767 to 32767. + + Integers outside this range are illegal, and ZIL doesn't support + floating-point numbers. + + Various arithmetic operations work with FIXes: + + + (addition) + + - (subtraction) + + * (multiplication) + + / (division) + + MOD (modulus) + + ABS (absolute value) + + RANDOM (generates a random number within a specified range) + +Example: + + <- 10 4> ; This expression subtracts 4 from 10, resulting in 6. + +3. ATOM (Variable): + + ATOMs function as variables, storing values that can be referenced + and manipulated. + + They are case-sensitive and can contain capital letters, numbers, + hyphens, question marks, and dollar signs. + + There are two types of ATOMs: + + LOCAL: These are temporary variables used within routines and + are specific to each routine. + + GLOBAL: These variables have values accessible to all routines + throughout the game. + +Example: + + ; Sets the GLOBAL ATOM player-name to "Alice". + +4. STRING: + + STRINGs represent text data enclosed within double quotes ("). + + They are used primarily for displaying text to the player. + + To include a double quote within a string, use a backslash () + before it. + +Example: + + ; Displays text with a quote. + +5. LIST: + + LISTs are collections of objects enclosed within parentheses ( ). + + They are primarily used within routines to improve code + readability and structure. + +Example: + + (NORTH TO KITCHEN WEST TO BEDROOM) ; LIST of room exits. + +6. TABLE: + + TABLEs are similar to arrays in other languages, storing multiple + elements of any type. + + They are created at the top level of your code (not within a + routine). + + Two types of TABLEs exist: + + TABLE: Stores elements without any additional information. + + LTABLE: The first element automatically stores the number of + elements in the table. + +Example: + + ; Creates an LTABLE of fruits. + +7. OBJECT: + + OBJECTs represent the core elements of the game world: rooms, + items, and characters. + + They are defined with properties like descriptions, synonyms, + adjectives, flags, and action routines. + + OBJECTs can be manipulated through operations like MOVE, REMOVE, + LOC, FIRST?, and NEXT?. + +Example: + + + +## Expressions in ZIL + +Expressions in ZIL combine data types and operations to perform +computations and manipulate game elements. ZIL uses prefix notation, +where the operator comes before the operands. + +Example: + + <+ 2 3> ; This expression adds 2 and 3, resulting in 5. + +Expressions can be nested to create complex logic and calculations. + +Example: + + > 5> ; Checks if (10 - (2 * 3)) is greater than 5. + +## Conditional Expressions and Predicates + +Conditional expressions evaluate to either true or false and are +crucial for decision-making in your game. ZIL uses several predicates +for comparisons and checks: + + EQUAL?: Checks if the first argument is equal to any of the + subsequent arguments. + + ZERO?: Checks if the argument is equal to zero. + + LESS?: Checks if the first argument is less than the second + argument. + + GRTR?: Checks if the first argument is greater than the second + argument. + + FSET?: Checks if a specific flag is set on an object. + + IN?: Checks if an object is located within another object. + +These predicates are often used within COND statements to execute +different code branches based on conditions. + +Example: + + + ) + (T + )> + +This COND statement checks if the OPENBIT flag is set on the DOOR +object. If true, it prints "The door is open." Otherwise, it prints +"The door is closed." + +## Edge Cases and Considerations + +While working with data types and expressions in ZIL, be mindful of +potential edge cases and specific behaviors: + + Integer range: Remember that FIXes are limited to the range of + -32767 to 32767. Exceeding this range will cause errors. + + Truth values: In ZIL, any non-zero value is considered true. + However, distinguish between false (zero) and the special token <> + used for clarity in representing boolean states. + + Synonym ambiguity: If multiple objects share the same synonym, the + parser might require further clarification from the player to + identify the intended object. + + Property manipulation: Not all object properties can be directly + manipulated with GETP and PUTP. Some require using GETPT and + manipulating the resulting property table. + +By understanding these data types, expressions, and potential edge +cases, you'll be able to write robust and efficient ZIL code for +your interactive fiction game. + +This chapter has provided a detailed exploration of ZIL's data types +and expressions. With this knowledge, you can now start building the +logic and mechanics of your game, defining how objects interact and +respond to player actions. In the following chapters, we'll delve +deeper into specific aspects of ZIL programming, further expanding +your IF development toolkit. + +# Chapter 3: Routines and Control Flow in ZIL + +Routines are the workhorses of ZIL programming, serving as +user-defined subroutines that implement the core logic and +functionality of your interactive fiction game. This chapter will +delve into the intricacies of defining, calling, and managing routines +in ZIL, providing you with the knowledge to structure your code +effectively and control the flow of your game's execution. + +## Defining Routines + +A routine is defined using the following syntax: + + + +Let's break down each element: + + routine-name: This is a valid ATOM name that uniquely identifies + the routine. + + (argument-list): This defines the arguments the routine can + receive, which we'll explore in detail shortly. + + expression expression ...: This represents the body of the + routine, containing ZIL expressions that are evaluated + sequentially when the routine is called. The result of the last + expression becomes the return value of the routine. + +## Argument List + +The argument list within the parentheses specifies the parameters the +routine can accept. It can be divided into three optional parts: + +1. Required Arguments: + + These are LOCAL ATOMs representing mandatory inputs for the routine. + + They are listed first in the argument list, separated by spaces. + +Example: + + + +In this example, the MOVE-OBJECT routine requires two arguments: +OBJECT-NAME and DESTINATION. + +2. Optional Arguments: + + These are arguments that the routine can accept but are not + mandatory. + + They are indicated by placing the string "OPTIONAL" after the + required arguments. + + Each optional argument is defined as a LIST containing a LOCAL + ATOM and a default value. If the calling routine doesn't provide a + value for an optional argument, the default value is used. + +Example: + + + +Here, the DESCRIBE-OBJECT routine takes OBJECT-NAME as a required +argument and VERBOSE as an optional argument. If VERBOSE isn't +provided, it defaults to T (true). + +3. Auxiliary Arguments (Local Variables): + + These are additional LOCAL ATOMs used as temporary variables + within the routine. + + They are declared after the optional arguments, preceded by the + string "AUX". + + You can provide an initial value for auxiliary arguments, similar + to optional arguments. + +Example: + + + +This routine has one required argument (CONTAINER) and one auxiliary +argument (COUNT) initialized to 0. + +Remember that any LOCAL ATOM used within a routine must be declared in +its argument list, either as a required argument, optional argument, +or auxiliary argument. + +## Naming Conventions + +Choosing meaningful and consistent names for your routines and +variables significantly improves code readability and maintainability. +Here are some recommendations: + + Use descriptive names that reflect the routine's purpose (e.g., + COUNT-GRUES, OPEN-DOOR). + + Employ common conventions for frequently used variables (e.g., + OBJ for object, CNT for counter, DIR for direction). + + Maintain consistent naming patterns throughout your codebase. + +## Looping with REPEAT + +To create loops within your routines, ZIL provides the REPEAT construct: + + + +The REPEAT evaluates the expressions within its body repeatedly until +it encounters a RETURN statement. Note that the empty parentheses are +mandatory. + +Example: + + + > + + + ) + (T + )>> + +This loop prints "HA HA HA HA HA!" by incrementing the CNT variable +and checking if it has reached 5. + +## Exiting Routines + +Routines typically return the value of the last expression evaluated +in their body. However, you can explicitly control the return value +and exit the routine using: + + : Immediately exits the routine and returns T (true). + + : Immediately exits the routine and returns <> (false). + + : Immediately exits the routine and returns the + specified value. + +Remember that RETURN within a REPEAT loop only exits the loop, not the +entire routine. + +## Restrictions and Formatting + +Be mindful of these limitations when working with routines: + + A routine can take a maximum of three arguments (required and optional combined). + + There can be a maximum of 16 LOCAL ATOMs within a routine. + +While ZIL ignores whitespace and formatting characters, using them +strategically is crucial for code readability. Indentation and +vertical alignment can help visually distinguish code blocks and +improve understanding of the routine's structure. + +By mastering the concepts of defining, calling, and managing routines, +you'll be able to construct complex and well-structured ZIL programs +for your interactive fiction games. + +# Chapter 4: Objects and Properties + +Objects are the fundamental building blocks of any interactive fiction +game created with ZIL. They represent everything from physical items +and locations to abstract concepts and characters. This chapter will +delve into the intricacies of creating and manipulating objects in +ZIL, providing a comprehensive understanding of their properties and +how they interact with the game world. + +## Creating Objects + +Objects are defined using the OBJECT subroutine, which takes several +arguments: + + + +Let's break down each element: + + object-name: This is the internal name used to reference the + object within ZIL code. It should be unique and descriptive (e.g., + BRASS_LANTERN, FRONT_DOOR). + + (DESC "short description"): This defines the object's short + description, displayed in brief room descriptions and the status + line. + + (ADJECTIVE adjective-1 adjective-2 ...): This optional list + specifies adjectives that can be used to describe the object + (e.g., RED, SHINY). + + (SYNONYM noun-1 noun-2 ...): This list defines nouns that can be + used to refer to the object. At least one synonym is required + (e.g., LANTERN, LAMP). + + (property value): This represents various properties assigned to + the object, such as SIZE, CAPACITY, ACTION, and more. We'll + explore these in detail later. + +Example: + + + +This defines an object named BRASS_LANTERN with the short description +"brass lantern." Players can refer to it using "lantern," "lamp," or +"light," and it has a size of 15. The ACTION property links it to the +routine LANTERN_F, which handles player interactions with the lantern. + +## Object Properties + +Properties define various characteristics and behaviors of objects. +Here's a detailed look at some commonly used properties: + + FLAGS: This property specifies the object's initial state using + flags like TAKEBIT (takeable), CONTBIT (container), OPENBIT + (open), and many more. Flags can be dynamically set and cleared + during gameplay using FSET and FCLEAR. + + ACTION: This property links the object to an action routine that + handles player interactions. For example, if the player tries to + EAT the APPLE, the APPLE_F routine will be called to handle the + action. + + DESCFCN: This property specifies a routine used by the describers + to provide a customized description of the object, allowing for + dynamic descriptions based on the object's state or location. + + LOC: This property determines the object's location. Initially, + it specifies the room where the object is found. As the player + interacts with the object, its location can change (e.g., moved to + another room or taken by the player). + + SIZE: This property defines the object's size or weight, + impacting how many objects the player can carry and how much space + it occupies in containers. + + CAPACITY: For containers, this property specifies the total size + or weight of objects it can hold. + + VALUE: In games with scoring systems, this property defines the + points awarded for taking or interacting with the object. + + LDESC: This property provides a long description of the object, + displayed when the player examines it or enters a room in verbose + mode. + + FDESC: This property defines a "first" description used before + the object is touched or interacted with for the first time. + + TEXT: This property contains text displayed when the player tries + to READ the object. + +These are just some of the commonly used properties. ZIL allows for +creating custom properties to suit your game's specific needs. + +## Manipulating Properties + +Object properties can be dynamically accessed and modified during +gameplay using the GETP and PUTP instructions: + + GETP: Retrieves the value of a specific property for a given + object. For example, retrieves the long + description of the current room. + + PUTP: Changes the value of a property for a given object. For + example, sets the size of the SWORD + object to 10. + +Note that some properties, like exits, cannot be manipulated directly +with GETP and PUTP. They require using GETPT and PUTPT to access and +modify their underlying table structures. + +## Edge Cases and Considerations + + Multiple adjectives: When a player uses multiple adjectives to + describe an object, the parser typically uses the first one for + matching. However, you can implement custom logic to handle + specific combinations or prioritize certain adjectives. + + Synonyms and ambiguity: If multiple objects share the same + synonym, the parser might ask the player for clarification. You + can use the GENERIC property to define a routine that helps + resolve such ambiguities. + + Property limitations: ZIL has limitations on the number of + properties an object can have and the size of property values. Be + mindful of these limitations when designing your game and consider + alternative approaches if necessary. + +By understanding the intricacies of object creation, properties, and +manipulation techniques, you can build a rich and interactive game +world within your ZIL-based interactive fiction. + +# Chapter 5: Rooms and Exits: Building the Spatial Fabric of Your Game + +Rooms are the fundamental building blocks of your interactive fiction +world, defining the spaces players can explore and interact with. This +chapter will guide you through the process of creating rooms in ZIL, +focusing on the various types of exits that connect them and the +action routines that bring them to life. We'll explore detailed +examples and edge cases, equipping you with the knowledge to craft a +compelling and immersive game environment. + +## Defining a Room in ZIL + +Rooms are created using the ROOM subroutine, which takes several +properties to define its characteristics: + + + +Let's break down each element: + + room-name: This is the unique identifier for your room, + represented as a global ATOM. + + (IN ROOMS): This indicates that the room belongs to the special + ROOMS object, which acts as a container for all rooms in your + game. + + (DESC "short description"): This defines the short description + displayed when the player enters the room and on the status line. + + (FLAGS flag-1 ... flag-n): Here, you specify flags that determine + the room's initial state, such as RLANDBIT (indicating the room is + on land) and ONBIT (meaning the room is lit). + + (property value): This section defines additional properties of + the room, including exits, long descriptions (LDESC), and action + routines (ACTION). + +## Exits: Connecting Your Rooms + +Exits are crucial for allowing players to navigate your game world. +ZIL offers several types of exits, each with unique behaviors and +implementation methods: + +1. Unconditional Exits (UEXIT) + +These are the simplest exits, allowing players to move in a specific +direction without any restrictions. They are defined as follows: + + (direction TO room-name) + +For example, (NORTH TO FOYER) creates an exit leading north to the +FOYER room. + +2. Unconditional Non-Exits (NEXIT) + +These define directions players cannot go in, but instead of the +default "You can't go that way" message, you can provide a custom +response: + + (direction "reason-why-not") + +For example, (WEST "A sheer cliff drops off to the west.") explains +why the player cannot go west. + +3. Conditional Exits (CEXIT) + +These exits allow movement only if a specific condition is met, +typically based on the value of a global variable: + + (direction TO room-name IF global-atom-name) + +For example, (EAST TO HIDDEN-CHAMBER IF SECRET-DOOR-OPEN) allows +passage east only if the SECRET-DOOR-OPEN global is true. + +You can also provide an alternative message if the condition isn't +met: + + (direction TO room-name IF global-atom-name ELSE "reason-why-not") + +4. Door Exits (DEXIT) + +These exits are specifically for doors, allowing movement only if the +door object is open: + + (direction TO room-name IF door-name IS OPEN) + +For example, (SOUTH TO GARDEN IF OAK-DOOR IS OPEN) allows passage +south only if the OAK-DOOR object has its OPENBIT flag set. + +5. Flexible Exits (FEXIT) + +These offer the most flexibility, calling a custom routine to handle +the movement logic: + + (direction PER routine-name) + +The routine can perform checks, modify the game state, and determine +the outcome of the movement attempt. + +Examples: + +Here are some examples of how these exits might be used in your game: + + UEXIT: (NORTH TO LIBRARY) - A simple exit leading north to the + library. + + NEXIT: (UP "The ceiling is too low to climb up here.") - Explains + why the player cannot go up. + + CEXIT: (WEST TO TREASURE-ROOM IF KEY-FOUND) - Allows access to + the treasure room only after finding the key. + + DEXIT: (EAST TO BALCONY IF FRENCH-DOORS IS OPEN) - Requires the + French doors to be open to access the balcony. + + FEXIT: (DOWN PER TRAPDOOR-EXIT) - Calls a custom routine to handle + the complexities of using the trapdoor. + +Things to Remember: + + Case sensitivity: Direction names, tokens (TO, PER, IF, IS, OPEN, + ELSE), and room/routine names must be capitalized in ZIL. + + Standard directions: The substrate assumes standard directions + (north, south, east, west, etc.). If you need custom directions, + consult the relevant documentation or seek assistance. + +## Room Action Routines: Adding Dynamic Behavior + +While exits define the connections between rooms, action routines +breathe life into them. These routines are associated with the ACTION +property of a room and are called in different contexts, identified by +specific arguments: + + M-BEG: Called at the beginning of each turn when the player is in + the room. This allows for dynamic changes or events to occur. + + M-END: Called at the end of each turn, after the player's action + has been handled. This can be used for cleanup or setting up + future events. + + M-ENTER: Called when the player enters the room, providing an + opportunity for special actions or descriptions. + + M-LOOK: Called by the describers when they need to generate the + room's long description. This allows for dynamic descriptions that + change based on the game state. + +Example: + +Here's an example of a room action routine that handles different +contexts: + + + > + +This routine demonstrates how you can use different contexts to create +dynamic and responsive environments within your game. + +## LDESC: Providing a Static Description + +The LDESC property allows you to define a static long description for +a room. This is useful for rooms that don't change significantly +throughout the game: + + (LDESC "You are in a cozy kitchen. The aroma of freshly baked cookies + fills the air.") + +However, if your room's description needs to change dynamically based +on the game state, you should use the M-LOOK clause in the room's +action routine instead. + +## Conclusion + +By understanding how to define rooms, implement various types of +exits, and leverage action routines, you can build a rich and +immersive game world for your interactive fiction. Remember to +consider the player's experience and use the different tools at your +disposal to create engaging and dynamic environments that enhance your +narrative. + +# Chapter 6: The Containment System and Accessibility + +The containment system is a fundamental aspect of ZIL programming, +governing how objects are located and interact within the game world. +This chapter will provide a comprehensive exploration of this system, +delving into the hierarchy of object locations and the rules that +determine object accessibility for player interaction. We'll also +examine the distinctions between local, global, and local-global +objects, equipping you with the knowledge to expertly manage object +placement and interaction in your ZIL games. + +## Understanding the Containment Hierarchy + +In ZIL, every object has a location, defined by its LOC property. This +property specifies the object's container, creating a hierarchical +structure that dictates where objects reside within the game world. +Rooms, for instance, are contained within a special object called +ROOMS, while items can be located within rooms or inside other +containers. + +Here's an example illustrating the containment hierarchy: + + ROOMS: This special object acts as the top-level container for + all rooms in the game. + + Living Room: This room object is contained within ROOMS. + + Treasure Chest: This object is located within the Living Room. + + Golden Key: This object is contained within the Treasure Chest. + +This hierarchical structure allows for complex object relationships +and interactions. For example, opening the Treasure Chest would make +the Golden Key accessible to the player, while the key itself might be +used to unlock a door in another room. + +## Rules of Accessibility and the Parser + +The parser, responsible for interpreting player input, relies heavily +on the containment system to determine which objects are accessible to +the player at any given moment. An object is considered accessible if +it meets the following criteria: + + Present: The object must exist within the game world and have a + valid LOC property. + + Visible: The object must be visible to the player, meaning it's + not hidden or inside a closed container. + + Referenceable: The object must be referenceable by the player, + meaning it has appropriate synonyms and adjectives defined. + +When the player attempts to interact with an object, the parser +analyzes the input and searches for a matching object based on the +provided noun phrase. The search prioritizes objects in the following +order: + + Local Objects: The parser first looks for matching objects within + the current room or carried by the player. + + Local-Global Objects: If no local object is found, the parser + searches for local-global objects accessible in the current room. + + Global Objects: Finally, the parser considers global objects, + which are accessible from any location in the game. + +This search order prioritizes efficiency, as searching through local +objects is faster than examining all objects in the game. However, it +can lead to unexpected behavior if multiple objects share the same +name. For example, if a local object and a local-global object are +both named "button," the parser will prioritize the local object even +if the player intended to interact with the local-global one. To avoid +such ambiguity, ensure unique names or provide additional context in +object descriptions. + +## Distinctions between Local, Global, and Local-Global Objects + +ZIL categorizes objects into three types based on their accessibility: + + Local Objects: These objects can only exist in one location at a + time. Most takeable objects fall into this category, as they are + either in a specific room or carried by the player. + + Global Objects: These objects are accessible from any location in + the game. They typically represent abstract concepts, characters + not physically present, or omnipresent elements like the sky or + ground. + + Local-Global Objects: These objects can be referenced in multiple + specific locations, but not everywhere. Doors are a classic + example, as they exist in the two rooms they connect. Other + examples include geographical features like rivers or mountains. + +Defining local-global objects requires specifying the rooms where they +are accessible using the GLOBAL property within each relevant room +definition. This allows for efficient parsing and prevents players +from referencing objects that wouldn't make sense in their current +context. + +## Edge Cases and Considerations + +While the containment system and accessibility rules generally +function seamlessly, some edge cases require careful consideration: + + Nested Containers: When dealing with nested containers, the + parser's search depth is limited by default. To ensure objects + within multiple layers of containers are accessible, use the + SEARCHBIT flag on the relevant containers. + + Ambiguity and Disambiguation: If multiple objects share the same + name, the parser might require disambiguation from the player. + Provide clear descriptions and distinct synonyms to minimize + ambiguity. + + Dynamic Changes: If an object's location or accessibility changes + during gameplay, ensure that the relevant properties and flags are + updated accordingly. + +By understanding these edge cases and applying the principles outlined +in this chapter, you can expertly manage object placement and +interaction within your ZIL games, creating a seamless and immersive +experience for your players. + +This chapter has provided a thorough exploration of the containment +system and accessibility rules in ZIL. By mastering these concepts, +you'll be able to craft intricate and believable game worlds where +players can interact with objects in a logical and intuitive manner. + +# Chapter 7: Events and Interrupts + +In interactive fiction, not all actions and responses happen solely +due to player input. Events can occur independently, adding dynamism +and enriching the game world. ZIL provides powerful mechanisms for +implementing such events through interrupts and room M-END clauses. +This chapter will delve into these features, offering a comprehensive +exploration of event handling in ZIL. We'll cover queuing and +dequeuing interrupts, designing effective event routines, and +addressing potential edge cases to ensure your events seamlessly +integrate into your interactive narrative. + +## Understanding Interrupts + +Interrupts are routines triggered by specific conditions or after a +set number of moves, regardless of player input. They allow you to +create dynamic events like a sudden storm, a character entering a +room, or an alarm going off. + +Here's how interrupts work: + + Defining the Interrupt Routine: + + Create a routine with a name typically prefixed with "I-" + (e.g., I-THUNDERSTORM). + + Within the routine, define the actions and responses that + occur when the interrupt is triggered. + + Ensure the routine returns true if it outputs text using TELL + and false otherwise. This is crucial for proper interaction + with the WAIT verb. + + Queuing the Interrupt: + + Use the QUEUE instruction to schedule the interrupt. + + Provide the interrupt routine's name and the number of moves + after which it should be triggered. + + For example, will trigger the + I-THUNDERSTORM routine after 10 moves. + + Interrupt Execution: + + After each turn where time passes (excluding parser failures + and specific commands like SCRIPT), the CLOCKER routine runs. + + CLOCKER checks queued interrupts and calls those whose time + has come. + + Once an interrupt runs, it's removed from the queue unless + queued with -1, which makes it run every turn until explicitly + dequeued. + + Dequeuing Interrupts: + + Use the DEQUEUE instruction to remove a queued interrupt + before it triggers. + + This is useful for situations where the event is no longer + relevant due to player actions or other changes in the game + state. + +# Designing Effective Interrupt Routines + +Here are some key considerations for crafting well-structured and +efficient interrupt routines: + + Check Player Location: Before outputting text or performing + actions, ensure the player is in a relevant location to experience + the event. This avoids nonsensical situations like a character + appearing in a room the player isn't currently in. + + Manage Interrupt Duration: If an interrupt involves multiple + actions or messages, use a counter or flag system to track its + progress and ensure it deactivates itself when finished. This + prevents the interrupt from continuously triggering and causing + unintended repetition. + + Consider Player Actions: Account for how player actions might + affect the interrupt. For example, if an interrupt involves a + character approaching the player, consider what happens if the + player moves away or interacts with the character before the + interrupt fully plays out. + +## Room M-END Clauses: Events within Rooms + +An alternative way to handle events is through M-END clauses within a +room's action routine. These clauses execute at the end of every turn +spent in that room, offering a way to create location-specific events +without relying on the global interrupt queue. + +Here's how to use M-END clauses: + + Define the M-END Clause: + + Within the room's action routine, include a COND clause + checking for the M-END argument. + + Inside this clause, define the actions and responses that + occur at the end of each turn in that room. + + Event Execution: + + At the end of every turn (before CLOCKER runs), the current + room's action routine is called with the M-END argument. + + If the M-END clause exists, it executes the defined actions + and responses. + +M-END clauses are ideal for events inherently tied to a specific +location, such as a dripping faucet, a flickering light, or a +recurring sound. Edge Cases and Considerations + +While interrupts and M-END clauses offer powerful tools for event +handling, be mindful of potential edge cases: + + Interrupt Conflicts: If multiple interrupts are queued to trigger + simultaneously, their execution order might not be guaranteed. + Design your interrupts to be independent or implement mechanisms + to manage potential conflicts. + + Player Death and Interrupts: When the player dies, ensure any + ongoing interrupts are appropriately handled. This might involve + dequeuing them or modifying their behavior to fit the new game + state. + + Save and Restore: Consider how events and interrupts interact with + save and restore functionality. Ensure that queued interrupts and + ongoing events are properly saved and restored to maintain game + consistency. + +By carefully considering these edge cases and designing your events +with foresight, you can ensure your ZIL game delivers a dynamic and +engaging experience for players. + +This chapter has provided a detailed exploration of event handling in +ZIL. By understanding interrupts, M-END clauses, and the nuances of +event design, you can now create a vibrant and responsive game world +that reacts to both player actions and the passage of time. + +# Chapter 8: Actors and Interaction + +Interactive fiction thrives on engaging characters that populate the +game world and interact with the player. ZIL refers to these +characters as actors. This chapter will provide a detailed guide to +creating and managing actors in your ZIL games. We'll explore how to +define actors, handle dialog and interaction, and address potential +challenges to ensure your characters feel believable and contribute to +an immersive narrative experience. + +## Defining Actors + +Actors are essentially objects with the PERSONBIT flag set, indicating +they are characters capable of independent actions and communication. +When creating an actor, consider the following: + + Basic Object Properties: + + Provide a descriptive DESC for the actor. + + Include relevant SYNONYMs and ADJECTIVEs for player reference. + + Set appropriate flags like OPENBIT, CONTBIT, and SEARCHBIT if + the actor carries items. + + Action Routine: + + Define an ACTION routine for the actor, similar to other + objects. + + Remember that this routine handles both player interaction + with the actor as an object (e.g., "examine actor") and + actions performed by the actor themself. + + dialog and Interaction: + + Implement logic within the action routine to handle dialog + and interaction with the player. + + Use the WINNER variable to determine if the player is + currently addressing the actor. + + Provide appropriate responses based on the player's input and + the game context. + +## Managing dialog and Interaction + +The WINNER variable plays a crucial role in managing dialog. +Typically, WINNER is set to the PLAYER object. However, when the +player addresses an actor using the TELL verb, the WINNER temporarily +becomes that actor. This allows the actor's action routine to handle +the subsequent player input as dialog directed specifically at them. + +Here's how to handle dialog in an actor's action routine: + + Check for M-WINNER: + + Use a COND clause to check if the RARG is equal to M-WINNER. + + If true, it indicates the player is speaking to the actor. + + Handle Player Input: + + Within the M-WINNER clause, implement logic to interpret and + respond to the player's input. + + Use VERB? and other predicates to identify the player's + intent. + + Provide appropriate responses using TELL, taking into account + the game context and the actor's personality. + + Default Response: + + Include a catch-all clause to handle unrecognized or + irrelevant input. + + This ensures the player receives feedback even if their + command doesn't have a specific response. + +Remember to switch WINNER back to the PLAYER object once the dialog +ends. + +## Challenges and Edge Cases + +While implementing actors, be mindful of potential challenges: + + Ambiguity: If multiple actors are present, ensure the parser + correctly identifies the intended recipient of the player's + speech. Use specific noun phrases or implement disambiguation + mechanisms. + + Confusing Responses: Ensure the actor's responses are consistent + with their personality and the game context. Avoid generic or + nonsensical replies. + + Unintended Actions: Prevent situations where the player can + manipulate the actor in unintended ways. For example, avoid + allowing the player to "take" or "drop" an actor. + +By carefully considering these challenges and implementing robust +logic in your action routines, you can create engaging and believable +actors that enhance the player's experience in your interactive +fiction game. + +# Chapter 9: The Parser and Syntaxes: Mastering Player Input + +The parser is responsible for interpreting the player's input. This +chapter will delve deep into the parser's role and its intricate +relationship with syntaxes, the rules that govern how players can +express their intentions. We'll explore how to define legal input +structures, utilize verb synonyms, and employ syntax tokens to guide +the parser effectively. Additionally, we'll unravel the mysteries of +GWIMming and the FIND feature, allowing you to create a truly +responsive and intuitive experience for your players. + +## Demystifying the Parser + +Imagine the parser as a dedicated language expert who meticulously +analyzes each sentence the player types. Its primary goal is to +identify three key elements: + + Verb (PRSA): The action the player wants to perform (e.g., TAKE, + OPEN, EXAMINE). + + Direct Object (PRSO): The primary object the action is directed + towards (e.g., BOOK, DOOR, KEY). + + Indirect Object (PRSI): An optional secondary object involved in + the action (e.g., "PUT BOOK ON TABLE"). + +The parser accomplishes this by comparing the player's input to a set +of predefined rules called syntaxes. + +## Syntaxes: Defining the Rules of Interaction + +Syntaxes are the building blocks of player interaction, dictating the +allowed sentence structures and their corresponding actions. Each +syntax specifies a particular combination of verbs, prepositions, and +noun phrases that the parser can recognize. + +Defining a syntax involves using the SYNTAX subroutine, where you +outline the sentence structure with OBJECT tokens representing noun +phrases and actual prepositions in their respective positions. For +example: + + + +This syntax tells the parser that any sentence in the form "TAKE +noun-phrase" is valid. The V-TAKE and PRE-TAKE indicate the default +action routine and pre-action routine, respectively, associated with +this syntax. + +Here are some additional examples of common syntax definitions: + + + + + + +Notice how syntaxes can accommodate various sentence structures, +including those with indirect objects and prepositions. + +## Edge Cases and Preposition Handling + +It's important to remember that the parser ignores the second +preposition when two consecutive prepositions appear. For instance, +both "SIT DOWN CHAIR" and "SIT DOWN ON CHAIR" would be recognized by +the following syntax: + + + +This behavior simplifies syntax definitions and accommodates natural +language variations in player input. + +## Guiding the Parser with Syntax Tokens + +While basic syntax definitions are essential, you can further refine +how the parser interprets player input by employing special tokens +within the syntax definition. These tokens provide additional context +and instructions to the parser, ensuring accurate and efficient +interpretation of player intentions. + +Here are some of the most commonly used syntax tokens: + + TAKE: Instructs the parser to implicitly take the object if it's + not already in the player's inventory. This is often used for + actions like READ or those requiring tools. + + HAVE: Requires the object to be in the player's possession for the + syntax to be valid. If not, the parser will generate a message + like "You don't have the X." + + MANY: Allows multiple objects to be specified in the noun phrase. + This is useful for actions like TAKE or PUT where players might + want to interact with several objects at once. + +Additionally, several tokens guide the parser in where to look for +objects: + + HELD: Look for objects held directly by the player (not inside + other containers). + + CARRIED: Look for objects held by the player, including those + inside containers they are carrying. + + ON-GROUND: Look for objects located directly on the ground in the + current room. + + IN-ROOM: Look for objects within containers that are on the ground + in the current room. + +By strategically using these tokens, you can significantly enhance the +parser's accuracy and create a more intuitive experience for your players. + +For example, the following syntax definition for TAKE ensures that +players can only take objects that are on the ground and allows them +to take multiple objects at once: + + + +## GWIMming and the FIND Feature: Filling in the Blanks + +One of the parser's capabilities is its ability to "get what I mean" +(GWIM). This feature allows players to omit certain information in +their input, and the parser will attempt to fill in the blanks based +on context and available objects. + +The FIND token, combined with a specific flag, enables GWIMming within +a syntax. For instance: + + + +If the player simply types "OPEN" without specifying an object, the +parser will search for an accessible object with the DOORBIT flag set. +If only one such object exists, the parser will assume that's the +object the player intends to open. + +This feature significantly enhances the game's intuitiveness and +allows for more natural language interaction. However, it's crucial to +use FIND judiciously to avoid ambiguity. If multiple objects with the +specified flag are present, the parser will prompt the player for +clarification, preventing unintended actions. + +## Mastering the Parser: Tips and Best Practices + +Here are some valuable tips for working effectively with the parser +and syntaxes: + + Start with simple syntaxes: Begin by defining basic syntaxes for + essential actions like TAKE, LOOK, and GO. Gradually add more + complex structures as needed. + + Use verb synonyms: Expand player vocabulary and allow for natural + language variations by defining verb synonyms with the SYNONYM + subroutine. + + Choose meaningful names: Use clear and descriptive names for your + action routines and pre-action routines to improve code + readability and maintainability. + + Test extensively: Thoroughly test your syntaxes and parser + interactions to ensure they function as intended and handle edge + cases gracefully. + + Consider player perspective: When designing syntaxes, think about + how players might naturally express their intentions and try to + accommodate various phrasings. + +By following these guidelines and carefully crafting your syntaxes, +you can create a robust and user-friendly parser that allows players +to interact with your game world seamlessly and intuitively. + +Mastering the parser and syntaxes is crucial for building engaging and +immersive interactive fiction experiences. This chapter has provided a +comprehensive exploration of these topics, equipping you with the +knowledge and tools to create a truly responsive and enjoyable game +for your players. + +# Chapter 10: Describers and Object Presentation + +In interactive fiction, painting a vivid picture of the game world is +crucial for immersing players in the narrative. This chapter delves +into the describers, a set of routines in ZIL responsible for +presenting rooms and objects to the player. We'll explore various +description methods, including NDESCBIT, LDESC, FDESC, and DESCFCN, +and learn how to handle darkness and light conditions effectively. By +mastering the describers, you'll be able to craft evocative and +detailed descriptions that bring your game world to life. + +## The Role of Describers + +The describers are called upon whenever the game needs to present a +room description to the player. This typically occurs when: + + The player enters a new room. + + The player types the "LOOK" command. + + Other verbs like "INVENTORY" or "LOOK INSIDE" require a + description of the surroundings. + +The describers handle both the room name and its descriptive text, +taking into account the game's verbosity level (verbose, brief, +superbrief) and whether the room has been visited before. + +## Describing Rooms + +There are two main components to a room description: + + Room Name: This is the DESC property of the room object and is + displayed every time the player enters the room. Some games + enhance the presentation by using bold type or adding an addendum + if the player is in a vehicle (e.g., "Living Room, on the couch"). + + Descriptive Text: This provides a detailed description of the + room's appearance and contents. It is displayed based on the + verbosity level and whether the room has been visited before. + +The describers first determine if the room is lit or dark. If dark, +they display a message like "It's too dark to see" and return. +Otherwise, they proceed to describe the room: + + Check for LDESC: If the room has an LDESC property (a static long + description), it is displayed. + + Call Room Action Routine: If no LDESC exists, the room's action + routine is called with the argument M-LOOK. The action routine + then handles the description dynamically, allowing for changes + based on game events. + +## Edge Case: M-FLASH + +There exists an additional context code, M-FLASH, which can be used in +a room's action routine to force a description regardless of verbosity +or previous descriptions. This is rarely used but can be helpful in +specific situations. + +## Describing Objects + +Object descriptions are handled by the DESCRIBE-OBJECTS routine, which +is called after DESCRIBE-ROOM unless the room is dark. This routine +offers several ways to describe objects: + + Default Description: If no special description is defined, the + object's DESC is used in a default sentence like "You can see a + [object name] here." + + LDESC: If the object has an LDESC property, it is used to describe + the object when it is on the ground in the player's room. + + FDESC: An FDESC property provides a special initial description + for the object before it is first moved. Once the object's + TOUCHBIT is set (by taking or putting it), the FDESC is no longer + used. + + DESCFCN: This property specifies a dedicated routine for + describing the object dynamically based on various conditions. + This offers the most flexibility and complexity. + +DESCRIBE-OBJECTS makes three passes through the objects in a room: + + Objects with DESCFCNs and FDESCs are described. + + Objects with LDESCs are described. + + Remaining objects are described using their default descriptions. + +Note: The contents of containers are described immediately after the +container itself. + +## DESCFCNs: Dynamic Descriptions + +A DESCFCN is a powerful tool for crafting context-aware descriptions +for objects. It involves creating a dedicated routine that handles the +description based on various conditions. Here's how it works: + + Define DESCFCN Property: Assign the DESCFCN property to the + object, specifying the name of the describing routine. + + Write the DESCFCN Routine: This routine takes one argument (ARG) + and checks if it is called with M-OBJDESC?. If so, it returns + RTRUE to indicate it will handle the description. Otherwise, it + proceeds to describe the object based on relevant conditions using + TELL statements. + +Example: + + (DESCFCN HORN-DESC-F) + + + ) + (,HORN-MOUNTED + + + )>) + ) + (T + )>> + +This DESCFCN describes the horn differently depending on whether it is +mounted on the handlebars and whether the player is on the Magic Bikepath. + +## NDESCBIT: Suppressing Descriptions + +The NDESCBIT flag tells the describers to skip an object's +description. This is useful when: + + The object is already described in the room description. + + The object is initially described in the room but becomes takeable + later. + +Caution: When using NDESCBIT for takeable objects, ensure the room +description stops mentioning the object once taken and that the +NDESCBIT is cleared when the object is moved. + +By mastering the describers and their various options, you can create +rich and immersive descriptions that enhance the player's experience +and bring your interactive fiction game to life. + +# Chapter 11: Vehicles and Movement + +In interactive fiction, players typically navigate the world by moving +between rooms. However, ZIL offers an additional layer of complexity +with vehicles - objects that players can enter and move around in. +This chapter explores the implementation of vehicles, including +defining vehicle types, movement restrictions, and handling object +interaction within vehicles. By understanding these concepts, you can +add depth and variety to player movement in your game. + +## What are Vehicles? + +Vehicles are non-room objects that can become the player's location. +Vehicles must have the VEHBIT flag set and typically also have the +CONTBIT and OPENBIT flags, as they can contain objects and need to be +"open" for the player to enter. + +## Defining Vehicle Types and Movement + +Movement between rooms and vehicles is governed by the "medium" of +travel. Rooms have flags like RLANDBIT (for walking), RWATERBIT (for +boats), and RAIRBIT (for flying vehicles). The WALK handler checks +these flags to determine if movement is possible. For example, moving +from a land room to a water room requires a water-based vehicle. + +Vehicles themselves have a VTYPE property that defines their type and +capabilities. This property is set up in a specific way, and +consulting experienced ZIL programmers is recommended when +implementing vehicles. + +## Movement Restrictions within Vehicles + +The Location routine (the ACTION property of the vehicle object) can +be used to restrict movement within vehicles. For example, you could +prevent the player from walking or taking objects while seated. It +also handles specific actions like getting up, taking into account +conditions like whether the seat belt is fastened. + +## Object Interaction in Vehicles + +When the player is inside a vehicle, object interaction can be handled +in several ways: + + Location Routine: The vehicle's action routine can handle + interactions with objects inside or outside the vehicle. + + UNTOUCHABLE? Predicate: This predicate can be used to determine + if an object is out of reach because the player is inside a + vehicle. + + DESCFCNs: Dynamic object descriptions can be used to reflect the + player's perspective from within the vehicle. + +## Edge Cases and Considerations + + Nested Vehicles: While ZIL allows for vehicles within vehicles, + this can quickly become complex and confusing for players. Use + this sparingly and with caution. + + Movement Verbs: Consider how verbs like "CLIMB" or "ENTER" + interact with vehicles. You might need to define specific syntaxes + and handlers for these cases. + + Object Visibility: Objects inside a closed vehicle might not be + visible to the player unless the vehicle is transparent or has the + SEARCHBIT flag set. + +By carefully considering these aspects, you can create engaging and +intuitive gameplay experiences involving vehicles and movement in your +ZIL game. + +# Chapter 12: Organizing Your ZIL Code + +As your interactive fiction game grows in complexity, maintaining a +well-organized codebase becomes essential. This chapter delves into +best practices for structuring and dividing your ZIL code into +multiple files. We'll explore the concept of the substrate, common +game files, and strategies for organizing code based on geography, +scenes, or specific game elements. By following these guidelines, +you'll ensure your code remains manageable, readable, and easy to +maintain. + +## The Importance of Organization + +Organizing your ZIL code offers several benefits: + + Maintainability: A well-structured codebase is easier to + understand and modify, making it simpler to fix bugs and implement + new features. + + Readability: Clear organization helps both you and other + programmers quickly locate specific code sections and understand + their purpose. + +## Organizing Your Game Files + +While you have flexibility in organizing your game-specific code, here +are some common approaches: + + Geographical Organization: Divide the code based on the game's + geography, with separate files for different areas or locations. + + Mystery-Based Organization: Structure the code around the game's + mysteries, with files dedicated to People (actors), Places + (rooms), and Things (objects). This is often used in detective or + puzzle-focused games. + + Scene-Based Organization: If your game is divided into distinct + scenes, you can organize the code accordingly. This can be helpful + for managing complex narratives with branching paths. + + Element-Based Organization: Dedicate separate files to specific + game elements with significant code. + +Ultimately, the best approach depends on your game's specific +structure and complexity. As your project evolves, you might need to +adjust your organization strategy to maintain clarity and efficiency. + +## Edge Cases and Considerations + + File Size: Avoid creating excessively large files, as they can + become difficult to manage. Split large files into smaller, more + focused ones. + + File Naming: Use descriptive and consistent naming conventions for + your ZIL files to improve readability and navigation. + + Dependencies: Be mindful of dependencies between files and ensure + they are loaded in the correct order. + +By carefully organizing your ZIL code, you'll create a solid +foundation for developing and maintaining a complex and engaging +interactive fiction game. + +# Chapter 13: Compiling and Debugging + +Bringing your ZIL code to life requires transforming it into a +playable game. This chapter explores the compilation process, guiding +you through the use of the compiler and assembler. We'll also delve +into debugging techniques, helping you identify and resolve common +errors in your ZIL code. + +## Compilation: From ZIL to Z-code + +Compiling your ZIL game involves two main steps: + + The compiler translates your ZIL source code into Z-assembly + language. This intermediate language is specific to the + Z-machine, the virtual machine that executes ZIL games. + + The assembler takes the Z-assembly code generated by the compiler + and converts it into Z-code, a machine-independent bytecode + format. + +This Z-code is what the Z-machine interpreter ultimately executes to +run your game. + +To compile your game, you typically use a command-line interface or a +dedicated development environment that integrates the compiler and +assmebler. The specific commands might vary depending on your setup. + +## Debugging: Finding and Fixing Errors + +Debugging is an essential part of game development, and ZIL offers +various tools and techniques to help you identify and resolve errors +in your code: + + Error Messages: Both the compiler and assembler generate error + messages when encountering problems in your code. These messages + provide valuable clues about the nature and location of the error. + + Commenting Out Code: Temporarily commenting out sections of code + can help isolate problematic areas and narrow down the source of + errors. + +## Common Errors and Troubleshooting + +Here are some common errors you might encounter when working with ZIL: + + Syntax Errors: These occur when your code violates ZIL's syntax + rules, such as unbalanced angle brackets or incorrect use of + operators. + + Runtime Errors: These errors happen during game execution, often + caused by issues like accessing undefined variables or attempting + illegal operations. + + Logic Errors: These are the trickiest to find, as the code might + be syntactically correct but produce unintended results due to + flaws in the game logic. + +When debugging, it's important to approach the problem systematically: + + Identify the Error: Carefully read error messages and observe the + game's behavior to understand the nature of the problem. + + Isolate the Cause: Use techniques like tracing and commenting out + code to narrow down the source of the error. + + Fix the Problem: Once you've identified the cause, make the + necessary changes to your code. + + Test and Verify: Recompile and test your game to ensure the error + has been resolved and no new issues have been introduced. + +## Edge Cases and Considerations + + Compiler Quirks: Be aware of potential quirks or limitations in + the compiler and adjust your code accordingly. + + Testing Thoroughly: Test your game extensively to catch edge cases + and unexpected scenarios that might trigger errors. + +By mastering the art of debugging and utilizing the available tools +effectively, you'll be able to ensure your ZIL code runs smoothly and +delivers a polished and enjoyable interactive fiction experience. + +# Chapter 14: Graphics and Sound + +While ZIL is primarily focused on text-based interaction, it also +provides capabilities for incorporating graphics and sound effects +into your interactive fiction games. This chapter explores how to +integrate these elements using the DISPLAY and SOUND instructions, as +well as considerations for managing picture files and ensuring +cross-platform compatibility. + +## Integrating Graphics + +To display graphics in your ZIL game, you use the DISPLAY instruction. +It takes three arguments: + + Picture Number: This identifies the specific graphic to be + displayed from the picture file. + + Y-Coordinate: The vertical position (in pixels) where the top-left + corner of the picture should be placed. + + X-Coordinate: The horizontal position (in pixels) where the + top-left corner of the picture should be placed. + +Example: + + + +This displays the picture identified by P-TITLE at the top-left corner +of the screen (coordinates 1, 1). + +## Implementing Sound Effects + +The SOUND instruction allows you to play sound effects in your game. +It takes four arguments: + + Sound Number: Identifies the specific sound effect to be played + from the sound file. + + Operation: Determines the action to be performed: initialize (1), + start (2, default), stop (3), or clean up (4). + + Volume: (Optional) Sets the volume level for the sound effect. + + Repeat Count: (Optional) Specifies how many times the sound should + be repeated. + +Example: + + + +This plays the sound effect CAR-BACKFIRE at volume level 5 and repeats +it twice. + +## Managing Picture and Sound Files + +Graphics and sound effects are typically stored in separate files from +the main game code. These files need to be organized and referenced +correctly for your game to function properly. + + Picture File: This file contains the actual graphics data and + invisible pictures used for positioning. It needs to be tailored + to each target platform to ensure compatibility. + + Sound File: This file contains the sound effects data in a format + compatible with the target platform. + +## Accessibility + + Consider players who might not be able to experience graphics or + sound due to disabilities. Provide alternative ways to access the + information conveyed by these elements. + +By carefully integrating graphics and sound effects into your ZIL +game, you can create a richer and more immersive experience for your +players. + +# Chapter 15: Advanced Techniques and Optimizations + +As you gain proficiency in ZIL programming, you can explore advanced +techniques and optimizations to enhance your interactive fiction games +and push the boundaries of what's possible. This chapter delves into +powerful ZIL features like tables, generics, and advanced property +manipulation. We'll also discuss strategies for optimizing code for +efficiency and memory usage, as well as techniques for handling +complex game mechanics and interactions. + +## Tables: Storing and Managing Data + +Tables in ZIL are similar to arrays in other languages, allowing you +to store and manage collections of data efficiently. They can hold +various types of data, including numbers, strings, object names, and +even routines. + +Creating Tables: + +You create tables at the top level of your ZIL code using the TABLE or +LTABLE instructions: + + + + +LTABLE creates a special type of table where the first element +automatically stores the number of elements in the table. This is +useful when you need to know the table's length dynamically. + +## Accessing and Modifying Table Elements: + +Use the GET and PUT instructions to retrieve and modify elements +within a table: + + + + +Example: + + > + + + > + +In this example, maze-exits is a table storing exit information for +different rooms. The code retrieves the exit for the current room +(stored in the current-room variable) and assigns it to the next-room +variable. + +## Generics: Handling Ambiguity + +Generics provide a mechanism for resolving ambiguity when the parser +cannot determine which object the player is referring to. By defining +a GENERIC property for an object, you can specify a routine that +handles these ambiguous cases. + +Example: + + + + + +Here, the BOOK-GENERIC routine is called when the player uses a noun +phrase like "book" and the parser finds multiple matching objects. The +routine can then ask the player for clarification or use other +strategies to resolve the ambiguity. + +## Advanced Property Manipulation + +While GETP and PUTP allow you to access and modify object properties, +ZIL offers more advanced techniques for handling complex property +manipulation: + + GETPT and PUTPT: These instructions operate on "property tables," + which can represent properties with values larger than 16 bits. + This is useful for properties like exits, which require multiple + bytes to store their information. + + GETB and PUTB: These instructions access and modify individual + bytes within tables, providing finer-grained control over property + manipulation. + +These advanced techniques are typically used for specific scenarios +and require a deeper understanding of ZIL's internal workings. Consult +the ZIL documentation and seek guidance from experienced programmers +when working with these instructions. + +## Optimizations: Efficiency and Memory Usage + +Optimizing your ZIL code can improve game performance and reduce +memory consumption. Here are some strategies to consider: + + Use efficient data structures: Choose appropriate data types and + structures to minimize memory usage. For example, use LTABLE only + when you need to know the table's length dynamically. + + Minimize routine calls: Avoid unnecessary routine calls, as they + can impact performance. Consider inlining small routines or using + macros when appropriate. + + Optimize conditional expressions: Structure your COND statements + to check the most likely conditions first. This can reduce the + number of comparisons performed. + + Use comments and formatting: Clear comments and formatting improve + code readability and maintainability, making it easier to identify + areas for optimization. + +## Handling Complex Mechanics + +ZIL provides various tools and techniques for implementing complex +game mechanics and interactions: + + Events and Interrupts: Use queued actions and interrupts to create + time-based events and dynamic responses to player actions. + + Actors and dialog: Define actors (characters) and handle + dialog interactions through the WINNER variable and specific + routines. + + Custom Syntaxes: Extend the parser's capabilities by defining + custom syntaxes for unique actions and interactions. + + Advanced Property Manipulation: Utilize advanced property + manipulation techniques to implement complex object behaviors and + game mechanics. + +By combining these techniques and optimizing your code, you can create +sophisticated and engaging interactive fiction experiences that push +the boundaries of the genre. + +Remember that optimization is often a trade-off between performance, +memory usage, and code readability. Choose the strategies that best +suit your game's needs and prioritize clarity and maintainability to +ensure your code remains manageable and enjoyable to work with. + +# Chapter 16: Using ZIL for Other Game Genres + +While ZIL was originally designed for creating text-based interactive +fiction, its flexibility and powerful features allow it to be adapted +for other game genres. This chapter explores the possibilities of +using ZIL to create different types of interactive experiences, +pushing the boundaries of traditional IF and venturing into new gaming +territories. + +## Beyond Text Adventures + +ZIL's core strengths lie in its ability to manage complex narratives, +track object states, and handle intricate player interactions. These +capabilities can be applied to various game genres beyond traditional +text adventures, including: + + Puzzle Games: ZIL can be used to create intricate puzzle + mechanics, manage object interactions, and track player progress + through challenging scenarios. + + Role-Playing Games: While ZIL might not be ideal for real-time + combat, it can handle turn-based RPG systems, character stats, + inventory management, and dialog interactions effectively. + + Simulation Games: ZIL's ability to track object states and + simulate complex systems makes it suitable for creating engaging + simulations, from managing a city to running a spaceship. + + Interactive Stories: ZIL can be used to craft interactive + narratives with branching paths and choices that impact the + story's outcome, offering a more engaging experience than linear + storytelling. + +## Adapting ZIL for Different Mechanics + +When using ZIL for non-standard game formats, you might need to adapt +certain aspects of the language and develop creative solutions to +implement specific mechanics. Here are some considerations: + + Input and Output: While text-based input remains ZIL's primary + interaction method, you can integrate other input methods like + mouse clicks or keyboard shortcuts for specific actions. Output + can also be enhanced with graphical elements or sound effects. + + Game Loops and Timing: ZIL's turn-based structure might need + adjustments for real-time or time-sensitive mechanics. You can use + interrupts and queued actions to manage timing and create the + illusion of continuous action. + + Object Interactions: ZIL's object-oriented structure is + well-suited for managing interactions in various game genres. You + can define custom properties and action routines to implement + specific game mechanics. + +## Examples and Edge Cases + + Graphical ZIL Games: Some developers have experimented with adding + graphical elements to ZIL games, creating hybrid experiences that + combine text descriptions with visual representations. + + Multiplayer ZIL Games: While ZIL is inherently single-player, + creative approaches can enable multiplayer interactions, such as + hot-seat gameplay or shared world experiences. + + Non-Narrative Games: ZIL can be used to create purely mechanical + games without a strong narrative focus, such as logic puzzles or + abstract strategy games. + +By thinking outside the box and leveraging ZIL's core strengths, you +can explore new possibilities for interactive game design and create +innovative experiences that go beyond the traditional text adventure +format. + +Remember that adapting ZIL for different genres might require +overcoming certain limitations and developing creative solutions. +However, the language's flexibility and power offer a unique +opportunity to explore uncharted territory in interactive game design. \ No newline at end of file -- 2.31.1