documentation/zil.md

   1 # Introduction
   2 This document covers the Zork Implementation Language, or ZIL for
   3 short, as originally developed and used by Infocom for their games.
   4
   5 ZIL is a subset of the MIT Design Language, or MDL for short, and
   6 pronounced as "Muddle". MDL is itself based on classic LISP.
   7
   8 ## Format
   9 This document is written using CommonMark, a markup language. More
  10 information about CommonMark can be found at <http://commonmark.org>.
  11
  12 ## Copyright And Licensing
  13 Permission is granted to copy, distribute and/or modify this document
  14 under the terms of the GNU Affero General Public License as published
  15 by the Free Software Foundation ("FSF"), either version 3 of the
  16 License, or (at your option) any later version published by the FSF.
  17
  18 You should have received a copy of the GNU Affero General Public
  19 License along with this document. If not see
  20 <https://gnu.org/licenses/>.
  21
  22 ## Definitions
  23 A "definition" is used to describe a room, object, routine, etc. in or
  24 used by the game. Each definition consists of a number of properties,
  25 flags, and/or instructions. A program written in ZIL can be thought of
  26 as consisting of one or more of these definitions. Definitions,
  27 properties, flags, and instructions include brackets which must be
  28 correctly paired and nested.
  29
  30 ## Comments
  31 Comments are ignored by the compiler. A comment begins with a
  32 semicolon (;) and continues until the end of the line. A multiline
  33 comment also begins with a semicolon but is enclosed in double
  34 quotes. However, single line comments may also be enclosed in double
  35 quotes. While comments may be placed anywhere in a source code file, a
  36 comment may not be placed inside an atom.
  37
  38 ## Parser
  39 The purpose of the parser is to receive and process the player's
  40 input. Its primary responsibility is to determine the player's
  41 intended action along with any objects that may be referred to.
  42
  43 The player's action is referred to internally as the PRSA (think "A"
  44 for action like "EAT", the direct object as PRSO (think "O" for
  45 "object") and the indirect object as PRSI (think "I" for indirect.)
  46
  47 For an example, the command "KILL TROLL WITH SWORD" would set the PRSA
  48 to KILL and the PRSO to TROLL and PRSI to SWORD. It is important to
  49 note that not all instructions from the player will necessarily have
  50 all three things, but a PRSA is required in all cases and you can't
  51 have a PRSI without also having a PRSO. In cases where there is no
  52 PRSI or PRSO, they are set to false.
  53
  54 Note that the PRSA isn't simply the word that the player entered. The
  55 PRSA from a given sentence is determined by the syntax definitions in
  56 the game. An example being: The player might type "CONSUME APPLE" but
  57 in the game's syntax definitions, the PRSA associated with "consume"
  58 might be EAT.
  59
  60 ## Syntax Definitions
  61 Syntax definitions are used by the parser to determine valid sentence
  62 structures. Each entry must correspond to this format:
  63
  64 A simple example might be:
  65
  66     <syntax xyzzy = v-magic>
  67
  68 Using this example, should the parser match the player's input to
  69 "xyzzy" then the PRSA is set to magic. PRSI and PRSO would be set to
  70 false.
  71
  72 ## Syntax Tokens