home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Media Share 9
/
MEDIASHARE_09.ISO
/
private
/
figment.zip
/
FIGMENT.DOC
< prev
next >
Wrap
Text File
|
1992-06-10
|
312KB
|
7,799 lines
Figment
The Imagination Processor
User's Guide
and
Command Reference
Revision 2.57
June, 1992
Copyright 1988-1992, Patch Panel Software
11590 Seminole Blvd.
Seminole, FL 34648
813-397-3530
All Rights Reserved.
Figment is a trademark of Patch Panel Software
Information in this document is subject to change without notice
and does not represent a commitment on the part of Patch Panel
Software. The software described in this document is furnished
as shareware. The software package, a self-extracting library,
may be re-distributed only in its entirety as the program
"Figpkg.exe". Other forms, e.g. "Figpkg.zip", are not from Patch
Panel and are not authorized for distribution.
Users are requested to register their copies. A more
comprehensive, fully typeset and perfect-bound (paperback)
version of this book is available to registered users along with
upgrades. Additional graphics and music utilities are also
available to registered customers. Consult the file "Order.frm"
for details.
Figment User's Guide Table of Contents
Table of Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . 1
A. Overview of Features . . . . . . . . . . . . . . . 1
B. How to Read This Document . . . . . . . . . . . . . 2
Part I. The Presentation Environment . . . . . . . . . . . 4
A. Getting Started . . . . . . . . . . . . . . . . . . 4
B. The Presentation Display . . . . . . . . . . . . . 5
C. The Object of the Story . . . . . . . . . . . . . . 6
D. Command Lines . . . . . . . . . . . . . . . . . . . 7
E. Synonyms . . . . . . . . . . . . . . . . . . . . . 9
F. The Actor . . . . . . . . . . . . . . . . . . . . . 9
G. Command Logs . . . . . . . . . . . . . . . . . . . 10
H. Command Reference . . . . . . . . . . . . . . . . . 12
Part II. The Story Editor . . . . . . . . . . . . . . . . . 21
A. Introduction to the Editor . . . . . . . . . . . . 21
B. Theory of Operation . . . . . . . . . . . . . . . . 21
C. How to Make an Interactive Story . . . . . . . . . 22
D. Method of Editing . . . . . . . . . . . . . . . . . 23
E. Cut, Paste, and Insert Functions . . . . . . . . . 26
F. The Top Level Editor . . . . . . . . . . . . . . . 27
G. Summary of Editing Operations . . . . . . . . . . . 29
H. Stuff Editor . . . . . . . . . . . . . . . . . . . 31
I. Scene Editor . . . . . . . . . . . . . . . . . . . 43
J. Story Maps . . . . . . . . . . . . . . . . . . . . 44
K. Story Rules (Logic Programming) . . . . . . . . . . 48
L. Editing Rule Bases . . . . . . . . . . . . . . . . 56
M. Pre-Command Rules . . . . . . . . . . . . . . . . . 67
N. Conditional Function Reference . . . . . . . . . . 70
O. Executional Function Reference . . . . . . . . . . 76
P. Player Maps . . . . . . . . . . . . . . . . . . . . 84
Q. Synonym Editing . . . . . . . . . . . . . . . . . . 85
R. Parameter Editing Screen . . . . . . . . . . . . . 86
S. Help Messages and User Type Editing . . . . . . . . 89
T. Link and Attribute Type Definitions . . . . . . . . 90
U. Profiles . . . . . . . . . . . . . . . . . . . . . 90
V. Standard Messages and Text Variables . . . . . . . 91
W. Full-Screen Text Editor . . . . . . . . . . . . . . 94
X. File Management . . . . . . . . . . . . . . . . . . 95
Y. Deleting Objects . . . . . . . . . . . . . . . . . 98
Z. Debugging Tips . . . . . . . . . . . . . . . . . . 99
Part III. Story Design . . . . . . . . . . . . . . . . . . . 101
A. Skill Level . . . . . . . . . . . . . . . . . . . . 101
B. Examine Strings . . . . . . . . . . . . . . . . . . 101
C. Health Points . . . . . . . . . . . . . . . . . . . 102
D. Strength . . . . . . . . . . . . . . . . . . . . . 102
i
Table of Contents Figment User's Guide
E. Conflicts . . . . . . . . . . . . . . . . . . . . . 103
F. Links . . . . . . . . . . . . . . . . . . . . . . . 105
G. Controlling the Random Number Generator . . . . . . 106
H. Potions and the Drink Function . . . . . . . . . . 107
I. Weighty Matters . . . . . . . . . . . . . . . . . . 108
J. Size and Containers . . . . . . . . . . . . . . . . 108
K. Waving the Flags . . . . . . . . . . . . . . . . . 109
L. Reading Scrolls . . . . . . . . . . . . . . . . . . 110
M. Strategic Weapons . . . . . . . . . . . . . . . . . 110
N. Food . . . . . . . . . . . . . . . . . . . . . . . 113
O. Characters as Containers . . . . . . . . . . . . . 113
P. Rules and Changing Scenes . . . . . . . . . . . . . 113
Q. User-definable Command Parser . . . . . . . . . . . 114
R. The Actor in Rules . . . . . . . . . . . . . . . . 117
S. The '@'-Words . . . . . . . . . . . . . . . . . . . 119
T. Help Messages . . . . . . . . . . . . . . . . . . . 120
Index . . . . . . . . . . . . . 122
ii
Figment User's Guide Introduction
Introduction
Figment is multi-media authoring system for interactive fiction.
It is a tool for manipulating text (and when purchased, graphics
and songs) under computer control either to present information
or to create an illusion. This makes it good for developing
certain types of simulators, role-playing trainers, and certainly
for entertainment. Figment has special features for modeling
character development which makes it a unique tool for character
and plot modeling as well.
You can develop stories and trade them with other Figment users.
You can also obtain a copy of "Figlet", the play-only form of
Figment. Figlet is the distribution vehicle for material you
generate with Figment. Figlet users are licensed to distribute
Figlet freely with their material to make stand-alone story
disks.
Figment is a spread-sheet/word processor/debugger for interactive
fiction. You can write, play, and debug your work all in one
package. No tedious compiling or loading is required. You can
run your work immediately. Figment brings the logic out to the
user level where you can modify it or do whatever you want with
it. The editor displays all the data structures for you to
modify.
A. Overview of Features
Briefly, Figment's many internal features are:
1. The window-managed display manages the screen efficiently
during playback. Color is supported in text and graphics
modes.
2. The Scene Description highlights changes during play in
reverse video, an excellent aid to comprehension.
3. The command parser closely models natural English and
supports series operators, multiple sentences, object
synonyms, and function synonyms.
4. The user-definable command parser supports boolean
operations on word groups. It makes possible a very
flexible command entry and opens the story to include
virtually any user statement as a legal command.
5. Function and object name synonyms.
6. Commands can be logged and played back like a player piano
with speed control or single-stepped for debugging.
7. The system senses player efficiency and can respond with
messages tailored to the user's skill.
8. Viewpoints allow you to describe situations from the point
of view of the different characters in the scene. The
player can assume the role of these characters to see the
1
Introduction Figment User's Guide
story from their perspective and to manipulate the
characters.
9. Full-screen data entry editors.
10. Text can be entered in a simple typing buffer or a full-
screen text editor as required.
11. The at-symbol (@) denotes special words to be substituted
into your text including the user's name, the Actor's name,
the scene name, the command line, etc.
12. Cut and paste operations are supported for editing most data
structures.
13. User-defined attributes let you build rich character
definitions.
14. Character profiles present a weighted decision matrix of
attributes so you can say for example "If Actor does not fit
profile of leader..."
15. User-defined object types, a useful adjunct to profiles.
16. Links between objects can have user-definable types with
positive or negative values. You can interpret the values as
meaning like/dislike, strong/weak, attraction/
repulsion...whatever you like.
17. Frame-based inference engine. The rule-base is built in
small rule-bases local to specific situations allowing good
performance. Both global and local rule-bases are
supported.
18. The Player map gives the player a memory of places and
things, and fore-knowledge of them as well. It allows
commands like "find object_name" or "go to place_name".
19. Script file output can be generated from your story. The
script can be printed on your line printer or edited in your
word processor.
20. Help message system. The author can develop and maintain
hints specific to the situation.
In addition, graphics and music can be keyed to the story for a
multi-media presentation. The graphics can be displayed in a
windowed text-with-graphics style like a WYSIWYG DTP package.
This version will play music and graphics, but they cannot be
written without the optional graphics and music library
utilities. The music requires an Adlib board for playback.
Contact Patch Panel for more information.
B. How to Read This Document
This is a much-shortened version of the manual registered users
will receive about 100 pages more material in an attractive,
typeset, perfect-bound volume.
Figment has two distinct parts: the Presentation Environment, and
the Editor. Part I of this book describes the Presentation
2
Figment User's Guide Introduction
Environment where you play the material that you have written.
Part I closes with a reference guide of all the commands used in
Playback mode.
Part II discusses the Editor. This part describes only the
mechanical process of editing the data. It deliberately
postpones discussion and theory to Part III. Part II includes a
reference guide of all the conditional and executional functions
you use to write your story rules.
Part III describes the inter-relationship of all the pieces and
illustrates constructions used to create different effects. Part
III is organized by topics and represents the programmer's notes
for every feature.
The Appendices discuss revisions and data conversion
considerations when converting stories from older revisions.
Note: Figment has an optional graphics presentation
mode, but you will find no mention of it in this
document. For information regarding any graphics
operation, consult the User's Guide for the Figment
Graphics Library Utility (Figglu) distributed with the
Figglu software. Similarly, any discussion of music-
related work is found in the corresponding book for
Emilu.
3
Presentation Environment Figment User's Guide
Part I. The Presentation Environment
When you start Figment, you enter the presentation environment.
Here you find a scenario description and you give English-like
commands that act upon the various scene elements. Your software
comes with a demo story, an accompanying log file, and a text
file called "hint.doc" for people who haven't the time to
struggle.
A. Getting Started
Stories are kept in files with ".sdf" file extension, but you do
not specify the extension. All you have to do to start the demo
story is type "Figment" followed by the path to the story data
file:
figment demo
figment b:demo ;demo on drive b
figment c:\datafiles\demo ;demo in another directory
Do this now so you can follow along with the discussion. Here
are some other starting options:
figment <newname> ;make up a name to make a new
; story.
Figment /s demo ;/s = suppress status display
Figment demo/s 10 ;10 = seed for random number
; generator
Figment demo 10 /s ;switches go anywhere
Figment demo /i ;suppress inventory display
NOTE: This is the shareware version of Figment. It is
about one fourth the capacity of the registered
version. If you attempt to read a story that is too
large, it will report "Story requires too many elements
- Terminating" and return to DOS. You will need the
registered version to read such a story.
a. Select Display Switch - /Dn
Figment automatically tests and selects the appropriate display
mode, but some clone adapters (notably non-register-compatible
EGA clones) can confuse the test giving undesirable results. The
system appears to "hang". If this symptom occurs, try specifying
the adapter manually with the display switch:
4
Figment User's Guide Presentation Environment
figment demo 10 /D3 ;3 = EGA Color
/Dn where n=
1 MDA Monochrome Display Adapter (No graphics)
2 CGA
3 EGACOLOR
4 EGAMONO
5 VGAMONO
6 VGACOLOR
7 MCGACOLOR
8 MCGAMONO
9 HERCULES
Note: Forcing a non-Hercules device to Hercules mode
might not be a good thing to do.
b. Random Number Generator
Figment supports random events. You can force the random events
to be predictable events by choosing the seed for the random
number generator as demonstrated in the example above. This is
necessary for debugging and often nice for playback.
B. The Presentation Display
Once started, you see four distinct regions (windows) on the
screen: Status Indicator Bar, Inventory, Scene Description and
Command Windows. These regions are "dynamic", meaning they
stretch and shrink as needed to accommodate changing needs.
The Status Indicator can be customized to the story requirements.
Some stories might not use it at all.
The Inventory region grows as your list of acquisitions grows.
Again, some stories might not use it. It changes when you change
viewpoint to reflect the actor's possessions. (A useful feature
since you might not know them otherwise.)
As the story progresses, elements of the Scene Description
change. The newly changed descriptions are displayed in reverse
video to emphasize them and making it easy to see the effects of
your commands. The Description Window can process multi-page
descriptions. It pauses with the message "strike any key to
continue" between pages.
The Command Window scrolls your commands and their responses.
Figment displays its ready prompt, the current actor's name, in
this case"Player:".
5
Presentation Environment Figment User's Guide
The Command Window scrolls split-screen fashion as you give
commands so that the scrolling lines do not destroy the Scene
Description. Ordinary reports to your actions are given to the
command region:
Player: go east
You can't go that way.
The Command Window can also process multi-page responses, but
note that the command dialogue is always sacrificed; it scrolls
off the top of the Command Window and is lost so be sure you have
read this message before typing any key to continue.
C. The Object of the Story
Most interactive fiction is driven by manipulating objects,
meaning you can examine them, take them, drop them, etc. They
represent "story variables".
Object names are composed of a few words, at least one of which
should be embedded in the scene description so that you have a
couple of chances of guessing right. "Oil lamp" might be
addressed in any of the following ways:
>take oil
>take the oil lamp
>take the lamp lighting the room
>take the lamp and jump in the lake
Commands begin with verbs. Verbs cannot be abbreviated:
>ta balloon
I don't understand the command: "ta".
>take balloon
You take the Red Balloon.
Object names represent arguments to the verb functions. Names
can be abbreviated:
>take ball
You take the Red Balloon.
This presumes that the string "ball" is unique within the current
scene. If there were an object called "Blue Ball" in the same
scene, you would have to be more specific.
6
Figment User's Guide Presentation Environment
D. Command Lines
Figment's command processor is very sophistocated. Many
punctuation operators are supported. Spaces before or after
these operators are optional. It is best not to use punctuation
except for cases as described here.
Figment lets you make complex commands that are broken down into
simpler commands for execution and logging. Thus the command:
Take the bat, ball and glove from the box, and give
them to the boy.
would be broken into:
take bat from box
take ball from box
take glove from box
give bat to boy
give ball to boy
give glove to boy
and dispatched for processing and logging. The resulting log
appears as though each little command were given separately.
Conversely, text files of commands can be read back into Figment
as command logs. These text files can contain the complex
commands since Figment will break them down into the simpler
forms and dispatch accordingly. (See Command Logs.)
1. Articles
Articles such as "the", "a" and "an" are stripped out. You need
not use them if you do not want to.
2. Multiple Sentences in a Command - the Period Operator
Multiple sentences can be given in a single command separated by
a period. Thus:
Take the bat. Go north. Give the bat to the boy.
The last period on a line is optional.
7
Presentation Environment Figment User's Guide
3. Series Operations - the Comma Operator
A comma between objects signifies a series of objects to be
submitted to a command for repeat processing. A series may also
use the modifier "and", and spaces are not required when the
comma separates the objects. Note that a series can be as short
as two objects:
take bat,ball
take bat and ball
take bat, ball, glove.
take bat, ball, and glove
take bat, ball and glove
take bat,ball,and glove
A series may be embedded between the verb and its modifier:
take bat,ball,glove from box
give bat,ball,glove to boy
but a series cannot be used with destinations after the modifier:
take candy. give candy to Bobby, Billy and Mary
A series cannot be used with verbs. "Take, drop and kick the
football" is illegal.
4. Pronouns
a. "it"
Substitutes the last object used. If no previous definition
for "it" exists, the message "vague pronoun reference" is
issued.
Take the book from the box and give it to the boy.
Note that this will give the book to the boy and not the box
to the boy. Note also that this carries over between
commands:
Take book.
examine ;examines scene leaves pronoun
unaffected
Give it to the boy.
This pronoun can lead to some confusion:
Take the arrows and give it to the indian.
8
Figment User's Guide Presentation Environment
Technically, this is correct since the object named "arrows"
is a single object, but the name implies a plural case
causing some people to say "them" which would substitute a
series yielding unexpected results.
b. "them"
A pronoun that is used to substitute the last series used.
Take the bat, ball, and box, and give them to
the boy.
This variable is also global between command lines and it
also returns a message, "vague series reference", when no
definition exists.
E. Synonyms
Figment supports synonyms for the command functions and for the
object names as well. This makes the story more flexible and
lets it flow smoother. The author defines the synonyms. "q" is
the synonym for "quit".
F. The Actor
The Actor is the character speaking to Figment, usually the
Player, but when you see a different character in the scene, you
can assume that role and act as that character. When you begin a
story, the command line indicates that the current Actor is the
Player by printing a ready prompt like this:
Player:
You change the Actor by typing the name of a character in the
scene followed by a colon ":". Figment responds with a new ready
prompt indicating the new character is speaking. Example:
Player: fairy: ;the player becomes the fairy...
Toothy Fairy: ;...and performs now as the fairy
This action costs no moves and triggers no story logic. You can
combine this action with the command for the actor:
Player: fairy: examine wand
Oh, darn! That tourist has it.
Toothy Fairy:
9
Presentation Environment Figment User's Guide
The Fairy remains the Actor until you decide to change back to
the player or to another character.
When you change the Actor, the Status Indicator changes to
reflect the new Actor's attributes. The Inventory also changes
to reflect the Actor's possessions. The Scene Description
changes to reflect the new Actor's viewpoint. This may change
only a portion of the description depending on how much of the
story is written from the new Actor's viewpoint.
G. Command Logs
Command Logs are like "story macros". The replay can be
automatic like a player piano or single-stepped by hitting the F9
key. Playback can halted by typing "i" for "interrupt".
Playback can then be single-stepped with the F9 key or continued.
play 5 ;play the log named same as story with 5 second
delays between commands
i ;stop playback
<f9-key> ;single-step some
<f9-key>
play continue ;proceed
Command logs are very important for designers debugging their
work, but that's not all. They are useful for generating script
files. They are 95% cheaper than save files for reproducing a
previous state and they can reproduce every state along the way
to the final one. You would need maybe a hundred save files to
do that.
Logs can be built by logging commands during play, but you will
probably goof. The best way to make command logs is to use your
word processor. That way, you can put comments on the end of any
line indicated with a prefixed ";" character. Thus a command
sequence such as:
take the ball ;the boy left it here
north ;enter the house
pause ;stop to check data in editor
put ball on table
...commands continue like this
can be written in a word processor and used as a log file.
Comments must end before the end of the line. Of course a log
file made in Figment cannot generate comments.
10
Figment User's Guide Presentation Environment
The text file from your word processor must not contain any word
processing codes such as margin settings, fonts, indents, page
breaks etc. If the resulting text file will not type cleanly
with the DOS "type" command, it will not be suitable input for
Figment.
If you do not indicate a log file name, the system will use the
last log name used. Failing that, it will use a log file with
the same name as the story. See also the Command Reference for
the "play", "log" and "step (F9)" commands.
The command verb "step" is a synonym for the F9 key and lets you
change the log file name for stepping.
step testlog1
testlog1 set for stepping.
F9
F9
...etc.
The Status line can display the log file name if desired - handy
for debugging since it is easy to forget which log file you are
using. Remove it from the status line when you ship your story
unless you ship the log file(s) too.
11
Presentation Environment Figment User's Guide
H. Command Reference
Figment recognizes its own built-in commands and special user-
defined commands. The author uses the user-defined command
processor to create a unique command for special situations such
as "Kiss the toad". We cannot discuss those commands since we do
not know what authors will develop so this section can only
discuss the built-in commands.
In the following definitions, "<>" means you insert something at
that point in the command. For example, <object> would mean that
you would supply an object's name. The symbols "[]" mean that
the part of the command is optional. You do not actually type
the characters "<>" or "[]".
Of course the author has ways of inhibiting or subverting these
commands, so you might not get the anticipated effect, but that
is the challenge of interactive fiction.
1. Charm <character>
One-shot version of the Hex command that allows you to disengage
and skip a wager.
2. Close <thing or feature>
3. Drink <thing>
4. Drop <thing>
5. Eat <thing>
Some stories do not concern themselves with food.
6. Examine [me or <object>]
The examine function often gives you essential clues, but it
costs you a move (Help does not). The different forms are:
"examine" by itself will describe the scene.
"examine me" will describe you, the player.
"examine" followed by an object name will describe the
object.
7. F1 - Enter Story Editor
Switch between Edit mode and Playback mode with F1.
12
Figment User's Guide Presentation Environment
8. F9 - Single-Step a Log File
Before you play your log file, you must re-establish the state of
the story when the logging process was started. Do this with the
"restore" or "restart" functions then hit F9. Each time you hit
F9, one command will execute.
The F9-key does not let you specify a file name so the Step
command is a command synonymn that allows you to change log
files. The F9-key will use the last log name used, if none was
used, then the log name matching the story name. (See "Step".)
You can step through a log then say:
play continue t where t = delay time in seconds
The log will then play out to the end automatically.
See also: Log, Play, and Save.
9. F10 - DOS Shell
You can leave Figment to go to the DOS command interpreter by
hitting F10. You may then do any work on your machine that you
like (word processing, spreadsheets, document printing,
communications, etc.) When you are ready to return to Figment,
simply type "exit". You will return to Figment exactly where you
left off. If you will be gone a long time, it is probably wise
to save your story before you leave. (See the command Save.)
This function expects to find the DOS command interpreter,
"COMMAND.COM" on the diskette in the default disk drive. You get
an error message and remain in Figment if COMMAND.COM is not
found.
10. Fight <character>
Fights are random processes with their outcome weighted by the
strengths of the two protagonists. You are locked into the fight
until it completes, meaning one protagonist dies (see also Hit).
The odds favor the stronger fighter, but certain objects improve
your odds by adding to your strength. Sometimes weaker
combatants win; they just get lucky.
Fighting is bad for your health. Lose most of your health, and
you lose your strength. Lose all your health, and you die. You
have some control over this process since you can wager the
number of health points you want to commit on each cycle of the
fight. This implies that you can hit heavy or hit light and
13
Presentation Environment Figment User's Guide
receive in kind. For example, if you wager 4 points, the system
computes a random transaction and apportions the results:
Wager: 4
You hit the Bear 3 times.
The Bear hits you 1 times.
This means that your opponent loses 3 health points while you
lose only 1 point. It also means that your maximum wager is the
full number of health points that you have.
You can skip a wager by entering zero or just hitting the Enter
key if you think (or know from experience - see Random Number
Generator) the random outcome will be unfavorable this turn, but
eventually you must commit to a wager. Skipping also costs a
move, but considering it can cost several moves to recuperate a
lost health point, it can be a successful strategy to skip.
Your health recovers with time after the fight. You gain
strength and sometimes skill as a result of defeating an
opponent.
A one-shot form of the fight command is provided as "Hit".
See also Hit, Charm, and Hex.
11. Find <object>
This command will locate people and things you have seen before
in prior scenes. It will change the scene to the scene where the
object is. You cannot find objects you do not know exist, and
you only know objects exist by seeing them in scenes. Sometimes
you have more knowledge than you realize so it does not hurt to
try.
This command is subject to any restrictions on path computation.
See also the "Go" command for more information on paths.
12. Give <thing> [to] <character>
The forms:
>give the book to the boy
>give book to boy
>give book boy
are all legal, but the form:
14
Figment User's Guide Presentation Environment
>give the boy the book
is not legal.
If you do not have the prescribed object in your possession, but
it can be found in the scene, Figment will automatically take the
object for you and then give it to the character. This counts as
a two step action meaning your move count is incremented twice.
The "take" action is a fully separate command, which is to say
that the Story Designer can impose conditions on that action.
See also: put, take.
13. Go <direction>
<[to] [the] scene name>
As you move in different directions, you change scenes.
Directions are given as the four points of the compass plus "up"
and "down". Thus:
>go north
>go up
Actually, "go" is optional and the directions can be abbreviated
to n, e, w, s, u, and d. So:
>n
changes to the scene to the north of the current scene as defined
by the story map.
The "go" command also recognizes the names of places (scenes)
where the player has been before. The player can say:
go to the river
go home
go to the basement
The scene you specify must be a scene you have been in before,
and you must know the directions back to the scene from the
current scene (typically by virtue of experience).
As you explore different scenes, you acquire knowledge about
where scenes are in relation to each other. When you have
reached that level of understanding about the story, it is nice
to let Figment do the work for you.
Figment will compute a path and begin moving through the scenes
along the path until the destination is reached. Each scene-
change along the way is a legal move, and it is subject to any
constraints upon the player that the player would experience if
15
Presentation Environment Figment User's Guide
the moves were made manually. If your health or your food
supplies are low, this command might exhaust you since each scene
change increments the move count.
It is conceivable that the destination is known, but the
directions needed to construct the path to it are not known.
When Figment cannot construct a path, it reports, "You don't know
the way from here." The player will have to explore some more by
giving the compass directions until more directions along the
path are known.
Some scenes function like one-way valves. They have no return to
earlier scenes. If such a scene lies along your path, the path
function fails and you stay where you are.
Each change of scene is subject to any restrictions placed on the
"go" command in each scene along the way. You may encounter a
scene along the way that restricts your leaving until you have
performed some special task. In such a case, the path terminates
at that scene. When you have completed the task, you can
continue, if you wish, by repeating your command: "go to the
river".
The Designer can give you knowledge of places and directions at
the start of the story. In which case, the path function can
succeed even if you have never been to the scene before. It's
worth a try, and it's valuable knowledge if it's true.
14. Hex <character>
"Hex" is the same as "Fight" except you compete on the basis of
magical ability. The one-shot form of Hex is Charm.
15. Hit <object>
The one-shot form of the Fight command with the advantage that
you are not locked in to a fight to the death. It is best
reserved for times when your health is low or when you are
surrounded by bad-guys and you wish to keep the option to
retreat.
16. Lock <thing or feature>
17. Open <thing or feature>
Used with containers and other objects such as doors. Locked
objects cannot be opened. Open containers describe their
contents in the Scene Description and Inventory.
16
Figment User's Guide Presentation Environment
18. Pause Command
An empty command whose sole reason to exist is to pause a log
file. Playback can be continued with the command "play
cont[inue]".
Do not confuse "pause" with "wait". See also: Play, Step (F9),
Wait.
19. Play [log_name] [cont[inue]] [delay_interval]
Plays or continues playing a log file. You will want to restore
your saved version of your story before playing back the log
file. The playback can be very rapid so you may want to hit your
"pause" key to study the responses or use the "step" command (F9)
to execute logged commands one at a time.
You can slow down the playback by specifying the delay interval
in seconds between commands: "play 5" plays the default log with
a 5 second delay between commands.
If you strike the key, "i" or "I" while Figment is playing a log,
the playback will interrupt playback immediately. The "step"
command (F9) may then be used to advance the log file or the
playback can be resumed with the "continue" option.
The option "cont" continues the log playback after it has been
interrupted or paused. Of course, it also works after stepping a
log file any number of moves with F9. The form of the command
is:
>play cont
You can specify log file names in the play command. This means
you can play or step to a pre-determined point then switch to a
different log.
20. Put <thing> [in or on] <thing or feature>
>put the ball in the box
>put the book on the table
The author can inhibit foolish placements:
>put the book on the flagpole
You can't put that there.
If you do not have the prescribed object in your possession, but
it can be found in the scene, Figment will automatically take the
17
Presentation Environment Figment User's Guide
object for you and put it in or on the object. This two-step
action is treated as a fully separate command, which is to say
that the author can impose conditions on the "take" action and
your move count increments twice.
21. Quit
Ends your Figment session and returns you to DOS. Consider
saving your session to disk first. This is the only legal way
out of Figment (Ctrl-C works, but it isn't legal). Even when
editing, you return to the Presentation Environment side and exit
with "quit". Quit shuts down music and switches off graphics
mode when those features are used. Ctrl-C does not.
22. Read [<Object>]
If the appropriate story conditions do not hold true, this
function just prints gibberish.
23. Restart [<Story Name>]
Restarts the current story (or one you specify) at the beginning.
You cannot restart a story that you saved with the "save"
command. Use "restore" for that. See the section on File
Management for more information on ".sdf" and save files.
24. Restore [<Story Name>]
Reloads a file made with the "save" command (See below). If you
do not specify a name it assumes you want to restore the story
you are playing (which might not have saved form). Restore
differs from restart. The state of the story returns to the
state at the time the story was saved.
25. Save [<Story Name>]
This function saves the story in its current state in a file on
the disk with the specified name. Do not specify a file
extension. A save file is reloaded with "restore". "Save" never
over-writes the original story conditions; their in separate
files. If you specify a name, Figment changes the current story
name to that name. Figment keeps the last save file as a backup
renamed to a ".bak" extension.
In order to use a ".bak" file, you must rename it to a ".sav" or
".sdf" file. You do this with the DOS command "rename". Again,
exit with F10, make the changes, return and use "restore" or
"restart".
See also Top Level Editor, File Management, Restore, Restart.
18
Figment User's Guide Presentation Environment
26. Script [on or off]
The Script command will output the story text, commands and
responses to a listing file as it is played. The resulting text
file can be read into your word processor. If you want to print
it, print from your word processor. It will need line-breaks and
your word processor does that for you automatically. The listing
is contained in a file with the name of the story and a ".lst"
file extension. The listing could be over-written so if you want
to guard against that, jump out of Figment with F10 and rename
the file to some other extension.
Note the forms:
Player: script on ;opens file, starts scripting mode
Player: script off ;turns off scripting, closes file
Player: script ;toggles on to off and vice versa
;does not open/close file
While scripting is enabled, Figment prints "Scripting" in reverse
video at the right of the command line.
It is probably best to play a log file with scripting enabled,
but you can also use it when you are giving commands manually.
You can toggle scripting on and off by saying "script" with no
on/off modifiers. This lets you turn off scripting while you
experiment then reenable scripting and proceed.
27. Shoot <object> [with <weapon>]
The shoot function requires great skill. The life expectancy of
novices shooting weapons is extremely short, but don't take our
word for it. Only certain weapons qualify as weapons that can be
shot. You would not shoot a sword for instance. This function
gives you an alternative to fighting on the basis of magic or
strength. If you have more than one suitable weapon, you must
specify which one to use.
28. Step <log_name>
Used to change the log file when single-stepping through the
story. Normally, single-stepping is done with the F9 key, but
that does not allow a file name.
29. Take <thing> [from <object>]
You can take a thing from the scene or, optionally, from a
character or feature in the scene. You get an error message if
19
Presentation Environment Figment User's Guide
you attempt to take the character or feature itself or if you
simply mis-type.
>take the amulet
You take the Amulet of Zendor.
>take the keg from the Saint Bernard
You take the Wooden Keg.
>take the Saint Bernard
You can't take the Saint Bernard.
>take the #$%^#
You can't take the #$%^#.
30. Toggle
Changes the Scene Description from the long-hand description to
the short-hand description. Whenever you return to a scene you
have been in before, you get a short-hand description. This will
change the display mode back to the long-hand description. Many
authors do not provide brief descriptions, in which case, Toggle
does nothing.
31. Unlock <thing or feature>
Many things must be unlocked before they can be opened. In many
cases, finding the "keys" that do this is the central theme of
the story.
32. Wait [number]
Skill suffers by waiting, but health can recuperate. If you
specify a number, Figment will wait that number of moves. Any
events that would normally transpire on those moves will still
take place even though waiting is in itself an empty command.
20
Figment User's Guide The Story Editor
Part II. The Story Editor
Part II discusses the mechanics of editing. Use it as your
editing reference when you want to know how to change something.
The "what and why" of editing is discussed in Part III once you
understand the mechanics.
A. Introduction to the Editor
The Editor is comprised of several data-entry editors to change
story elements, including the story logic, with a few simple
keystrokes. You can enter the editor at any time before or
during play to fix a bug. Similarly when developing material in
the editor, you can switch to playback mode and see immediately
how it plays.
You will understand the editor much better if you have a working
example in front of you. Call up the demo shipped with your
software and follow along with the discussion trying each topic.
You cannot damage the original data so experiment at every stage
of the discussion. Hit the F1 key to flip back and forth between
the story and the editor. Try it now.
When you first enter the editor, your cursor is at the top row of
the screen which is called the Top Level Editor. Hitting the
up/down-arrow keys flips through the different editors. Keep
flipping and you come back to where you started. Hit page-
up/down to enter/exit a screen editor. Try it now.
Some of the data structures you want to see are hidden from view
until you need them, for example links in the object data
editors. Use Page-down to get to lower levels and the
left/right-arrow keys to move across the level. The data appears
when you put the cursor on the word "Links".
Now that you can see the different data structures, we will talk
about how Figment works and how to make a story.
B. Theory of Operation
With Figment, you create objects and scenes. The objects
represent characters, props, and features in the scene. The
scenes (which are also a type of object) represent places where
the objects reside. You associate the objects to their scenes by
making a link from the scene to the object.
Scenes are tied together by the Story Map. With the map done,
you can use the "go" command in Presentation Mode much like
21
The Story Editor Figment User's Guide
walking through the rooms on a house tour. Without a map, you
are stuck forever in the first scene.
You write rules to govern the object behavior. The collection of
all rules is called the story logic. Without the logic, the
story is lifeless; the player can manipulate the objects, but
nothing exciting happens.
The text used in the story is stored in a variety of data
structures. The initial text to describe an object is part of
the object's data structure. It appears automatically when the
object appears in (is linked into) the scene. Rules store text
to dispense in response to actions or to replace the object
descriptions. "Standard Messages" are snippets of frequently
used text that can be used as "text-variables" in other text
messages. For example, the description, "The door is open." can
contain a reference to a standard message consisting of only the
word "open" which can be changed when the Player closes the door.
C. How to Make an Interactive Story
From the above, you should recognize a simple procedure for
creating a story:
Create scene objects and "stuff" objects
Write initial object descriptions.
Link stuff objects to scene objects
Create map to relate scenes one to another
Create logic
Of course you need not create all your objects before you create
scenes, etc. You just need a few to get going. You can add more
later. There is no hard, fixed order of development. Work on
what pleases you now.
The map gives your story structure so the first few sessions are
aimed at building up the map so you can take the house tour.
Logic development is the hardest so postpone it as long as
possible. Try to sketch out your story with scenes and objects.
It is easy to develop "Paralysis by Analysis" so do not get too
deep into logic development too soon. You can easily add scenes
later, but overhauling your map destroys your existing logic so
do not attempt much logic until your map gels.
Many secondary data structures are used to embellish the story:
object types, link types, attributes, and profiles. You add
these as you need them to make the rules so do not concern
yourself with these too early in the project. The Player Map is
22
Figment User's Guide The Story Editor
made for you automatically during play, but you can fill it in if
you want to give the player foreknowledge of places and things -
another embellishment. Make Help messages last after other
people have played your story.
USE COMMAND LOGS! Make one very early in the project, and use it
to drive your development efforts. You can deliberately add
commands that you know will fail. Why? Because a log can
represent future work - a story outline. The log fails in the
early going, but as you develop more data and rules you progress
further and further until finally you can complete the entire
log. You then go back and make a harder outline or a different
outline and repeat the process. Also learn to insert "Pause"
commands at points where you know the log will fail, then you can
experiment manually. And since you need to use logs so much, you
will probably want to fix the random number generator so get used
to starting Figment from DOS with the command form:
figment <story_name> <seed_number>
The first log you write is probably only the commands required to
navigate through the scenes to the final scene of your story.
Gradually you add activities within the scenes developing the
rules for them. Single-step through your log and take notes of
things you want to change. Change the logic as required to make
the log work.
Recognize that what you are making is really a model. Although
the model can improve, it can never really be finished since you
can always add more conditions by expanding the log file or
writing a completely different one. But eventually, the model
becomes sufficiently large to encompass a large number of
situations and demands placed on it. At that point, you probably
deem the work "complete enough".
D. Method of Editing
The method of editing could be described as a "Poor-man's Mouse"
interface since you will be navigating across the screen with the
cursor control keys and in many cases changing values with them.
Figment is remarkably fault tolerant. The two most notable areas
where it is not are the areas of file management and deleting
objects. In both cases, Figment is obliged to assume that you
want the command performed and so performs it. It is your
responsibility to understand the full ramifications of these
commands. To that end, special sections on these topics are
provided late in the editing discussion when you have a better
23
The Story Editor Figment User's Guide
understanding of the editing operations. Until you reach that
point, we recommend that you do not do these operations.
1. Scrolling Values
Except where text is specifically required, you merely position
the cursor over the data value you want to change, then hold down
the up-/down-arrow cursor keys until you reach the value you
want. Release the key, and the new value is set. We call this
process "scrolling the data value". Most data values are set
this way so you will hear the term many times in this document.
Usually different data types are displayed in different locations
so when scrolling values, there is never any confusion about what
is being changed. In the case of expression editing within
rules, different data types can be used in the same location.
When this occurs, we use the "Home" key to change the data type
then we use the up-/down-arrow keys to scroll the data value.
Pay particular attention whenever we discuss the Home key,
because it is not obvious from looking at the screen that the
Home key can be used.
2. Navigating the Screen
In order to scroll a data value, you must put the cursor at the
value's screen position. There are two pairs of keys that will
do that. The left-/right-arrow keys move the cursor within the
current editing level. We call this "advancing the cursor". The
Page-up/Page-Down keys change the current editing level. Often,
you must step down through several mini-levels. The Escape key
is used as a super-exit key when you want to leave these levels
and move on to another task.
3. Text Editing
Text can be changed in two ways: use the typing buffer to type in
new text to replace the old text, or use Figment's full-screen
text editor. The typing buffer is the easiest way when the text
is small such as object names. Your editing capability is
limited to the backspace key for correcting typos however.
Often, you begin to write a little message and end up writing a
monster several sentences long riddled with corrections you would
like to make. No problem. Just hit F6 and the text is swept
into the full-screen editor.
The full-screen text editor pulls the text into a buffer where
you can use common word processing commands to move around in the
24
Figment User's Guide The Story Editor
buffer and change the text. This is the preferred text editing
method for the longer messages you want to write. More on that
later.
Any text item can be up to 2 KBytes long, including names, which
is about a full screen completely covered with text. Considering
that scene descriptions and command responses are composed of
several text items, you can compose screenfuls of text if you
desire. Bear in mind that this costs computer memory, but you
should find that your imagination is taxed before the system is.
A text item can be "erased" (set to length zero) simply by
striking the key labeled "Enter" (or "Return" on some keyboards)
instead of typing text when the cursor is positioned over the
text item. In fact, it is so easy to do this we caution you to
stay away from the Enter key until you are sure you want it.
Text strings that you write are passed around during play and may
be used in several different places. Often they are grouped
together to form paragraphs and they are added and removed from
that paragraph as the play progresses. Figment runs the
paragraph through a low-budget pretty-printer which breaks the
lines at word boundaries. Therefore, if you attempt to force
some artificial format on the text within the editor, it can
often look wrong at run-time.
Similarly, hyphenating produces unexpected results at run-time.
Unless the word is actually a hyphenated word, it is best not to
insert additional hyphens.
Ignore end-of-line restrictions and simply type blindly away.
When the cursor reaches the end of the line, it simply wraps to a
new line and keeps on going. This produces lines with words that
wrap in the middle, but as we said, Figment cleans this up at
run-time.
When using the typing buffer, you can write many lines. When you
get to the end of the line, keep going. Don't hit Enter until
you are through and want to submit the text. Yes, it looks like
you are writing all over creation, but keep going. No harm done.
When you are finished, hit Enter, and jump up to the Top Level
Editor for a moment, and the screen fixes itself.
In the full-screen editor, you can always use hard-returns if you
want them, and you need them for paragraph breaks, but you must
use the full screen editor to enter them, because they terminate
the typing buffer.
25
The Story Editor Figment User's Guide
4. Error Message Reports
Most errors are simple mis-steps and only merit a beep. Larger
errors report to the second line of the screen. The message
remains until you hit another key so just go on about your
business and the message disappears.
E. Cut, Paste, and Insert Functions
Cut and paste operations have been implemented for some data
structures, but not all. We discuss the general nature here and
cover details on a case-by-case basis for each data structure.
These functions are context-sensitive, meaning you get the
correct cut-paste operation for the item on which the screen
cursor is positioned.
1. Insert
The "insert" function is designed to open a gap in a list of data
elements and leave you a new data item for editing. It is used
wherever the order of items is important. Currently, it is
implemented for rule bases, expressions and rule messages. You
insert a new data item into a list or sequence by hitting the
Insert key when the cursor is positioned over the item where you
want the new item inserted.
2. Cut - F7
The cut function (F7 key) parks a data structure in a buffer
temporarily for pasting to a new location in a list or sequence.
It is implemented for text strings of all kinds, rules, and
expressions.
Different cut buffers are used for each data type. Cutting one
data type will not overwrite any different data type parked in
its cut buffer. It does, however, overwrite the existing
contents of the buffer when you repeatedly cut the same data
type.
Text strings can be cut anywhere they are used in objects or
rules. They can then be pasted back in new places. This means
that you can cut description strings out of objects and paste
them back as rule messages and vice versa.
The F7 key will cut a text item whenever the screen cursor is
positioned at the start of the text. You cannot take half a
26
Figment User's Guide The Story Editor
string. Cut the whole string, paste a copy back and edit the two
strings separately.
The cut buffers are not written to disk so they do not carry over
between sessions, but they are unaffected by play or file
read/write operations.
3. Paste - Alt-F7, Shift-F7
The paste function pastes a copy of the appropriate cut buffer to
the new location as indicated by the screen cursor. If the cut
buffer is empty, meaning you forgot to cut something, the paste
function just beeps.
When you paste a text string in an object (description or
examination message), the old string at the cursor location is
deleted and replaced with a copy of the string in the cut buffer.
You can move to another location and paste another copy of the
same string. For object text strings, the Shift-F7 and Alt-F7
keys are synonymous. You can use either key.
Sequences behave slightly differently. When you paste something
in a list or sequence, the existing items are bumped back in the
sequence, and the item in the cut buffer is inserted in the
sequence. Repeated pastes make multiple copies. Rules in rule
bases, expressions in clauses and rule message lists are all
examples of items in sequences or lists.
The two different paste keys, Shift-F7 and Alt-F7, are provided
so that you can insert items in the sequence differently. Shift-
F7 inserts the item into the sequence after the item your cursor
is pointing to. Thus if your cursor points to item number 7, the
newly pasted item becomes item number 8 and the cursor advances
to point to it. Alt-F7 inserts the new item before the item your
cursor is pointing to. Thus, item 7 becomes item 8 and the newly
pasted item becomes item 7 to which your cursor is still
pointing.
Alt-F7 appears most like the traditional paste operation used in
word processors so it will seem most natural to you. Shift-F7 is
used most for tacking items onto the ends of lists and sequences,
a frequent task.
F. The Top Level Editor
The highest level in the editing hierarchy is the Top Level
Editor. It calls the different screen editors for the different
27
The Story Editor Figment User's Guide
Story Elements. You also read and write many data files from the
Top Level Editor.
You enter the Top Level Editor from the Presentation Environment
by hitting the F1 key. This puts the first screen editor on the
screen, the Stuff Editor. The Top Level Editor is always
displayed as the top line in any other screen editor (except the
text editor).
The editor will warn you when you attempt to edit data or write
data to disk that has been changed during play:
Warning! Data changed during play. Proceed? (Y/N)
You have the choice of proceeding (which you must do when you are
debugging a story and want to know what went wrong) or retrieving
the data from disk (Use Shift-F2. See File Management). You
will only be warned once; if you proceed to edit the altered data
you will not be warned if you write it to disk. If you are
debugging, be sure to retrieve your original data after learning
the fault and before making changes.
You return to the Presentation Environment via the Page-Up key
from the Top Level Editor or by hitting F1 from anywhere in the
editor. Try moving in and out of the Editor hitting F1 and Page-
Up:
F1 to enter Story Editor from Presentation Mode
F1 or Page-Up to exit Editor to Presentation Mode
The different screen editors form the next level down from the
Top Level Editor. You can view these different editors with the
Up-/Down-Arrow keys when the cursor is positioned by the element
name, which it is when you enter the Top Level Editor from the
Presentation Environment. Each time you hit the key, the next
screen editor is displayed.
Note that as you keep hitting the Up-arrow key you come back
around to the first screen and that the Down-arrow moves through
the list of screens in the opposite direction. This philosophy
is common throughout the Story Editor; every key has its opposite
number and lists are scrolled through to the end whereupon they
"wrap" back around and start over. For long lists, it is often
easier to go backwards one step from the beginning to reach the
end.
The Top Level Editor also controls file input/output, but we will
postpone that discussion until later. Just note here that you
move over to change the filename with the Left-/Right-arrow keys.
As with the Up-/Down-arrow keys you get the cursor-wrap and
28
Figment User's Guide The Story Editor
forward-reverse effects. F2 and F3 will read and write files
respectively anytime your cursor is anywhere on the top line so
don't hit them until you want to modify files.
You can leave Figment and return to DOS temporarily by hitting
F10 when in the Top Level Editor only. This does not terminate
Figment. It leaves it sleeping in memory until you return with
the DOS command "exit". This lets you change filenames or disks
before doing file I/O operations. F10 is enabled anytime your
cursor is anywhere on the top line of the editor screen.
As mentioned in the Command Reference, F10 requires the file
"COMMAND.COM" to be on the diskette in the default drive.
So far, we have viewed different screen editors, but we have not
entered them. Do that with Page-Down. Page-Down means "Enter
lower-level editor". Correspondingly, Page-Up means "Exit to
higher level editor". Change to the screen editor titled "Stuff"
using the Up-arrow key, then hit Page-Down. Your screen cursor
jumps down to the next level which displays all the "Stuff" that
have been defined for the story.
G. Summary of Editing Operations
At this point, we have demonstrated much of the major editing
features so a brief summary is in order before we continue.
Figment assigns its editing functions to special keys so they are
executed with single keystrokes. The key assignments are as
follows:
Summary of Editor Key Assignments
Up-/Down-Arrow means change the value of the item on
which the cursor is sitting. We call this process
scrolling the value. We deliberately use the word
"scroll" in the remainder of this document to mean
these arrow keys.
Right-/Left-Arrow means advance to the next item on a
given editing level. We deliberately use the word
"advance" in the remainder of this document to mean
these arrow keys.
Page-Up/Page-Down means change to the next level of
editing operations. Hit Page-Up enough times and you
find yourself back in the Presentation Environment.
29
The Story Editor Figment User's Guide
ESC - Escape is a super-page-up key. Probably
preferred to Page-up since it cannot over-shoot the Top
Level Editor. It is a rapid exit from deep levels.
F1 enters the Editor from the Presentation Environment.
It also is a rapid exit from any level in the editor to
the story. Repeated strikes on F1 toggles back and
forth between the editor and the story.
F2 reads the file whose name is given on the top line
of the screen. F2 only works in the Top Level Editor.
F3 writes to the file whose name is given on the top
line of the screen. F3 only works in the Top Level
Editor.
Shift-F2 reads the saved data file, the ".sav" file.
Similar to "restore" in the Presentation Environment.
It works only in the Top Level Editor.
Shift-F3 writes a save file, the ".sav" file. Similar
to "save" in the Presentation Environment, but there is
an important difference - it sets the data to starting
conditions so the ".sav" file can be renamed a ".sdf"
file. Top Level only.
F4 generates a listing file of the currently displayed
object type or rule base. F4 is only enabled in the
Top Level Editor.
Shift-F4 generates a full listing file of all the
objects or all the rule bases in the database. Shift-
F4 is enabled in the Top Level Editor.
F5 alphabetizes the stuff or scene objects depending on
which screen you are viewing. Implemented at the
object name level only (not the Top Level).
F6 invokes the full-screen text editor. ESC exits this
editor and returns to the Story Editor. Enabled
whenever the cursor is positioned over a text item.
F7 - Cuts a text string, rule or expression.
Shift-F7 - Paste, the opposite of F7. In a sequence,
it pastes after the current item.
Alt-F7 - Paste also. In a sequence, pastes before the
current item.
30
Figment User's Guide The Story Editor
Insert - Inserts (opens) a gap in a list or sequence.
F10 exits Figment temporarily to DOS. "Exit" returns
you to Figment. F10 only works in the Top Level
Editor.
"+" creates new things: objects, links, rules,
expressions, etc.
"Delete" deletes things created with "+".
"Home" used mainly in expression editing to change data
types for scrolling values. Also negates conditional
functions.
If you attempt to think of these keys as cursor movement keys,
you will have a very hard time in the editor. The cursor has a
mind of its own and moves where it must to point to your position
in the editing hierarchy. In short, if you're trying to follow
the cursor, you're in trouble, because it's following you!
In practice, we break this convention in only a few places: in
the full-screen text editor, the keys are used as they are in
most word-processors, for example Page-Up moves to the top of the
page; in the object editors we move through a matrix of names up,
down, left and right with the arrow keys since it seems more like
a full-screen text editing operation; and in label editing, we
allow the up/down arrow keys to move up and down a list of names
since scrolling is not used there.
Once you make this conceptual leap, you should find that a great
many editing operations resolve to only three key-pairs.
Play alters the data so you must write your editing changes to
disk before starting play or they will be lost. A rigorous
editing procedure would dictate that you should enter the editor,
examine data structures to identify a problem, retrieve the save
file from disk, make the changes, put the data back on the disk,
return to the Presentation Environment, and play through to see
if the correction was valid.
H. Stuff Editor
Objects come in two types: Scenes and Stuff. "Stuff" are best
defined as objects that are not scenes. Stuff comes in three
types: "Things", "Features" and "Characters". Stuff and Scenes
are identical data structures except that they are stored in
different places. If you learn how to edit Stuff, then you know
how to edit Scenes.
31
The Story Editor Figment User's Guide
Objects are large and only a portion of the data can be displayed
at a time. If you want to study all the object data, you can
dump it to a listing file by hitting the F4 key when in the Top
Level Editor. This will dump all the stuff objects or scene
objects depending on which type is displayed when you hit the
key. The data is written to a file with the same name as your
story but with a ".lst" extension. You can print this on your
lineprinter with the DOS "print" command. Use F10 to invoke a
DOS shell so you can type or print this file.
You enter the Stuff Editor from the Top Level Editor by
displaying the screen labeled "Stuff" using the Up-Arrow key.
You move down one level from the Top Level Editor to the Stuff
Editor using the Page-Down key. You exit the Stuff Editor by
moving up one level to the Top Level Editor with the Page-Up key.
1. Stuff Names
When you enter the Stuff Editor, you see the names of all the
stuff that have been defined for the story. Your cursor lands on
the first name which is lit in reverse-video. The names are
displayed in a row-column matrix.
Hit the right-arrow key and hold it down. The cursor and
reverse-video box advances sequentially to each object name. The
matrix of names can be large, so we break convention and use the
up-/down-arrow keys to move up and down rows within the matrix.
You can change any object name by typing a new name in its place
when the cursor sits on that object's name. Names are text which
means you can make them up to 2 KBytes long if you like. We
display only the first 15 characters. When you hit return, the
new name is entered in place of the old name. It is bad practice
to leave object names blank although it is harmless. As with all
text items, you can also hit F6 and use the Full Screen Text
Editor, but names are short so typing is easier.
Anytime you change an object name, that change is immediately
reflected throughout the story. You never have to go around the
editor changing each occurrence of the name wherever it is used.
You can duplicate names, but it is bad practice. Also names that
only partially duplicate existing names can cause some confusion
for inexperienced players. If you have two objects, one named
"Red Ball" and the other named "Blue Ball" and the player says
"Take ball.", the system responds with the first ball found, red
or blue.
32
Figment User's Guide The Story Editor
Avoid punctuation in names. Names like "Mr. Johnson" should
omit the period since that will be mistaken for a sentence
terminator. Upper/Lower-case does not matter; use what you like.
2. Creating and Deleting Objects
If you want to create new objects, hit the "+" key any time your
cursor is in the matrix of object names. The new object is added
to the end of the matrix and labeled "(Undefined)". There is no
special order required of objects. They can be created at any
time. You just make them when you need them. You can make
several at one time and fill them in later. Any object named
"(Undefined)" will not be written to disk (See the discussion on
File Management later in this document) so it will eventually
disappear with any subsequent file write/read operation if you do
not use it. Thus new objects should be given at least a working
title if you want to keep them around.
When the object list exceeds the space available to display the
names, the list can be scrolled. Simply move the cursor down any
column of names in the matrix of names. When you reach the
bottom row, the matrix begins scrolling row by row until you
reach the end.
If you create more objects than can be displayed, you may think
that nothing is happening, but scroll the name matrix and you
will find them at the end of the list. When you can create no
more objects, Figment beeps as you strike the "+" key.
Deleting objects is slightly harder. Advance the cursor until it
is over the object you want to delete and hit the "Delete" key.
This is easy enough, but it has created some problems for you.
Objects are the fundamental building blocks for the stories.
Many story elements refer to them. Now that you have deleted the
object, these other elements have nothing to refer to. Figment
inserts a dummy reference temporarily until you can change the
reference. You will have to work through the editor and change
or eliminate these references. You will see them marked
"(Deleted)" in object link lists, rule bases, and maps.
A full discussion of deleting objects is deferred until after you
have an understanding of the full editing process and the
aforementioned object references. For now, we recommend that you
consider re-naming an object instead of deleting it. All of the
references in other story elements will then reflect the new
name.
33
The Story Editor Figment User's Guide
3. Alphabetizing Objects
It is convenient to arrange the names in alphabetic order. You
can do that simply by hitting the F5 key when the cursor is in
the name matrix. You can do this anytime you add a new object or
change an object name.
You have done all that you can do at this level. You can move
down a level and change the object's data with Page-Down or you
can return to the Top Level Editor with Page-Up. When you move
down a level, the object's name remains lit in reverse-video to
remind you which object you are editing.
4. Player Object
The first object in the Stuff List is the Player Object. You
cannot delete this object. The name of this object is changed to
reflect the player's name given in the entry dialogue when
Figment is started. (See "Getting Started".) You are free to
edit this object, but its type remains "Player" and cannot be
changed. Neither can you alphabetize this object. Regardless of
the player's name, this object never moves from the first
position.
5. Object Data Selection
Page Down from the Name Level and you can choose the data you
want to edit. See the line labeled:
"System Attributes Text User Attributes Links"
Your cursor lands on "System Attributes", and they are displayed.
As you move the cursor left or right, the various data types are
displayed in turn. If you Page-up from this level you return to
the name level, and the data type you selected is displayed for
each object as you cycle through the objects.
Stop at the data type you want to edit and hit Page Down to enter
that level.
a. System Attributes
This presents the attributes and flags required for the built-in
functions. It also includes the user-defined object types. Your
cursor lands on the attributes. Advance the cursor to the flags
34
Figment User's Guide The Story Editor
or the object types if you want to select them. Hit page down to
enter the level of your choice.
(1) Attribute Editing
Each attribute is used by a particular built-in function so
attributes control how objects are used. Except for the Type
attribute, you need not worry about any other attributes until
you use functions in the story that need them. You can also use
the attributes in rules that you write:
If {
Player is linked to Obj Sub-Typ Money
}...
This would mean, "does the Player have anything valuable?"
Changing the object's Type attribute from "Thing" to "Feature"
means that people cannot pick it up and carry it to another
scene, for example an object called "Weather" is a feature of a
scene. As mentioned earlier, the object type will not change on
the Player Object.
The sub-type is used mainly with objects of type "Thing".
Objects of sub-type Armor or Weapon are used in fighting.
Objects of sub-type container report their contents when they are
open, meaning when their "Open" flag is set to read "OPEN".
"Food" means the object can be eaten. "Strategic" means it is a
weapon that functions at a distance; it can be shot. Potions can
be drunk. Scrolls can be read. "Goody" is a catch-all. If you
do not know what something is, call it a goody. "Money" means
the object has monetary value. Leave the sub-type alone until
some function requires you change it. See Part III.
Strength, health, magic, size, and weight are numeric values,
scroll them up or down as desired. They range from -127 to 0 to
127. Note that they can be set to negative values only for
objects of type "Thing", but read the discussion on them in Part
III before using negative attributes. You will probably want to
specify a health value for any character you create since this is
important for conflicts.
Note as well the way that numeric values change when they reach
very high or very negative quantities. By the nature of binary
math, a signed 8 bit integer becomes -128 when you increment past
+127.
The limit attribute specifies the maximum number of links you can
make to other objects. It is used, for example, to tell when the
35
The Story Editor Figment User's Guide
player cannot take any more things or when you cannot put any
more things in containers. This numeric quantity varies from 0
to 32, the maximum links allowed. It is probably best to leave
it at 16 until you know you want more or less. The editor will
not let you set this value lower than the existing number of
links for the object.
Some objects would never have objects linked to them, for example
objects of sub-type food. This means the limit attribute can be
used to mean something else. In the case of food, the limit
attribute means the food value. See the discussion on food in
Part III of this document. Similarly, the limit means the number
of shots available for strategic weapons. Again, you are
referred to Part III for more detail.
To edit attribute data, advance through the attributes until you
arrive at the one you want to change. Hold the Up- or Down-
Arrow key down and the values will scroll. Release the key when
you reach the value you want. Exit this level with Page-Up
regardless of your cursor position.
(2) Flag Editing
Flags are special (one-bit) attributes used to indicate the state
of the object or permission to modify that state. The flags are
changed both by functions in the rule bases and by the player's
commands during play.
The flags are edited in the same manner as the attributes so we
need not repeat those instructions. A flag only has two states
that depend on the type of the flag: ON or OFF, TRUE or FALSE,
YES or NO, etc. You see these displayed on the Flags line.
Flags are grouped in pairs. The first flag in the pair is the
permission flag for the pair. It indicates whether or not the
player should be allowed to modify the second flag in the pair.
Permission flags are set to read "YES", meaning permission
granted (the player is allowed to modify), or "NO" meaning
permission denied. Whenever permission is denied and the player
attempts to modify a flag during play, the message "You are not
allowed." is returned.
The Lock-permission flag disables the story commands "lock" and
"unlock". You typically want to leave them disabled except for
specific objects you want players to unlock.
The Lock flag controls the story commands "open" and "close".
Objects can be locked open or locked closed. Locked objects
36
Figment User's Guide The Story Editor
return the message, "You can't. It's locked." if you attempt to
open or close them during play.
The Open-permission flag also controls the open and close
functions during play. Typically it is used so the Designer can
control the Open flag via rules.
In addition to reserving the flags for exclusive use, the
permission flags prevent the player from making silly
constructions such as opening a character.
The Put-permission flag is used to indicate if the player can put
an object ON this object. The Put function also has a form, Put-
in, that is used with containers. That form also checks the
permission flag.
The Put flag itself is used to indicate if there is an object on
this object. Some objects are ambiguous and can take objects
placed in them or on them, e.g. a chest of drawers. This flag
resolves the ambiguity later when you attempt to describe the
object.
Further discussion of flags is deferred to Part III.
(3) User-Defined Object Types
The System Type attribute tells you an object is a "Thing", but
is it an automobile or an airplane? A Louis XIV table? User-
defined Object Types let you add more descriptive labels to
objects. They are a more advanced topic, however, and beginners
need not be concerned about them.
User types are labels that you create separately. They have
their own editor to define the labels as part of the Parameter
Editing Screen (see Parameter Editing). All you do here is
scroll through the list of labels that you defined on the
Parameter Editing Screen.
You might for example set the object type to character, the sub-
type to container (so the system will report the object's
possessions) and add the user type label "Waiter". Then you
could tell if there is a waiter in the room with a menu or
perhaps your dinner.
Editing the object's type labels is easy. From the System
Attribute level, advance the cursor to the title "User Types".
Hit Page Down. Hit the "+" key to add new type labels. Scroll
up or down to change the label. Hit "Delete" to remove an
37
The Story Editor Figment User's Guide
unwanted label. Advance through the labels with the Left- and
Right-Arrows. "Escape" or Page-Up exits this level.
The order of the labels is not important. An object either has a
label or not. The various functions merely test for the label.
You will notice that the system will not let you duplicate
labels.
You have conditional and executional functions to test and modify
the user type attribute in your rules.
(4) User-Defined Flags with Probabilities
User-defined Flags are 1-bit attributes you can use to signify
something has happened or should happen. Flags have only two
states: TRUE and FALSE. The flags are intended for use in your
story logic. Rules can test and change these flags to signal
changing events. This is an advanced topic so we will discuss it
later.
b. Text
Figment pulls the text from the object and uses it to build scene
descriptions or examination reports. The text that you write
here merely represents the initial conditions for the objects.
The rules that you write can replace these descriptions with
different ones. That is how the story changes with the Player's
actions.
Descriptions come in two forms: Long and Short. This is just for
variety, and it can be a handicap during development trying to
maintain both descriptions so you might want to focus on one and
ignore the other. Usually this means you ignore the brief
description since the long description is the default mode. A
switch is provided in the Parameter editing screen to switch off
brief mode processing. Normally, this switch is OFF until you
want to add brief mode text to your story.
If you do not write a description of the object, it will be
invisible during play. This is legitimate, and often, too many
object descriptions make the resulting composite scene
description too clumsy so you blank some out. When making a new
object, you usually write something trivial like, "Here is the
x...", so you can see that you successfully linked the object
into the story. Later, you change the text to say something more
appropriate to the story.
The examination message is reported to the command window during
playback whenever the player examines an object. It is optional
so you can ignore it until you need it.
38
Figment User's Guide The Story Editor
We described how to edit text earlier, but remember that they
cannot exceed 2048 characters in length, and they can be edited
by typing over them and/or by hitting F6 to invoke the full
screen text editor.
You have by now perhaps noticed that long text is displayed as a
single line followed by "(...More)" implying that there is a
longer text string than is actually displayed. If you want to
view the full string, hit F6. This puts you in the Full Screen
Editor. It is assumed that you want to be here anyway if the
text is longer than a single line. Hit "ESC" to exit the editor.
Figment is unique because it can change the story depending on
who is speaking. The Player can see another character in the
scene and change to that character and see the story through that
character's eyes. We call that process "Changing the Actor".
Figment does that with Viewpoints.
(1) Viewpoints
A viewpoint is a set of description and examination messages
written from the perspective of a character in the scene. We
will call them simply views for short. If you purchase the
optional graphics and music packages, you can assign images and
music to the viewpoints as well.
Any object can have up to four views, but it always has at least
one, the default view a.k.a. the "Player's Viewpoint". As
Figment builds the Scene Description during playback, it searches
the scene and each object in the scene for views that match the
current Actor. If no view for the Actor is found for the object,
it uses the text in the Player view for that object.
You label each view for an object (Except the first, it's fixed
to "Player".) as being the viewpoint of some character. Of
course if you do not have three characters defined (beyond the
Player), you cannot have the four total views.
Figment will not let you duplicate viewpoints. When you add a
new view, Figment chooses the next character from your list of
objects that does not duplicate an existing view for this object.
You can then scroll the character names to find other legal
candidates if you like.
The character viewpoints for your objects need not be the same
viewpoints for all objects unless you want them to be. Also,
many objects appear the same to everyone so other viewpoints are
39
The Story Editor Figment User's Guide
not required; don't feel you have to define viewpoints if you do
not want to.
The actor currently defined in the story is shown at this level.
If you have changed the Actor in the story, you see that name
here. Otherwise, it reads "Player". The system automatically
displays the "Actor view" when you enter the text level editor.
Most of the time, this will be the Player View.
Editing the viewpoints is simple. From the word "Text", hit
Page-Down. Your cursor lands on the view number. If there are
more than one view, you can cycle through the views by scrolling
up or down. Add a new view by hitting the "+" key.
You can delete a viewpoint by hitting the "Delete" key when the
cursor is positioned over the number of the viewpoint you want to
delete. Rules can refer to viewpoints in the "Copy msg"
function. When you delete a viewpoint, no effort is made to
change such a reference to the deleted viewpoint. They simply
become ineffective since there will be no destination for the
copying.
Advance the cursor to label the view by scrolling the character
names until you see the one you want. Advance onward and edit
the text in the usual manner.
You can change the Actor here if you like, but remember it
changes the actor for the story so be sure to put it back when
you are through. Advance the cursor to the Actor name and scroll
the character names. When a character name for the Actor matches
a name for a view, the text on the screen will change to that
view. You can Page-Up to the object name level and display this
Actor's view of each object as you advance through the object
names.
c. User-Definable Attributes
Put the cursor over the word "User Attributes". The attributes
for this object are displayed.
The original premise for user-defined attributes applies to
characters, but that does not limit them only to the characters
or to human attributes. We will begin by discussing characters
and expand the philosophy later to include other needs.
Writers are taught to develop characters along three lines:
physical, psychological, and spiritual. Figment groups user-
definable attributes in three categories called simply Types 1,
2, and 3. You can establish the convention within your work that
40
Figment User's Guide The Story Editor
Type 1 attributes are the physical attributes and Type 2
attributes are the psychological ones etc. Attributes for a
hypothetical character might be:
Type 1 Type 2 Type 3
Strength 50 Courage 10 Devotion 10
Beauty 20 Bravery 2 Purity -40
Warts 10 Paranoia 33 Je ne sais quoi 100
Bad Smell 15 DrinksLikeFish 99 Chemistry 12
Dresses Funny 10 Morals 0 Kind to Animals 23
Intellect -10
User-definable attributes are merely text labels that you add to
the system on a separate editing screen (See Links and Attributes
later in this document). As you can see from the example above,
the labels can be anything you can think of. Once you have
defined them for the system, you can add them to your objects
here by scrolling those previously defined labels and setting
their value. The value can range from +127 to -128.
You need not specify a value if you do not want to. It might be
best to wait and see what values are required as you test your
story.
User Attributes are used in character profiles (See Profiles
below). These allow you to specify a decision matrix for special
situations or character types. You also have conditional and
executional functions to test and modify the attributes in your
rules.
We said that user attributes can be used for inanimate objects
too. Consider attributes for an object like an airplane:
Type 1 Type 2 Type 3
Engine 50 Turbulence -10 Airframe -32
Fuel 10 Attitude 20
Icing 10
From this you might surmise the engines are running fine, the
fuel's getting low, the turbulence is getting bad, and that crack
in the wing has you worried. Hope the de-icers hold out.
Notice that the concept of Physical, Psychological and Spiritual
attribute types does not apply when you are not speaking of
characters. Hence we call them simply Types 1, 2, and 3.
The purpose of the three categories is so that future functions
can operate on the groups if desired. For example, if you defeat
an opponent in battle, you might win or acquire their physical
41
The Story Editor Figment User's Guide
(Type 1) attributes, but if you fall in love you might share
(average) the spiritual (Type 3) attributes. Currently the major
activity for user attributes is in Character Profiles (See
Profiles below), which allow weight factors to be applied to
groups of attributes based on their type.
Editing user attributes is easy. Page Down to the attribute line
you want to change. Move the cursor left or right to the
attribute or value you want to change. Scroll as required. If
you do not see an attribute you want when scrolling, go to the
editing screen for Links and Attributes and define one.
Page Down will move the cursor down and add more attributes when
you hit the end of the list. The delete key will delete the
attribute the cursor is pointing to. The "+" key adds attributes
without moving the cursor. Page-Up moves the cursor up and
eventually exits this level. "Esc" immediately exits this level.
d. Link Editing
Links are associations between objects. There are many ways that
objects might be associated. Figment lets you label the links to
represent these different associations. For example, consider
the many ways that John and Mary might be related:
Lovers
Family - spouse, sibling, children, parents, cousins
Classmates
Work-related
Church Group
Tennis Match
.
.
.
Knowing the type of relationship tells you more information which
means you can write more complex rules with link types, but you
are not required to specify the type of link if you do not want
to. It is just an option to enrich the story. The default link
type is "Generic", meaning "no implied type", and you may use it
for all your links if you like.
Even if you know the relationship, you do not know the strength
of the relationship. Figment lets you model the strength of
relationships by including an optional value. You can test or
change this value from the story logic.
42
Figment User's Guide The Story Editor
If {
John is linked to Mary by Romance > 20
}...
The size of the number implies the strength of the relationship.
Negative values are allowed. Again, do not be concerned with
values for the links in the early going. They are another
refinement for advanced users.
Link types are defined on their own editing screen (See Links and
Attributes, below). Here, you merely scroll those types you have
defined previously.
The most common use for links is associating objects with scenes.
When the Player says "take the ball", Figment breaks the link
from the scene to the ball and makes a link from the Player to
the ball. The story's Scene Description no longer mentions the
ball, because that link is gone, and the Inventory reports the
ball in the Player's possession. In truth, nothing really
happens to the ball at all! The system is wide open. You could
link everybody to the ball, and it would appear as though
everyone had the ball.
The method for editing links is similar to that for user
attributes.
The limit attribute for the object specifies the maximum number
of links you can make up to a final limit of 32. (See the
discussion on links in Part III.)
The system lets you make duplicate links, but duplicate links can
confuse your logic. Check your design and correct it if
necessary.
I. Scene Editor
Once you know how to edit Stuff, you know how to edit Scenes
since they are the same data structure and the same editing
style.
Most attributes are ignored for scenes. They are there only for
the purposes of standardization with stuff. You may want to use
the lock and open flags when you get to writing rules. They can
be used safely. Also, the limit attribute affects the link count
as with the Stuff objects.
Links are important to scenes. Scenes are not much to look at by
themselves. They get their richness by virtue of the stuff that
you link to them. The order in which you create links can be
43
The Story Editor Figment User's Guide
important too since they affect the description paragraph for the
Scene Description during play.
When Figment composes the Scene Description in the Presentation
Environment, it looks at the link list for the scene to see what
descriptions to use. The first line of text comes from the scene
object itself, its description line(s) are from the scene
description that you see when you display the scene in the
editor. Then it gets any feature description text from any
feature stuff that are linked to the scene, then the character
descriptions, and finally, any thing descriptions. Thus the
story's Scene Description flows from what the scene is like, to
who is in it, and finally to what you can take from it. As
events occur, either by your action or the story's, they may
alter the scene so the description is re-composed and re-
displayed. If no changes occur, then nothing happens.
You are not required to link the Player Object into the scene,
but when you do, the player's description is added to the scene
description just after the scene object's description.
Since features automatically come before any characters anyway,
you need not worry about placing them in front of characters in
the scene's link list. You need only get the features in the
order in which you want them to appear relative to each other
feature. The first feature description you want to appear must
have its object name appear ahead of any other feature on the
scene's link list. The same applies for the characters and the
things.
All this points to the importance of setting an object's type
attribute when you create new stuff as we discussed earlier.
That is all there is to editing scenes. We will use the scenes
to construct the Story Map.
J. Story Maps
Earlier, we recommended a methodology wherein we said you should
make objects, make scenes, link the scenes to their objects, and
build the Story Map so we will discuss maps next. Figment
supports two kinds of maps: the Story Map and the Player Map.
The Player Map is a luxury we can ignore for now.
44
Figment User's Guide The Story Editor
1. About Maps
The map ties the scenes together. In it, you specify each
scene's neighbors and what direction to go to reach them. Maps
usually are only edited when you add new scenes to the story,
delete old ones or when you want to change the exit directions.
You do not edit the map just because you modified the scene or
its name. If you change a scene's name, you immediately see the
new name when you switch the screen to view the map.
You are not obliged to use all the scenes you have defined. In
fact, scenes are not really in the story until you put them in
the map. Scene-change operations will not work in the story
until you make a map entry for your scene.
Story logic is very intimately related to the Story Map. Figment
sub-divides its rule base into local rule bases for every scene
in the story (technically map block in the story). It makes a
new local rule base every time you create a map block. (Careful
- It also deletes it when you delete the map block.)
Figment has one very special feature to its Story Map: you can
re-visit old scenes and encounter new logic. You are not
required to make your story do this, but you can do it. It is
all in how you make your map. For purposes of this discussion,
we will refer to any map that does not make new rule bases for
old scenes as a simple map, and we will call a map that does make
a new rule base for an old scene a complex map.
2. Editing Simple Maps
To access the Story Map, move to the Top Level Editor and change
the screen with the Up-Arrow key. The screen displays a matrix
of scene blocks. Each block is numbered and titled with the name
of a scene we want to use. Note that if none of the scene names
repeat in the block titles, then it is a simple map. Under each
block title name are the names of the titled scene's neighbors
listed by the compass directions you would use to access the
neighboring scene.
We display the symbol "-*-" to mean that there is no neighboring
scene in that direction. The player gets the message, "You can't
go that way." when attempting to leave the scene in that
direction.
Note that you are not required to return by the same path that
you arrived. In the real world, if Scene A is west of Scene B,
then logically B is east of A. This law does not hold true for a
fictional world; you can return to A from B by any direction you
45
The Story Editor Figment User's Guide
like. If B does not refer to A, then it is a one-way street from
A to B with no return to A.
Story maps are easy to edit once you recognize that all you are
doing is specifying the exits from a scene. The mechanics of
editing are simple (since by now you are an experienced story
editor): Page-Down from the Top-Level, Right-Arrow to the block
you want to change, Page-Down to the direction you want to
change, scroll the scene names then Right-Arrow to another scene
or Page-Up until you are back to the Top-Level.
You can add or delete map blocks with the "+" and "Delete" keys.
The new block is titled "Not Defined". When you create more map
blocks than will fit on a screen, you see nothing happening, but
if you advance the cursor to the last block on the screen,
Figment will begin scrolling blocks. Continue advancing until
see your added blocks at the end of the list.
The first block in the map is the entry scene for the story.
Thereafter, there is no mandatory order. The first scene points
to its neighbors who in turn point to their neighbors, etc. Thus
the second block on the screen is not necessarily the second
scene the player will see when playing the story.
As you plan your map, remember that if during play you return to
a scene you were in before, it will be in whatever condition you
left it and its rule bases will also be in whatever state they
were when you left (rules that switched off do not switch on
again).
3. Complex Map Editing
Complex maps are, naturally, harder. Remember we mentioned that
the scenes are numbered in the map block titles? This is crucial
to an understanding of complex maps. An example helps here.
Retrieve our demo and bring the map up on the screen in the
editor. We attempt to reproduce this here in our book, but it is
better to see it in action. Using the first three blocks from
that demo map as an example:
0 Mountains 1 Foggy Hollow 2 At the Beach
N 1 Foggy Hollow 3 Dark Forest -*- N
E -*- -*- -*- E
W 4 Spooky Cave -*- -*- W
S -*- 0 Mountains 1 Foggy Hollow S
U -*- -*- -*- U
D 2 At the Beach -*- -*- D
46
Figment User's Guide The Story Editor
This seems straightforward. If we leave scene zero, the Mountain
scene, going north we arrive at scene 1, the Hollow. Continuing
northward from there, we end up at scene 3, the Dark Forest.
What happens if we change the title of block 3 from Dark Forest
to Mountains? Do this now by scrolling the name using your
cursor control keys. Now in block 1, the record has changed to
indicate the mountain scene is simultaneously to the north and
the south of the Hollow. But note that the numbers are
different.
Now imagine that we travel this new path we have just made. If
we go south from the Hollow, we return to block zero, the
Mountain scene as we left it and with the rule bases as we left
them. If we go north from the Hollow, we enter the same Mountain
scene (object) but a different set of local rules.
Now assume you edit the block titled Hollow. Position your
cursor to the North direction record. You find as you scroll the
scene names that you get two references to the scene named
"Mountains". You get "0 Mountains" and "3 Mountains". Which one
do you want? Your choice would be based on which rule base you
want.
Thus it is important to note the numbers next to the scene names
and make sure as you design your map that you are pointing to the
scene the way that you want to. By now you recognize that you
are not specifying scene names in map blocks, you are specifying
other map blocks which happened to be titled with the scene
names. Map blocks do not really have names, just numbers.
47
The Story Editor Figment User's Guide
K. Story Rules (Logic Programming)
Rules form the logic that drives your story, and they are
undoubtedly the hardest part of Figment for new users. Figment
can function with absolutely no rules - but it is very dull. The
more rules you can add, the more interesting your story will be.
In other words, you have to achieve critical mass. A couple
hundred rules with maybe 600 rule-expressions makes a nice story.
It is very easy to get in over your head with rule bases.
Initial efforts seem to go well enough, but you soon reach a
point where doubling the size of the rule base more than
quadruples the complexity. Do not try to fight this phenomenon;
it is one of those immutable facts of life. Our advice, when
that happens, is to split the scene into two, smaller, simpler
scenes.
Assume one case where you put thirty rules into one scene and
another case where you put three rules into ten scenes. In terms
of story development, your story has grown by the same quantity
in both cases, but the work will be much easier in the second
case. We say this because beginners tend to overwork the first
scene and become disillusioned when they "hit the wall". You
have to work up to it gradually if you want to scale the wall.
This is partly why we tell you to make several scenes and a map
before you write rules.
1. Theory of Operation
A rule specifies actions to take in the event of certain
conditions. In many cases, the action is simply to print a
message in response to the operator's command creating the
illusion of a dialogue. The "conditions" might be a certain
player action or the state of the many object attributes and
associations. If the conditions hold true, the rule is said to
"fire", meaning its specified actions are performed. The
collection of all rules is called the Story Logic.
Figment divides the logic four ways into global and local logic
and pre-command and post-command logic. Pre-command logic is
concerned with a specific action. Post-command logic is
concerned with the effects of any action. This allows you to
make a "logic sandwich" that surrounds any action:
>Take the Booby Trap
[test for "take" and locked Booby Trap]
It doesn't look safe to me, but ok if you say so.
[command proceeds]
You take the Booby Trap.
48
Figment User's Guide The Story Editor
[test for possession of locked Booby Trap
then kill player and print message]
Some people go out with a bang. Others go out with a
wimper. Lucky you. You get to do both!
Global logic applies to all scenes. Local logic applies only to
the scene for which it was written.
Global and local logic are identical in nature, but global logic
is stored separately and used repeatedly in every scene. Usually
you write all logic for the local scene. When you find you want
to use the same rule in a different scene, you move it to the
global storage area with cut and paste operations. Rules
governing the behavior of objects of type "Thing" are good
candidates for global rules because the player can carry them
from scene to scene.
The logic is organized into sequences of rules called rule bases.
There are four rule bases that apply when processing any comand:
Global Pre-Command Rule Base
Local Pre-Command Rule Base
Global Post-Command Rule Base
Local Post-Command Rule Base
The primary reason for the organization is to improve the
performance, but it has the added effect of cataloging the rules
so you can find them easier, which is always good to do.
We will ignore global logic now since the important distinction
is between the pre- and post-command rules. You can develop
rules local to a scene. When you see you need them in other
scenes, you can move (cut/paste) them to the global rule base.
When a command is given during play, Figment will process the
command sufficiently to ensure the arguments are legal and that
the command syntax is correct. Any mistake here will stop the
processing and yield some generic error message. This means that
none of your logic will be triggered by ordinary operator errors.
This error-check ensures that the command will complete
successfully unless you have written some intervening logic.
Some common operator errors:
>take the book
You already have it.
>take the ball
There is no ball here.
>drop the rock
You don't have a rock.
49
The Story Editor Figment User's Guide
Once a command is determined to be legal, Figment interrupts
command processing and checks every rule in the Global and Local
Pre-Command Rule Bases to see if there is a rule for this command
action. There may be several such rules or there may be none.
Any rules for this command are evaluated to see if their
conditions hold true. If they hold true, the rule fires and its
Command Flag is returned which enables or disables continued
command processing. Rule processing continues until all rules
that apply have been processed.
Figment returns from rule processing to complete the command
execution. It is at this point that the normal command action
takes place if the command has not been disabled by a rule.
Summarizing:
All Global and Local Pre-Command Rules are checked on
every command to find applicable rules.
All applicable rules for the action are evaluated. (We
do not quit early if a rule inhibits the command.)
Rules that fire return a flag to indicate whether
command processing should continue. A single negative
flag will stop the command processing.
We know the command will complete, because it was pre-checked so
Figment only needs permission from your rules to proceed. After
all this, the Post-Command rules seem anti-climatic. They just
test for changes in state meaning links or attributes which
changed since the last command completed.
From all of the above, you should recognize that all Global Pre-
Command Rules are processed on each and every command regardless
of the scene making it the most-used rule base while the Local
Post Command Rules are processed only on a successful command in
the current scene making them the least-used rule bases.
Minimizing global pre-command rules and maximizing local post-
command rules improves performance and makes debugging your story
easier - if Figment ignores a rule base so can you. Figment will
ignore the post-command rule bases entirely until a command
completes successfully.
Most beginners over-use the pre-command rule bases. This is bad
for several reasons: performance suffers, capacity in rule bases
is finite, and the rules are too action-specific. Probably half
of these rules could be re-written as Post-Command rules creating
a better balanced, better performing story that is more user-
tolerant.
50
Figment User's Guide The Story Editor
Observe. A pre-command rule is concerned with an action. A
post-command rule is concerned with the result of an action.
Many times it is just the result you want. Imagine the object of
a scene is to obtain a bank loan. Bankers only need to see
sufficient funds to repay a loan, and there are many ways to
achieve that. You would have to write many pre-command rules to
consider them all, but you only need to test a user-defined
attribute for "Net Worth" or "Cash Flow" with a post-command rule
to satisfy a banker.
Most interactive fiction hinges around the player making the
correct actions. This is often unavoidable, but the price is
that many stories are stuck until the player discovers the right
move. It also does not tolerate the player's innovations. They
often can think of things you did not. You can avoid this by re-
phrasing the rule as a post-command rule and creating some
literary device waiting in reserve that creates the right
conditions if the player takes too long to perform the right
action. This is really the best of both worlds because it
tolerates beginners without penalizing experts.
2. Anatomy of a Rule
It's time to study the rule itself. Post-Command rules are
slightly simpler so go to the Top Level Editor and set the screen
to display the Post-Command Rule Base and follow along with the
discussion. Page-down and you can scroll the rule number to see
the different rules in the rule base.
A rule has three major parts: a conditional clause (the "IF"
part), an executional clause (the "THEN" part) and up to sixteen
messages that can be "dispensed" (printed, used, or sent
somewhere). The conditional clause has up to eight expressions
(typically tests of links and flags), all of which must hold true
in order to fire the executional clause. The executional clause
can perform up to eight operations each time the rule fires.
You can specify three types of rules: IF, WHILE and FOR. Page-
down from the rule number level. Your cursor lands on the rule
type. These types scroll under the cursor when you hit the Up-
Arrow key.
The IF-type rule will fire only once. It then switches itself
OFF and is never processed again for the remainder of the story.
To the right of the rule number, you see an indicator which reads
"Switched: ON (or OFF)". You can reset this manually if you
like. Usually you check this indicator when debugging to see if
the rule fired.
51
The Story Editor Figment User's Guide
A WHILE-type rule is an IF-type rule that never switches off. It
will always fire when its conditions hold true. The indicator
should always read "ON" for a WHILE clause. (It might not if you
have recently changed the type and forgotten to switch it back ON
so get in the habit of checking.)
The FOR-type rule is very powerful (read tricky). It is used for
stunts. A counter tracks the number of times that the conditions
have held true. You specify the start and stop counts when you
want the rule to fire. If you specify the start count to be 3
for example, then nothing happens the first two times the
conditions are true. You can also specify a step count which
causes the rule to fire every second or third time and so forth.
This can be used to make messages appear at intervals. The
indicator will show the rule has switched OFF when it reaches its
specified stop count.
The processor checks each rule but skips to the next rule when it
sees the rule has been switched off. Rules should always be
switched on at the start of play for the scene. You may,
however, want to switch off some rules in order to debug others.
The switch also functions as a "soft delete". You can keep an
obsolete rule switched off and switch it on later if you decide
to keep it. There is no way to switch a rule on during play once
it is switched off. You can, however, simulate that effect by
testing a lock flag (or any other attribute or flag) and having
another rule change that lock flag. Thus a rule can appear to be
asleep until the lock flag changes. There are many examples of
this in the demo.
The Conditional Clause, the Executional Clause and the Messages
represent separate editing levels that you enter with Page Down.
The rule editing screen is the most dynamic editing screen. The
rule expands and shrinks as you add and delete expressions and
messages. The expressions themselves also expand and shrink as
you change their functions, arguments, and modifiers. You often
cannot display all the messages at once so you see a rolling
window of messages as you step through the message list.
All of the conditional expressions must hold true for the rule to
fire. Experienced users will recognize this as a "Logical AND"
and immediately ask where is the "Logical OR"? The answer is
that each rule in the rule base is logically OR'd meaning that
Rule A fires, OR Rule B, OR Rule C, etc. So if you want to OR an
expression, copy the rule and change the conditional expressions.
This sounds wasteful, but in practice if you change the
conditions, you probably will change the executional expressions
and/or the messages too which means you need a new rule anyway.
52
Figment User's Guide The Story Editor
3. Expressions
This is an overview of expressions and their editing. We will
cover expression editing in full detail later.
We call each line of the conditional or executional clause an
expression. An expression is composed of a function, objects
that act as arguments to the function, and modifiers. For
example:
While {
Player is linked to Ball by Ownership
}...
This expression asks "Does the Player own the ball?" (as opposed
to merely having it in his or her possession.) The conditional
function in this example is "is_linked_to". Its arguments are
Player and Ball, and the term "by Ownership" acts as a modifier.
Figment will check to see if there is a link with the label
"Ownership" in the Player's link list. If there is, the rule
fires.
The syntax reference (see Conditional Function Reference, later)
indicates that the modifiers for "is_linked" are optional. That
means if you scroll them far enough, they blank out. This yields
the expression: "Player is linked to Ball". Figment would then
return "true" if it found any link to the ball in the Player's
link list regardless of type or value.
We change each portion of an expression by scrolling. Try it.
Advance the cursor from the rule type to the first expression and
hit Page-down. The rule type lights in reverse video to signify
expression editing has been initiated. Your cursor lands on the
expression's function. Scroll the functions and stop at the
function you want to use. Notice the entire expression can
change depending on the function. Some functions need three
arguments while others need only one, some have modifiers, etc.
When you have decided on the function move the cursor left or
right to set the arguments and the modifiers.
We will cover the rule editing in detail later.
You are not required to write any conditional expressions at all
if you do not want to. An empty conditional clause means the
rule is always true, and it fires every time the player
successfully completes a command. Pre-command rules, by the way,
cannot have empty conditional clauses, because they test for
action so you would be testing for no action which means it would
become a Post-command rule. (When you want a Pre-Command rule to
53
The Story Editor Figment User's Guide
fire on any command, you can negate the User-defined Command
Parser.)
Neither are you required to write any executional clause at all.
Often you need only the message since it prints to the command
window automatically so it is not unusual to see an empty
executional clause.
4. Messages
Interactive fiction requires delivering an appropriate message in
response to a player's actions so shipping text strings to
various destinations is an important activity for executional
functions. Most rules are used primarily to hold messages for
delivery at the appropriate time. The text that you defined for
your objects merely represents the initial condition. Your rules
will alter it during play by copying messages to the description
and examination strings.
When the rule fires, its Current Message is printed automatically
to the Command Window where it appears as though in response to
the player's command. You can switch the automatic printing off
when you want the message copied to a different destination. For
example, the message can be copied to an object's Long
Description which will cause the story's Scene Description to
change.
The rule reports its Current Message number at the end of the
line titled "Messages". Usually this begins as message number
one. The Current Message number does not change unless you
change it with the executional function "inc_message" which
increments the current message number. This can be used to
change the message for the next time the rule fires or for
copying multiple messages to multiple destinations. For example:
While {
Player is linked to Ball
} Then {
inc_message
} Messages: 4 total Switched On Current Msg: 1
1. Hey that's a neat ball.
2. It's not yours. You better not keep it.
3. I think it belongs to someone else.
4. You're going to get in trouble.
This rule prompts a warning message to the command line each time
the player completes a command as long as the player has the
object named Ball. With each move the message gets progressively
ominous, because the Current Message pointer is incremented each
54
Figment User's Guide The Story Editor
time the rule fires. Eventually the last message is encountered.
The inc_message function cannot increment past the last message
so this rule will continue prompting the last message each time a
command completes, meaning the system will nag ad nauseum until
you drop the ball. Some people won't want the nagging message
that keeps prompting. In which case, change the rule type to
"For 1 to 4 step 1". Now the rule shuts down after it reaches
the fourth message.
An executional function, "on_skill", is also provided that allows
you to deliver the appropriate message relative to the player's
skill level so you can even tailor your work to beginners or
experts. There are five skill levels so on-skill chooses one
message from a block of five. You can have up to 16 messages and
combine "inc_message" with "on_skill" to increment to the next
block of five messages. This can yield a progression of three
messages chosen according to the player's skill.
Often you do not want the message to be printed automatically.
You can suppress the automatic printing with the ON/OFF switch on
the Messages line so you can copy messages to object descriptions
and examination messages without printing them to the command
window.
5. A Rule Base in Action
An example from the demo serves to illustrate a sequence of rules
in action. These rules are all post-command rules meaning that
the player must complete a move each time the rule is to be
processed for possible firing. In other words, we have
programmed a mini-drama to unfold while the player is fiddling
with other things. The entire sequence discussed here takes a
total of 9 moves to complete.
We add the character "Rushin' Bear" to the scene. We want to put
messages to its description message, but we will clobber the
existing message before it is displayed (Relatively harmless, but
wasteful), so we delay the message transfer one move with a FOR
clause that begins on the second move after the bear is added to
the scene:
FOR 2 to 5 step 1 {
<scene> is linked to Rushin' Bear
} THEN {
copy msg to Rushin' Bear's Long Description
inc_msg
} Message 4 Total Switched OFF
< 4 messages >
55
The Story Editor Figment User's Guide
By delaying the start of message transfer to the second move
after the bear arrives, we allow the object's original
description to be displayed, then we copy a message in its place
and increment this rule's message pointer to this rule's second
message. Process repeats three more times. The result is that
we announce the bear's pending arrival with a sequence of
increasingly ominous messages.
Once done, we want the bear to initiate a fight so we unlock the
bear after the fifth move:
FOR 5 to 5 Step 1 {
* the scene * is linked to Rushin' Bear
} THEN {
unlock Rushin' Bear
} Message 0 Total Switched OFF
< no messages>
This functions exactly like an IF statement, but it is delayed 5
counts. We then follow with a third rule (not shown here), a 4-
count FOR statement that tests the Bear's lock flag and unleashes
a barrage of punishment forcing the player to fight the bear or
die. The entire Bear sequence was triggered by the player's
action. (Extra Credit: Study the listing in the demo. Can you
find the event that brought the Bear? Wasn't that easy?)
This sequence of only three rules has driven a little mini-drama
in the scene. There can be many such dramas contained within the
rule bases, all of which progress one notch with each command.
The player only sees the Scene Description change and the command
responses appear after typing a command. The impression is as
though the different dramas played out in the scene are
progressing in parallel.
L. Editing Rule Bases
Once you have practiced editing objects (stuff and scenes), rule
editing should come as no great difficulty. They are, by their
nature, more complex than objects so there is a greater amount of
work here.
By now you should recognize that if what you want to edit is not
accessible with the Right-Arrow key, it is on a level lower and
that the Page-Down key will reach that level. You should also
recognize that the editor will show you what you can edit on this
level by holding the Right- or Left-Arrow down and watching where
the cursor flies.
56
Figment User's Guide The Story Editor
Also the Home key is used extensively in expression editing to
give you more options.
1. Rule Base Editing
From the Top Level Editor, select the appropriate screen editor
for Pre- or Post-Command Rule Base editing. Hit Page-Down. Your
cursor lands at the rule number. We call this the Rule Base
Level, because you are addressing the rule base as a whole, not
elements of the rule (Yes, the rule's switches are at this level
for convenience).
You can display the different rules in the rule base by scrolling
the rule number. The label, "Rule #1 of 10" means there are ten
rules in this rule base and you are viewing the first one. You
can also delete, insert, cut or paste a rule at this point.
Moving left, you can change the scene (Map Block, actually) by
scrolling the scene name to access the different rule bases for
each scene of the story or the global rule bases. Moving right,
you can change the switches for the particular rule currently
displayed.
Page-Up from this level returns you to the Top-Level Editor, also
Escape.
a. Adding/Deleting Rules
Rules can be added or deleted with the "+" and "Delete" keys
respectively. Try adding a new rule now and note that the rule
count changes. The new rule has been added to the end of the
rule list and the screen now displays the new rule.
You are probably wondering why the screen display did not change.
The reason is that the "+" function is actually a copy function
too. It made a copy of the rule you were viewing when you hit
the "+" key and displayed the copy, changing only the rule
number. Often you want to make a rule very similar to a rule you
already have. Display this rule with the Up-Arrow key then hit
"+". The new rule copy is added to the end of the list. Now
edit the new rule to adapt it to your needs.
Note that this can also be used for re-ordering the rule sequence
by copying rules to the end of the list with the "+" key then
deleting the originals with the "Delete" key. The order of rules
can be important when rules are dependent on each other. A
better way to change the order of the rule sequence is to use cut
and paste operations.
57
The Story Editor Figment User's Guide
To delete a rule, scroll the rule number until you are displaying
the rule you want to delete. Hit the button labeled "Delete" on
your keyboard. There are no contingencies to be concerned with
as with object deletion. Only the deleted rule is affected.
b. Inserting Rules
You can insert an empty rule anywhere in the sequence. Scroll up
the rule number until you are viewing the point where you want to
insert a new rule. Hit the key labeled "Insert" on your
keyboard. The rule you are viewing and the following rules will
be moved back in the sequence one position and you will be
viewing a new rule you can edit.
c. Cutting Rules - F7
The "cut" function is especially useful for moving rules within
the sequence and between different rule bases. There is no
difference between local and global rule bases, and you can move
rules freely from one to the other. There are subtle differences
between pre- and post-command rules, but the paste function will
let you paste the wrong type, and you are expected to correct the
differences (the first expression, and the enable switch).
To cut a rule, simply scroll the rule number until you are
displaying the rule you want to cut and hit the F7 key. The rule
is removed from the sequence and held for a later paste
operation.
Repeated strikes on F7 is comparable to Delete. Each time you
cut a rule, the last rule in the cut buffer is over-written with
only the final rule cut being saved for pasting.
d. Pasting Rules - Shift-F7, Alt-F7
The "paste" function presumes you have cut a rule prior to the
paste operation, and it will beep if there has been no rule cut
prior to the paste operation. If you are not sure what rule is
in the cut buffer, paste it anyway. You can delete it or cut it
out again with a single keystroke so no harm done.
To paste a rule, scroll the rule numbers until you arrive at the
point in the sequence where you want to insert the rule. Hit
Alt-F7 to paste the rule before this rule or Shift-F7 to paste
after this rule. In either case, you will end up displaying the
newly pasted rule.
58
Figment User's Guide The Story Editor
If you want to paste a rule to the first position in a sequence,
display rule number one and hit Alt-F7. If you want to tack a
rule onto the end of the sequence, display the last rule and hit
Shift-F7.
Repeated pastes will insert repeated copies into the rule base.
e. Changing Scenes (and Rule Bases) in the Editor
To the left of the rule number is the scene name. This indicates
you are looking at the local rule base for the scene (Map Block
actually) in question. Move the cursor over the name and scroll
the name. You have changed the display to display the local rule
bases for a different scene in your map. You should recognize
that they change in the order in which they are specified in your
map (not the order in which the scenes are listed in the Scene
Editor).
Every Map Block gets its own pair of rule bases. When you enter
the editor, you are looking at the rule bases for the current
scene (Map Block) in the story, but you can change the scene here
and study other rule bases. Note that this changes the scene for
the story as well. If you hit F1, you find yourself viewing the
story in a different scene.
The Shift-F3 (write-all) function in the Top Level Editor is
designed to reset the story to the starting scene. Usually you
hit this routinely on your way out of the editor so any scene
changes here are harmless. Sometimes, you are just poking around
and do not want to save your changes so remember to put the scene
back before you leave the editor.
The scene-change function will not work if you have not made a
map. This discussion assumes you are working on an existing
story which has a map defined. If you are working on a new
story, you are stuck in scene zero until you define the map. See
the section on map editing for further details.
A word of caution. Note that there is a number beside the scene
name. This is the number of the map block, since as we
mentioned, it is the map block that you are changing. See the
section on the Map Editor for full details of Map Blocks.
Remember we mentioned that sometimes you re-use scenes with
different logic by creating different map blocks titled with the
same scene. The number tells them apart.
59
The Story Editor Figment User's Guide
f. Global Rule Bases
Global rule bases appear in every way identical to the local rule
bases. To access them for editing, simply move the cursor over
the scene name and scroll up or down until the name "Pre-global"
or "Post-global" appears. Add and edit the rules as you would
edit any sequence. Be sure to re-set the scene name if you are
returning to the Presentation Environment.
g. Rule ON/OFF Switch
Also at this level is the aforementioned switch to turn off the
rule. Many rules switch off during the course of play. You can
manually toggle this switch by advancing over to this item and
scrolling this flag. Continue advancing and the cursor wraps
back around to the scene name and the rule number.
h. Listing Rule Bases
The F4 key will write the full rule base (either Pre- or Post-,
not both) for the current scene to a disk file where you can read
it at your leisure. The F4 key is enabled in the Top Level
Editor when the screen is displaying either the Pre- or the Post-
Command rule editor. Page up to the top line on the screen and
hit F4. You just made a listing file on your disk with the same
name as the story but with a ".LST" file extension. Every time
you hit F4, the previous contents of this file are deleted and
replaced with the new listing. You can exit with F10 to read
this file with the DOS command "type" or print it on your printer
with the DOS "print" command.
If you change the screen (or change the scene) to display a
different rule base, then hit F4 again, the same disk file will
be re-used and your last listing will be lost. (Call it a
"losting".)
Shift-F4 generates a listing file for all the rule bases for
every map block, in effect, a full logic dump. Take care. This
can generate a file 60% as large as the original story file. If
you are tight on disk space, you may want to swap diskettes
before hitting Shift-F4. Again, this over-writes any existing
listing file.
Listings are fully expendable, feel free to delete them when you
need to recover disk space. The file is automatically created
when you hit F4 if the file does not already exist.
60
Figment User's Guide The Story Editor
Note. DOS installs a print driver routine the first time you
give the print command after booting up. This routine is then
left in memory waiting for any subsequent print requests. If you
have not printed anything before you start Figment, and you use
F10 to visit DOS and do your printing, you will install this
print driver at a memory location above the last memory address
that Figment consumes. Eventually, you return to Figment and
quit completely to run another DOS application. If this program
consumes more memory than Figment did, it runs afoul of the print
driver sitting in an unusually high location in memory, and you
get the alarming message:
Insufficient memory to execute program.
The only way to kill this print driver is to re-boot your
machine. Hit reset.
To avoid this problem, load the print driver first by giving the
print command with no filename. This loads the driver and
reports to you that the print queue is empty. Now start Figment.
If you use this feature often, you may want to create a batch
file so you will not forget.
2. Rule Level Editing
Hit Page-Down from the Rule Base Level Editor and your cursor
lands at the Rule Type. Advance the cursor and it moves
sequentially to the Conditional Expressions, the Executional
Expressions and the Messages where it wraps back to the rule
type. These are separate editing levels, and you can access them
by hitting Page-Down when the cursor is at these locations.
Page-Up/Escape returns to the Rule Base Level Editor.
a. Rule Type
You can scroll the rule type. Notice the start, stop, and step
counts magically appear and disappear when you set the rule type
to FOR. Notice if a rule is switched OFF that changing the type
does not automatically switch it ON. You must do this manually.
b. Expression Editing
Expression level editing is very similar for both the conditional
and executional clauses so we will describe both processes
simultaneously. There is only a slight variation in format
between the two expression types.
61
The Story Editor Figment User's Guide
When you enter expression level editing with Page-Down, the
rule's type statement or the word "Then" lights up in reverse
video to indicate the expression level editor is enabled. If you
do not see this light, you cannot edit the expressions. Figment
will only beep as you attempt to scroll values.
Continue hitting Page-Down to move down to the expression you
want to change. Page-Down also automatically adds new
expressions for you when you hit the end of the list up to a
maximum of eight expressions per clause. It then moves down to
the newly added expression.
Page-Up moves up the list and finally exits the expression level
editor whereupon the reverse video returns to normal signifying
you have left expression editing.
The "+" key automatically adds new expressions to the end of the
list, but it does not move into them.
The Delete key deletes the expression the cursor is on.
The rule display automatically expands and contracts to
accommodate newly added and deleted expressions.
If the clause is empty, it reads "No Expressions", meaning you
must add one. Otherwise Figment will beep when you attempt to
edit nothing.
As you make changes to the expressions, Figment re-computes the
line length to accommodate the various options you have selected.
The cursor centers on the function phrase or the function's
argument phrases. It changes position slightly as you change
these phrases. The cursor can only be an approximate guide to
say that you are working on the function or its arguments. It
cannot indicate all the possible options at each location.
Experiment with the up/down arrow keys and the Home key to see
what your choices are.
(1) Setting the Function
When you enter expression editing, your cursor lands on the
expression's function. The editing operations that you can do on
an expression depend on the function so this will be your first
task. Set the function you want by scrolling the function names
with the Up-Arrow key.
You can negate conditional expressions by hitting the Home key
when the cursor is on a function. The Home key is very powerful,
62
Figment User's Guide The Story Editor
but here it only serves to toggle negation on or off. (See data
types below.)
The editor will only scroll the functions that are legal for your
context: conditional functions will only scroll in conditional
expressions, executional functions in executional expressions and
story commands in the first conditional expression of a pre-
command rule. No system-level functions (restart, restore, save,
toggle, etc.) will be seen in the expression editor meaning you
are not allowed to write rules to inhibit or restrain them.
(2) Expression Argument Counts
The editor varies the expression argument count according to the
function. Some functions require no arguments while some allow
several. As you advance the cursor with the right-arrow key, the
cursor skips over each argument position and eventually wraps
back to the beginning of the expression when the maximum
allowable argument is passed. Thus as you change the function,
the cursor will make shorter or longer laps as you cycle it left
and right.
Some functions have different forms that use different numbers of
arguments. For example, you can say:
If {
Player does take ball
}...
or
If {
Player does take ball from boy
}...
In such a case if you choose not to use the last argument, simply
scroll up (or down) the last argument's name until it blanks out.
The modifier will also disappear.
(3) Data Types - The "Home" Key
Each function specifies the legal data types for its arguments
(see the Command Reference sections) so that the editor can
inhibit mistakes before they occur. The "Home" key is used to
access different data types for the function arguments. It also
serves to negate conditional expressions when the cursor is
positioned over the function.
63
The Story Editor Figment User's Guide
Some functions allow a wide variety of data types for the
function arguments while others allow only one. You can check
the syntax in the Command Reference sections that follow. You
might find it easier just to try hitting the Home key. If
nothing happens, the function allows no other options for data
types at that location in the expression.
For example, the function "is linked to" tests for a link from
one object to another. When making links, you should recognize
that scenes can have links to objects, but objects cannot have
links to scenes. The reason is that links imply "possession" or
similar association. Scenes have objects in them, but objects do
not have scenes in them. Neither can scenes be linked to other
scenes. Thus the "is linked to" function specifies its arguments
as follows:
<stuff or scene> is linked to <stuff>
If you strike the Home key when the cursor is positioned over the
first argument, you can change to scrolling scene names from
scrolling stuff names. Another strike on the Home key, and you
are back to scrolling stuff names.
The significance of this is that you can access any scene name in
many functions, but only where it is legal to do so. For
example, you might want to specify scene names or directions when
testing the "go" command:
If {
Player does go North
}...
or
If {
Player does go to Basement
}...
(4) Arguments Specified by Attributes
Some functions allow their arguments to be specified by the
attributes Type and Sub-type. For example:
If {
Player is linked to obj sub-type Money
}...
64
Figment User's Guide The Story Editor
This would be read as: "If the player is linked to an object of
sub-type 'Money'..." meaning "Does the player have something of
value?".
To access the attributes, simply hit the Home key when the cursor
is positioned over the second object until you see the sub-type
attributes. Scroll the sub-type names until you see the one you
want.
(5) Pronouns
Whenever you specify arguments to functions indirectly, for
example by their attributes, you create a separate problem. How
do you refer to them later? Figment supports some special
pronouns for that purpose. For example:
If {
Player is linked to obj sub-type Money
} Then {
Take * the object * from Player
}...
We display the pronoun "the object" between asterisks to remind
you that this is a pronoun.
Further discussion on pronouns is available for registered users.
(6) Cutting and Pasting Expressions
You can cut an expression out of the clause by hitting F7. The
cursor location does not matter. It can be anywhere on the
expression. The expression can then be pasted back with Alt-F7
or Shift-F7 as described above for rules.
When you paste an expression of the wrong type in a clause,
Figment quickly converts the function in the newly copied
expression to the appropriate type. Figment is in effect
politely telling you that you will have to re-state the
expression anyway. Net effect, pasting will not look much
different from inserting for the majority of cases.
(7) Inserting Expressions
The Insert key will insert a new expression in the clause at the
cursor location. The existing expressions are bumped back to
open the gap in the sequence for the new expression.
65
The Story Editor Figment User's Guide
Note when inserting a new first expression to a pre-command
rule's conditional clause, the old expression moves back and is
transformed to an ordinary conditional expression.
3. Message Editing
Message editing is accessed via Page-Down when the cursor is
positioned over the word "Message" on the screen. The word
"Message" lights up in reverse video when you enter the message
editing level, and the cursor jumps to the message switch. Set
the message display switch to "off" or "on" by scrolling up with
the Up-arrow key. Advance to the "Current Msg:" position with
the Right-arrow key.
The Current Message refers to the message that will be passed or
displayed the next time the rule uses its messages. The
executional function "inc_message", for example, will advance the
Current Message pointer so that the next message can be passed.
If you have been playing the story before entering the editor,
you might see it pointing to some value other than 1. You would
set the Current Message value whenever you use a function like
the user-defined command parser ("say_cmnd") that uses the first
rule message by default. Otherwise, you probably do not have to
change this value.
Advancing one more position (or hitting Page-Down) puts you in
position for editing the rule messages. Page-Up/Down moves you
to the appropriate message for editing. You cannot edit a message
where none exists so hit "+" or Page-Down when there are no
messages so that you have a message to edit. Note that the
message total shown on the screen updates as you add and delete
messages. If it reports zero messages, you cannot edit a message
until you add one.
Page-Up/Down behaves in a similar fashion as for expression
editing so do "+" and Delete. Note that when screen space is
limited, the messages will roll up/down in a window as required
to fit the available space.
The F7 key will cut the message to the text buffer from which it
can be pasted back (wherever text is needed: rule messages,
object names, descriptions, etc.).
Pasting behaves slightly different for rule messages than it does
for object text strings. The message the screen cursor points to
is not replaced by the text in the cut buffer. Instead, the cut
buffer is inserted as a message in the list of rule messages.
Alt-F7 and Shift-F7 behave as they do in expression editing, and
repeated paste operations will generate repeated copies.
66
Figment User's Guide The Story Editor
The message itself is edited in the normal manner for all text.
When the cursor is positioned at the start of the message, you
can type in replacement text directly or you can hit "F6" and use
the full-screen text editor to modify existing text.
Page-Up exits the message editing level and returns to the rule
editing level. When the list of messages is long, Escape is
easier.
Be sure to leave the rule's current message indicator reading the
message number you want. Typically this is the first message,
but you can skip messages if you want.
That is all there is to editing rules. You can exit with Page-
Up. We now discuss the distinction between Pre- and Post-Command
Rule Bases and then discuss the various rule functions in detail.
M. Pre-Command Rules
Often you want to intercept or block a command from executing.
Pre-Command rules allow you to do that.
Change the screen now so you can study the Pre-Command Rule
Editor. It is very similar to the Post-Command Rule Editor, by
deliberate design so that you will have less editing to learn.
The major distinctions are the addition of the "Command" switch
in the upper right corner of the screen and the first conditional
expression.
The Pre-Command rule differs from its Post-Command counterpart in
that its first conditional expression tests for the verb in the
player's command. This expression is phrased as, "If {player
does [not] <verb>}". The remaining expressions, if any, test
state variables as the Post-Command rule does.
The Pre-Command Rule has the option of enabling the command
(allowing it to proceed) or disabling it (blocking command
completion). A blocked command is a failed command, and the
Post-Command rules are not processed. Pre- and Post- rules are
often used in combination. A rule in the Pre-Command Rule Base
performs operations that in turn trigger a rule in the Post-
Command Rule Base.
Pre-Command rules are rules tagged for a specific function. Some
functions turn this around and deliberately use them as a source
of user-defined messages. (See Fight, Shoot, Hit, Charm) The
User-Defined Command Parser is implemented as a Pre-Command Rule,
67
The Story Editor Figment User's Guide
but this is the subject of an entire section of this book by
itself.
1. Modifiers in Pre-command Rule Expressions
We have seen conditional expressions with modifiers, and we have
seen how we can use them or omit them in our expressions when we
want to be specific or general. Many story commands have
modifiers too, and you have the option of testing for these
modifiers or ignoring them. When you ignore the modifier, you
create a broader test case, and when you include the modifier you
create a more specific test.
For example, the expression:
If {
Player does give bat
}...
does not care to whom the player gives the bat, while the
following expression does:
If {
Player does give bat to Boy
}...
Only a few commands use modifiers, but they are critical
commands:
take - from
give - to
put - in
put - on
shoot - with
Modifiers are associated with the last argument in the
expression. If you have blanked this argument, then you will not
see the modifier either. Scroll the argument until you see the
object name you want. The modifier will appear along with the
argument name. Figment will set a default modifier commonly used
with the chosen function. Where the function allows more than
one modifier (e.g. put), you can change the modifier by hitting
the Home key and scrolling the modifier names. Hit the Home key
again and you are back to scrolling object names.
68
Figment User's Guide The Story Editor
2. Directions in Pre-Command Rules
You can test for specific directions in the "go" command. The
same philosophy applies as described above for modifiers. If you
do not specify a direction, then the rule will fire regardless of
which direction the player goes.
3. Negating Pre-Command Rules
Negation is allowed for Pre-Command Rule expressions. The first
conditional expression in a pre-command rule is phrased as, "If {
Player does (command)...}" or "If { Player does not
(command)...}". The form changes when you hit the "Home" key.
A negated command rule simply means that the rule will fire on
any command unless the player gives this command. In fact a
negated "while" rule will fire every time until the player gives
the specified command. This can be very tedious if the same
message repeats continuously so such a rule would probably
include extra conditional expressions to narrow the possibilities
of its firing.
Some functions have alternate forms and the rule can be very
specific. Consider the case where the test is:
If {
Player does not take Ball
}...
and the player says "take ball from boy", which is different so
the rule would fire.
69
The Story Editor Figment User's Guide
N. Conditional Function Reference
This section describes the Conditional functions you can use in
your rules. The next section describes the Executional
functions. Conditional functions are used in the conditional
part of a rule. They are phrased slightly different from the
executional functions in order to achieve a more natural style.
If {
Player is linked to Ball
} Then {...
seems more natural than perhaps:
If {
is linked Player Ball
} Then {...
Meanwhile, Executional functions are used in the command sense.
...} Then {
link Romeo to Juliet by Romance > 30
copy msg to Romeo's Long Description
}...
1. Does_Action
Syntax <Character> does [not] <action>
This is the primary conditional function for pre-command rules.
You only see this function when you are editing the first
expression of a pre-command rule.
The character can be any character including the Player and the
Actor.
The action is any legal command from the Presentation
Environment, but you will not find system-level commands like
"restore" or "restart" here. The syntax for the action follows
the command syntax in the Presentation Environment. Only rarely
is there a special option. For example:
If {
Actor does go anywhere
} Then ...
You will not find the direction "anywhere" in the "go" command
syntax. It is a special implementation so you can write rules to
inhibit all exits from the scene.
70
Figment User's Guide The Story Editor
2. Fit_Profile
Syntax <object> does [not] fit profile of <profile label>
Compares a set of the object's attributes to a weighted decision
matrix of attributes. See Profiles.
3. Have_Attribute
Syntax
<object> does [not] have attribute <attr label> [<>= value]
<pronoun>
If {
Actor does have attribute Wisdom > 12
}...
4. Is_dead
Syntax: <character> is [not] dead
Use this in conflicts to test for the defeat of characters. When
an opponent dies in a conflict it is probably the Player that
killed them. When Players die in a conflict, it is not clear who
killed them since there can be multiple opponents. This will
tell when the Player is dead, but it will not tell you who did
the deed.
There is also a special case where you want to use this function:
If {
Player is dead
} Then {
Kill Player
} ...
This seems especially vindictive, but Figment is always trying to
recuperate Players when their health is failing. If this healing
process coincides with the death blow, Players appear to
resurrect. This rule, however, seals their fate. It also gives
you an opportunity for some parting words.
It is probably wise to put such a rule in the Post-Command Rule
Base for any scene where a conflict can occur or you can put it
in the Global Post-Command Rule Base.
71
The Story Editor Figment User's Guide
5. Is_linked_to
Syntax
<object> is [not] linked to <object> [by link-type] [<>=value]
<pronoun> <obj type>
<obj sub-type>
<pronoun>
<obj user-type>
If {
Boy is linked to ball
Romeo is linked to Juliet by Romance > 12
John is linked to Mary by Marriage
John is linked to House by Mortgage > 100
}...
You can test for links to object types or sub-types. For
example:
If {
Player is linked to obj sub-type Money
} Then {
take * the object * from Player
}...
Another example:
If {
Player does give Flowers to Juliet
Player is linked to Juliet by Romance > 20
} Then {
Link Juliet to Player with Romance 20
} Message 1 Total Switched: ON Current Msg: 1
1. Gosh, @Player, I didn't know you cared.
6. Is_locked
Syntax: <object> is [not] locked
If {
Bear is not locked
} Then {
change Player's Health -2
} Message 1 Total Switched: ON
1. Boy these bears get mean when you chain 'em up don't
they?
72
Figment User's Guide The Story Editor
7. Is_open
Syntax: <object> is [not] open
8. Is_type
Syntax: <Stuff> is [not] <user type label>
<Scene> <type attribute>
<Pronoun> <sub type attribute>
If {
Player is user type Lawyer
}...
The type and sub-type attributes are provided for completeness.
There is no crying need for them, but they might be useful
testing pronouns.
9. Is_wizard
Syntax: <Player> is [not] wizard
If {
Player is wizard
} Then {
unlock Door
open Door
} Message 1 Total Switched: ON
1. The Shaman knows a Wizard when he sees one
and steps aside holding the door for you.
10. Probable_Event
Syntax: <value>% [not] Probable Event
This conditional function will generate a random action of your
designation. The rule would look like:
While {
15% Probable Event
} Then {
go_to_map_block 7 Over the Cliff
} Messages 1 Total Switched: ON Current Msg: 1
1 A capricious wind blows you off the cliff.
The percentage you specify determines the probability, hence the
name Probable Event. In this case, the player has a 15%
73
The Story Editor Figment User's Guide
probability of getting blown off the cliff each time the rule is
checked.
You may negate the function. Something that is 85% not probable
is 15% probable. You can also just change the percentage and
achieve the same effect.
This rule will drive you bats during debugging or demonstrating
your story even if you specify the starting seed for the random
number generator. You may have to switch the rule off manually
in the editor.
11. Say_cmnd (User-Defined Command Parser)
Syntax: Player does [not] say cmnd
This is the User-Defined Command Parser. It is only used in Pre-
Command rules. The function uses the first message in the rule
as a specification of word groups and the Boolean operations that
should be performed to form a sentence from the word groups.
Punctuation should not be used. Differences in upper or lower
case letters is ignored. Rule messages can be up to 2K bytes,
but command sentences cannot exceed 80 characters.
Example:
If {
Actor does say cmnd
<other conditions go here>
} Then {
unlock door
open door
copy msg to Door's Long Desc.
inc_msg
copy msg to Door's Brief Desc.
} Message 1 Total Switched: On Current Msg: 2
1. (Abracadabra or Shazam or Hocus Pocus)
2. With a rumbling groan, the mighty stone door swings open.
3. The door stands open before you.
A simple example like this could probably be solved with
synonyms, but not as well. Synonyms are global and act as extra
handles for grabbing built-in functions. In this case if
synonyms were used, people would be using magic words to open
doors, windows, boxes,... everything. User-defined commands can
be local to specific situations within a scene so that you can
write unique rules.
74
Figment User's Guide The Story Editor
Only the first message is tested. The remainder are left for
your use. This makes this rule form unique in that you probably
want to leave the message pointer set to the second message and
not, as is usual, pointing to the first message. If you left the
rule pointing to message number one, the effect would be as
though the command phrase were being echoed back to the player.
More discussion on Synonyms and the User-Defined Command Parser
can be found in Part III.
75
The Story Editor Figment User's Guide
O. Executional Function Reference
The executional functions are used in the second part of the
rule. You can see these functions when you scroll them in the
editor.
1. Assign_User_Type
Syntax: Assign <label> to <stuff>
<scene>
<pronoun>
Adds the user-defined object type label to the object if the
object does not already have the label. See also "Remove User
Type".
2. Change
Syntax: Change <object>'s <attribute> <value>
Changes an object's attribute by the specified value. If the
value is negative, this is equivalent to subtracting the value.
Attributes are signed 8 bit quantities, meaning they can hold
numbers from -128 to +127. Normally in computer math if you add
too much to a positive integer, you "overflow" and get a negative
number. That is, 126 + 2 = -128 in 8 bit integer math. Figment
prevents overflow; it just stops when it reaches the limit so
with the change function, 126 + 2 = 127.
While {
Player is linked to Pharoah's Curse
} Then {
Change Player's Health -2
} Messages Switched: ON Current Msg: 1
1. You feel your life force gradually slip from you.
3. Change User-Attribute
Syntax: Change <object>'s <Type 1 Attribute> <value>
<pronoun> <Type 2 Attribute>
<Type 3 Attribute>
Used to specify a value to add to the object's specified
attribute value. If the object does not have the attribute, the
attribute is added to the object and set to the value. The value
can be positive or negative.
76
Figment User's Guide The Story Editor
Attribute values are signed 8-bit integers meaning they can vary
from -128 to +127. This function does not permit overflow. If
you add 5 to 124 for example, the result will be 127.
4. Change_score
Syntax: Change_score <value>
Changes the player's score by the amount specified. Values can
be positive or negative.
5. Close
Syntax: Close <object>
Set the object's "open" attribute flag to read "CLOSED". The
open, close, lock and unlock functions are more powerful in the
rules than they are for the player during play. The player can
only perform these operations on objects whose sub-type attribute
is set to "Container", and only when the object's permission flag
lets them. The story designer, however, can perform these
operations on any object. This, in effect, reserves this flag
partially for private use.
6. Copy_Msg_To
Syntax:
Copy msg to <character>'s view of <object>'s Long Desc.
<pronoun> Brief Desc.
Exam. Msg.
This function copies the rule's current message to the specified
viewpoint of an object. The old object text is lost. The
message is also printed to the Command Window unless the rule
specifies that printing is switched off.
If the message you are copying is of zero length, it will
effectively erase the destination string.
When editing this function, set the destination object's name
first. The system will then scroll the legal viewpoints for that
object. Since many objects have only the default, Player,
viewpoint, the viewpoint scrolling will often be frozen at
"Player's view".
77
The Story Editor Figment User's Guide
Copy_msg_to is commonly used in conjunction with repetitive rules
(While and For) and the Inc_msg function to create message
progressions:
For 1 to 4 by 1 {
<some conditions>
} Then {
copy msg to Player's view of <object_name>'s Long Desc.
inc_msg
} Message 4 Total Switched: OFF Current Msg: 1
<4 messages specified>
In the example above, the rule type "While" could be used instead
of the "For" type, because Inc_msg stops at the last message so
the message progression stops harmlessly. Of course a "While"
could not be substituted for the "For" if the statement were
changed to "For 2 to 8 by 2 {...", which slows the progression
down to every other count.
7. Go_to_Map_Block
Syntax: go to Map Block <Map Block>
This executional function will change scenes from within a rule
base. When a rule fires and this function is encountered, the
scene will change to the new scene as specified from the Story
Map block number.
Assume the pre-command rule base for a given scene includes the
following rule:
While {
Player does eat Magic Cookie
} Then {
Go_to_map_block 3 Thru Looking Glass
} ...
This function behaves differently than other executional
functions. Normally an executional function just executes
immediately. However, changing scenes also means the rule base
will change so a jump to a new scene in the middle of processing
the rule base would also jump you to the middle of another rule
base. Not good. Moreover, we want all the other rules to have
their chance to vote on the action as they do with all commands.
Therefore, this function is designed to wait until the pre- and
post-command rule bases are completed before jumping to the
specified scene.
78
Figment User's Guide The Story Editor
If you use this function in a pre-command rule as in the example
above, you can control it with the "Enable" switch. If you
disable the function, the post command processing is not
performed and the jump to the new scene is also not performed.
Other pre-command rules can also be testing for the "eat"
command, and they in turn might disable the "eat" command and
thereby inhibit the jump.
If there are multiple rules checking for a command, you will
probably want this rule to be a "While" rule. Otherwise, it will
expire, but Figment will not jump to this scene, when other rules
block the command. When the player's actions eventually satisfy
the various rules involved, the "while" rule can still fire and
trigger the jump to the new scene.
When used in a post-command rule, Figment will allow the post-
command rule base to complete before changing scenes. Then, it
changes scene and cycles through the post-command rule base for
the new scene. This method preserves the appearance of a "go"
command.
Notice that you are specifying map blocks, not scene object
names. If you are using a complex map (see the User's Guide for
a discussion of complex maps), you will get the correct map block
that you want.
8. Inc_moves
Syntax: Inc_moves
Used to increment the move count when your rule disables the
player's command and you do not want to give the player a free
move. It increments one move at a time, but you can use it
several times in the same executional clause.
9. Inc_msg
Syntax: Inc_msg
Increment the rule's message pointer one message after the
message has been displayed on the command line or copied to an
object (see also Copy_Msg_to). Rules can have a total of up to
16 messages, but usually less. Inc_msg will never exceed the
existing total. If Inc_msg were to execute five times while the
message total was set to 2, the second message would appear four
times.
79
The Story Editor Figment User's Guide
For 1 to 5 Step 1 {
<scene> is_linked_to Stage Coach
} Then
inc_msg
} Message 5 Total Switched: ON Current Msg: 1
1. You see a cloud of dust on the horizon.
2. Hmm. It's the Wells Fargo Express.
3. You pull your bandanna over your face and check your
pistol.
4. Thundering hooves drown out your pounding heartbeat.
5. You race from hiding and rob the stage.
10. Kill
Syntax: Kill <character>
Usually used by the Story Designer to terminate the player and
hence the story when the player attempts a conspicuously bad
action. It can also be used to defeat the conflict "escape
clause" (see also is_dead).
11. Link_to
Syntax: Link <object> to <object> by <link_type> [<value>]
<pronoun> <pronoun>
Adds a reference to the second object in the first object's link
list. The Link function creates a link of the specified type and
sets the value to the specified value. Example:
...} Then {
Link Romeo to Juliet by Romance 12
}...
You cannot make duplicate links with this function. If the link
of the specified type already exists, the expression value is
merely added to the existing link value.
Links are one-way in Figment. The Juliet-object now shows a link
reference to the Romeo-object. If the feeling is mutual then add
another expression for the opposite link. Otherwise, this is
unrequited love, but who actually loves whom? That all depends
on what messages you print when you test the links. You can
write the text either way.
80
Figment User's Guide The Story Editor
12. Lock
Syntax: Lock <object>
13. Msg_to_name
Syntax: Msg_to_name <object>
Copies the rule's current message to the object's name thereby
renaming the object. This is fully legitimate and often done.
Since Figment is designed to reference the current object name at
all times, your rules using the old name are automatically
switched to the new name so they function as intended.
14. On_skill
Syntax: On_skill
The on_skill function sets the rule's message pointer according
to the Player's current skill level. There are 5 skill levels
and 16 possible messages. Thus the first message is used for the
first (novice) skill level, and the second message for the second
level, etc. You are not required to specify a message for each
level. The message pointer then stops at the highest message
specified. For example the following rule generates one message
for novices and a more informative message for more experienced
players:
If {
Passage Door is_locked
} Then {
on_skill
} Message 2 Total Switched: ON Current Msg: 1
1. The sign reads: "Forbidden Zone".
2. The sign reads: "Forbidden Zone", but you don't
believe everything you read do you?
This function is special in that it must appear first on the list
of executional functions for the rule, otherwise, it will be
ignored.
81
The Story Editor Figment User's Guide
15. Open
Syntax: Open <object>
Set the object's "Open" attribute to read "OPEN". This function
does not concern itself with the status of the object's lock
flag.
16. Remove_User_Type
Syntax: Remove user type <label> from <object>
<pronoun>
See also "Add User Type".
17. Take_from
Syntax: Take <object> from <object>
Removes a link entry in the second object's link list that refers
to the first object. If the object is not linked to some other
object, it is out of play until another rule links it to
something.
If {
<test conditions here>
} Then {
take Royal Jewels from Player
link Royal Jewels to <scene_name>
} ...
The above example is equivalent to the command "drop" except the
player does not give the command. Since no message is given, the
player might not even be aware that it happened, although the
object's description will now appear in the scene description.
18. Toggle_lock
Syntax: Toggle_lock <object>
Changes the object's lock attribute flag from ON to OFF or from
OFF to ON. See also "lock" and "unlock". Also ignores the lock-
enable flag.
82
Figment User's Guide The Story Editor
19. Toggle_open
Syntax: Toggle_open <object>
Changes the object's "open" attribute flag to OPEN from CLOSED or
from CLOSED to OPEN. Also ignore the open-able flag. See also
the executional functions close and open.
20. Unlock
Syntax: Unlock <object>
Changes the object's lock attribute flag to OFF.
See also the executional functions lock and toggle_lock.
83
The Story Editor Figment User's Guide
P. Player Maps
Figment uses the Story Map to track scenes and the directions
from those scenes to other scenes. The Player is assigned a
similar map to track map knowledge acquired as a result of play.
The Player Map tracks the scenes that the player has visited and
the directions used from those scenes.
Initially, the player has a very limited knowledge of the Story
Map. Only the starting scene is known at the start of play (but
the author can specify more). When the player moves to a
different scene, the player's knowledge of the new scene is added
to the Player Map. The player only acquires the direction
knowledge that he or she has actually used. That is to say, just
because you have visited a scene, does not mean that you know all
the possible exits from that scene.
The "go" command during playback can refer to places (scenes) by
name and Figment will compute the path to the scene from the
Player Map. Similarly the "find" command computes a path to a
scene that has the object the Player wants to find.
Often, you want to give the Player foreknowledge of places and
things. For example a story about a haunted house would probably
speak of the public rooms: living room, dining room, front hall,
et cetera so you want people to refer to them naturally by name
as in "go to the Living Room" or "find the coffee table". On the
other hand, you do not have to tell them about the secret
passageway in the library.
The Story Designer can edit the Player Map to provide any amount
of environmental knowledge as required. Editing the Player Map
is similar to editing the Story Map, but the Player Map can never
be more than the Story Map. You are not really constructing a
map when you are editing the Player Map. You are specifying
values as "on" or "off" meaning the player knows or does not know
this scene or direction.
The Player Map screen editor is accessed from the Top Level
Editor. It is the screen following the Story Map. You move the
cursor in the same manner as with the Story Map, but the values
that scroll are restricted to only those contained in the Story
Map. Thus when you set a value in the Player Map you are saying
that the player knows this scene or a direction from this scene
in the Story Map.
You cannot add or delete blocks from the Player Map. You are
restricted to the same blocks as defined by the Story Map. You
turn them off or on by moving the cursor to the appropriate
84
Figment User's Guide The Story Editor
location and scrolling up or down with the up-arrow or down-
arrow keys.
You cannot edit the directions from a scene until you specify the
scene in the map block title. (The Player cannot know the exits
from a scene until the scene is known). If you turn "off" the
scene in the block title, any directions you have specified are
also turned off.
If you want the Player Map to be equivalent to the Story Map, you
can dump the Story Map to disk with F3, change the screen to the
Player Map and read the map data into the Player Map with F2.
This is a handy technique since it is often easier to say what
you don't want than it is to say what you do want.
It is a good idea to compare the Story Map with the Player Map
you are making. This is easy to do. Go to the Top-Level Editor
and switch between the two screens while studying one block at a
time. You will notice entire blocks or exits from blocks that
you will want to specify.
Q. Synonym Editing
Figment allows you to specify synonyms for both functions and
objects. A synonym simply allows you to substitute any phrase
consisting of any number of words for a Figment command or an
object name in the story. It allows you for example to say:
>cut the rope or
>pick up the rock
instead of:
>unlock the rope or
>take the rock
In the examples above, you would still write rules that test for
the "unlock" and "take" functions. Rules will never refer to
synonyms. "Cut" is not actually a command.
Synonyms take a lot of the frustration out of stories, and their
use is encouraged.
Synonym editing is simple and straightforward. We'll skip the
navigation discussion. New synonyms are created by hitting the
"+" key and they are deleted with the "Delete" key. The text is
typed in or edited.
85
The Story Editor Figment User's Guide
Synonyms form a part of your story file. They also can be dumped
separately so that you can move them into new stories. You will
want to do this. If you get used to saying "look" for "examine"
you will quickly notice its absence in your new story.
R. Parameter Editing Screen
This screen editor includes two separate editors: the Parameter
Editor and the Status Editor. From the Top Level Editor, Page-
Down. The cursor lands on the title "Parameters". You can
advance the cursor to the "Status Editor" to access that editor.
There is also an indicator panel to tell you how full your story
is to aid your planning.
1. Parameter Editor
Parameter editing allows you to change some fundamental story
parameters. By now you should understand the editing process
enough that we can dispense with discussions of page-down and
arrow keys and simply focus on the parameters themselves.
a. The Title
The title is a text string that you provide. You may use this to
include your copyright statement if you like. The title with its
copyright statement is written to the save file and fulfills the
requirement of the copyright laws for embedding your copyright
statement in the data files. It is also displayed each time the
story is retrieved, also in compliance with the requirements of
copyright law. Most texts on copyrights say it is good practice
to make a copyright statement early in the development process.
You never know if you might want to publish it.
The title message is allocated its own screen at the start of the
story. If you define a title message, Figment will pause after
printing it and print the message: "Strike any key to continue."
The intention is that you will define a title with perhaps a
copyright statement, an abstract or introduction, licensing
information, etc.
The user's name is also requested in the title message processing
whenever you include the word "@Get_User" in the title. You can
do this at the start of the title, and echo it back later in the
message with "@Full_name". The name is parsed into the @User[]
names, and the Player name is set to @User[0], the user's first
name.
86
Figment User's Guide The Story Editor
Usually during development, you do not want to be bothered with
user name processing so you omit the keyword "@Get_User" from
your title. Later when you want to distribute your story, you
replace the keyword.
b. Exit Message
The "Exit Message" string will be printed whenever the player
quits or is killed. The copy_msg_to executional function can
copy rule messages to the exit message so that you can maintain
it during the course of your story.
c. Password
You can assign an optional password to your story that will
prohibit people from editing your story. When this string is
defined, Figment will prompt you for the password before it
switches to editing mode with the F1 key.
d. Default Player Name
This name is assigned to the Player object during start-up. It
is used regardless of what name has been left assigned to the
Player object during play or editing. This eliminates the need
to set this with rules during start-up.
e. Moves and Score
The move count and the score can be adjusted here. The Shift-F3
function automatically zeroes them before saving the data. You
can adjust the move count and score in order to modify the skill
level (displayed here for convenience) for debugging skill-
dependent sequences. The Move counter must be greater than zero
in order for the skill level to change (guards against divide-
by-zero error).
f. Recuperation Parameters
"Recup-int" means "recuperation interval". When the Player's
health is low, Figment restores the Player's health slowly over
time to represent a healing process. Increasing this interval
slows the recuperation process while decreasing it speeds it up.
g. Food parameters
"Food-cnt" tracks the current food point status. This value
increases as the player consumes food and decreases one point at
a time in an interval specified by "Food-dec-int". Setting a
87
The Story Editor Figment User's Guide
high food count and a large interval will effectively eliminate
food concerns from your story if you would rather not bother with
it. Going the other way will have your player consuming
everything in sight in a desperate attempt to stay alive.
Figment begins warning you when the food count is getting low.
"Food-msg-int" specifies the interval between these messages.
The appropriate size would be:
initial-food-count * food-dec-int / 5 = food-msg-int
You can always specify other values which makes Figment more or
less of a food nag.
h. Brief Enable Switch
The processing of brief messages can be disabled by setting this
switch. This greatly eases story development and reduces the
data file size. The default mode is "Disabled". When you want
to add brief messages to your story, change the switch to
"Enabled".
When brief-mode processing is disabled, Figment uses the Long
Description message always. When Brief is enabled, Figment uses
the brief message when one is defined, otherwise no description
of the object is printed. Remember that brief mode descriptions
are used only when you return to a scene you have been in before.
2. Status Editing
The status banner displayed at the top of the screen during
playback can be modified to display the parameters and attributes
you want to use.
The status banner is composed of active elements that report the
various parameters as formatted text. The various text pieces
are strung together as a single line of text. Hit the "+" key to
add a new element. Hit the "Delete" key to remove an element.
Scroll the parameters using the up- and down-arrow keys. Hit the
Home key to access a different data type. The data types are
arranged as follows:
Story Parameters: Score, Moves, Current Scene Name, Log Name
Actor's System Attributes: Skill, Strength, Health, etc.
Actor's Category I User Defined Attributes
Actor's Category II User Defined Attributes
Actor's Category III User Defined Attributes
88
Figment User's Guide The Story Editor
Repeated strikes of the Home key will cycle the data types from
Story Parameters through the System Attributes and on through the
various User-Defined Attributes.
S. Help Messages and User Type Editing
These two editors are combined on one screen. Move the cursor
over the desired editor and hit page-down.
1. Help Message Editor
Every map block has a help message string. You can edit them
here. If there are more blocks than lines, just keep hitting
page-down and they will begin to scroll until you find the one
you want. Edit the text in the normal manner with the typing
buffer or the full-screen editor.
During play, the copy_msg_to function in your rules can copy new
messages to the help message. This allows you to create context-
sensitive help.
Usually the help message is more instructive as opposed to the
examination messages which might be descriptive.
2. User Type Label Editing
User type labels for objects are text strings that you create to
describe things. They might be character types: "Cleric",
"Warrior", "Thief", or they might be object types: "Car", "Boat",
"Plane" or anything else you can think of. You might also
categorize scenes: "Chase Scene", "Death Scene", "Romantic
Interlude", etc.
You can add and delete labels with "+" and "Delete" keys.
Labels can be as many characters long as you like, but we often
can only print the first 10-16 characters so brevity helps.
Don't make duplicate labels.
When you delete a label, Figment checks for references to that
label in other data structures. Object type labels are used in
objects and rule expressions ("is_user_typ" and "assign"). If
some data structure uses this label, Figment reports it and
stops. You must remove this reference by going to that data
structure and deleting the reference before you can delete the
label. There are probably more references like this one so you
will want to check for them before returning to delete the label.
When there are no references to a label, it is easy to delete it.
89
The Story Editor Figment User's Guide
It is much easier to rename a label. Just type a new name for
the label. All references to the label will reflect the new
name. Figment really does not know what your labels mean, it
only knows that deleting them can destroy a lot of other work so
it checks before deleting.
This process is deliberately similar to that for the Link Types
and the User Defined Attributes so once you get the knack, the
others follow neatly.
T. Link and Attribute Type Definitions
A separate editing screen is used to specify the link types and
attribute types. The method of editing is sufficiently similar
that we can discuss them together. The process is very similar
to that for User-defined object types. As before, Link and
attribute types are merely text labels that you create to
identify a link or attribute you want to use.
The labels you make can be as long as you like, but screen space
limitations mean we can often only display 10-16 characters
depending on where they are used. Abbreviations are fully
legitimate. Use them as needed.
Do not duplicate link labels. User Attributes can duplicate if
the duplicate labels are in separate categories. For example,
"strength" might be a physical, psychological or spiritual
attribute for a character. If you felt that way, then you would
list strength separately in each category.
You can delete link types and user attributes. As with object
types, Figment reports the first conflict it finds and stops.
Delete the reference, and you can come back and delete the label.
Link labels are used in objects and rule expressions ("is_linked"
and "link"). Attribute labels are used in objects, rule
expressions, and profiles.
You cannot delete link type "Generic".
The editing keys work in the by-now-familiar manner. "+",
Delete, Page-Up, Page-down keys perform as they always do. The
ESC key is a rapid exit to the next highest level.
U. Profiles
Profiles are a weighted decision matrix applied to an object's
user attributes. They allow you to list attributes and apply
weight factors to arrive at scores. The resulting scores can
90
Figment User's Guide The Story Editor
return TRUE/FALSE values if they are above or below the cutoff
criteria.
For example, assume you want to determine if Romeo and Juliet are
lovers. You might write the following rule:
If {
Romeo does fit profile of Juliet's Lover
Juliet does fit profile of Romeo's Lover
<other conditional expressions>
} Then {
Link Romeo to Juliet by Romance Value 20
Link Juliet to Romeo by Romance Value 20
} ...<sound of violins and waves crashing on beach>
More information on profiles can be had in the User's Guide for
Registered users.
V. Standard Messages and Text Variables
Standard messages can be used as "text variables" to create
specially-adaptable messages.
Text is used in several places:
object descriptions
object examination messages
command responses (from rules firing)
Wherever text is written, the user can include the special text
symbol: "@Msg: nnn", where nnn means some number, three decimal
digits or less. Figment will remove this symbol during
processing and insert the message as specified by the number.
(see @-Words)
A separate editing screen is provided where the developer can
write these standard messages. Their only identifier is their
number so they are referred to as Standard Message 1, Standard
Message 2, etc. to differentiate them from rule messages.
By themselves, Standard Messages can simplify development and
maintenance. Where a line of text is used frequently, the
developer can write it once and use it repeatedly. Maintenance
is thereby simplified too, because only one instance must be
corrected.
Further, you can create text composed only of standard messages.
You can write rules that copy their messages to the standard
messages. The result is that the standard messages function like
91
The Story Editor Figment User's Guide
text variables to form a larger body of text that changes as
different rules fire.
When you are using Standard Messages as Text Variables, the
message can look odd, because it is often just a scrap of text.
A standard message might read:
12. and it has the old text I don't want anymore.
Then the object's examination message can include a reference to
Message 12 among the text that it reports:
"This is the object's examination message, @Msg: 12"
making the examination message read:
"This is the object's examination message, and it has the
old text I don't want anymore."
92
Figment User's Guide The Story Editor
A rule might then say:
If {
<something>
} Then {
copy msg to Standard Message 12
} Messages 1 Total Switched: ON Current Msg: 1
1. and it has the new text I want to see.
When the rule fires, the examination string now reads:
This is the object's examination message, and it has the new
text I want to see.
Of course text can be composed only of Standard Messages:
"@Msg: 5 @Msg: 2 @Msg: 9"
or if you want paragraph breaks in the report:
"@Msg: 5
@Msg: 2
@Msg: 9"
The result is a unique string composed of standard messages which
can be changed as rules fire and copy their messages to the
Standard Messages. It is probably difficult to make a reasonable
body of text if you are trying to manipulate a composition made
from more than a few messages. Complexity rises rapidly here.
1. Editing Standard Messages
Editing the messages is easy. The '+' key adds new messages.
Deleting standard messages can cause headaches. If you delete
Message #2, for example, Message #3 becomes #2. If your text
refers to Message #2, it will get a different message than was
originally intended. This reference has to be edited manually by
changing the text. Not fun, especially if there are 30 messages
after #2. Consider just blanking the message instead. You can
use it later if you need another standard message.
93
The Story Editor Figment User's Guide
W. Full-Screen Text Editor
The full-screen editor implements a limited sub-set of text
processing commands available on full-function word processors.
It is designed so that it can be invoked seamlessly from the
typing buffer since most story messages start small and grow
suddenly when inspiration strikes.
To invoke the text editor, simply hit F6 at any time while typing
text anywhere in the Story Editor. The screen erases and the
text you began to type and the text it was replacing are put into
the editing buffer and displayed on the editing screen.
The cursor keys now behave like word processing keys:
Left- or Right-Arrow moves the cursor one character.
Up- or Down-Arrow moves the cursor one row.
Home moves cursor to start of row.
End moves cursor to end of row.
Page-Up moves cursor to start of buffer.
Page-Down moves cursor to end of buffer.
Ctrl-Left- or Ctrl-Right-Arrow moves cursor one word.
Ctrl-end deletes text from current cursor position to the
end of the current row.
Delete deletes one character in front of cursor.
Backspace deletes one character behind cursor.
Escape exits the editor.
CTRL-X exits editor, but discards the changes returning the
original string unchanged. Use this when you goof.
Just type text as you would in any word processor. When you are
through, simply hit Escape. The screen erases, and you find
yourself back in the Story Editor with your cursor pointing to
your new text string.
The editing buffer is limited to 25 lines of 80 characters.
(When we say it's a full-screen editor, we mean it - ONE full
screen.)
See also the discussion on hard and soft returns in section
I.A.2. titled "Editing Text" earlier in this document.
94
Figment User's Guide The Story Editor
Tabs are not implemented in the editor since their results would
be unpredictable during playback as messages are combined in
different ways.
X. File Management
Playback quickly alters the data you so carefully edited so good
file management skills are important to protect your work.
Figment can produce a great many file types that may seem
confusing at first. This section discusses these various files
so you can manage them properly.
1. File Naming Conventions
When you start a story, default file names are constructed from
the story name and some standard file extensions. Other
utilities like logging and scripting also produce files with
special name extensions. You can recognize the type of file by
its extension. These extensions are:
.sdf - story data file
.sav - saved data file
.bak - last saved file
.lst - listing or script output
.log - log file
Of these, the files you really want to archive are the Story Data
File and the text form of your log file if you have one. The
rest can be periodically purged from your disk. The DOS batch
file, "purge.bat" is provided for that purpose. Edit this batch
file to suit your needs, but rename it so it will not be
clobbered by the old purge batch file when you upgrade.
You should recognize the story file by now since it is the file
that you read in at the start of the session. The save file is
the file you write with the "save" command in the Presentation
Environment or the Shift-F3 key in the editor. Figment cannot
write a story data file (".sdf"). It can only write a save file
(".sav"). In this way, the story data file is protected and
never over-written. It preserves the data in the form you want
it for startup. To make a story data file, simply rename a save
file using the DOS command, "rename":
rename demo.sav demo.sdf
Another way is to copy the data:
copy demo.sav demo.sdf
95
The Story Editor Figment User's Guide
You might do this at the end of an editing session so that the
story data file is ready for the start of the next session.
The save file represents work in progress. It is good practice
to keep it separate from the story data file until you have had a
chance to test it out and build confidence that it is doing what
you want. When you are satisfied with it, you can rename it to a
story data file. Some people like to copy it to a working name
so they can start figment with that name, otherwise you must use
"restore" after starting to get your working version loaded.
copy demo.sav temp.sdf
figment temp
Later, you can rename or copy the working copy back to the
intended name:
rename temp.sav demo.sdf
The best way to get started is to copy our demo file so you can
begin creating your own files for practice.
copy demo.sdf <new_name>.sdf
Then start Figment with that name:
figment <new_name>
You can start a completely new story by making up a new name that
does not exist on your disk. Use that name to start Figment:
figment zilch
Figment finds no file named "zilch.sdf" so it starts without it.
You arrive in Figment staring at a very dull story. You then
enter the editor and begin creating your data. When you save
your data, you have a new file called "zilch.sav"
2. Read-all, Write-all
Shift-F2 and Shift-F3 are the primary read-write tools for
developers. These are similar to "save" and "restore" in the
playback environment, but there is one important difference.
Shift-F3 is designed to prepare the save file for use as a story
data file (.sdf file). This means it will set important data to
the values they should have at the start of the story. For
example, the move count and the score should be set to zero. The
scene should be set to the first scene in the map, et cetera.
96
Figment User's Guide The Story Editor
The process sounds good on paper, but recognize the limitations.
Figment cannot tell what the Player's health should be for
example or any of many attributes and associations. Figment does
warn you before editing if you have been playing your story so
you should have retrieved your file from disk before editing.
The Shift-F3 function really expects that you will be developing
with a log file to play the story through a standard set of
commands as you work to debug your story. Without this log file,
the Shift-F3 function's automatic reset will certainly aggravate
you. If you did not want the automatic reset, you could hit F1
to return to the playback environment and then say "save". This
would save the data without the automatic reset.
Except in rare instances, the "save" command is not recommended
for developers. Use Shift-F2 instead.
The "restore" command and the Shift-F2 function are the same.
3. Data Backups and Version Numbering
After you quit Figment, you may want to make backup copies of the
files you made on a separate diskette. Use the DOS COPY or XCOPY
command to do this.
At the least, you will want the ".sdf" file, but you may want any
others you have been making, for example logs. The following
command will copy all the files for a story from the current
directory to a diskette in drive B.
copy <story name>.* b:\*.*
You can, if you like, rename the files at this time and thereby
create version numbers:
copy story.* b:\story2.*
The advantage, of course, is that you can go back and retrieve
old versions should you discover some disastrous consequence of
your editing.
As mentioned previously, the listing file produced for the rules
is expendable. You can see that if you do not delete it before
copying the set, you will be proliferating obsolete listing
files. We recommend that you print any listings that you want,
then delete "*.LST" before copying the data set.
97
The Story Editor Figment User's Guide
The DOS batch file, "PURGE.BAT", will delete the data set files,
the backup file and the listing file for a story. It will not
delete story data files, log files, nor save files. It is a
useful tool for cleaning up a disk or directory that is cluttered
with obsolete files. To use it, simply type "purge <story_name>"
(where <story_name> means you type the name of the story) from
the DOS command line prompt.
4. The Data Set Files
The Data Set read/write functions (F2/F3) have largely been
superseded by the restore/save functions (Shift-F2/Shift-F3) and
so have most of their applications. The Data Set files let you
dump portions of your story so you can read them into a different
story. Yes, as a matter of fact, you can screw up your story
using F2/F3 so they are not recommended for beginners or the
faint of heart. Information on the Data Set files can be found
in the User's Guide for registered users.
Y. Deleting Objects
As mentioned earlier, deleting objects is easy: advance the
cursor over the object name and hit the "Delete" key. The
problem is the object references, and it is similar to handling
the "(Not Found)" problem.
Figment inserts a reference to a dummy object named "(Deleted)"
wherever there is a reference to an object you are trying to
delete. When all references have been replaced, it safely
deletes the object. Figment cannot resolve what to do with these
references so it does not try. It simply leaves this dummy in
place for you to correct at your leisure. There are many places
this object might be referenced:
Link lists in other objects
Rules
Story and Player Maps
Deleting one object can make many references to the "(Deleted)"
object. Deleting several objects at once simply makes more
references and it can make it hard for you to figure out the
right correction. Maybe you want to delete one object at a time.
Note when deleting scenes that this does not remove rule bases.
The map block that referred to this scene is simply titled
"(Deleted)". Only when you delete this map block in the map
editor will the rule base for that map block be lost. You may
play your story with the map still referring to deleted scenes.
98
Figment User's Guide The Story Editor
When you arrive in a deleted scene, Figment politely reports,
"This scene has been deleted." This should be your cue to fix
your map.
You can leave these references to "(Deleted)" in place, play your
story and fix them when found. The sky has not fallen and panic
is not required. You can even write and read the story to/from
disk. The reference to "(Deleted)" stays with you until you are
ready to fix the reference. It is simply a civilized reminder
that you have some editing to do. As with all edits you will
want to write the repaired data to disk when done.
Recognize that if you are deleting an object just to replace it
with a different object, then you should not delete the object at
all. You should rename it.
Z. Debugging Tips
By now, it should be clear that the data in the editor reflects
the current state of the story when you entered the editor. This
means that the editor functions well as a debugger because it can
display any data at will. Coupled with a log file and its pause,
interrupt and single-stepping features, this is a powerful
debugging technique.
This section gives you advice for what to look for in the editor
when you have a problem with your story. Once you have
identified the problem, read in the data from disk to reset the
data to the starting condition, fix the problem, then file the
data back out and go back to the Presentation Environment to try
your fix.
If you are not getting the messages in the description you
expected, check the scene object and the objects in the scene.
If the messages are there, but not displaying, check the
attributes. If the attributes are wrong, the object might be
ignored. If the attributes are right, look at the scene object
to see if the offending object is linked in to the scene. Most
likely this problem occurs with new objects when you forget to
set the attributes or link it into the scene.
If you are not getting messages you expect from rules, you can
have several problems:
Check to see if the message has switched off.
Check the rule type. Is it an "If" rule that has switched
off when it should have been a "While" rule that would stay
on?
99
The Story Editor Figment User's Guide
Do the conditions hold true?
If the rule conditions require links between objects, do
those links exist?
Is the message pointer displaying the wrong message
currently in the editor?
Did you leave the message print switch set wrong?
Did you omit an "inc_msg" step in the executionals?
Check Pre-command rules to see if you forgot to set the
enable/disable switch.
Check the order of rules. Does a rule that should establish
the conditions for this rule come after this rule? Change
the order.
If you have been deleting objects or juggling data files,
look for a reference to "Deleted" or "Not Found".
100
Figment User's Guide Story Design
Part III. Story Design
So far we have discussed what Figment is, how it works, and its
commands and procedures. This section discusses some of the
finer points of story design that are not immediately obvious
from the mechanical descriptions so far.
A. Skill Level
You need not worry about the skill level in the early stages of
your story design. This is an embellishment that comes later in
the evolution of your story. Once your story has developed a
structure and you can point to key milestones in the play, then
you can award points with "change_score" when the player
completes certain tasks.
Skill can be considered a measure of the player's efficiency. If
the player achieves point awards (that you the story designer
give the player) greater than or equal to the number of moves,
then the highest skill level is achieved. There are five levels:
Novice, Average, Pro, Expert, and Wizard.
A player's health grows slowly over time to a level limited by
the player's skill. Since health points are the "fuel" for
battle, player's with greater skill can start from a greater
advantage. This is a minor point, however.
Similarly, the maximum food-count that a player can achieve is
also a function of skill. Thus excessive food is wasted on
novices, while wizards get more mileage from their food. Maybe
they are in better training.
A good rule of thumb might be to award a number of score points
with "change_score" equal to the minimum number of moves required
to complete a scene. (Actually, you will have to award a few
extra points for round-off.) This strategy makes it
theoretically possible to attain Wizard status although it will
be practically impossible.
See also the discussion on strategic weapons later in this
section since they are the only thing that absolutely requires
skill.
B. Examine Strings
Examination strings are a useful way for providing necessary
clues so that play can proceed. The "on_skill" function was
specifically intended so you can pass clues at an appropriate
101
Story Design Figment User's Guide
level of difficulty based on the player's skill. You might
choose to reveal more information to highly skilled players as a
reward for earning their high status. On the other hand, you
might take pity on beginners. In practice, you might do some of
both at different times in the story.
Examine strings are also used to write victory messages in
conflicts. See also "Conflict Conclusions" later in this
section.
C. Health Points
As mentioned your health suffers in conflicts. It also suffers
from hunger. When the player's health is low, Figment begins a
recuperation process by gradually incrementing the player's
health until it reaches limits according to the player's skill.
Depending on how you have composed your scene, you may have to
speed this process up.
You can manipulate this directly with executional functions in
rules by concocting some literary device ("You discover a healing
potion") and award extra health points with the "change_health"
function. This can also back-fire ("Sorry, this must have been a
bad batch.").
Potions and food, when consumed, add their health attributes as
well. You can sprinkle them throughout your story, but you
cannot dictate when the player will actually consume them.
Players can be understandably gun-shy about them since they can
also backfire on them with negative attributes. See the
discussions on potions and food later in this section.
You can also control the rate of recuperation for the story in
the parameter editor. Fast-paced stories with many fight
sequences may require faster recovery. Increasing the
recuperation rate increases the probability that the player will
escape defeat in conflicts. See also the escape clause
description under "Conflicts" in this section.
D. Strength
A player's strength can grow steadily to the maximum (+127) value
after sufficient conflicts if you do not create some pitfalls to
reduce it. For a while, you can compensate for this with more
potent bad guys, but eventually, you may have to prune the
player's strength level. Poor health of course reduces the
player's strength automatically.
102
Figment User's Guide Story Design
Similar thoughts apply to magic. There are no automatic
reductions for magic so you must apply your own.
E. Conflicts
In order to start a conflict (Hex or Fight) the opponent must
have some health points, otherwise you immediately defeat your
opponent. If this happens, it probably means the story designer
did not intend for you to engage this character in conflict. As
a story designer, perhaps you do not want to signal your
intentions so clearly. You may want to give all your characters
some health points so they can put up some kind of fight.
Note that you are not required to give your characters any
strength or magic points. The player can engage these characters
and quickly dispatch them. They must have neither strength nor
magic for this to occur (Otherwise, the character might deflect
you. Read on.).
You do not grow by defeating wimpy characters without the
necessary qualifications (magic or strength), but you get a point
award as though this were a good thing to do. In fact, you might
be eliminating someone who could help you solve a puzzle, in
which case you won a small consolation, but lost in the end.
An opponent who has only magic, but no strength will deflect you
if you attempt to fight the character. Similarly, you will also
be deflected if you attempt to hex a character who has only
strength and no magic. In this way, you are coerced into the
correct form of conflict. Characters can have both strength and
magic, in which case you can either fight or hex them, but not
both since they (or sadly, you) will be eliminated by one
conflict or the other.
Although you are locked into a fight to its conclusion, the story
still proceeds as you fight. That is to say that each wager
counts as a move and the post-command rule base is still
processed with each move. This means that other actions can
still transpire while you are engaged in battle. Consider using
"hit" and "charm" when characters gang up on you. At least then
you might be able to retreat.
Perhaps we should not tell you, but there is one loophole out of
conflicts. The fight ends when you lose all your health, but
Figment doles out health points when you are ill. If the killing
blow drops you to zero only, and if it happens to be that move
when Figment gives you a health point, then you are out of the
fight but miraculously saved. We recommend you flee. (Yes, this
was a bug, but we liked it so much we made it a feature.)
103
Story Design Figment User's Guide
1. Conflict Conclusions
You may have noticed there are no gruesome remains after
dispatching your opponents in battle. (This is a family show.)
Figment's little minions quickly spirit away the remains leaving
any objects the character possessed behind as booty.
This can be used as another way to introduce new objects into
play since objects that characters have are not known to the
player unless you happen to write messages mentioning them. Note
that there is nothing to stop a player from taking these things
directly from the character unless you write pre-command rules to
prevent them. Of course it is extremely difficult to take what
you do not know is there, but this knowledge quickly comes with
repeat plays. (Skill from experience again.)
When the conflict is over, Figment reports the examination
message for the victor. Thus if you want a clever message to
appear at the end of the conflict, you write a Pre-Command rule
that loads the examination messages for the character and the
player. Since any existing examination messages are probably not
appropriate for the moment of victory, you will have to write a
rule just to blank them so you may as well write some appropriate
message.
You can also use this rule to award points in advance in addition
to the one that the player will get for winning. If the player
loses the battle, the score is irrelevant anyway so there is no
harm in awarding extra points in advance.
2. Negative Attributes in Conflicts
The editor prohibits negative attributes for all objects except
those of type "Thing", but the Player's attributes can go
negative as a result of consuming food and potions. Since
conflicts take the sum of the appropriate attributes in order to
weight the outcome, a negative attribute can serve to handicap
the Player. There are two possibilities. Consider them when
debugging conflicts.
One possibility is that the player's attributes themselves are
less than one. In which case, Figment will not allow the player
to enter the conflict in the first place.
The second possibility is that the player may be carrying objects
with negative attributes. Figment sums the attributes of the
104
Figment User's Guide Story Design
player's possessions to arrive at a value for weighting the
results of the random number generator.
Figment grants one small boon when dealing with negative
attributes. If the sum of the attributes is negative, Figment
adds the minimum to the Player's attribute to allow the conflict
to proceed. In the extremely unlikely event that the player
might win, the added attributes remain as a bonus even if the
offending objects are later dropped.
Whether or not the player succeeds as a result of this, depends
entirely on the opposing character. If the opposing character is
weak, then the player stands a fair chance of winning. This
gives rise to an interesting situation: present two characters,
one weak, one strong. If the player fights the weak character
first, then drops the handicap, it is possible that the player
will then have sufficient strength or magic to defeat the strong
character, but the player must choose which to fight first.
F. Links
Links were originally very simple: A was linked to B, that was
it. Now links include types and values which makes them
significantly more complex to develop and track during play. Our
advice to beginners is to ignore the link type and value until
your work grows to a point that needs to distinguish the link
type. A plain, vanilla, generic link is all you need for most
tasks.
You can have links to as many as 32 objects, unless you have set
the limit attribute to less. Restricting links in this way
causes certain effects. For example, you may not want people to
load a container too full. Characters with low link limits will
refuse things that are given to them.
Figment will not let you exceed the link limit set for an object.
The most likely objects to exceed their limits are the player,
any scene, and any container. The commands "put", "take",
"drop", and "give" are designed to insulate objects against
exceeding their limits, but there is no guarantee you will like
the way it is done. For example, when you drop an object and
exceed the scene's limit, you get the message "You drop the
<object>...and it disappears!". This is really a statement of
last resort, because players tend to function like hyperactive
pack rats grabbing everything that isn't nailed down and dumping
them in some convenient scene. Therefore setting a low link
limit on a scene makes it a very inhospitable place for orphaned
objects.
105
Story Design Figment User's Guide
The executional function, "link", cannot be so subtle. If this
function encounters a limit during play, it prints a nasty error
message to the command line. This message is really aimed at
you, the developer, not the end user. If you have designed your
story and tested it well, you should not see this message during
normal play.
Avoid duplicate links. They are fairly harmless, but you should
avoid them anyway. The second link would be ignored until the
first one was removed. The executional function, "link", will
not make a duplicate link; it just changes the value when the
intended link duplicates an existing link.
There is nothing to say that an object cannot be linked into many
different scenes. Often, this might be a standard feature so
there will not be any confusion if the player should attempt to
take the object, but it does not have to be a feature.
Containers greatly expand your capacity. An object can be linked
to 32 objects which in turn can be linked to 32 objects which in
turn....well, there is almost no limit. Thus if the player has a
container, the container can have its own container, etc. The
player has to load these in sequence:
>take ball
>put ball in box
<repeat up to 31 more objects>
>take box
>put box in bag
<repeat up to 31 more objects>
>take bag
but at least it is possible to nest objects several levels down.
These nested objects would have to be unloaded in reverse order
with the take-from command:
>take box from bag
>take ball from box
See also the additional discussion on containers later in this
section.
G. Controlling the Random Number Generator
Figment's random number generator gives you the ability to
control it so that you can predict its behavior for debugging or
training purposes.
106
Figment User's Guide Story Design
Computer random number generators require an initial starting
number called a seed. Once this seed number is supplied, the
routine can return an endless list of random numbers. The
sequence is random, but the seed is not, hence the term "Pseudo-
random". Indeed, for the same seed, you will get the same
sequence.
Figment supplies a new seed number each time you start so that
the sequences will always be different. This is probably what
you want during playback, but it is certainly not what you want
when you are debugging stories, for example with log files.
Therefore, Figment allows you to specify the seed when you start.
Thus the command from DOS:
figment <story_name> <seed_number>
will start Figment with the specified seed number. The number is
any integer between 0 and 32767. The number you choose is not
important. So long as you use the same number every time, you
will get consistent results when your log files encounter
conflicts.
This procedure is also useful for beginners and young players who
want to simplify the conflicts.
H. Potions and the Drink Function
The drink function tests to see if the object sub-type attribute
is set to "Potion". If not, the command fails.
When the player drinks a potion, the potion's strength, health,
and magic attributes are added to those of the player. This is a
good place to use negative attributes. Potions can be a mixture
of some good qualities and some bad qualities. For example, a
potion that increases strength might reduce health.
If the player does not have the potion, but the scene does, then
Figment performs an automatic "take" command. This take command
is a fully legal take operation: any rules you have waiting for a
take operation will fire, and anything that causes it to fail
will cause the drink command to fail. The move count is
incremented twice if taking is required. The post-command rules
are also processed.
A potion must be opened in order to be drunk. If the potion is
not open, Figment will not open it automatically.
The potion's limit attribute indicates how many times the potion
can be drunk.
107
Story Design Figment User's Guide
I. Weighty Matters
The weight attribute is another way to limit the player's
possessions besides the limit attribute. It indicates how much
the player can carry on the basis of weight, whereas the limit
attribute indicates the quantity on the basis of count. If the
player wants to take an object, that object's weight attribute
cannot exceed the player's weight attribute (less the sum of the
weights for any objects that the player is already carrying).
You are not required to specify an object's weight; it can be
weightless. This means you can ignore weight early in the story
design and add it later to add another dimension to the story.
Weight really only applies to objects of type "Thing" and varies
from -127 to 127. Objects with negative weights are, in effect,
lighter than air. Their negative value reduces the sum and allow
the player to carry more weight:
>take the helium balloon
You feel lighter.
J. Size and Containers
The size attribute is used with containers in much the same way
that the weight attribute limits the player object. The size of
an object to be added to a container cannot exceed the
container's size as indicated by its size attribute (less the sum
of the sizes of any objects already in the container).
As with weight, you are not obliged to specify an objects's size.
The player never is concerned with an object's size, only its
weight.
Containers can be somewhat magical in the sense that you can
place many objects in the container and then specify an arbitrary
weight for the container (even zero weight if you like)
completely independent of the object weights. In addition,
containers count as only one object so they greatly enlarge the
player's carrying capacity.
Size really only applies to objects of type "Thing" and varies
from -127 to 127. Objects with negative size, when added to a
container, have the ability to fit more objects in the container
than would be possible without them.
108
Figment User's Guide Story Design
K. Waving the Flags
Figment now provides a number of different flags with controls on
their use and functions designed to test them. The Lock and Open
flags seem obvious. Actually, the lock flag can be used on many
things as a general-purpose permission flag:
> Take the cannonball.
No.
> Take the cannonball.
It's heavy.
> Take the cannonball.
You might hurt yourself.
> Take the cannonball.
Oh, all right.
You take the cannonball.
1. Lock Flags and Lock-Enable Flags
Technically speaking, any object can be locked, but when applied
to story situations, it would not make much sense if the player
went around locking and unlocking or opening and closing
everything in sight. (Which he or she could do, by the way, if
the permission flags are not set. The default permission is
therefore "NO" which requires you to specify which objects the
player can lock or open.) Since most objects will have access to
their flags denied to the player, their flags are available for
use in your rules.
We use the Lock flag often in our rules. When the right
conditions are met, we change the flag. Many other events are
testing this flag, and when it changes, it triggers these events.
You will see many rules in the Pre- and Post-command Rule Bases
testing this flag.
The executional functions, "Open" and "Close" are more powerful
than the forms of these commands that the player uses. Notably,
the Open executional function does not test the Lock flag. Hence
objects can be opened or closed regardless of the status of their
Lock flag. This makes the Open flag a free switch for you to use
just like the Lock flag, for example for characters to indicate
they will take an object if you give it.
2. User-Defined Object Flags
User-Defined Flags can be used as simple flags for general
purpose use. They can also get very complex as the following
example shows. Do not feel you have to make them complex if you
do not want to. Use them at whatever level you feel comfortable.
109
Story Design Figment User's Guide
Function for use in your rules are provided to access user flags.
This, along with their associated probability assignment is what
gives them their power. The conditional function "is_true" tests
user flags, and the executional function "set" changes them:
If {
User-flag 3 is true on Jack
} Then {
set Bob's user-flag 4 TRUE
} etc.
When some important event has occurred, you can test for it and
set a flag on some object. Many scenes later, you may need to
know if that event occurred. You can test that flag and know if
the event occurred.
The executional function "clear-usr-flags" can erase all flags on
up to three objects:
If {
} Then {
clear user flags on Jack Bob Elmer
} etc.
A set of four user-definable probability values is also provided
for use with the higher-level functions that access the flags.
Currently, only the executional function "print_msg_choice" uses
them. The rest of this discussion is deferred to the registered
user's manual.
L. Reading Scrolls
Scrolls just produce nice gibberish when they are read. You
disable this by writing a pre-command rule that tests for the
read function and disables it so you can substitute your message
when the appropriate conditions are met.
Since scrolls are defined by a sub-type attribute, objects can be
things, features, and even characters and still qualify as
scrolls. This means the player can read signs, inscriptions,
monuments, documents etc.
M. Strategic Weapons
A strategic weapon is any weapon that functions at a distance.
More specifically, it is an object whose sub-type attribute is
set to read "Strategic". Their advantage should be obvious since
they allow you to dispatch an opponent without risking a fight.
110
Figment User's Guide Story Design
This luxury does not come free however. You might be risking all
since your shot is governed by a random process which could come
up heavily against you.
Strategic weapons come in two parts: the weapon itself and its
ammunition. You must have both objects in order to shoot the
weapon. Create both objects in the Stuff Editor and link the
weapon to its ammunition. The limit attribute for the ammunition
object determines how many times the weapon can be fired. It is
decremented each time the weapon is fired.
Actually, the ammunition is contrived to be an ammunition holder,
for example:
Weapon Ammunition Holder
gun clip, magazine, or chamber
bow quiver
phaser battery pack or power cell
When the ammunition runs out, Figment reports, "Your <ammunition
holder> is empty." The type attribute for strategics and
ammunition should be "Thing". The sub-type attribute should be
"Strategic" for the weapon and "Goody" for the ammunition holder.
The player's skill largely determines the outcome which means
that the lowest two skill levels should not use strategics. The
best a Novice can do is avoid a self-inflicted injury. An
Amateur can do better but cannot succeed in killing an opponent
so there is little reason to try. The next three classes have a
low, medium and high chance of success respectively.
Strategics are a high risk weapon. Any skill level can still
score so lowly with a strategic weapon that he or she dies of a
self-inflicted wound. When the player scores high, however, the
opponent is quickly dispatched.
It must be said that some Wizards are better than other Wizards
since it is an unlimited class, you just get more (or less)
Wizardly. Therefore, when it comes to strategics, there can
still be some surprisingly inept Wizards out there (You know who
you are).
Figment has some generic result messages for strategics that it
will use, but you can write your own, more specific messages in a
pre-command rule. Figment will look for an active rule testing
for the shoot function and defer to the messages therein. This
rule must be a "While" rule. (This is very important. Otherwise
it will switch itself off and be skipped.) It would look
something like this:
111
Story Design Figment User's Guide
Switched: On Command: Enabled
While {
Player does shoot bow
...other conditions...
} Then {
No executional expressions
} Message 5 Total Switched: OFF Current Msg: 1
1 <Disaster>
2 <Bad but surviving>
3 <Still missed>
4 <Wounded opponent>
5 <Successful hit>
This special rule in no way prohibits you from writing other pre-
command rules that will prevent the player from shooting, but
those rules should appear after this special rule in the sequence
(curious, but true). Figment will take the first "shoot" rule
that it finds when it wants messages.
Figment weights the results of the random number generator
according to the Player's skill and grids the results on a scale
of 1 to 5 with 1 being disastrous. It then reports the nth.
message from your rule or its generic message list.
A result of one is disastrous. The player's health is set to
zero. This will kill the player, but it is subject to the
aforementioned escape clause (see "Conflicts" above) so the
player might survive severely wounded.
Results of two and three are simply misses and only cost a move
and the ammunition.
A result of four results in wounding the opponent. The opposing
object's health is decremented by the amount of the ammunition's
strength. Remember to specify the health for the opposing
object, otherwise this score will be equivalent to a successful
hit regardless of the ammunition's strength. Consider also the
effect of negative attributes for the ammunition's strength; the
opponent would get healthier the more it was "wounded":
"Ooh. Now you've made him very, very mad."
Five is a successful hit. The opponent object will be stripped
of its possessions and removed from the scene. The player's
score will be incremented one point. You can write a post-
command rule that tests for the absence of the opponent to
deliver whooping congratulations and further increment the
Player's score if you like. If your story line hinges around the
opponent's corpse you may rename the late lamented object and
reintroduce it with this same rule.
112
Figment User's Guide Story Design
Although you do want to specify your ammunition's strength, there
is no need to specify strength or magic attributes for the
strategic weapon itself.
N. Food
As mentioned under parameter editing, you can control Figment's
behavior regarding food. Depending on your settings, your player
may be satisfied for days between rations or they may be forced
into a feeding frenzy.
You also set the food value for the food item by setting the
object's limit attribute up to its maximum (32). Thus some foods
may satisfy your craving while others are empty. (Didn't your
mother tell you this?) The player's maximum gain from a food
item is limited by his or her skill at the time the item is
consumed so novices should conserve their rations while newly-
anointed wizards might want to reward themselves with a pause for
refreshment.
You may also fortify your food with Strength, Magic and Health
attributes since these will be added to the Player's when the
food is consumed. Negative attributes are allowed here as with
potions.
Guard your food. Figment can be a bit piggish at times. Bon
appetit.
O. Characters as Containers
Ordinarily, the player cannot tell when a character has an
object, but if you set the character's sub-type attribute to
"Container", Figment will report the container-character's
contents when the character's Open flag is set to "Open". You
can then write rules that manipulate the flag and hence display
or not display the character's possessions at your whim.
P. Rules and Changing Scenes
From the nature of rule base processing as it was defined, you
should understand how the rule bases perform when changing
scenes. The last rule base to be processed when exiting a scene
will be that scene's Pre-command Rule Base. The change-scene
command will execute and the Post-command rules for the new scene
will be processed.
113
Story Design Figment User's Guide
If you write rules fashioned as "If" rules and place them in the
new scene's Post-command rule base, they can fire when the player
arrives in the scene. These rules then serve to initialize the
scene. Of course, these rules only function one time since "If"
rules expire so the effect is lost when players repeatedly enter
the same scene.
Q. User-definable Command Parser
The user-definable command parser allows virtually any command in
play mode to trigger pre-command rules.
The executable function, "say_cmnd" parses the command line
according to a specification given in the first message of a pre-
command rule. It looks like this:
If {
Player does say_cmnd
} Then {
add_to Consulting Room Johnson
copy msg to Player's view of Watson's Long Desc.
change_score 1
} Message 2 Total Switched: OFF Current Msg: 2
1. (send or show)(him or Johnson)(in or up) or thank you
mrs hudson
2. Watson prepares to take notes.
The first message of the rule is a specification for acceptable
words or phrases on a command line. The remaining messages are
available for other uses. Let's see how the specification works.
Imagine the situation:
Your faithful housekeeper Mrs. Hudson announces your
visitor. "There's a Mr. Johnson to see you, Mr.
Holmes."
Your reply might be:
>show him in please
or
>send him up
or
>thank you mrs hudson
The specification in the pre-command rule reads:
(send or show)(him or Johnson)(in or up) or thank you
mrs hudson
114
Figment User's Guide Story Design
The parentheses "()" serve to "AND" phrases while the keyword "
or " serves as the boolean "OR" operator. This example specifies
several acceptable combinations of words and/or phrases which we
can group as follows:
send him in
show Johnson up
It also allows the phrase:
thank you Mrs Hudson
This is something like choosing from a Chinese menu. Choose one
from column A, one from column B, etc. According to this
example, you must choose one from each column, because the
parentheses indicate they have all been AND'd together. This
yields a number of legal statements that the player might give:
send him in
send Johnson in
send him up
send Johnson up
show him in
show Johnson in
show him up
show Johnson up
thank you Mrs Hudson
Of course if the player gives extra words, Figment will ignore
them:
>send him in please Mrs Hudson
The player must give the full phrase in order to trigger the
rule:
>thank you
is not enough unless you modify the specification to allow it:
(send or show)(him or Johnson)(in or up) or thank you
mrs hudson or thank you
Another legitimate specification to achieve the same end is:
(send or show)(him or Johnson)(in or up) or (thank you)
(mrs hudson or )
A rule like this can be placed in any pre-command rule base
either global or local. Presumably most will be local.
115
Story Design Figment User's Guide
The user-definable parser is deliberately tolerant. It will
accept the legal phrases in any order. All that is required is
to give the requisite number of phrases. The specification:
(send or show)(him or Johnson)(in or up) or thank you
mrs hudson
will accept "him in send", but not "Mrs Hudson thank you" while
the specification:
(send or show)(him or Johnson)(in or up) or (thank you)
(mrs hudson or)
will accept "Mrs Hudson thank you".
The user-definable command parser can be negated. This has the
effect of firing the rule until the player gives the desired
command. For example:
While {
Player does not say_cmnd
Consulting Room is linked to Mrs. Hudson
} Then {
No Executional Expressions.
} Message 2 Total Switched: ON Current Msg: 2
1. (send or show)(him or Johnson)(in or up) or thank you
mrs hudson
2. Mrs. Hudson discreetly clears her throat.
The negated rule will fire until the player gives the specified
command. You may wish to write negated command rules as "If" or
"For" rules instead of "While" rules so that they can switch off
after a few tries. Otherwise, they can be very frustrating.
The user-parser has the third highest precedence after the
system-level commands (restart, save, toggle, etc.) and the
synonym processing so that you can use any word or phrase even if
it is similar to Figment's built-in functions. Phrases like
"take off" and "drop dead" can be used without triggering error
messages: "There's no off here" or "You don't have a dead".
Negated user-defined commands will not interfere with system
level commands, because they have lower precedence.
Note that punctuation must be avoided. Punctuation has special
meaning to the command parser. The comma (,) means make a series
operation as in "take bat, ball, glove". Similarly, the period
(.) means end the command or separate commands. If the player
gives the command:
116
Figment User's Guide Story Design
Thank you, Mrs. Hudson.
Figment will interpret this as:
Thank you ;"I don't understand the command `Thank'".
Thank Mrs ;"I don't understand the command `Thank'".
Hudson ;"I don't understand the command `Hudson'".
The player must simply ignore punctuation except where it is used
to signal series operation or command termination. Upper/lower
case distinctions are of course ignored.
There are words that will defeat your desired statement. You
will want to exclude any statement that uses them. For example,
the statement "send him in" would be defeated if the player used
"do not" as in "do not send him in" or "don't". The phrase
"Thank you Mrs Hudson" would be defeated if the player said "No
thank you Mrs Hudson". You want to specify these negative words,
and you can do that by enclosing them in square brackets "[]" as
follows:
[do not or dont](send or show)(him or Johnson)(in or up)
or [no](thank you)(mrs hudson or )
The square brackets can be specified in any order. The following
example is equivalent to the previous example:
(send or show)(him or Johnson)(in or up)[do not or dont] or
(thank you)(mrs hudson or )[no]
Note that the contraction "don't" was written as "dont" and that
the abbreviation "Mrs." was written as "mrs". Punctuation should
not be included in the specification message, but upper/lower
case distinctions do not matter.
R. The Actor in Rules
You can use the term "Actor" in your expressions wherever you
might use a character. When you use the Actor, you are testing
for "whomever might be speaking" as opposed to the Player which
refers specifically to the object reserved for the user.
Using the Actor in your conditional expressions has the advantage
of flexibility since it is a more general term than "Player".
This asset turns into a liability when you use it in executional
expressions. It can produce chaos, because function destinations
will be determined at run-time. There is no telling where the
following message might end up although it is a correct
construction:
117
Story Design Figment User's Guide
copy msg to Actor's view of Actor's Long Desc.
Consider using the Actor instead of the Player when writing rules
designed to restrict movement from a particular scene until the
user has resolved some task. If you do not test for the Actor,
the user can change to another character and slip through to
another scene and change back. A pre-command rule to prevent
this might look like this:
Scene: X Rule: 1 of n Switched: ON Disabled
If {
Actor does go Anywhere
<scene name> is locked
} Then {
No Executionals
} Message 1 Total Switched: ON Current Message: 1
1. Sorry. You can't go yet.
The Actor, by default is the Player object, but the operator can
change this during play. You can change the Actor object to
another character object whenever that object is linked into the
scene. You will get an error message if you specify a character
not present in the current scene. You change the Actor by giving
the character name followed by a colon. You can also add the
command for the character in the same command line, thus:
Player: Mary: go north ;change Actor to Mary and
Mary: ; depart northbound.
The ready prompt changes to indicate the current Actor and the
status and inventory displays change as well. Only the Player
object is scored however which affects skill.
Actually, you need not spell the character's full name, but you
will want to spell enough to be unique. If the letter "y" in
"Mary" is unique, meaning no other character name has a "y" in
it, then the following is equivalent to the above example:
Player: y: go north
You go north.
Mary:
A character can be linked into any number of scenes, but once the
Actor is set to the character, Figment will remove that character
link from all other scenes. Thus you can be sure that the
character is only found linked into the current scene. This
action is done at scene-change time so until you change scenes,
your links will be unaffected.
118
Figment User's Guide Story Design
To change back to the Player object, you will probably have to
return to the scene where you left the Player. (Say "find
Player".)
The above applies now to the Player object as well. At the start
of play, the Actor is assigned to the Player object. Thus the
rule applies: the speaking character cannot be present in more
than one scene at a time. Rules can be written to make more
links, but the links will be stripped out again as soon as the
Actor changes scene.
S. The '@'-Words
Special system names and words can be incorporated into your text
using special names within your text string. These special names
are indicated by the at-symbol (@). The names must be spelled
exactly as you see them here, including the capital letters.
Whenever your text is used, Figment substitutes the appropriate
text for the special name. Hence these special names function
like text variables within your text.
The words are:
@Actor - Substitutes the current actor's name.
@Player - Substitutes the current Player's name. Typically
this yields the User's first name, but during development
and testing of your story, it would be the generic text
"Player".
@Scene - Substitutes the current scene name.
@It - Substitutes the last object name used in the command
line.
@Them - Substitutes the last series of object names used in
the command line.
@Full_name - Substitutes the user's full name. This is the
preferred form when you want the full name since it avoids
problems with titles, middle names, four names, reversed
names, etc. @Full_name is loaded when "@Get_User" is
inserted in the title message. If "@Get_User" is omitted
from the title message, "@Full_name" is empty.
@User[n] - where n = 0 through 2. Substitutes the User's
first, middle or last name. User[0] is reliably the user's
119
Story Design Figment User's Guide
first name. User[1] is the middle name and is empty when
less than three names are entered. User[2] is the second
name when two names are entered, otherwise it is the third
name. People with four names suffer. Titles such as "Sr.,
Jr., II, and III" are lost. Many cultures place the family
name first and the individual's name last. There is no
support for this. @User is loaded by @Get_User during title
message processing.
@Command - Substitutes the current command sentence. You
can give commands consisting of several sentences, but they
are processed one sentence at a time so this returns the
current sentence.
@Words[n] - where n = 0 to maximum words in command line.
Probably Words[0] is most useful since it is typically the
verb.
@Msg: n
T. Help Messages
Help messages are defined for each map block. These are separate
text strings that you can edit in their own editing screen. You
can also revise them during play as the story progresses by
copying new messages to them as rules fire.
The player can just type "help" and the currently defined message
appears. This is usually something more than an examination
message might do.
A rule to change the help message might look like this:
If {
<conditional expressions>
} Then {
Copy_msg_to Current Scene's Help Msg
} Messages 1 Total Turned: OFF Current: 1
1. Be patient. Sometimes the answer just comes to
you.
This might imply that the player should simply use the
"wait" command until some time-bomb you have prepared fires.
As the scene progresses, you can trigger more rules to update the
help message. This action can be combined as part of existing
rules so help message maintenance only costs a few expressions
plus one message.
120
Figment User's Guide Story Design
Whenever no help message is defined for a scene, the player gets
a gentle rebuff when requesting help.
121
Story Design Figment User's Guide
Index
+ 31, 33, 46, 57 Conclusions 104
@-Words 119 design notes 103
@Actor 119 Containers 16, 77, 106
@Command 120 link limit 105
@Full_name 86, 119 reporting contents of 35
@Get_User 86 Copy_Msg_To 77
@It 119 Cursor Control Keys 29
@Player 119 Cut 26, 30, 58
@Scene 119 Expressions 65
@Them 119 rules 57, 58
@User[n] 119 Test Messages 66
@Words[n] 120 Text 26
Actor Data Set Files 98
during playback 9 Debugging Tips 99
in rules 117 Delete 31, 58
viewpoints 39 Player object 34
Advance 29 rules 57
Alphabetizing objects 34 with objects 33
Alt-F7 27, 30, 58, 65, 66 Directions
Armor 35 during play 15
Articles Display
in commands 7 switch 4
Assign_User_Type 76 Does_Action 70
Attributes Does_Fit_Profile 71
as arguments 64 Does_Have_Attribute 71
editing operations 35 Drink 12, 107
failure to specify 99 Drop 12
in scenes 43 Eat 12
negative 104 Editing Operations
with food 113 summary of 29
with potions 107 Error Messages
Change User-Attribute in editor 26
executional function 76 Examination Message 38, 101
change_health 102 victory message 104
change_score 101 Examine 12
Characters message design 101
as containers 113 Executional
Charm 12 clause 51
Close 12, 77 Executional Function
Comma Operator Reference 76
in commands 8 Expression 62
Command Parser editing 61
User-definable 114 modifier 63, 68
Command Reference 12 negation 62, 63
Command Window 5 F1 - Enter Editor 12, 28
Conditional clause 51 also exit from editor 30
types of 51 F10 - DOS Shell 13, 31
Conflicts in editor 29
122
Figment User's Guide Story Design
F2 30 Insert 26, 31, 58
read a file 29 Interrupt
F3 log files 17
write a file 29, 30 Inventory
F4 - Listing 30 changes w/actor 10
objects 32 Is_dead 71
rule bases 60 Is_linked_to 72
F5 - Alphabetize Objects 30 Is_locked 72
F6 67 Is_open 73
F6 - Text Editor 30 Is_type 73
F7 26, 30, 58, 65, 66 Is_wizard 73
F9 19 it 8
F9 - Step a log file 13 Kill 80
Figglu 3 Labels 41
Fight 13, 103 user types 37
Figlet 1 Limit
File ammunition 111
input/output 28 editing 35
management 95 food value 113
naming convention 95 Link_to 80
Find 14 Links
Flags 34, 36, 43 design notes 105
Food 36, 102, 104 editing operations 42
design notes 113 in scenes 43
limited by skill 101, 113 type labels 90
parameter editing 87 Listing
sub-type attribute 35 objects 32
FOR 51, 55, 78 rule bases 60
Full-Screen Text Editor Lock 16, 52, 81
description of 94 editing 109
Give 14 Log 7, 107
Global Rule Bases 60 play a log file 17
Go 15, 16, 64, 69, 79 step a log file 13
Go_to_Map_Block 78 Logic Programming 48
Goody Magic 103
sub-type attribute 35 editing 35
Have_Attribute 71 Message
Health 13, 101 editing 66
design notes 102 pointer 56, 75, 79, 81
editing 35 Method of Editing 23
recovery 14 Move count 15, 18
Help Message 89 Msg_to_name 81
Hex 16, 103 Negating rules 69
Hit 16 Negative Attributes
Home key 31, 62, 63 in conflicts 104
IF 51 Objects
delayed execution 56 creating them 33
Inc_moves 79 definition of 31
Inc_msg 79 deleting 33, 98
Inc_score 77 names 32
123
Story Design Figment User's Guide
User Types 37 rules and changing 113
On_skill 81, 101 Screen Display 5
Open 16, 35, 43, 73, 81 Scrolling 24, 29
Page-Down 29 Scrolls 35, 110
Parameter Series 8
editing 86 Shift-F2
Paste 26, 27, 58 read save file 30
Pause 17 Shift-F3
Period Operator write save file 30
in commands 7 Shift-F4 - Write Full Listing
Play 17 30
Player Map 84 Shift-F7 27
Player Object 34 Shoot 19
Potions Size 35, 108
design notes 107 Skill
Pre-Command design notes 101
explanation of 67 levels 101
Presentation Environment 4 on-skill 81
Probable Event 73 when shooting 19
Profiles 90 Standard Messages 91
Pronouns 65 Starting
Put 17 existing story 4
Quit 18 new story 96
Random Number Generator Status
controlling 106 editing 88
Read 18 Indicator 5
Remove_User_Type 82 Step 19
Restart 18 story
Restore 17, 18 restarting 18
Rules story editor 21
adding/deleting 57 story elements 28
changing scenes via 113 Story Design 101
copying 57 Story Editor 21
current message 54 Story Map 15, 78, 85
definition of 51 Complex maps 46
editing 56 editing 44
expression editing 62 path 45
negating 69 restricts scene change 59
re-ordering 57 Simple Maps 45
Save 13, 18, 30, 95, 96, 98 Strategic Weapons 110
Say_cmnd 74 Strength 13, 103
Scene Description 44, 54 design notes 102
highlights changes 5 editing 35
with Actor change 10 Stuff 31
Scene Editor 43 names 32
Scene-change 45 objects 31
Scenes Stuff Editor 31
changing in editor 59 Sub-type attribute 35
entry scene 46 Synonym 85
objects 31 Syntax
124
Figment User's Guide Story Design
explanation of symbols 12
Take 19
Take_from 82
Text
changing it 24
erasing 25
length of 25
Text editor 24, 31
invoking 94
key definition summary 94
them 9
Toggle 20
Toggle_lock 82
Toggle_open 83
Top Level Editor
description of 27
Type attribute 35, 44
Unlock 20, 83
User Types 37
defining labels 89
User-Definable Attributes
defining labels 90
editing 40
User-definable Command
Parser 114
Viewpoints
editing 39
Wager 14
Wait 20
Weapon 35
Weight 35, 108
WHILE 51
125