7 | |CENTER| *C was a captain, all covered with lace;*
8 | |CENTER| *D was a drunkard, and had a red face.*
12 .. image:: /images/picC.png
15 |C|\onventional -- static -- fiction can be written using nothing more than
16 pencil and paper, or typewriter, or word-processor; however, the
17 requirements for producing IF are a little more extensive, and the creative
18 process slightly more complex.
20 * For static fiction, you first write the text, and then you check it by
21 reading what you've written.
23 * For IF, you still have to write all of the text, but you also have to
24 establish what text gets displayed when. Once you have written the
25 necessary Inform instructions, you use a :term:`compiler` program to
26 convert them into a playable format. The resulting information is played
27 by an :term:`interpreter` program, which permits you to interact with
28 your developing world.
30 With static fiction What You Write Is What You Read, but with IF the format
31 in which you initially write the game doesn't bear much resemblance to the
32 text which the interpreter ultimately displays. For example, the "William
33 Tell" game, in the form that we wrote it, starts like this:
35 .. code-block:: inform
37 !============================================================================
38 Constant Story "William Tell";
40 "^A simple Inform example
41 ^by Roger Firth and Sonja Kesserich.^";
46 !============================================================================
54 You will never need to look at it in the form produced by the compiler::
56 050000012C6C2C2D1EF6010A0C4416900010303230313031004253FEA90C0000
57 0000000000000000000000000000168F000000000000010200000000362E3231
60 but, as you'll notice from the full transcript in :doc:`/appendices/c`, the
61 player will see the following::
63 The place: Altdorf, in the Swiss canton of Uri. The year is 1307, at
64 which time Switzerland is under rule by the Emperor Albert of
65 Habsburg. His local governor -- the vogt -- is the bullying Hermann
66 Gessler, who has placed his hat atop a wooden pole in the centre of
67 the town square; everybody who passes through the square must bow to
68 this hated symbol of imperial might...
70 Clearly, there's more to writing IF than just laying down the words in the
71 right order. Fortunately, we can make one immediate simplification: the
72 translated form produced by the Inform compiler -- those cryptic numbers
73 and letters held in what's known as the :term:`story file` -- is designed
74 to be read by the interpreter program. The story file is an example of a
75 "binary" file, containing data intended for use only by a computer program.
76 Forget all that unreadable gibberish.
78 So that leaves just the first form -- the one starting "``Constant Story``"
79 -- which represents the tale written as a piece of IF. That's the
80 :term:`source file` (so called because it contains the game in its
81 original, source, form) which you create on your computer. The source file
82 is a "text" (or "ASCII") file containing words and phrases which can be
83 read -- admittedly after a little tuition, which is what this guide is all
86 .. Generated by autoindex
89 pair: NotePad; text editor
90 pair: SimpleText; text editor
91 pair: TextEdit; text editor
92 pair: Windows; operating system
94 How do you create that source file? Using a third software program: an
95 :term:`editor`. However, unlike the compiler and interpreter, this program
96 isn't dedicated to the Inform system -- or even to IF. An editor is an
97 entirely general tool for creating and modifying text files; you've
98 probably already got a basic one on your computer (an IBM PC running
99 Windows comes with NotePad, while an Apple Macintosh has SimpleText or
100 TextEdit), or you can download a better one from the Internet. An editor
101 is like a word-processing program such as MS Word, only much less complex;
102 no fancy formatting features, no bold or italics or font control, no
103 embedded graphics; it simply enables you to type lines of text, which is
104 exactly what's needed to create an IF game.
106 If you look at the game source above, or in :doc:`/appendices/c`, you'll
107 notice ``Include "Parser";`` and ``Include "VerbLib";`` a few lines down
108 from the top of the file. These are instructions to the Inform compiler to
109 "include" -- that is, to merge in the contents -- of files called
110 ``Parser.h`` and ``VerbLib.h``. These are not files which you have to
111 create; they're standard :term:`library files`, part of the Inform system.
112 All that you have to do is remember to Include them in every game that you
113 write. Until you've a fair understanding of how Inform works, you've no
114 need to worry about what they contain (though you can look if you want to:
115 they're readable text files, just like the ones this guide will teach you
118 So, we've now introduced all of the bits and pieces which you need in order to
119 write an Inform adventure game:
121 * a text :term:`editor` program which can create and modify the
122 :term:`source file` containing the descriptions and definitions of your
123 game. Although it's not recommended, you can even use a word-processing
124 program to do this, but you have to remember to save your game in Text
127 * some Inform :term:`library files` which you Include in your own game
128 source file in order to provide the :term:`model world` -- a basic game
129 environment and lots of useful standard definitions;
131 * the Inform :term:`compiler` program, which reads your source file (and
132 the library files) and translates your descriptions and definitions into
133 another format -- the :term:`story file` -- intended only for...
135 * an Inform :term:`interpreter` program, which is what players of your game
136 use. A player doesn't require the source file, library files or compiler
137 program, just the interpreter and the game in compiled format (which,
138 because it's a binary file not meaningful to human eyes, neatly
139 discourages players from cheating).
141 .. Generated by autoindex
145 All of those, apart from the editor, can be downloaded for free from the IF
146 Archive. One approach is to fetch them individually, following the
147 guidance on Graham's page: visit http://www.inform-fiction.org/ and look
148 for the "Software" section. However, if you're using a PC or a Mac, you'll
149 find it easier to download a complete package containing everything that
150 you need to get started.
154 Inform on an IBM PC (running Microsoft Windows)
155 ===============================================
157 Although the Windows operating system is upgraded on a fairly regular
158 basis, its basic capabilities and ways of working have remained
159 more-or-less consistent for many years. The information here applies to
160 PCs running Windows 95 onwards.
162 .. rubric:: Installing and testing Inform
166 1. Download http://www.firthworks.com/roger/downloads/inform_pc_env.zip to
167 a temporary location on your PC.
169 2. Use a tool like WinZip to unzip the downloaded file, giving you a new
170 ``Inform`` folder. Move this folder (and its contents) to a suitable
171 location on your PC -- a good place would be ``C:\My Documents\Inform``,
172 but you could also use ``C:\Documents and Settings\yourname\My
173 Documents\Inform``, ``C:\Inform`` or ``C:\Program Files\Inform``. You
174 should now have this set of folders:
176 .. image:: /images/inform_pc_env.*
179 In order to make the download small and fast, these folders include just
180 enough to get you started as an Inform designer -- the compiler and
181 interpreter programs, the library files, the ``Ruins.inf`` example file
182 from the |DM4|, and a template for your own first game. A few other
183 folders are included as placeholders where you could later download
184 additional components, if you wanted them. As soon as possible, you
185 should download the |DM4| into the ``Inform\Doc`` folder -- it's an
186 essential document to have, and has been omitted from this download only
187 because of its 3MB size.
189 3. To verify that the downloaded files work properly, use Windows Explorer
190 to display the contents of the ``Inform\Games\MyGame1`` folder: you will
191 see the two files ``MyGame1.bat`` and ``MyGame1.inf``:
193 .. image:: /images/filelist1.*
196 ``MyGame1.inf`` is a tiny skeleton game in Inform source format. By
197 convention, all Inform source files have an extension of .inf; Windows
198 has an inbuilt definition for ``.inf`` files, and so shows its Type as
199 "Setup Information", but this doesn't seem to matter. If you
200 double-click the file, it should open in NotePad so that you can see how
201 it's written, though it probably won't mean much -- yet.
203 .. Generated by autoindex
207 4. ``MyGame1.bat`` is an MS-DOS batch file (an old kind of text-only
208 computer program, from the days before point-and-click interfaces) which
209 runs the Inform compiler. Double-click it; a DOS window opens as the
210 game compiles, and you'll see this::
212 C:\My Documents\Inform\Games\MyGame1>..\..\Lib\Base\Inform MyGame1
213 +include_path=.\,..\..\Lib\Base,..\..\Lib\Contrib | more
215 Inform 6.30 for Win32 (27th Feb 2004)
217 C:\My Documents\Inform\Games\MyGame1>pause "at end of compilation"
218 Press any key to continue . . .
220 Press the space bar, then close the DOS window.
224 On Windows NT, 2000 and XP, the DOS window closes of its own accord
225 when you press the space bar.
227 5. A story file ``MyGame1.z5`` has appeared in the folder; this is the
228 compiled game, which you can play using an interpreter:
230 .. image:: /images/filelist2.*
233 The extension of ``.z5`` signifies that the story file contains a
234 Z-machine game in Version 5 (today's standard) format.
236 6. Use Windows Explorer to display the contents of the ``Inform\Bin\Frotz``
237 folder, and double-click ``Frotz.exe``; the interpreter presents an
238 ``Open a Z-code Game`` dialog box.
240 7. Browse to display the ``Inform\Games\MyGame1`` folder, and select
241 ``MyGame1.z5``. Click ``Open``. The game starts running in the Windows
244 8. When you tire of "playing" the game -- which won't take long -- you can
245 type the QUIT command, you can select ``File > Exit``, or you can simply
246 close the Frotz window.
248 9. Using the same techniques, you can compile and play ``Ruins.inf``, which
249 is held in the ``Inform\Games\Download`` folder. RUINS is the game used
250 as an example throughout the |DM4|.
252 .. rubric:: Setting file associations
254 The business of first starting the interpreter, and then locating the story
255 file that you want to play, is clumsy and inconvenient. Fortunately, when
256 you first run the Frotz interpreter, it automatically creates an
257 association with story files whose extension is ``.z5``. From now on,
258 you'll be able to play a game simply by double-clicking its story file. If
259 some any reason this doesn't work, you can set up the association yourself:
261 1. Double-click ``MyGame1.z5``; Windows asks you to select the program
264 * type ``Z-code V5 Adventure`` as the "``Description for...``"
265 * click to select "``Always use this program...``"
268 2. Browse to display the ``Inform\Bin\Frotz`` folder, and select
269 ``Frotz.exe``. Click ``Open``.
271 .. rubric:: Changing the Windows icon
273 If the Windows icon that's displayed alongside ``MyGame1.z5`` doesn't look
274 right, you can change it.
276 1. In Windows Explorer, either select ``View > Options...`` and click
277 ``File Types``, or select ``Tools > Folder Options...`` and click ``File
280 * select the game file type in the list, which is in order either of
281 application (Frotz) or of extension (Z5)
284 2. In the ``Edit File Type`` dialog, click ``Change Icon``.
286 3. In the ``Change Icon`` dialog, ensure that the file name is
287 ``Inform\Bin\Frotz\Frotz.exe``, and select one of the displayed icons.
288 Click ``OK`` to close all the dialogs. The files in the folder should
291 .. image:: /images/filelist3.*
294 .. rubric:: Compiling using a batch file
296 You can view -- and of course change -- the contents of ``MyGame1.bat``,
297 the batch file which you double-click to run the compiler, using any text
298 editor. You'll see two lines, something like this (the first chunk is all
299 on one long line, with a space between the ``MyGame1`` and the
302 ..\..\Lib\Base\Inform MyGame1
303 +include_path=.\,..\..\Lib\Base,..\..\Lib\Contrib | more
304 pause "at end of compilation"
306 These long strings of text are command lines -- a powerful interface method
307 predating the icons and menus that most computer users know. You won't
308 need to master the command line interface in order to start using Inform,
309 but this section will tell you what these particular command lines are
310 doing. There are four parts to the first line:
312 1. ``Inform`` refers to the compiler program, and ``..\..\Lib\Base`` is the
313 name of the folder which contains it (addressed relative to *this*
314 folder, the one which holds the source file). Double-dots stand for "go
315 to the parent folder".
317 2. ``MyGame1`` is the name of the Inform source file; you don't need to
318 mention its extension of ``.inf`` if you don't want to.
320 3. ``+include_path=.\,..\..\Lib\Base,..\..\Lib\Contrib`` tells the compiler
321 where to look for files like ``Parser`` and ``VerbLib`` which you've
322 Included. Three locations are suggested: this folder, which holds the
323 source file (``.\``); the folder holding the standard library files
324 (``..\..\Lib\Base``); the folder holding useful bits and pieces
325 contributed by the Inform community (``..\..\Lib\Contrib``). The three
326 locations are searched in that order.
330 On the command line, you sometimes also see a compiler :term:`switch`
331 such as :option:`-S`, used for controlling detailed aspects of how
332 the compiler operates. Rather than do that here, we find it more
333 convenient to place any necessary switches at the very top of the
334 source file, as we'll explain in the next chapter.
336 4. ``| more`` causes the compiler to pause if it finds more mistakes than
337 it can tell you about on a single screen, rather than have them scroll
338 off the top of the MS-DOS window. Press the space bar to continue the
341 .. Generated by autoindex
343 pair: Windows; operating system
345 The second line -- ``pause "at end of compilation"`` -- just prevents the
346 window from closing before you can read its contents, as it otherwise would
347 on Windows NT, 2000 and XP.
349 .. Generated by autoindex
353 You'll need to have a new batch file like this to match each new source
354 file which you create. The only item which will differ in the new file is
355 the name of the Inform source file -- ``MyGame1`` in this example. You
356 must change this to match the name of the new source file; everything else
357 can stay the same in each ``.bat`` file that you create.
359 .. rubric:: Getting a better editor
361 .. Generated by autoindex
363 pair: NotePad; text editor
364 pair: TextPad; text editor
366 Although NotePad is adequate when you're getting started, you'll find life
367 much easier if you obtain a more powerful editor program. We recommend
368 TextPad, available as shareware from http://www.textpad.com/; in addition,
369 there are some detailed instructions at
370 http://www.onyxring.com/informguide.aspx?article=14 on how to improve the
371 way that TextPad works with Inform. The biggest single improvement, the
372 one that will make game development dramatically simpler, is being able to
373 compile your source file *from within* the editor. No need to save the
374 file, switch to another window and double-click the batch file (and indeed,
375 no further need for the batch file itself): just press a key while editing
376 the file -- and it compiles there and then. You can also run the
377 interpreter with similar ease. The convenience of doing this far outweighs
378 the small amount of time needed to obtain and configure TextPad.
381 single: Apple Macintosh
385 Inform on an Apple Macintosh (running OS X)
386 ===========================================
388 .. Generated by autoindex
390 pair: Mac OS X; operating system
392 Whereas our instructions for using Inform on a PC apply to just about all
393 versions of Windows, on the Macintosh we need to be more precise. Our
394 guidance here is specifically for Mac OS X, rather than for its predecessor
395 OS 9, and it may be helpful if we first mention a few relevant differences.
397 Mac OS X is a robust system constructed around -- or on top of -- BSD
398 [#bsd]_ UNIX. There are several kinds of applications that will run on
401 * Aqua: specifically designed for the Graphical User Interface of Mac OS X,
402 and taking advantage of its underlying technologies. Broadly, there
403 are two types of Aqua application:
405 * Cocoa: built with programming tools designed for Mac OS X.
407 * Carbon: built with the programming tools designed for Mac OS 9 and
408 earlier versions, but "translated" to take advantage of OS X.
410 * Classic: designed to work on Mac OS 9 and earlier versions. They need to
411 run in the Classic environment of OS X; roughly speaking, Classic is an
412 emulation of the older Mac systems.
414 .. Generated by autoindex
416 pair: Linux; operating system
418 * X11: based on a windowing system designed for the UNIX/Linux world. They
419 need an X-Windows server to run, and their appearance and functionality
420 may seem a lot different to what the Aqua user expects.
422 * UNIX: most UNIX programs (including Linux) will run on your Mac OS X, but
423 they usually have to be accessed (or configured) from the UNIX core of
424 your Mac, through the Terminal utility.
426 These differences may be significant, since some of the tools designed to
427 develop and run IF on a Mac system (for example, ones you'll find in the
428 Archive) have been built by programmers working in different environments
429 with varying technologies. We have tried to select tools that will make
430 your life easy as a beginner, but in time you may want to investigate
431 alternative approaches.
433 .. rubric:: Installing and testing Inform
437 1. Download http://www.firthworks.com/roger/downloads/inform_macosx_env.sit
438 to a temporary location on your Mac.
440 2. Use a tool like StuffIt Expander to unpack the downloaded file (if your
441 system configuration is standard, a mere double-click will make it
442 self-extract at the current location, if it hasn't already expanded all
443 by itself). You'll now have a new ``Inform`` folder. Move this folder
444 (and its contents) to a suitable location in your Mac.
448 It is a good idea for now to place it in your home directory;
449 otherwise, a few pre-configured items may not work as explained.
450 Once you learn the basics of the configuration, you may move the
451 Inform folder to a different location and hack all the defaults like
452 the professionals do.
454 You should now have this set of folders:
456 .. image:: /images/inform_mac_env.*
459 In order to make the download small and fast, these folders include just
460 enough to get you started as an Inform designer -- the compiler and
461 interpreter programs, the library files, the ``Ruins.inf`` example from
462 the |DM4|, and a template for your own first game, which you may copy
463 and rename each time you begin a new Inform project. A few other
464 folders are included as placeholders where you could later download
465 additional components, if you wanted them. As soon as possible, you
466 should download the |DM4| into the ``Inform/Doc`` folder -- it's an
467 essential document to have, and has been omitted from this download only
468 because of its 3MB size.
470 3. To verify that the downloaded files work properly, use the Finder to
471 display the contents of the ``Inform/Games/MyGame1`` folder: you will see
472 the files ``MyGame1.command`` and ``MyGame1.inf``:
474 .. image:: /images/mac_filelist1.*
477 ``MyGame1.inf`` is a tiny skeleton game in Inform source format. By
478 convention, all Inform source files have an extension of ``.inf``.
479 However, Mac OS X may show its Kind as "FUJI BAS IMG document", and try
480 to open it with GraphicConverter. If you're not a regular user of FUJI
481 BAS IMG documents, you'll probably want to change this. Either:
483 * right-click on the file (or Ctrl-click)
485 * select ``Open with`` and choose ``Other...``
487 .. Generated by autoindex
489 pair: TextEdit; text editor
491 * in the ``Open with`` dialog, go to the ``Applications`` folder and
494 * click to select "``Always open with``"
500 * right-click on the file (or Ctrl-click)
502 * press Option, select ``Always open with`` and choose ``Other...``
504 * in the ``Open with`` dialog, go to the ``Applications`` folder and
509 Now, if you double-click the file, it should open in TextEdit so that
510 you can see how it's written, though it probably won't mean much -- yet.
514 The above process may affect only this specific file. To change
515 the program that opens by default *all* ``.inf`` files, try this:
517 * right-click on the file (or Ctrl-click)
519 * select ``Get Info``
521 * in the ``Open with`` tab, select TextEdit as the application
523 * click the ``Change All...`` button, and confirm the change when asked.
525 4. ``MyGame1.command`` is a Terminal Shell Script (a UNIX executable
526 command-line file, a kind of text-only computer program from the days
527 before point-and-click interfaces) which runs the Inform compiler.
528 Double-click it; a UNIX window opens as the game compiles, and you'll
529 see something like this (the working path will reflect your folder
532 Last login: Sat Jul 3 03:07:51 on ttyp1
534 /Users/Dave/Inform/Games/MyGame1/MyGame1.command; [Hal:~] Dave%
535 /Users/Dave/Inform/Games/MyGame1/MyGame1.command; exit
536 Inform 6.30 (27th Feb 2004)
542 Verify this output. It's what's in the PDF, but the command prompt
543 looks like it's in the wrong place.
545 5. A story file ``MyGame1.z5`` has appeared in the folder; this is the
546 compiled game, which you can play using an interpreter:
548 .. image:: /images/mac_filelist2.*
551 The extension of ``.z5`` signifies that the story file contains a
552 Z-machine game in Version 5 (today's standard) format.
554 6. Use the Finder to display the contents of the ``Inform/Bin/Zoom``
555 folder, and double-click ``Zoom``; the interpreter presents an ``Open``
558 7. Browse to display the ``Inform/Games/MyGame1`` folder, and select
559 ``MyGame1.z5``. Click ``Open``. The game starts running in the Zoom
562 8. When you tire of "playing" the game -- which won't take long -- you can
563 type the QUIT command, you can select ``Zoom > Quit Zoom``, or you can
564 simply close the Zoom window.
566 .. rubric:: Setting file associations
568 .. Generated by autoindex
572 The business of first starting the interpreter, and then locating the story
573 file that you want to play, is clumsy and inconvenient. Fortunately, when
574 the system first "sees" the Zoom interpreter (which is a nice Aqua
575 application) it automatically creates an association with story files whose
576 extension is ``.z5`` (and with other Infocom formats). From now on, you'll
577 be able to play a game simply by double-clicking its story file.
579 The files in the folder should now look like this:
581 .. image:: /images/mac_filelist3.*
584 .. rubric:: Compiling using a command-line file
586 If you have followed these instructions to configure your system, every
587 time that you need to compile your source code you just have to
588 double-click on the file ``MyGame1.command``. However, this file is good
589 only for this folder and for ``MyGame1.inf``.
591 If you want to start coding another game, you may copy the folder
592 ``MyGame1`` with all its contents and rename it as you please (for example,
593 ``MyGame2`` or something more appropriate). Inside the folder, you'll also
594 want to rename the relevant files:
596 ``MyGame1.inf`` might become ``MyGame2.inf``, or ``MobyDick.inf``,
599 ``MyGame1.command`` would change to match: ``MyGame2.command``, or
600 ``MobyDick.command``.
602 You can view -- and of course change -- the contents of
603 ``MyGame2.command``, the command file which you double-click to run the
604 compiler, using any text editor. You'll see two lines, something like this
605 (the second chunk is all on one long line, with a space between the
606 ``MyGame1`` and the ``+include_path``)::
608 cd ~/Inform/Games/MyGame1/
609 ../../Lib/Base/inform630_macosx MyGame1
610 +include_path=./,../../Lib/Base,../../Lib/Contrib
612 These long strings of text are command lines -- a powerful interface method
613 predating the icons and menus that most computer users know. You won't
614 need to master the command line interface in order to start using Inform,
615 but this section will introduce you to a few basic concepts to get your
616 bearings. The first line changes the working directory to
617 ``~/Inform/Games/MyGame1/``. The command ``cd`` (also known as ``chdir``,
618 short for "Change Directory to") lets you travel to the desired folder,
619 specified by the path, in this case: ``~/Inform/Games/MyGame1/``. The
620 ``~`` symbol stands for your home directory. That is, if your user name
621 were Dave, the above path is equal to::
623 /Users/Dave/Inform/Games/MyGame1/
625 You want to change that line so that it reads: ``cd
626 ~/Inform/Games/MyGame2/``
628 There are three parts to the second line:
630 1. ``inform630_macosx`` refers to the compiler program, and
631 ``../../Lib/Base`` is the name of the folder which contains it
632 (addressed relative to *this* folder, the one which holds the source
633 file). Double-dots stand for "go to the parent folder".
635 2. ``MyGame1`` is the name of the Inform source file; you don't need to
636 mention its extension of ``.inf`` if you don't want to. You'll want to
637 change this to match the name of your new file: ``MyGame2``.
639 3. ``+include_path=./,../../Lib/Base,../../Lib/Contrib`` tells the compiler
640 where to look for files like ``Parser`` and ``VerbLib`` which you've
641 Included in the source file (this may sound confusing now, but it will
642 make a lot of sense after you've delved a bit deeper into this Guide).
643 Three locations are suggested, separated by commas: this folder, which
644 holds the source file (``./``); the folder holding the standard library
645 files (``../../Lib/Base``); the folder holding useful bits and pieces
646 contributed by the Inform community (``../../Lib/Contrib``). The three
647 locations are searched in that order.
651 On the command line, you sometimes also see a compiler :term:`switch`
652 such as :option:`-S`, used for controlling detailed aspects of how
653 the compiler operates. Rather than do that here, we find it more
654 convenient to place any necessary switches at the very top of the
655 source file, as we'll explain in the next chapter.
657 Once you've finished editing those lines, ``Save`` the file (not
658 ``SaveAs``), overwriting the original, and make sure that your text editor
659 doesn't append an extension like ``.txt`` (TextEdit, the default editor
660 that comes with OS X, is polite enough to ask you about this).
662 You'll need to have a new command file like this to match each new source
663 file which you create. The only item which will differ in the new file is
664 the name of the Inform source file -- ``MyGameN``. You must change this to
665 match the name of the new source file; everything else can stay the same in
666 each ``.command`` file that you create.
668 .. rubric:: Making your own command-line file
670 There are two peculiarities by which your system understands that
671 ``MyGame1.command`` is a Terminal Shell Script. One is the extension
672 ``.command``, and the other is an attribute of the file which marks it as
673 "executable" (the "executable bits"). If it doesn't meet both conditions,
674 ``MyGame1.command`` won't run as it should. You have to be careful when
675 editing this file: if you were, for instance, to open it in a text editor
676 and save it to a different location with a different name, the executable
677 bits might get lost, and when you double-click it, you would see:
679 .. image:: /images/mac_exec_error.*
682 To make a command file from scratch (also, to fix this problem) you can
685 1. Open any text editor and write (using your own path)::
687 cd ~/Inform/Games/MyGameN/
688 ../../Lib/Base/inform630_macosx MyGameN
689 +include_path=./,../../Lib/Base,../../Lib/Contrib
691 where ``MyGameN`` stands for the name you have chosen for your Inform
694 2. Save the file in the folder ``MyGameN`` and call it ``MyGameN.command``.
695 Make sure that the text editor doesn't append a ``.txt`` extension; if
696 it does, rename the file manually.
698 3. Go to ``Applications > Utilities`` and double-click on ``Terminal``.
699 This opens the utility which provides you with a set of windows to
700 access the UNIX command line. Supposing the computer is named Hal, and
701 the user Dave, you should see something like this::
703 Last login: Wed Jun 30 18:05:55 on ttyp1
707 4. Every time that you open a Terminal window, you're at your home
708 directory (as noted by the tilde after the computer's name). You can
709 travel to your working folder by typing::
711 cd Inform/Games/MyGameN
713 You'll see how the path changes::
715 [Hal:~/Inform/Games/MyGameN] Dave%
717 Now you can make the command file executable with::
719 chmod 777 MyGameN.command
721 5. Alternatively, you can omit the cd command if you give the full path to
724 chmod 777 ~/Inform/Games/MyGameN/MyGameN.command
726 This sets the executable bits for the file ``MyGameN.command``.
728 6. Close the Terminal window.
730 Now, every time you need to compile your game, you can just double-click on
731 ``MyGameN.command`` from the Finder.
733 .. rubric:: Getting a better editor
735 Although TextEdit is adequate when you're getting started, you'll find life
736 much easier if you obtain a more powerful editor program. We'd really like
737 to recommend one -- there's an exciting list of possibilities at
738 http://osx.hyperjeff.net/Apps/apps.php?sub=5 -- but at the time of writing
739 none of them seems outstandingly suited to IF authorship. If you find one
740 that works really well, please let us know.
742 .. rubric:: More about the editor
744 .. Generated by autoindex
746 single: syntax colouring
748 As well as the ones that we recommend, other good text editors are listed
749 at http://www.firthworks.com/roger/editors/. One feature that's well worth
750 looking out for is "hotkey compilation" -- being able to run the compiler
751 from *within* the editor. Another is "syntax colouring", where the editor
752 understands enough of Inform's syntax rules to colour-code your source
753 file; for example: red for brackets, braces and parentheses ``[ ]`` ``{ }``
754 and ``( )``, blue for reserved words like ``Object`` and ``print``, green
755 for items in quotes like '...' and "...", and so on. Syntax colouring is
756 of great assistance in getting your source file correct and thus avoiding
757 silly compilation errors.
759 .. rubric:: More about the compiler
761 The Inform compiler is a powerful but undramatic software tool; it does an
762 awful lot of work, but it does it all at once, without stopping to ask you
763 any questions. Its input is a readable text source file; the output is a
764 story file, also sometimes known as a :term:`Z-code file` (because it
765 contains the game translated into code for the Z-machine, which we describe
766 in the next section).
768 If you're lucky, the compiler will translate your source file into Z-code;
769 perhaps surprisingly, it doesn't display any form of "success" message when
770 it succeeds. Often, however, it fails, because of mistakes which you've
771 made when writing the game. Inform defines a set of rules -- a capital
772 letter here, a comma there, these words only in a certain order, those
773 words spelled just so -- about which the compiler is extremely fussy. If
774 you accidentally break the rules, the compiler complains: it refuses to
775 write a Z-code file. *Do not worry about this*: the rules are easy to
776 learn, but just as easy to break, and all Inform designers inadvertently do
777 so on a regular basis. There's some additional information about dealing
778 with these mistakes, and about controlling how the compiler behaves, in
781 .. rubric:: More about the interpreter
783 .. Generated by autoindex
787 One of the big advantages of the way Inform works is that a compiled game
788 -- the Z-code story file -- is portable between different computers.
789 That's not just from one PC to another: exactly the same story file will
790 run on a PC, a Mac, an Amiga, UNIX workstations, IBM mainframes, PalmOS
791 hand-helds, and on dozens of other past, present and future computers. The
792 magic that makes this happen is the interpreter program, a software tool
793 which pretends to be a simple computer called a :term:`Z-machine`. The
794 Z-machine is an imaginary (or "virtual") computer, but its design has been
795 very carefully specified, so that an expert programmer can quite easily
796 build one. And that's exactly what has happened: a Macintosh guru has
797 built an Inform interpreter which runs on Apple Macs, a UNIX wizard has
798 built one for UNIX workstations, and so on. Sometimes, you even get a
799 choice; for popular machines like the PC and the Mac there are several
800 interpreters available. And the wonderful thing is: each of those
801 interpreters, on each of those computers, is able to play every Inform game
802 that's ever been written *and*, as a surprise bonus, all of the classic
803 1980s Infocom games like "Zork" and "The Hitchhiker's Guide to the Galaxy"
806 (Actually, that last sentence is a slight exaggeration; a few games are
807 very large, or have pictures included within them, and not all interpreters
808 can handle this. However, with that small pinch of salt, it's pretty
811 That's enough waffling: let's get started! It's time to begin designing
814 .. rubric:: Footnotes
817 "BSD" stands for Berkeley Software Distribution, the name of the UNIX
818 derivative distributed in the 1970s from the University of California,
819 Berkeley, and used collectively for the modern descendants of those