CP/M/CPM_CDROM.iso/cpm/misc/game40.lbr/SCENE.DZC/SCENE.DOC

Text File | 1994-08-30 | 107.3 KB | 2,676 lines

 Overview:

 The "GAME4.0" game creation system is composed of two programs:
 SCENE.COM and PLAY.COM.  SCENE is used to compile an ASCII
 source file called name.SRC which you create using any word
 processor program.  PLAY is used to play the generated name.SCN
 data file.  For details on running PLAY.COM, see PLAY.DOC in
 this library.


                        TABLE OF CONTENTS
                        =================


 1. INTRODUCTION

 2. WRITING THE SCENARIO FILE
      2.1 Basic Grammar
      2.2 Optional Frills
           Starting Text
           Ending Text
           Bad Ending Text
           Assistant
           Guards
           Score
      2.3 Location Records
      2.4 Item Records
      2.5 Movement Tests
      2.6 Phrases
      2.7 Effect Records
           Varieties of "IF" tests
                Variable tests
                Location tests
                Assistant/Guard tests
                Random chance tests
           Varieties of "THEN" actions
                Change variables
                Change items
                Change locations
                Move player
                Change assistant/guard status
                Change score
                Print effect strings
                Perform default action
                End the game
      2.8 Short Strings
      2.9 Effect Strings

 3. TIPS AND TECHNIQUES
      3.1 Make good use of comments
      3.2 Arrange your scenario file logically
           Location Records
           Item Records
           Movement Checks
           Phrases
           Effect Records
           Short Strings
           Effect Strings
      3.3 Draw a map
      3.4 Tackle your game in small chunks
      3.5 Use foresight in assigning location numbers
      3.6 Use foresight in assigning object numbers
      3.7 Keep "Cheat sheets"
           SCENE "grammar" summary
           List of item numbers
           Variables list
           "Point" list
           "Word" list
           "Puzzle" list
           "Time line"
           "Special" lists
      3.8 Include "temporary short-cuts" during the writing
      3.9 Add "descriptions" to non-portables
      3.10 Intercept built-in commands
      3.11 Elaborate on "Search"
      3.12 Change the portability of an item
      3.13 Create a move counter/countdown timer
      3.14 Use the assistant/guard
      3.15 Play fair

 4. COMPILING YOUR SCENARIO
      4.1 Running SCENE
      4.2 Splitting your source file
      4.3 SCENE feedback

 5. SUMMARY


                     =======================
                     ||  1. INTRODUCTION  ||
                     =======================


 It is a hard thing for a CPMer to be a text adventure game
 addict.  Once you have mastered the original Colossal Cave
 Adventure, and Zork and its sister offerings from Infocom, must
 you hang up your sword and lantern?

 Never!  The number of possible scenarios is as infinite as the
 universe -- and if software companies will not supply us, why
 then, we will simply grow our own.  "Do It Yourself" is still an
 honored tradition among CPM users.

 You aren't a programmer?  That isn't a problem.  David
 Goodenough has greatly simplified your task with this game-
 creation system that handles all the tedious inner workings.
 You don't know how to build a parser?  Or even what one is?  You
 wouldn't know a movement chart if it was labeled in 20 point
 type?  No matter.  That has already been taken care of.  With
 this system you are a playwright, not a programmer.

 Your game will be built out of just five types of units, which
 can be put together in any order and in virtually any quantities
 you want.

 First, there are "locations", which can be anything you can
 describe, from the control room of a methane processing plant on
 Jupiter to a broom closet in a contemporary home.  Second are
 "items", which are any objects you want your players to interact
 with, such as magic carpets or the traditional gem-encrusted
 idols.  Think of these as the setting and props for your play.

 The other three units, "effect records", "phrases", and
 "movement tests" are closely related and combine to form your
 plot.  With the "effect records" you specify what can happen
 during the game.  The other two are the triggers that cause
 these things to happen.  For example, you could write a move
 test that says, if the player rides his elephant across the ice
 bridge then collapse the bridge and kill the elephant.  Or you
 could have the phrase "rub lantern" cause a malevolent genie to
 appear.  Anything.  In the world of your game, you are god.

 In addition, there are a handful of optional frills you can add
 to "accessorize" your game.  For example, you can add an
 assistant and a foe to expand the cast of your play.

 Since the process is so free-form, you needn't have your entire
 game worked out in advance.  You can tackle it in pieces,
 working on just one area or one puzzle for your player at a
 time.  Then move on to the next, letting your game grow to
 whatever stature you choose, be it a one-puzzle bonzai or a
 sequoia to rival Zork.

 Suppose you have the idea that "Twin Peaks" should be
 immortalized in a game.  You might start by deciding that the
 player will be Special Agent Cooper.  Write a few locations, to
 provide a main street for the town.  Create an item, a mini-
 cassette so he can save his thoughts for Diane.  Then give your
 scenario a trial run by walking Cooper through the town. Not
 bad, but shouldn't there be a Double-R diner for him to visit,
 complete with the best damn cherry pie and a cup of joe?  And a
 jukebox to play?  And you've got to add The Great Northern
 Hotel, complete with roving bands of drunken Norwegian
 investors!  And after those have been added, well, how about the
 saw mill?  And the Sheriff's Office?  (Don't forget the
 doughnuts.)  And who will you choose for your assistant, the
 stalwart Sheriff Truman or hapless Deputy Andy?  The villain has
 got to be Bob, naturally!  Of course, Cooper needs a crime to
 solve, so don't forget to supply a body and plant clues for him
 to discover....

 Most important, when your game is finished, don't forget to
 distribute it so your fellow gamesters can enjoy it.  And don't
 be surprised if you discover that the challenge of writing your
 own game is just as much fun as solving someone else's.


               ====================================
               ||  2. WRITING THE SCENARIO FILE  ||
               ====================================


                        2.1 BASIC GRAMMAR
                        =================

 SCENE expects that you will follow certain rules of "grammar":

 It needs pure ASCII input so be sure to use that mode (ASCII or
 non-document) of your word processor.

 Each module, and each part of a module, must start on a new
 line.

 The first letter or character on a line determines how SCENE
 interprets that line.

 The semicolon (";" ) is used to designate "comments" -- when
 Scene encounters one it skips the rest of that line or, if it
 was the first character on the line, it skips the entire line.
 You will find many uses for comments during the writing of your
 source file: you can embed "markers" so you can navigate more
 quickly through the file; write "reminders" to yourself of
 additions/changes to make in future; add "labels" to sections to
 remind yourself of why you are doing something; etc.  Since
 these comments are not included in the ".SCN" data file they
 don't make your game any larger, so use them freely.

 NOTE: If you are putting a comment on the same line as part of
 the game, ALWAYS put at least one space BEFORE the semicolon.
 If you don't, SCENE might not recognize it as comment marker and
 then try to compile your remarks.

 Case matters to SCENE.  All letters that are supposed to be
 interpreted by it should be lower case. This means that upper
 case letters, or mixed upper and lower, should only be used in
 text that is to be stored and displayed to the player.
 Basically, that means WITHIN strings:  text set off by
 quotations marks, braces or brackets.  This includes long and
 short descriptions of locations, long and short descriptions of
 items, Short Strings, Effect Strings, Starting, End and Bad End
 Strings, and assistant and guard strings.  (All of these will be
 described in detail later.)  Upper case can also safely be used
 within comments, since those are not interpreted either.

 Sometimes you might want the game to pause when it is printing
 out text for the player.  For example, the text fills more than
 one screen and the player will need time to read it.  Or, you
 have set up a joke, and want a pause before the punch line.  To
 do this, there is a pause command that can be used A) in the
 long descriptions of locations, B) in the text of the Starting,
 Winning, and Bad Ending strings, and C) in "Effect" string
 texts.  (These will be explained later.)

 A pause is signaled by putting a "~" in the first column of a
 line within a string.  When the game is played, the text up to
 that point will be displayed followed by a line prompting the
 player to hit any key when he is ready to go on.  The rest of
 the text, or up to the next "~", will then be displayed.  You
 may have multiple pauses in a single string.  (It isn't
 required, but it will look nicer if you leave a blank line
 before the line starting with the "~".)

 Other "grammar" rules are specific to each module, and will be
 covered separately.


                       2.2 OPTIONAL FRILLS
                       ===================

 These are the optional embellishments you can add to your game.

 Starting text
 =============
 This takes the format of an "s[" starting in the first column of
 a line, followed by any amount of text starting on the next
 line, ending with a "]".  This text will be displayed when the
 game starts, and can be used to "set the scene" or give the
 player a little background information.  The "~" command works
 here.

 During the play of the game this introductory text will be
 followed by the description of the location the player is
 starting at.  Example:

 s[
 You are fleeing for your life as a pack of wolves draws ever
 nearer . . ..

 ~You awake with a start.  It was just a dream.  It was only
 a dream.

 ~But then why can you still hear the wolves howling?]

 Ending text
 ===========
 This take the form of an "e[" beginning in the first column of a
 line, followed by any amount of text starting on the next line,
 ending with a "]".  (The pause command "~" can be used here,
 too.)  This text will be displayed when the player reaches the
 "good end" of the game, that is, has won.  Since the player has
 probably worked hard to get to this point, it might be nice to
 make a big deal out of it -- congratulate him on the win, tell
 him he has become the master of the universe, whatever.  After
 this text has been printed the game terminates and returns to
 the CP/M prompt.  Example:

 e[
 Whoopie!  You win!  You get to marry the princess and live
 happily ever after!  (etc.)]

 Bad ending text
 ===============
 This takes the format of a "b[" beginning in the first column of
 a line, followed by any amount of text starting on the next
 line, ending with an "]".  (The pause command "~" can be used
 here, too.) This text is displayed when the player comes to a
 "bad end", that is, had lost.  You should inform the player that
 he has lost (you have died, been thrown in jail, turned into a
 lump of stone, whatever) and perhaps offer sympathy (mock or
 sincere) and maybe a challenge or encouragement.  After the text
 is printed the game will offer him a choice to start over or
 quit.  Example:

 b[
 You have died.  Try again -- maybe you'll manage to defeat the
 evil wizard next time!]

 Assistant
 =========
 You can give the player an "assistant" who will follow him
 around.  (If you want the assistant to do anything else, you
 will have to write an Effect Record about it.  See Tips &
 Techniques.) This is done by putting an "a" in the first column
 of a line, followed by a description of the assistant up to 39
 characters long.  While the assistant is activated this
 description will be printed out in the format "The <assistant
 description> is with you." after each move.  The game starts up
 with the assistant inactive.  Examples:

 a loyal Mr. Spock
 a robot
 a village constable

 Guards
 ======
 You can also add some "guards" to the game.  The format for this
 is a "g" in the first space of a line, followed by how many
 guards (total) you want in the game, followed by the probability
 of creating one on any given move, followed by the number of the
 Effect Record (this is explained later) that will be performed
 every turn that one is present, followed by up to 59 characters
 of text that will be printed when the guard is present.  Some
 examples:

 g 8 10 12 There is a Klingon guard here!
 g 4 33 18 There is an  evil troll near you!
 g 12 20 5 An enchanted mist surrounds you.

 The game starts with the guards inactive.  You must write an
 Effect Record that will activate the guards in reaction to
 something the player does, either moving to a particular area
 (for example, the Sultan's harem) or entering a particular
 command (such as, open safe.)  MOVEMENT TESTS and PHRASES will
 cover this in detail.

 Once the guard mechanism is activated, a guard will be created
 in the player's location based on the probability you specified
 with the second number.  If you specified more than one guard,
 the following ones will not be generated until the current one
 has been overcome by the player.

 Each move the guard is active the text string you entered will
 be printed to announce his presence.  Until the guard is killed
 or de-activated, and except for the first move after a guard's
 creation, the game will also perform whatever actions you wrote
 in the guard's Effect Record.  For example, the Klingon might
 shoot at the player -- perhaps even killing him!

 NOTE: The "guard" need not be evil, or opposed to the player, or
 even a person.  Since you determine what the "guard" does in an
 Effect Record, it could be a leprechaun that shows up and gives
 the player some treasure.  Or the "guard" could be nothing more
 than scene dressing, perhaps some birds that fly by on occasion.

 Score
 =====
 This is simply a line that starts with an "x" in the first
 column, followed by a number which is the maximum points a
 player can attain in the game.  Example:

 x 500

 If the player types "score" he will be told, for example, that
 he has 100 points out of 500 possible.  If you don't enter a
 maximum, the player is simply told how many points he has
 accumulated, but has no way to guess how close to finishing the
 game he may be.

 NOTE: The maximum points is not a limit used by the game.  You
 could declare that the maximum number of points is 200 and then
 arrange the game so the player could actually obtain 800 points.
 This would confuse the player, but not the game:  it won't
 terminate and declare him the winner upon obtaining 200 points,
 or anything like that.


                       2.3 LOCATION RECORDS
                       ====================

 A "location" is any place that the player can be during the
 game.  These can also be called "rooms", but a location could be
 just part of what we normally think of as a room (for example,
 the east end of a large ballroom) or not a room at all (perhaps
 a meadow or a perch halfway up a tree.)

 A location module starts with a label to show that it IS a
 location and WHICH location.  This label consists of the letter
 "l" in the first column of a line, followed by one space
 followed by a number.  If you want, you can add a comment to
 yourself after that.  Sample location labels:

 l 1
 l 57
 l 112 ; the cockpit of the Millenium Falcon

 Locations must have a number between 1 and 199.  If you
 accidentally give two locations the same number the details from
 the one later in the file will be written over the details of
 the earlier one, in effect erasing it.

 Some locations have special significance:
 Location 1 is where the player will start.
 Locations 2 through 10 are 'hide rooms', in which some items
     will not be described even if they are present.  (See
     "ITEMS" for more on this.)
 Locations 5 through 15 are 'safe rooms', which guards cannot
     enter.  (See "Change Assistant/Guard Status" for more on
     this.)
 Only locations 1 to 119 can be used in the Effects Records.
     (This is covered under "EFFECT RECORDS".)

 Next you give the "short description" of the location.  This is
 the text that will be displayed each time the player arrives at
 that location, preceded by the words "You are".  Put a percent
 sign in column one, followed by your description enclosed in
 quotation marks.  Your description can be up to 255 characters
 long, and can extend over multiple lines.  (SCENE will consider
 everything up to the next quotation mark as part of the
 description.)  As an alternative, if a location has the same
 description as another you have already entered, you can just
 put the number of that LOCATION after the percent sign.

 NOTE: that location must come earlier in your file.

 Sample short descriptions:

 %"in the cockpit"
 %"standing at the end of the road.  Before you is a handpainted
 sign:

            BEWARE OF RHINOCEROS"
 %112

 Next, you can optionally enter a longer description.  It should
 begin with either a "[" or a "{" in the first column of a new
 line, can be of any length and number of lines desired, and is
 ended with a matching "]" or "}".  A long description set off by
 square brackets will be displayed the first time a player enters
 a location and in response to "look" commands.  A long
 description set off in braces is ONLY displayed after "look"s.
 (The start and end must both be brackets or both be braces.)  If
 your description is longer than one screen, or you want to add
 pauses for artistic reasons or suspense, the "~" pause command
 can be used as many times as you like.

 Next, you have the option of declaring a location to be "dark"
 by putting a comma (",") in the first column of a new line.  The
 player will not be given the description of a dark location, or
 told of any objects that may be there, unless the lit light
 source is on him or at the same location.  (See OBJECTS for more
 about this.) Also the assistant and guard will not be described
 and the guard effect will not be performed in an un-lit dark
 room.  Each time the player moves without his light source in a
 dark location there is a chance that he will be killed.  (This
 is built-in, and cannot be changed by the scenario.)

 Next, you have the option of making the location a "credit" one
 by starting a line with a "c" followed by a number from 1 to
 100.  The first time the player moves to that location his score
 will be increased by that number of points.  Arriving in a room
 by teleport does not award the credit.  (This is usually used to
 "reward" a player for having successfully overcome some obstacle
 or having solved a puzzle.)

 Next, you must specify how this location is connected to other
 locations.  This is done by entering a letter for the direction,
 followed by a letter indicating what type of connection,
 followed by the number of the location that connection leads to.
 Each connection description must start in the first column of a
 new line.

 SCENE uses six directions (north, east, south, west, up and
 down) which are abbreviated to their first letters (n, e, s, w,
 u and d, respectively.)

 SCENE has three built-in connection descriptions:  doors
 (abbreviated to d), stairs (s) and passages (p).  These will be
 used to generate the suitable notice for the player.  (For
 example, "There is a door to the east.")  If your connection
 doesn't fit those categories, you can use an "x" which will not
 generate a notice for the player though he will be able to go
 that direction.  If you want to notify him that he can move in
 that direction, you must include mention of it in the location's
 short description.  For example:

 %"the center of a large grassy meadow.

 Trails leading north and east have been worn in the grass."

 If no connection is described for a given direction, the player
 will be told "You can't go that way" if he tries that direction.

 There is a second way to close off a direction.  If you put an
 "n" after the direction, followed by a string number, the player
 will still be unable to go that direction but the game will
 instead print out the string you have assigned to the number
 after the "n".  (See "SHORT STRINGS" for more on this.)  This
 can be used when a passage is only temporarily blocked, perhaps
 by a locked door (how to change a blocked passage to an
 unblocked one is covered in "EFFECTS") or whenever you want to
 add some "color" to the game.  For example, suppose your
 location description had included "There is a large mirror on
 the north wall."  You might want the game to respond, "Do you
 think you're in Wonderland??" if the player tries to go north.

 If these were the connections for a location:

 nx44
 en5
 sd42
 wp73
 ds15

 They would mean:
 an undescribed connection leads north to location 44
 no way east, but print string 5 if the player tries it
 a door leads south to location 42
 a passage leads west to location 73
 stairs lead down to location 15
 and, since nothing was listed for up, trying to go that way
 would get the default "you can't go that way" message.

 Finally, the location record is terminated by a period in the
 first column on a line by itself.

 NOTE:  A location record must start with a "l 12"-type label and
 must end with a line with just a period.  All the other elements
 can be included in any order or omitted as you please.  However
 if you always include the elements in a set order you are much
 less likely to omit any accidentally.  The same applies to the
 connection descriptions:  they can be in any order, even mixed
 between other elements of the location record, but clustering
 them and always using the same order (perhaps neswud) will
 lessen your chances of accidentally forgetting to include one.

 Here is an example of a typical location record:

 l 76           ; Location 76, the passage outside your cabin
 %"in the passage outside your cabin"
 [The ground here is rather messy, it shows signs of the heavy
 traffic that is usually passing back and forth]
 ,
 c50
 nx44
 en5
 sd42
 wp73
 ds15
 .


                         2.4 ITEM RECORDS
                         ================

 The second type of modules are "Item Records."  An item is any
 object you want your players to interact with, such as magic
 carpets or the traditional gem-encrusted idols.  In format, item
 records are much like locations records.

 An item record starts a label, an "i" in the first column of a
 line, followed by a space and then a number from 1 to 59.
 Again, some numbers have different uses.

 Item 1 is special: it is considered the "lamp" item.  It does
 not have to be describe as a "lamp".  It could be any obvious
 light source (lamp, lantern, flashlight, torch, etc.) or any
 object that will be used as a light source within the game (for
 example, a crystal ball that provides magic light.)  If the
 player has item 1 in his inventory, then the command "on" will
 activate it, and "off" will turn it off.  The player will be
 able to see in "dark" locations only if the lamp is "on" and
 either in the player's inventory or at the same location as the
 player.  The game begins with the "lamp" off.

 Only items 1 through 44 can be seen and interacted with by the
 player.  Items 45 to 59 have to be "swapped" into a lower number
 before they can be used.  (This will be explained in "EFFECT
 RECORDS.")

 Next comes the item's description.  This starts with a "%" in
 the first column, followed by a description of up to 158
 characters enclosed in quotation marks.  Examples:

 %"a pair of ruby slippers"
 %"a torn scrap of paper, bearing the numbers:

           23 - 12 - 13.5 - 110"

 Instead of including the actual description, you could put the
 number of the Short String that holds the description.  (See
 "SHORT STRINGS for more about this.)  This makes it less
 immediately obvious what an item is when reading the source
 file, but will make no difference when playing the game.  The
 only advantage of putting an object's description into a Short
 String is that several items could then easily be given
 identical descriptions by specifying that each use the same
 Short String for its description.  Example:

 %31

 Next, you can give an optional description that will be printed
 when the player "examine"s the item.  Again, this can be up to
 158 characters and should be enclosed in quotation marks.  For
 example:

 x"The slippers seem to be size 7."

 NOTE: "Portable" items can only be examined when the player is
 carrying them, but "non-portables"  can be examined if the
 player is in the same location as the item.

 Next, you should give a one word name that the player can refer
 to the item by.  If you like, you can also provide a synonym,
 also a single word.  These take the form of a single quote
 followed by the word, each starting its own line.  For example:

 'slippers
 'shoes

 NOTE:  since SCENE and PLAY only consider the first four letters
 of each word, you must be sure that each item's name, when
 truncated to four letters, is unique.  For example, confusion
 would result if you tried to have both "chalk" and "chalice" in
 the same game.  (Spelling out the words in full in the scenario
 file can make it easier to work on the file and has no effect on
 the game.)

 Next, you can add a line with just an "h".  This makes the item
 "hideable", which means that it will not be included in the "You
 see" list when it is in one of the hide locations (locations 2 -
 10).  The player will have to use the "search" command before
 its presence will be revealed.

 Next, a line with just an "a" can be added.  This means this
 item would not be included if the player types "take all".  (The
 reason for this option is to force the player to take it by name
 -- probably because you want the act of taking it to trigger
 some effect.  This is covered under "EFFECT RECORDS.")

 Next, a line consisting of a "c" followed by a number from 1 to
 100 would mean the player would be credited with that number of
 points the first time the item is picked up.

 Next, the starting location of the item must be given.  This can
 be any of the location numbers (1 - 199) or one of three special
 cases:

 -1 means the item is being carried, that is, is in the player's
    inventory.
 -2 means the item is "out of the game", that is, in no place the
    player can reach.
 -3 is a synonym for the location the player is at when the
    command is processed.

 Next, a line with a "w" followed by a number from 1 to 100 gives
 the object that "weight".  This simply limits what the player
 can pick up, since he has a maximum carrying capacity of 100.
 If you don't want the player to be able to take an item, give it
 a weight of -1.  If you don't specify a weight it will default
 to 0, meaning the player will always be able to take it no
 matter what else he is carrying.

 Finally, the record ends with a period in the first column of
 its own line.

 Here is a typical item record:

 i 15
 %"A diamond ring"
 x"This is a gold ring set with a one-carat diamond."
 'diamond
 'ring
 h
 a
 c 5
 l 2
 w 15
 .

 NOTE:  As with location records, the internal elements of an
 item record can be given in any order or omitted.  However,
 omitting some will have strange effects.  For example, if you
 don't give the object a "name", the player not will be able to
 "take" or "drop" it.  If you don't specify a location the item
 will not appear in the game.  Always putting the elements in the
 same order will help avoid accidental oversights.


                        2.5 MOVEMENT TESTS
                        ==================

 This module plus the next, "PHRASES", are used as triggers:
 when a player makes a particular movement, or types in a certain
 phrase, an "effect record" is triggered, causing other things to
 happen.  Together they combine to form the "plot" of your game.

 There may be up to 74 movement tests in your game.

 A movement test is just one line long.  It begins with an "m" in
 the first column, followed by the number of the location the
 player is moving FROM followed by the number of the location he
 is moving TO, followed by the number of the effect record that
 should happen when he makes that movement.  For example, the
 following line would trigger Effect Record #30 when the player
 moved from location 10 to location 20:

 m 10 20 30

 For your convenience, you could add a reminder to yourself after
 a comment marker:

 m 52 16 110  ; boarding pirate ship

 In addition, -1 can be used as a "wild card" location, matching
 any location number.  Therefore "m -1 30 15" would trigger
 effect 15 whenever a player moves to location 30 and "m 10 -1
 16" would trigger effect 16 whenever a player moves from
 location 10.  If both locations are given as -1 (m -1 -1 43),
 that effect will be triggered after each movement.  This can be
 used to build in a "clock" or "countdown timer".  (See "MOVE
 COUNTERS" in the "Tips and Techniques" section.)

 After each move (N S E W U or D) the player makes, the game
 scans all the movement records, and performs the actions
 attached to each test that applies.

 NOTE: The game processes a "WAIT" command by doing a move FROM
 the present location TO the same location, and thus matching
 movement tests can be triggered by "wait"s.


                           2.6 PHRASES
                           ===========

 Phrases are the other way that Effect Records can be triggered.
 In essence you tell the game, "If the player types in this
 command, go do this effect".  These are defined in a single
 line, with a "p" in the first column followed by either a one or
 two word phrase (each word of the phrase must be preceded by a
 single quote mark with no intervening space), followed by the
 number of the Effect Record to be done.  Examples:

 p 'drink 'coffee 54
 p 'scream 27

 Only the first four letters of each word are considered, so you
 must be sure not to use two phrases that cannot be distinguished
 on that basis.  For example, if you put both these phrases in
 your scenario file:

 p 'eat 'strawberry 35
 p 'eat 'straw 24

 they will interfere with each other, and both will trigger the
 same effect.  In this example, Effect 35 would be triggered
 whether the player typed "eat strawberry" or "eat straw" (or
 even "eat strap" or "eat strazzlkdlej".)

 The game does distinguish between "verbs" (the first word) and
 "nouns" (the second), so two commands like this would not be
 confused even though they reduce to the same pair of 4-letter
 words:

 p 'strangle 'pullet 21
 p 'pull 'strap 78

 A phrase such as 'break 'vase will result in destroying the
 OBJECT called "vase" only if you WANT it to and include that
 among the actions of the Effect Record that phrase triggers.

 NOTE:  You can use up to 134 phrases in your game.  You are also
 limited to a total of 134 "words" -- this means, unique four
 letter combinations used as item names and parts of phrases
 combined.  The verb/noun/name distinction doesn't count here:
 even if you use "chain" all three ways in your game (an item
 named 'chain  as well as the phrases "break chain" and "chain
 dog"), "chain" would only count as one "word".


                        2.7 EFFECT RECORDS
                        ==================

 This final module determines what actually happens in the game.
 In them you can cause text to be displayed to the player, change
 the items (make them appear, disappear or alter their appearance
 or other attributes), change the locations (adding or removing
 connections to other locations, altering their descriptions,
 etc.), make the assistant or enemies appear or vanish, give the
 players bonus points, teleport him to a different location,
 bring about the good or bad ending -- or any combination of
 those effects.

 Effect records are basically a set of "if then" statements.  In
 the "if" you have the game check to see if conditions in the
 game are those you care about, and the "then" specifies what
 should happen if they are.  The optional "else" is performed
 when the "if" tests aren't met.

 For example, suppose your game has an elephant (item #4) the
 player can ride and there is an ice bridge connecting a river
 bank (Location #14) with an island (#15).  You, as "god", don't
 think the player should be allowed to ride the elephant over the
 bridge.  Here is how you would prevent it: first, you need a
 movement check (m 14 15 25) so the game will do effect 25 when
 the player crosses the bridge.  Effect 25, then, checks to be
 sure that the player is indeed "breaking" your rule (IF the
 player is riding the elephant) and if he is, it carries out the
 consequences you have decreed (THEN collapse the ice bridge and
 kill the elephant).  If the "IF" conditions are NOT met, the
 "THEN" effects don't happen -- in this example, if the player
 ISN'T riding the elephant, he simply crosses the bridge to the
 island with nothing unusual happening.

 An Effect Record begins with a line with an "f" in the first
 column, a space, and then the number of that effect.  To help
 remind you of why this effect should be happening (a big game
 might have over a hundred Effect Records), you could then add a
 comment.  Samples:

 f 24
 f 12 ; "eat strawberry"
 f 18 ; boarding pirate ship

 The Effect Record ends with a period in the first column of its
 own line.

 In between, you can have any number of "if then" statements,
 possibly ending with an "else".  For example, suppose you had
 statements equivalent to this format:

 if  some conditions
   then  some actions
 if  other conditions
   then  other actions
 else
   then  last actions

 NOTE:  There can only be one "else" in an Effect Record.

 When this effect was triggered, the game would check to see if
 the first set of conditions were met.  If yes, it would perform
 the first set of actions.  If not, it would then check to see if
 the second set of conditions applied.  If yes, the second set of
 action would be done.  If neither set of conditions were met, it
 would do the "else" instead, by doing the "last actions".  There
 can be any number of "if then" statements, checking for dozens
 of possible sets of conditions if you want.

 NOTE: As soon as one set of "if" conditions are met, the game
 does those actions and does NOT consider any of the following
 statements.  This means you should put more specific tests
 earlier in the effect record than more general ones.  Returning
 to our elephant/ice bridge example, suppose the game also
 included a giant helium balloon, and you have decided that if
 the player is holding the balloon it will offset enough of the
 elephant's weight to allow him to ride across the bridge.
 Consider the effect of these "if then" statements:

 if (riding elephant & holding balloon)
    then ( print "the bridge creaks but you cross safely")
 if (riding elephant)
      then (collapse bridge & kill elephant)

 (The above lines are intended to be illustrative only -- the
 words inside the parentheses are not correct GAME syntax.)

 In this order, the game will behave as you plan.  However, if
 you reversed the statements' order, the bridge will always
 collapse even if the player has the balloon, since the more
 general conditions of the first statement are met and carried
 out before the game could test the more specific condition of
 also holding the balloon.

 In each set of conditions, the whole set is considered true only
 if ALL the individual conditions evaluate true.

 SCENE does not allow for "OR" constructions: if there was a
 second item that would also allow the elephant to cross the ice
 bridge (perhaps an anti-gravity belt), you will have to include
 a separate "if then" for that possibility (being sure to place
 it, too, earlier than the general 'riding elephant' one):

 if (riding elephant & holding anti-gravity belt)
    then ( print "the bridge creaks but you cross safely")

 If you want some action to ALWAYS happen when the effect is
 triggered, you can simply use the "else" line:

 f 71
 else
  then (some actions)
 .

 NOTE:  "if" can be abbreviated to an "i", "then" to a "t", and
 "else" to an "e".  The effect records will be a little harder to
 understand immediately but it will reduce the amount of typing
 you need to do.  Also indentation on the "then" lines is
 optional.  Your choice.

 Varieties of "IF" tests
 =======================
 The "if" part of an if/then can be made of any number of any
 combination of the following tests.  The only limit is that the
 entire line must be no more than 198 characters long.

 NOTE: There should be NO spaces between the various components
 of one test, and there should be one space between successive
 tests in an "if" statement.

 Variable tests
 --------------
 There are 26 variables in a game, labeled "a" to "z", each of
 which can have a value from 0 to 100.  (All variables are set at
 zero at the start of a game.)  These are used to keep track of
 the status of things that can be changed by the player's actions
 in the course of the game.  There are many types of things that
 can be changed, some more obvious than others.  Some examples:

 The "status" of something can be changed.  For example, a
 treasure chest could be closed and locked, closed but unlocked,
 or open.  A bottle could be empty or holding wine or holding
 water.  By associating a variable with that item, you can check
 the value of the variable to determine what the current
 condition is.  For example, suppose your game started with a
 bottle of wine.  You could decide that you will use the variable
 "b" to keep track of its state, and thus 0 means full of wine.
 If the player drinks the wine, the effect that allows him to
 drink it will set the value of "b" to 1, meaning empty.  An
 effect that allows the player to fill the bottle with water
 would then set "b" to 2.  Emptying the bottle would change "b"
 back to 1.

 A variable can also be used to determine how many times
 something has been done.  Perhaps the action can only be done a
 limited number of times -- say, he only has 3 matches.  Or
 perhaps he has to perform an action a multiple number of times
 before you want something to result -- for example, he must dig
 7 times before the treasure chest turns up.

 Note that these reasons could be combined: perhaps a canteen can
 hold 5 drinks of water.  Filling the canteen sets that variable
 to 5.  Each time the player drinks the value of the variable
 drops by one.  When the variable reaches 0 the canteen is empty
 and the player will not be able to drink again until he refills
 it.

 A less obvious use of a variable is to determine WHAT a
 particular item currently is.  Since the identity of an item can
 be changed (see CHANGING ITEMS for how this can be done) it
 might be necessary to know which version it currently is.  For
 example, suppose you have a "vase" as item #6 in your game.  It
 may be possible for the player to turn it into "broken pieces of
 glass", perhaps by dropping it.  Now, suppose each version of
 the object has an intended use -- the vase to carry some water,
 the pieces of glass to cut a rope.  If the player types the
 command "cut rope" you have to check not only, does he have item
 #6? but also WHICH VERSION of #6?  This can be done by using
 "v" = 0 to mean it is the vase and "v" = 1 to mean it is the
 pieces of glass.

 The tests that can be done on variables are: Is it equal to some
 number?  Is it NOT equal to some number?  Is it less than some
 number?  Is it greater than some number?  Variable tests take
 the form of a "v", followed by the letter of the particular
 variable you are testing, followed by the appropriate "operator"
 ("=" means "equals", "#" means "does not equal", ">" means "is
 greater than" and "<" means "is less than") followed by the
 numerical value (from 0 to 100) that you are testing against.
 Some examples:

 vx=5
 vb#37
 vv<12
 vr>66

 which test, respectively, if variable x is equal to 5, if
 variable b is not equal to 37, if variable v is less than 12,
 and if variable r is greater than 66.

 Location tests
 --------------
 Sometimes certain effects should only happen if the player or
 some object(s) are either at, or not at, certain locations in
 the game.  For example, a player probably shouldn't be able to
 light a match if he is swimming underwater.  Location tests take
 the form of an "l", followed by the number of the item in
 question, followed by an "operator" ("@" means "is at", "!"
 means "is not at"), followed by the location in question.  Some
 examples:

 l6@52
 l13!114

 test, respectively, that item 6 is at location 52, and that item
 13 is not at location 114.

 There are a few special cases that can be used in location
 tests.

 A "-1" used as the object (that is, before the operator) refers
 to the player.  So, l-1@13 would test if the player is at
 location 13 and l-1!23  would test if the player is not at
 location 23.

 Also, used as locations (that is, after the operator) the
 following numbers have special meanings:

           -1 = in the player's inventory
           -2 = "out of the game"
           -3 = synonym for the player's location

 Thus,  l13!-1 is a test that item 13 is not being carried by the
 player, and l42@-3 tests that item 42 is in the same room as the
 player.

 NOTE: only locations 1 to 119 can be used in location tests.  Be
 sure not to assign a higher number to a location that you will
 want to use in any Effect Record tests.

 Assistant/Guard tests
 ---------------------
 These are straightforward:

 a-             Tests if the assistant is not with the player
 a+             Tests if the assistant is with the player
 g-             Tests if there is no guard nearby
 g+             Tests if there is a guard nearby

 Random chance tests
 -------------------
 Sometimes you want things to happen only some of the time.  This
 can be done with a chance test, which generates a random number
 from 0 to 99 and compares it with the cut-off value you supply:
 if the number is less than the cut-off, the condition is met,
 otherwise it fails.  The format is an "r" followed by a cutoff
 number between 1 and 100.  For example:

 r67

 means the test will be met approximately 67% of the time.

 Note: you can use a series of random tests if you want to select
 between multiple effects.  For example, suppose you have a
 gumball machine for the player to use.  You might want him to
 get a gumball 60% of the time, a whistle 10% of the time, a
 rabbit's foot 20% of the time, and nothing at all the remaining
 10% times.  You would write a series of if/then statements like

 if r60
   then (give gumball)
 if r25
   then (give whistle)
 if r67
   then (give rabbits's foot)
 else
   then (give nothing)

 Note that each "r" is a new random number, so in this example,
 the first r-test (r60) will be false 40% of the time.  Thus the
 10% chance of the whistle comes from taking 25% of the times it
 fails the first test.  Similarly, 30% of the time BOTH the first
 and second tests will fail -- so the overall 20% chance of the
 rabbit's foot is 67% of the cases that reach that level.

 Another likely use for a random test is to determine which room
 the player is sent to.  For example, suppose you want the player
 to have an equal chance of exiting an elevator on floors 1, 2
 and 3.  These tests will accomplish that:

 if r33
   then (put on floor one)
 if r50
   then (put on floor two)
 else
   then (put on floor three)

 Remember that the various types of tests can be combined in one
 "if" statement in any numbers desired, up to a maximum line
 length of 198 characters.  The series of tests is concluded when
 SCENE encounters a carriage return or a comment marker.  Some
 examples:

 if g+ r80   ; most of the time, do this

 this test would be met 80% of the times that a guard was nearby

 if l-1@5 l15@-1

 this would check if the player was at location 5, and carrying
 item 15

 if ve=5 a- l12@-1 l11@-1

 This would test if variable "e" had been set to 5, the player's
 assistant was not present, and the player was carrying both
 items 12 and 11.

 Note that in the case of "if g+ r80" you could follow it with a
 "if g+" to to catch the remaining 20% of chances when the guard
 was present.  And an "else" would then handle the times when no
 guard was present.


 Varieties of "THEN" Actions
 ===========================
 The "then" part of an if/then can be made of any number of any
 combination of the following possible actions.  (Just as with
 the "if" tests, there should be no spaces WITHIN action command
 but there should be one BETWEEN multiple action commands in a
 then statement.  (The "else" part of an Effect Record is in
 essence a catch-all "then" statement, so all types and
 combinations of "then" actions can also be used in "else"
 statements.)  As with "if"s, a "then" line can be up to 198
 characters long, and is concluded with a carriage return or
 comment marker.

 Change variables
 ----------------
 You can add or subtract some number from a variable, or set it
 to a new value.  (Remember that the value of a variable must
 stay in the range 0 to 100.)  This is done by a "v" followed by
 letter of the variable to change, followed by the operator ("+"
 to add, "-" to subtract or "=" to set value), followed a number.
 Some examples:

 ve=12
 vj+7
 vx-2

 These would, respectively, set variable e to 12, add 7 to
 variable j, and subtract 2 from variable x.

 Change items
 ------------
 You can change an item's description, move it around, alter its
 weight (or any other feature in its definition) or make it
 appear or disappear.  This is done by copying the description of
 one item over the previous description of another.

 For example, consider these two item records:

 i 5
 %"crystal vase"
 'vase
 l 1
 w 10
 .

 i 51
 %"broken shards of glass"
 'glass
 'shards
 l -3
 w 10
 .

 By copying item #51 over #5, you will transform his crystal vase
 into broken pieces at his current location (because of the -3 as
 its location), perhaps in response to the phrase "break vase."

 The format of this type of change is an "i", followed by the
 number of the item to be changed, followed by an "=", followed
 by the number of the item with the new description.  For the
 previous case, the proper action is:

 i5=51

 This is how items 45 through 59 come into play.  Since only
 items 1-44 will be described as being present at a location or
 in a player's inventory, the higher numbers are invisible for
 all practical purposes.  When you want one of them to appear you
 have to copy its description over that of a lower number item.
 Obviously this will have the effect of making the first item
 vanish, so you must be careful that that is the effect you want.

 It is safe to copy a higher object over a lower one in three
 cases:

 A) When the first item is being logically transformed into the
 second one, as was the case with the vase/glass shards, or
 turning some wood into a pile of ashes, and so forth.

 B) When the first item was never visible.  If a lower numbered
 item was never defined, or defined but not given any "%"
 description it will be "invisible" to the player, and you can
 copy the item you want to appear over it at the appropriate
 point in the game without making something else disappear.

 C) When the first item must have already been "destroyed" prior
 to that point in the game.  For example, suppose one lower
 number item is a hand grenade, and the only way the player can
 enter a locked fortress is by using the grenade to blow open the
 gate.  And suppose that within the fortress the player can cause
 a K-Ration to appear by pressing a button.  It would be safe to
 copy the K-Ration item description onto the grenade item number,
 since the grenade will have already vanished before that point.

 The important point is to avoid "vanishing" some item the player
 has reason to think he still has, and especially one he needs.
 For example, don't copy a new item over the shovel the player
 will need to dig up a treasure chest!

 Change locations
 ----------------
 Similarly, you can change the description of a location.  The
 format of this change is an "l", followed by the number of the
 location to change, followed by an "=", followed by the number
 of the new location description.  For example:

 l4=27

 would make location 4 a copy of location 27.

 This can be used to change any aspect of a room description.
 For example, consider these two location records:

 l 10
 %"in a room with a door in the south wall"
 np15
 sn42
 .

 l 11
 %10
 np15
 sx73
 .

 If the player is at location 10 and tries to go south, string 42
 will be printed (which might say "the door is locked"), but
 he'll stay at location 10.  However, the phrase 'unlock door'
 might cause the door to open.  This would be done by:

        l10=11

 which causes location 11 to be copied onto location 10. All the
 entries are the same save for the south movement, which becomes
 sx73.  This means that location 10 now has a route south to
 location 73.  Note that the description for location 11 is %10,
 which causes it to be a duplicate of the description for
 location 10.

 Other changes can be made in a room by the same method:  for
 example, the new room description could reflect the changes some
 action of the player has caused: perhaps the walls are scorched
 after a fire, perhaps the mirrors that covered the walls are now
 broken, perhaps a secret passage to the south is now open, etc.
 Or perhaps the new description is the same except it no longer
 has a "," line, and thus is no longer dark.

 As with location tests, only locations number 1 - 119 can be
 used in these changes.

 Move player
 -----------
 You can also change the location of the player, and anything he
 might be carrying, by "teleporting" him to a new location.  This
 is done by a "t" followed by the number of the location he
 should be moved to.  Example:

 t117

 You can make it obvious to the player or not that something has
 happened.  If the description of the new location is different
 than where he used to be he will of course know he has moved,
 but if the two locations have the same short description he will
 not realize it unless you give him a hint or until he discovers
 some related change.

 NOTE:  You can only teleport the player to a location numbered
 from 1 to 119.  Also, this bypasses the Movement Tests, so any
 Effect that was supposed to happen when the player entered that
 location, or left the current location, will NOT be triggered.

 Change assistant/guard status
 -----------------------------
 Both the assistant and the guard are inactive at the start of
 the game.  An "a+" makes the assistant appear and an "a-" will
 make him vanish.

 The guard status works a little differently.  A "g+" activates
 the guard mechanism, and makes a guard visible IF one had been
 previously created.  A "g-" de-activates the guard mechanism and
 masks the presence of an already created guard.  That guard
 isn't dead though; he will re-appear when a "g+" is performed.

 There is also a random element built into guard creation.  A
 guard will be created only when the guard mechanism is active
 (via g+), there is currently no guard present, there are still
 "unused" guards available, and a random number in the assigned
 range is generated.  (Thus only one guard is ever present at a
 time.)

 A "gk" KILLS a guard, assuming one is in the room with the
 player when the effect is run.  If you chose to have more than
 one guard, new ones will continue to be created until the player
 has made the proper number of kills.

 Also, if a guard is visible and the player enters one of the
 "safe" locations (#5 - 15), the guard will temporarily vanish.
 This guard will automatically re-appear when the player leaves
 the "safe" area.  This can be used to create a haven for the
 player or if the logic of the game requires that the guards not
 be allowed in some areas.  For example, vampires should stay out
 of churches.

 Change score
 ------------
 This is the third way to affect the player's score.  (The other
 two are awarding points for entering a certain location or
 taking a certain object.)  The format is a "c" followed by a
 number between 1 and 100.  (It is impossible to reduce a
 player's score.)  Example:

 c40

 If you want to award more than 100 points in a certain effect
 (possibly for solving an EXTREMELY tricky puzzle) you can break
 it down into multiple credit changes.  For example, these
 commands would give the player 250 points:

 c100 c100 c50

 Print Effect Strings
 --------------------
 Almost every "then" command will include a "print effect string"
 command, since that is the main way of notifying the player that
 things are happening.  The format for the command is a "["
 followed by the number of the Effect String that should be
 printed, like this:

 [213

 (See "EFFECT STRINGS" for more on this.)

 Besides the strings you enter, there are four common responses
 you can cause to be printed just by entering the appropriate
 letter ("n" or "u" or "h" or "s") in your "then" statement.
 These result in the following responses:

 a "n" results in a "Nothing happens"
 a "u" results in a "I don't understand"
 a "h" results in a "You have no <object>"
 a "s" results in a "You see no <object>"

 (In the last two cases, the game uses the second word from the
 player's command as the object.)

 For example, suppose there was a haystack in location 7.  Your
 scenario might include these lines:

 p 'search 'haystack 22

 f 22 ; search haystack
 if l-1@7  ; player is in right location
 then [73  ; so tell him what he finds
 else
  then s
 .

 Now, if the player types "search haystack" anywhere except
 location 7, the game will respond "You see no haystack."

 Perform default action
 ----------------------
 Sometimes you want the game to do the normal action related to a
 phrase AS WELL AS something special.  This is done by including
 an "f" in the "then" statement.  For example, if the player
 takes the cork out of a cask you might want the game to print a
 string describing beer pouring out all over the floor, but it
 should go ahead and "take" the plug, too.  That is, put the plug
 into the players inventory.  The "then" statement for this might
 look like this:

 then [83 f

 End the game
 ------------
 There are two ways of ending the game, good and bad, also known
 as "winning" and "losing".  Putting an "e" into a "then"
 statement means that the player has won.  The game will print
 out the text you entered for the "e" command, and then
 terminate.

 Similarly, a "b" causes the game to print the "bad end" text,
 notifying the player that he has just blown it.  It will then
 offer him the choice of restarting the game or quitting.

 NOTE:  There is no set limit for the number of Effect Records
 you can define but there IS a limited amount of storage space
 set aside for them.  Obviously, an effect with many "If Then"
 statements, with many tests and actions, will use more storage
 space than short, simple ones.  The effect mechanism codes your
 tests and actions into the same storage space, starting with the
 high end and working down, so you should start at the low end
 and work up.  It is ok to skip Effect Record numbers, and you
 don't have to assign them in any particular order.
      When you compile your scenario SCENE reports on how much
 Effect Record space has been used -- this number can go up to
 2099.  This is plenty for about 100 FX Records of "reasonable"
 complexity, but if you plan a large game, keep an eye on this
 number to be sure you don't run out of space.

 2.8 SHORT STRINGS
 =================
 There can be up to 199 Short Strings.  These can be entered
 anywhere in your source file EXCEPT inside a record module.  For
 example, if the string is to hold the description of an item, it
 could be put on the line just after the "." line that closes
 that module, or just before the "i 23" type label that starts
 it, or anywhere else you please.  Since Short Strings are used
 for both blocked-passage "You can't go that way" type messages
 and item descriptions, you might find it more convenient to
 cluster them together, perhaps just before the Effect Strings at
 the end of your source file.

 The format for a short string consists of a quotation mark in
 the first column of a line, followed by the number of the
 string, from 1 to 199.  The next line should start with a
 quotation mark, followed by your text, ending with another
 quotation mark.  The text can be up to 158 characters long.
 (Short Strings are stored internally, so the total space
 available for them is limited by your computer's memory size.)
 Example:

 "23
 "a golden statue of Buddha"
 "17
 "The way south is blocked by a locked door."

 If you want to include a quotation WITHIN a string, you will
 have to use single quotes instead.  Example:

 "103
 "The conductor says,'Let me see you ticket, please,' and blocks
 the door."

 NOTE:  You do not have to use the numbers in any particular
 order, and it doesn't matter if you skip some numbers.  Just
 don't assign the same number to two different strings:  the
 second will overwrite the first, erasing it.

 Strings you create by putting the text in quotation marks after
 the "%" in an Item Record (instead of explicitly using a number
 and then listing the text for that number separately) are
 assigned a number by SCENE.  It starts at 199 and works down,
 and will not reassign a number if you have already used it.
 However, if YOU later assign a string to a number that SCENE had
 already used, the second string will overwrite and destroy the
 first one.  To avoid any possibility of this, you should start
 the string numbers you assign at 1 and work up.  (Since the
 maximum number of strings that the computer can assign numbers
 to is 118 -- two for each of the 59 items in your game -- you
 are completely safe if you keep your strings numbers under 80.)

 2.9 EFFECT STRINGS
 ==================
 There can be up to 219 Effect Strings.  These strings are
 printed when called for by the "then" part of an Effect Record.
 The format is a "[" in the first column, followed by the number
 of the string, from 1 to 219.  Next, put another "[" in the
 first column of the next line, and type in the text you want
 displayed, ending with an "]".  The string can be of any length,
 and the pause command "~" can be used as many times as you want
 within it.  Everything up to the next "]" will be considered
 part of that string.  For example,

 [124
 [The door swings open on its rusty hinges, revealing a dark
 passage.

 A breeze carrying the scent of seaweed blows in your face.]

 These strings can be entered anywhere within your scenario file
 that suits you, EXCEPT inside another record module.  For
 example, you could put the string on the line right after the
 "." line that concludes the effect record that calls it.  Or
 before the "f #" line that starts the record.  Or you could
 cluster all the print strings in one area at the end of your
 scenario -- this might be less convenient during writing, but
 would make it less likely that you will assign two strings to
 the same number.  (That would cause the second string to be
 written over the first, effectively erasing the first one.)

 NOTE:  Again, it is not necessary to assign string numbers in
 any particular order, and it doesn't matter if you omit some
 numbers.

 Also note that Effect Strings and Short Strings are stored
 separately, so it doesn't matter if you reuse numbers between
 them.  That is, you can have both a "1 and a [1 string in the
 same game without any problems.


                  ==============================
                  ||  3. TIPS and TECHNIQUES  ||
                  ==============================


                  3.1 Make good use of comments
                  =============================

 This is THE most important tip:  Use lots of comments!

 Label each function by what calls it:
 f 13  ; eat sandwich

 Label each "if" with what you are testing for:
 if l21@-1 l32@-1 ; does he have both candles and matches?

 Label each "then" that is more complex than a simple print
 string:
 then i12=56 ; swap burning candles for unlit ones

 Put in "road map" markers:
 ; ========== start of island locations =====

 Label alternate versions of locations with their intended use:
 l 21 ; starting living room

 l 22 ; living room after secret passage opened


 And anything else that occurs to you.  Remember, everything you
 write will seem perfectly clear and obvious to you at the
 moment, but if your game is a large one that will be written
 over several weeks labels will save you from having to puzzle
 out the purpose of something over and over.  And if you ever
 have to go back to your game months later, to fix some bug that
 has been discovered, you will be so grateful for those comments.


             3.2 Arrange your scenario file logically
             ========================================

 The SCENE compiler doesn't care what order you use when you
 create your scenario file, or even if there is any order at all,
 but it can make a great difference in ease of writing and de-
 bugging your game.

 Location Records
 ================
 If the locations in your game break up into logical groups (say,
 island vs. mainland, above ground vs. below ground, earth vs.
 rocketship vs. moon), keeping the location records arranged that
 way will lessen the time you spend searching for any particular
 area.  To make it even easier, put in "road map" dividers:  put
 a ";" in the first column, followed by something that is eye-
 catching, unique (so it can be easily searched for by your word-
 processor) and includes a label of what area the following
 locations belong to.

 Item Records
 ============
 These could be put either near the location record of the place
 that they will start in, or grouped together in your file.  If
 you do the latter, adding a "divider" road mark and keeping the
 records in numerical order will make it easy to determine which
 numbers have been used/are still available.

 Movement checks
 ===============
 These can be grouped together for convenience, but it really
 makes little difference.  This is because ALL movement checks
 are scanned each move, and duplicate movement checks are allowed
 and don't interfere with each other.  For example, you might
 have two "do each move" checks  ( m -1 -1 2  and m -1 -1 3)
 which are doing different tasks.

 Phrases
 =======
 Phrases DEFINITELY should be grouped together, and I suggest
 that you keep them in alphabetical order.  This is because if
 you accidentally duplicate a phrase, the first one in your file
 will "mask" the second one, and prevent it from working
 properly.  For example, you might have written the phrase 'open
 'door early in your game, in connection with player getting
 something out of a safe.  Days later you could accidentally
 define the same phrase, this time in the context of opening the
 door of a spaceship.  If you don't remember that you have
 already used the phrase, the player might never be able to get
 into that spaceship.

 NOTE: It is perfectly ok to use one phrase in several
 senses/locations.  You must just be sure that all the possible
 actions are handled in the SAME Effect Record, and that your
 "if" tests can distinguish between them.  For the safe/spaceship
 scenario, something like this would work:

 f 12 ; 'open 'door
 if l-1@13  ; player in living room?
   then (print out string about what was in safe, make items
           appear, etc.)
 if l-1@76 ; player on spaceship gangplank?
      then (swap location 76 so can now enter space ship)
 else
   then u ; print "don't understand", since not near a door
 .

 (If there were other locations with doors, simply keep adding
 appropriate "if thens" before the "else".)

 Obviously, having all your phrases alphabetically grouped in one
 area makes it simple to see whether the phrase you have in mind
 is a new one, to be given its own new Effect Record, or already
 in use, in which case you'll need to add one or more new "if
 thens" to the existing Effect Record.

 Effect Records
 ==============
 The logical place for these is in a group after the "phrases"
 area.  Keeping them in ascending numerical order will speed up
 locating the one you want to work on and make it easier to avoid
 duplicating a number.

 Short Strings
 =============
 You might want to place each "you can't go that way"-type string
 right after the location record that uses it, and each "item
 description" string after its object record.  Or you might also
 group these together in ascending order.  The first system is
 quicker to write and more easily understood when reading the
 scenario file, the second system lessens the chances of
 duplication numbers.

 Effect Strings
 ==============
 Again, these could go either after the Effect that uses them or
 grouped together after the Effect Records as a whole.  The
 advantages are the same as with the Short Strings, but since
 there will probably be many more of these and they tend to be
 longer, I prefer to put them together at the end of the file.
 (Also, it may be that the same string could be used by several
 different Effect Records.)


                          3.3 Draw a map
                          ==============

 Having a map of your game's locations on paper will make it
 easier when entering the connections between locations.  As you
 enter the Location Records, be sure to note the number you
 assigned to that location on your map.  (And if you have
 alternate versions of the same location, put down all their
 numbers, and what they are for/how they differ.)  This is very
 useful when you want to write an "if then" statement checking if
 the player is in the Sultan's Harem -- and you've forgotten
 which number that location is.


               3.4 Tackle your game in small chunks
               ====================================

 It is inevitable that you will make some errors, or typos at
 least, as you write you game.  These problems are much more
 easily tracked down if you know the flaw MUST be in the
 relatively small number of lines you just added.

 The free-form nature of this game system makes this approach
 easy and natural.  You might concentrate on one physical area
 (the rooms in a house, the grounds around it, the main street of
 a town) or the Phrases and Effect Records involved in one small
 puzzle ("unlock safe" and "open safe" and "read will") at a
 time.  When you have written them use SCENE to compile your
 scenario, then test your work by running it with PLAY.  If you
 added a new area, "walk" through it, reading all the descrip-
 tions, making sure all the locations connect the way you meant
 them to, "searching" and "examining" as appropriate.  If you
 added some phrases or movement checks, try them out: unlock that
 safe, read the will, etc.  If you discover a problem, or realize
 that you overlooked something (did you remember to test that the
 player HAS the will before he can read it?), go back to the
 scenario file and correct it.

 Basically, it is much easier in the long run if you don't move
 on to adding something new until you have the earlier parts
 working correctly.


         3.5 Use foresight in assigning location numbers
         ===============================================

 Remember that you have a limited number of "safe" and "hiding"
 rooms, and that only 1-119 can be use in "if then" tests and
 actions.  That will probably be sufficient for your game, but
 don't "waste" them by giving an unimportant location one of
 those special numbers.  One system is to keep a paper list of
 all the room numbers and check them off as you assign them.  As
 you create each new location ask yourself, Do you want to hide
 some object in this room?  Do you want to keep the guards out of
 this location?   If the answer is yes, assign an appropriate
 number: 2 - 10 for hiding, 5 - 15 for "safe" rooms, (5-10 if it
 needs to be both). If no, is there anything else that will
 happen "here"?  Will I ever need to test if the player or some
 item is located here?  Will I ever want to "swap" this location
 for a different version of it?  If yes, assign the next unused
 number from 16 to 119.  If the answer is no, give it the next
 available number higher than 119.  With this system, you may end
 up with long stretches of unassigned location numbers (nothing
 from 70 to 119, say, but you have used 120-150) but that has no
 bad effect on the game.

 If you ever find you need to change a location's number (perhaps
 you found out you DO need to be able to teleport the player to
 what you thought was an unimportant location) all you need to do
 is edit your scenario.  However, remember that you must change
 ALL the times that location is referred to by number.  Suppose
 you are changing room 130 to 86.  Not only do you need to change
 it in the "L 130" record, you also need to change the Location
 Record of each location that it connects with: if you go east to
 location 131, be sure to change location 131 so that it goes
 west to 86 instead of the old 130.

 If you are changing a location FROM a number 119 or less, you
 should also check for that location in the effect records, and
 substitute the new location number there, too.  (Be sure to
 remember that locations used in Effect Records must be 119 or
 lower.)


          3.6 Use foresight in assigning object numbers
          =============================================

 Remember that only items from 1 to 44 are "visible" to the
 player.  Items that should "exist" from the beginning of the
 game, then, must be given one of those numbers.  (And, of
 course, if you want to include a light source, it MUST be #1.)

 Less obviously, if you want something to be "appear" at a
 location it wasn't in earlier, you will have to give it a number
 HIGHER than 44.  It will then be "invisible" until you have
 "swapped" it onto a lower number.

 You will almost certainly want to "destroy" or "vanish" some
 item in the course of the game.  To do this, have an invisible
 item -- one with no description and no "names".  For example:

 i 10 ; item to "vanish" others
 l-2
 .

 Copying this item onto any other will make that item disappear.
 Note: this item could equally well be given a number from 45 -
 59.  It makes no difference so use whichever type of item you
 can spare most easily. (See "ITEM RECORDS" for more
 considerations on swapping items into and out of existence.)

 It is possible that you will HAVE to make another item appear --
 and you have already used up all the higher number items that
 would normally be used to do this by copying over a lower
 number.  There is a way around this, but it is something of a
 kludge.  Instead of making something appear in a room it was in
 before, you use an item that was always present and visible in
 the room -- but it is actually a DIFFERENT room.  This can be
 done by having two versions of a room with the exact same
 description and connections, and teleporting the player between
 them.

 For example, room 23 and 24 are two versions of a cafeteria,
 identical except for their location number, and the item in
 question is a cup of coffee which the player can buy from a
 vending machine.  Here are the necessary records:

 i 29
 %"a cup of coffee"
 'cup
 'coffee
 l 24
 .

 l 23 ; cafeteria w/o coffee
 %"an ordinary cafeteria.  Built into the wall is a vending
 machine.  Above its slot is a sign, offering a cup of coffee for
 25 cents."
 sd30
 .

 l 24 ; cafeteria w/coffee
 %23
 sd30
 .

 l 30
 %"a hallway outside the cafeteria"
 nd23
 .

 p 'insert 'quarter 30

 f 30
 if l-1@23 l20@-1 ; player in first version of cafeteria, with
                  ;  quarter
  then t24 i20=59 ; teleport player to version with coffee and
         ;vanish quarter
 .

 From the player's point of view, a cup of coffee has appeared,
 but in fact the coffee was there all along -- he changed, it
 didn't.  Since the description of the room is the same, and
 going out the door will take him to the same location he came in
 from, he has no reason to suspect what actually happened.  This
 seems to work as nicely as making something appear by swapping
 items, but there is one big problem: any items set down in the
 first version of the cafeteria by the player will not make the
 trip with him.  From his point of view, they have vanished.

 Even more peculiar, if he leaves the cafeteria and then re-
 enters it, those items will now be there!  What's worst, though,
 is that if the player sets any items down in the second version,
 and leaves without them, he loses them forever!  (Because the
 only way to reach location 24 is by inserting the quarter -- and
 he no longer has it.)  You could treat this flaw as a "feature",
 by adding to the description a sign saying  that "management
 takes no responsibility for items lost or stolen", but it's
 still a kludge, and should be used only as a last resort.


                     3.7 Keep "Cheat sheets"
                     =======================

 Having certain information on paper can save you from a lot of
 time scrolling through your file looking for it, certainly more
 than it will take you to make your "cheat sheets."  Two types
 have already been mention:  your map, and the list of location
 numbers that shows which have been used/are still available.
 Here are some other types that may be handy:

 SCENE "grammar" summary
 =======================
 Handy for instant reference when you can't immediately remember
 how to make a location dark or some other detail.  The last
 three pages of this doc file are the summary I used.

 List of item numbers
 ====================
 Number lines 1 to 59, and as each Item Record is entered, make a
 note of what it is, plus maybe what it weights and how many
 points it is worth and its starting location.

 Variables list
 ==============
 Label lines from "a" to "z", and note what you are using them to
 keep track of, and what the various values mean.  For example:

 f - contents of flask. 0 = alcohol, 1 = poison, 2 = empty
 t - status of trapdoor. 0 = closed, 1 = open.
 m - how many matches player has.  starts at 6.

 (Note the use of variables with mnemonic significance.  This
 won't always be possible, but you might as well do so when you
 can.)

 "Point" list
 ============
 If your game is oriented towards awarding points, you might want
 to keep track of them separately, so you can use some
 consistency in assigning them and make sure the final total is
 what you are after.   For example, each "treasure" the player
 picks up might be worth 25 points.  Getting past "blocked"
 passages might be worth 50 points each.  Solving trickier
 puzzles might be good for 100 points.  Whatever.

 "Word" list
 ===========
 This is just an alphabetical list of all the words you have used
 in the game, both item "names" and "verbs" and "nouns" used in
 phrases.  If you start running tight on words this list can be
 scanned for the possibility of combining synonyms.  (For
 example, do you really need both "burn" and "ignite"?)

 "Puzzle" list
 =============
 This is just a list of the obstacles a player has to overcome,
 or puzzles he must deal with.  It will give you some idea of how
 hard or easy your game is, perhaps leading you to add
 complications or simplify things.  Also, if you have "plotted"
 out your game overall, checking the items off as you work them
 into your scenario file shows you how your game writing is
 progressing.

 "Time Line"
 ===========
 If your game is basically linear this can be useful.  By
 "linear", I mean that the player must pretty much accomplish
 things in a set order.  For example, maybe the player must
 explore the starting area and discover a map to a pirate
 treasure.  Then he has to construct a ship to get to an island.
 Then he had to explore that island.  Then he has to actually
 solve the puzzles guarding the treasure.  And so forth.

 Obviously this is of no use if the player can tackle the puzzles
 in the game in almost any order, as was true in the "Original
 Adventure" game.

 "Special" lists
 ===============
 These would be anything called for by the exact game you are
 working on.  For example, if your game includes the player
 having to concoct a magic potion, a list of all the ingredients
 might be useful to have at hand.  (And a list of the order they
 should be added to the pot, if that matters.)

 Another example: In the first game I wrote using this system
 (FAUST), I wanted the names of all the people and places in the
 game to come from Horror movies.  I kept a list of possibilities
 so I could cross them off as they were used and add others as
 they occurred to me.

 Basically, remember that is is safer to write down any "idea" or
 "inspiration" that occurs to you so it won't be forgotten when
 the time comes to add it to your game.


      3.8 Include "temporary short-cuts" during the writing
      =====================================================

 If you are following the "write a piece then test it" method of
 writing your game, you will eventually get tired of having to do
 all the early steps in your game before you can reach the
 position in the game you actually want to test.  By putting in
 temporary "shortcuts" you can eliminate this.  For example,
 going back to the pirate treasure idea, if you are working on
 the puzzles involved in getting the treasure chest out of its
 cave, you really don't want to spend the time building and
 sailing the ship to the island.  Instead you can add a
 "temporary shortcut" to get you to that point.  Just choose one
 of the unused directions from an early location and add a
 connection to a location near the puzzle you want to test.  For
 example, going "up" from the front yard might land you just
 outside the island cave.  This will save you a LOT of time.

 NOTE:  Be sure to add some unique "tag" after these shortcuts.
 For example,

 ux122 ; $$$$$$$$ SHORT CUT -- REMOVE LATER $$$$$$$$

 And, of course, make sure you remove all of them before you
 compile the release version of your game.  (With "tags" of this
 format, searching for '$$$$$' with your word processor will keep
 you from overlooking any of them.)


             3.9 Add "descriptions" to non-portables
             =======================================

 This can add color to your game, making it richer and more
 pleasurable to play.  If your game includes a dungeon, perhaps
 the phrase "examine dungeon" should elicit a string like this:

 [23
 [The floor is covered with blood stains, so many they overlap
 each other in layer upon layer, and the walls seem to ring yet
 with the screams of the poor souls who were tortured here.]

 This isn't necessary to the solution of the game, but think of
 it as putting chocolate sprinkles on your ice cream cone:  You
 don't NEED them, but isn't it nicer to have them?

 Of course, these descriptions COULD reveal information necessary
 to the solution.  For example, perhaps the only way the player
 will discover the combination to the safe is by "examine desk",
 which reveals that the numbers 36 - 24 - 36 have been carved
 into its top.  (Or does that have more to do with the secretary
 than the safe?  Hmmmm.)

 NOTE: You can do the same thing by using an object with a long
 description instead.  Both of these sets of lines will create
 the same result to the command "examine desk".  Which you pick
 depends on whether you have more phrases or objects left to use.

 i 23 ; desk -- used to reveal combination
 %"a wooden desk with a scarred top"
 x"Carved into the top of the desk is the name "Sheila", and the
 numbers 36 - 24 - 36."
 'desk
 l 23
 w -1   ; so the desk in non-portable
 .

     - or -

 p 'examine 'desk 85

 f 85 ; examine desk
 if l-1@23  ; player in office
 then [118
 else
  then s  ; print You see no desk
 .

 [118
 [Carved into the top of the desk is the name "Sheila", and the
 numbers 36 - 24 - 36.]


                 3.10 Intercept built-in commands
                 ================================

 If the effect of a built-in command doesn't suit your particular
 scenario, you can prevent it from acting by entering that
 command as a phrase and building your own Effect Record for it.

 For example, suppose you are using a 'drop 'something command to
 trigger an effect -- Perhaps "drop flask" is supposed to lead to
 a description of the flask shattering and releasing a noxious
 gas.  If the player, while holding the flask, instead types
 "drop all" the effect will not be triggered and the player may
 never realize that the noxious gas is available and is the
 weapon needed to solve a puzzle.

 To avoid this, you could include these lines in your source
 file:

 p 'drop 'all 23

 f 23 ; drop all
 else
  then  [56
 .

 [56
 ["All" does not work with "Drop".  You must refer to each item
 separately.]

 In essence, this "turns off" the built in command "drop all"
 completely.  You could instead use some check in f 23 to see if
 the player is holding the troublesome item, and allowing the
 "drop all" command to work any other time, but that rapidly gets
 cumbersome.  If you are using more than just one or two "drop"
 phrases to trigger effects, I'd suggest you simply turn the
 phrase "drop all" off entirely.  And, if you choose to do this,
 you might want to turn off "take all" as well, for symmetry.
 Simply adding the phrase "p 'take 'all 23 " to the above lines,
 and adding the words 'or "Take"' to string 56 will accomplish
 that.


                    3.11 Elaborate on "Search"
                    ==========================

 Items with an "h" line are hidden in locations 2 - 10 -- that
 is, they will not be listed as being present until the player
 uses "search".  This is fine for locations where things might
 reasonably be hidden (for example, if the location is described
 as "full of things" or "leaves cover the ground") but less than
 realistic under other circumstances.  Is the player really
 supposed to believe he just didn't notice a $10 bill in the
 middle of an otherwise empty hallway?  Or an elephant --
 anywhere??

 If you want, you can use phrases to make a situation more
 believable.  Suppose you want the player to have a dime, but you
 want him to solve a (very minor) puzzle to get it.  You could
 set up something like this:  Item 18 will be the dime, once you
 have copied Item 47 onto it.  Location 7 is a hallway with a pay
 phone.  Your source includes these lines:

 p 'search 15
 p 'examine 'telephone 16
 p 'search 'telephone 16

 f 15 ; search
 if l-1@7 then [117   ; if player in room 7, print string 117
 else
  then f               ; otherwise do normal "search"
 .

 [117
 [The hallway is empty except for a pay phone on the wall.]

 f 16 ; examine/search telephone
 if l-1@7 ; player near telephone
 then i18=47 [118  ; see "item manipulation" for how to make
                   ; things appear
 else
  then [119
 .

 [118
 [You flip the coin return and a dime rolls out.]
 [119
 [What telephone?]

 Now, a "search" in the hallway just reminds the player that the
 phone is there -- a nudge in the direction of the proper action.
 Only if he carries through with a "search telephone" or "examine
 telephone" will the dime appear.


              3.12 Change the portability of an item
              ======================================

 You can make an item that was non-portable become portable, or
 the reverse, by copying onto the item one with the same
 description except for a different weight.  How/why the player
 does this could be one of the puzzles in your game.  For
 example, the solution to another puzzle depends on his being
 able to move a 3 foot cube of lead to a different location --
 and it is too heavy for him to lift at first.  The swap to the
 "lighter" version could happen if he:
   A) exercises to build up massive muscles
   B) finds a grow pill and becomes a huge, strong giant
   C) drinks a "strength" potion
   D) finds an antigravity gizmo
   E) finds an "element transmuter" and changes the lead into tin
   F) learns a spell and makes the cube float
 or anything else that fits the theme of your game.


            3.13 Create a move counter/countdown timer
            ==========================================

 Unfortunately these nifty items weren't built-into the game, so
 you will have to create a substitute if you need one.  This can
 be done by using variables and movement checks.  For example,
 suppose you want to have a bomb that explodes three moves after
 the player pushes its button.  Including these lines in your
 game will accomplish that:

 m -1 -1 13 ; do this effect EVERY move

 p 'push 'button 12

 f 12 ; push button (on bomb)
 if l24!-1  ; player doesn't have bomb
  then h ; tell him so
 else
   then vb=1 [23  ; flag variable b that bomb has been activated
 .

 [23
 [The bomb starts ticking loudly.]

 f 13 ; any move -- bomb timer
 if vb=4 l24@-3   ; been three moves, and player near bomb
   then [24 b   ; blow the idiot up and bad end game
 if vb=4 l24@100   ; 3 moves, bomb in location we care about
   then [25 l100=101 i24=59 vb=0   ; change location 100 --
     ; perhaps now a formerly locked door has been blow open
     ; make the bomb vanish, reset the variable since bomb no
     ; longer ticking down
 if vb=4   ; 3 moves, neither of first two conditions met
   then [25 i24=59 vb=0   ; the same as the previous, except
       ; there has been no location change: the player wasted
       ; the bomb
 if vb>0   ; bomb has been activated, but not 3 moves ago
   then vb+1   ; bump the variable by one for this move
 .

 [24
 [The last thing you ever hear is a tremendous explosion, etc.]
 [25
 [You hear a loud explosion.]

 NOTE:  Even though effect 23 will be done EACH move throughout
 the entire game, most of the time nothing will happen since
 there is no "then" (or "else") that would apply when vb=0.

 Remember that variables can only have the values 0 to 100.  If
 you want to count higher than that, you will have to use two,
 working together: one keeps track of how many "hundreds" of
 moves there has been, while the second is clocking the moves of
 each set of 100.

 For example, suppose you simply want to set a "time" limit on
 your game:  if the player hasn't finished in 350 moves, you blow
 the whistle, everybody out of the pool.  Here is how you could
 do that:

 m -1 -1 2  ; every move -- move counter

 f 2
 if vb=3 va=50  ; got to the magic number
   then [2 b ; bad end the game
 if va=99 ; this move completes the latest "hundred"
   then vb+1 va=0 ; up "b" by 1, reset "a" to 0
 else
   then va+1 ; bump "a" by one for this move
 .

 [2
 [some sort of "out of time", "too slow", etc. remarks]

 Nesting two variable like this allows you to count up to 100
 hundreds, or 10,000.  That ought to meet any reasonable need,
 but added a third level to the count would cover numbers up to a
 million!


                   3.14 Use the assistant/guard
                   ============================

 The only thing the assistant will automatically do in the game
 is follow the player around while he/she/it is activated.  This
 gets old pretty fast, so you might want to:
   A) add some thing(s) the player can get the assistant to do
   B) add some way for the player to get rid of the assistant,
      either temporarily or permanently, when he tires of it
   C) combine A & B
   D) skip the assistant entirely.

 D is simple: just don't include an "a the bumbling Dr. Watson"
 type line.

 B is straight forward, too.  Simply add a phrase or two that
 trigger an effect that turns the assistant off:

 p 'fire 'Igor 14
 f 14
 else
    then  a- [12
 .

 [12
 [Igor looks at your reproachfully, then turns and plods away.]

    - or -

 p 'shoot 'Wesley 85
 f 85 ; shoot Wesley
 if l23@-1  ; player has the phaser
   then a- [73
 .

 [73
 [For a split second Wesley glows in the phaser beam, then he
 vanishes entirely.]

 If you want the player to be able to get the assistant back
 again, provide some "reversible" method of turning it off, such
 as a room the assistant can be locked in and released from at
 will.

 Getting the assistant to do something is simply a matter of
 building an effect that accomplishes whatever you want done,
 just as if the player himself was the one doing it.  Naturally
 the "if" part should include an "a+" to be sure the assistant
 (for simplicity, call him Igor) is present, and the "then"
 includes any changes Igor has "caused" plus some string telling
 the player that Igor is the one who has done whatever.

 The tricky part is how the player is supposed to get Igor to do
 it.  There is no provision for him to give Igor orders, so
 you'll have to improvise.  Basically, any phrase you include in
 your game, or any movement test, could cause something to be
 done by Igor. Perhaps all the player has to do is go to some
 location, or pick up some object when Igor is present, to have
 the effect trigger automatically.  For example, maybe just going
 to the "funny face" contest with Igor in tow will result in the
 player being awarded a silver cup.  Or if the player knocks on a
 locked door while Igor is around, perhaps Igor, in a fit of
 helpfulness, batters it down.

 A guard can be used the same way: perhaps the way through a
 sealed hatch is to have a Klingon chase you into the room,
 whereupon he shoots at you and disintegrates the hatch when his
 shot goes wild.

 If the "proper" action is rather unobvious (why should the
 player eat the sandwich while a guard is threatening him?) be
 sure to hint at it VERY strongly, either in the game or its doc
 file.


                          3.15 Play fair
                          ==============

 In a sense, a game like this is a challenge from the writer to
 the player:  are you smart enough to come up with the same
 solution that I thought of?  Note the phrasing:  the SAME
 solution, not just A solution, or even THE BEST solution.  It is
 perfectly possible that the player will think of and try (in
 vain) some really nifty solution to a problem that you didn't
 even think of.  (For example, I wanted to take the giant
 clam/oyster from "Adventure" down to the hot room near the
 volcano and steam it open.  It was a reasonable possibility, and
 it COULD have been the proper method -- but it wasn't the one
 the writers had in mind.)

 Since you, the writer, have the upper hand, you must be sure you
 are fair to the player.  Your chosen solutions should be
 "logical" within the context of the game.  So it would be okay
 for a player to open a locked door by means of a key, or using a
 screwdriver to take the hinges off, or using an axe to chop it
 down -- but not by some nonsensical command like "kiss door".
 This also means that items and methods should fit the milieu of
 your game: spells and magic potions are fine and dandy in an
 "explore the magic land of Zoom" type game, but shouldn't be
 used in a Thirties Hard-Boiled Detective game.

 There should be plenty of hints to gently nudge the player along
 the correct paths -- if he is alert enough to notice them.

 If solving your game requires the use of some commands that
 aren't immediately obvious, tell the player about them.  For
 example, you might give the player a complete list of the
 "verbs" that the game understands in an associated .doc file.
 Or let him see the required command somewhere (does "Fee Fie Foe
 Foo" ring a bell?) or even "overhear" someone else using the
 command.  (If it worked in Ali Baba and the Forty Thieves, it
 can work in your game.)

 Above all, avoid idiotically hard or pointless problems that can
 only be solved by "brute force."  For example, requiring the
 player to enter a three digit number with no hint as to what the
 right number is.  (Do you expect him to punch in each
 combination from 000 to 999??) Or forcing a player to get a fish
 by typing "take trout", with no clue to him that the fish is
 indeed a trout and not a salmon or bass or mackerel or tuna or
 any of a hundred possibilities.  (Incidentally, these examples
 come from actual games I have seen.)

 Remember:  you want people to enjoy your game.  If they don't
 discover fun things to do and read, if they don't feel they are
 making progress, they will quickly lose interest and quit.  Make
 your game a pleasure to play -- or don't waste your time writing
 it.


                ==================================
                ||  4. COMPILING YOUR SCENARIO  ||
                ==================================


                        4.1 Running SCENE
                        =================

 SCENE is run by typing its name, followed by the name of the
 scenario it should compile.  So, if your source file was called
 "TARZAN.SRC", the command is:

 SCENE TARZAN

 NOTE:  You can type the entire name, but SCENE automatically
 truncates the name at the period, and then looks for a file with
 that name plus the extension ".SRC".

 When SCENE is running it produces a temporary file (holding most
 of the string text), with the same name plus the extension
 ".$$$".  After it has scanned through the entire source file it
 then produces the ".SCN" file which is the data file your game
 will be run from.  As a (very rough) rule of thumb, this means
 you need free space on your disk of around twice the size of
 your source file.  For example, the included Star Trek game has
 about of 39K SRC files, and generates a 30K $$$ file and a 49K
 SCN file.  If your game gets very large -- or if your disks are
 relatively small -- you may reach the point that one disk will
 no longer hold SCENE.COM plus the SRC, $$$ and SCN files.

 To alleviate this problem, SCENE allows you to specify which
 drive(s) it should place the SCN and $$$ files on.  This is done
 by putting the drive name(s) after the basic command.  If you
 don't enter one or both of these, it defaults to placing that
 file on the same drive as one most recently indicated.  Some
 examples:

 A>SCENE TARZAN   ; SCENE, SRC, SCN and $$$ will all be on A

 A>SCENE B:TARZAN    ; SCENE is on A:, the SRC file is on B, and
 both the SCN and $$$ files will be on B:

 A>SCENE TARZAN B:  ; SCENE & SRC on A, SCN and $$$ on B

 A>SCENE B:TARZAN B: A:  ; SCENE & $$$ on A, SRC and SCN on B.

 If you need still more space, SOURCE allows you to change the
 disk that the SCN file will be written on after it has completed
 the first scan and before it writes the final output.  At this
 point it prints a prompt,

 Input floppy changed to receive output?
 Y = yes  A = abort   else No

 If you want the SCN file on a different disk, change it at that
 point and then answer "Y".  If you want the SCN on the same disk
 already in the specified output drive, hit the return.  The
 third option, Abort, is a way to bail out if you have made a
 mistake in specifying which files go where.  Keep in mind that
 SCENE needs to have the temporary $$$ file available to it while
 it is writing the SCN file.  If you want the SCN file on a
 different disk, you must NOT have had the $$$ written on the
 disk you will be removing!

 This arrangement of files will usually make the best use of
 space on smaller disks:  Have just SCENE.COM on the disk in the
 A: drive, and nothing but your SRC file on the disk in B.  Type
 this command:

 A>SCENE B:TARZAN B: A:

 Since the $$$ file is written on A, you can change the disk in B
 to receive the SCN file.  Using this arrangement, your SRC file
 can be almost as large as the full size of your disk.


                  4.2 Splitting your source file
                  ==============================

 Obviously, working on a SRC file of that size can cause problems
 for your word processor, and also can be slow.  To avoid this,
 it is possible to split your source into any number of smaller
 pieces.  This is done by adding a "chain" command at the end of
 each of the pieces except the last.  (Anything in the file AFTER
 a chain command will be ignored so make this the LAST line of
 the piece.)  This command is a "<" followed by the name of the
 next piece of the source.  Examples:

 <TARZAN2.SRC
 <PART-2
 <ITEMS.REC
 <STRINGS

 NOTE: the file names of the second and later pieces can be
 anything legal under CP/M, however the FIRST piece, the name you
 will enter on the command line when you compile your game, MUST
 have the type ".SRC".


                        4.3 SCENE feedback
                        ==================

 While SCENE is running it keeps you apprised of what is
 happening by printing out the type of each record as it
 processes it.  This results in a row of letters & characters,
 like this:

 llillplmmmmff[[ll"

 and so forth.  If it runs into something it does not understand
 it will print a message about it, such as, unknown record type,
 location expected, and so on.  SCENE will continue to process
 your file to the end no matter how many errors it finds.

 Discovering what the problem is can be made easier by comparing
 the list of records processed with your source file:  if the
 error message came just after the third location record
 processed, that it where you should start looking.

 The most common type of error is failing to pair opening and
 closing markers properly:  remember, each string must START and
 END with the appropriate markers (either two "'s, or a set of
 [], or a set of {} ).  If you fail to include the closing marker
 scene will continue scanning through your file until it finds
 one (most likely, one that was supposed to close a different
 string, meaning that everything between them is turned into one
 long string instead of whatever you meant it to be) or until it
 exceeds the "legal" length of a string of that type.

 Another common slip is to fail to close one record before
 starting another.  Remember, records that involve more than one
 line must end with a line with just a "." in the first column --
 this holds for location, item and effect records.

 The third most common error is to put spaces where they don't
 belong, or fail to put them where needed.  The "pieces" of
 individual "if" tests and "then" actions must NOT have spaces
 between them. That is, l23!34 is a proper test, NOT l12 ! 34.
 The main place omitted spaces cause problems is before comment
 markers.  If the semicolon isn't preceded by at least one space
 (unless it is the first thing on a line) it can be "discarded"
 during processing.  If this happens, SCENE will then try to
 interpret your comments as commands, resulting in at least one
 "error" message per word in the comment.

 If SCENE is complaining about the "operator", it generally means
 you mixed the operators from one type of test into a different
 one.  (Only @ and ! work for location tests, for example.)  You
 can check out the proper operators on the Summary pages.

 After it has compiled your entire source file, SCENE will report
 the counts of how many of various types of things have been
 used: how many locations, items, FX records, movement tests,
 phrases, words, short strings and FX strings.  You might want to
 keep an eye on these totals in relation to the maximum numbers
 allowed.  This is especially true for the FX records: unlike all
 the other categories, you cannot tell from your source file or
 cheat sheets how many have been used.

 Compiling a larger game can take a few minutes.  For example,
 the includes Star Trek game was compiled using the command
 "A>SCENE STAR A: B:" on a 4 Mhz Z80 CP/M 2.2 computer with two
 5-1/4 inch floppy drives.  It took 1 minute 18 seconds to finish
 the initial scan and write the $$$ file, and another 1 minute 22
 seconds to generate the SCN file.

 SCENE will beep after it finishes the initial scan and is ready
 for you to change floppies if necessary, and also after it
 finishes writing the SCN file.


                        ==================
                        ||  5. SUMMARY  ||
                        ==================

 LOCATIONS   1 to 199 allowed;
 =========   1 = start; 2-10 can "hide" items; 5-15 off-limits to
             guards;  only 1- 119 can be used in tests, swaps and
             teleportations;

 l 76    ; optional note for yourself
 %"short description up to 255 characters, printed each time
   player in room"
 %74     ; alternate form for short description, makes room same
         ; as previously defined room 74.  use only one form
 [optional long description -- first visit & after "look"
 command]
  - or -
 {optional long description -- only after "look" command}
 ,     ; makes location "dark": player will need light to see
 sd42  ; "door" leads south to 42
 us15  ; "stairs" lead up to 15
 np44  ; "passage" leads north to 44
 wx73  ; unspecified connection to 73
 en76  ; triggers "can't go that way" message #76 if go east
       ; default "You can't go that way" since no "down" entry
 c10   ; 10 points given first time move to this location
 .     ; marks end of location record

 ITEMS      1-44 can be visible in game, 45-59 must be swapped
 =====      onto a lower number before they can be seen or used;
            Item 1 is the light source;

 i 15
 %"description of item, printed when item in room or inventory"
 %6       ; alternate form, use short string #6 for description
 x"(optional) longer description given when 'examine'd"
 'name1   ; one word, used to refer to object
 'name2   ; (optional) one word synonym;
 h        ; (optional) "hide" object if in locations 2 - 10
 a        ; (optional) "take all" will not include this item
 c 5      ; (optional) 5 points first time object taken
 l 2      ; initial location; -1 = player's inventory
          ; -2 = non-accessible;
          ; -3 = wherever player is;
 w 15     ; (optional) weight of item, -1 means non-portable
          ; player can carry up to 100 total
 .        ; marks end of item record

 MOVEMENT TESTS
 ==============
 m 22 8 31   ; if player moves FROM loc. 22 TO loc. 8
             ;  do Effect Record 31;
             ; -1 for either location matches all;  -1 for both
             ; locations means effect will be done each move;

 PHRASES
 =======
 p 'verb 'noun 54  ; if command is "verb noun" do effect 54
 p 'verb 21        ; if command is "verb" do effect 21

 EFFECT RECORDS
 ==============
 f 23   ; optional reminder to yourself
 if  conditions     ; any number of if/then lines can be used
                    ; if none are true then the "else" action
   then  actions    ; will always be done
 if  other-conditions
   then  other-actions
 else               ; (optional) actions to be done if none of
   then  last-actions    ; the "if" conditions are met
 .  ; marks end of record

 CONDITIONS  can be any combination of the following tests
 ==========  all tests must be met for the "if" to be true;

 VARIABLE TESTS   26 variables possible, "a" to "z", 0 to 100
 --------------
 vx=5    ; tests if variable x is equal to 5
 vb#37   ; tests if variable b not equal to 37
 vg<12   ; tests if variable g is less than 12
 vr>66   ; tests if variable r is greater than 66

 LOCATION TESTS  only for locations 1-119 and -1, -2, -3
 --------------
 l6@52     ; Tests if item 6 is at location 52
 l13!114   ; Tests if item 13 is not at location 114

 Special cases:
       as item, -1 = player
       as locations
           -1 = player's inventory
           -2 = "out of the game"
           -3 = synonym for the player's location

 ASSISTANT/GUARD TESTS
 ---------------------
 a-             Tests if the assistant is not with the player
 a+             Tests if the assistant is with the player
 g-             Tests if there is no guard nearby
 g+             Tests if there is a guard nearby


 RANDOM CHANCE TESTS  0 to 100% chance allowed
 -------------------
 r40  ; 40% chance will be true


 POSSIBLE ACTIONS   can be any combination of the following
 ================

 CHANGE VARIABLES  variable value must stay in the range
 ----------------  of 0 to 100 or undefined result
 ve=12  ; set variable e to 12
 vj+7   ; add 7 to variable j
 vx-2   ; subtract 2 from variable x

 CHANGE ITEM
 -----------
 i21=51 ; make item 21 a copy of item 51

 CHANGE LOCATION  only for locations 1 to 119
 ---------------
 l4=27  ; make location 4 a copy of location 27

 MOVE PLAYER  only for locations 1 to 119
 -----------
 t117 ; teleport player to location 117

 CHANGE ASSISTANT/GUARD STATUS
 -----------------------------
 a-  ; makes the assistant vanish
 a+  ; makes the assistant appear
 g-  ; de-activates guard mechanism, masks guard
 g+  ; activates guard mechanism, makes guard visible
 gk  ; kills the guard standing beside the player

 CHANGE SCORE
 ------------
 c40 ; add 40 points to the score; must be between 0 and 100

 PRINT AN EFFECT STRING
 ----------------------
 [213 ; prints effect string 213, use "~" for pause for keypress

 built-in effect strings:
 n ; print "Nothing happens"
 u ; print "I don't understand"
 h ; print "You have no <object>"   (2nd word of current command)
 s ; print "You see no <object>"

 PERFORM DEFAULT ACTION  only useful for phrase effects that
 ----------------------  intercept built-in commands
 f ; complete the normal action of the command after other
     actions (if any) were done.

 END THE GAME
 ------------
 e  ; the good game end, meaning the player has won
 b  ; a bad game end, meaning the player has lost

 MISCELLANEOUS   all these are optional embellishments to
 =============   your game

 s[
 starting text -- printed when game begun]

 e[
 good end text -- congratulate player on winning]

 b[
 bad end text -- tell player he lost/died ]

 a loyal Mr. Spock  ; (optional) description of assistant, up to
                    ; 39 characters long, printed each move
                    ; when assistant on

 g 8 10 12 There is a Klingon guard here!
              ; first # = how many guards; second # = probability
              ; of one appearing; third # = number of Effect Rec
              ; performed when one is present (except 1st time);
              ; the rest is the text to be printed when guard is
              ; present, up to 59 characters

 x 300        ; maximum points possible in game, used by "score"
              ; command