------------------------------------------------------------
HUGO v2.5 - An Interactive Fiction Design System
PROGRAMMING MANUAL

Copyright (c) 1995-2000 by Kent Tessman

(Revised February 2000)
------------------------------------------------------------





------------------------------------------------------------
The following conventions are used in this manual:

	<parameter>	for required parameters
	[parameter]	for optional parameters
	FILE		for specific filenames
	FunctionName	functions, etc.
	'token'		tokens, keywords
	...		for omissions
------------------------------------------------------------





------------------------------------------------------------
APPENDIX A:  SUMMARY OF KEYWORDS AND COMMANDS


*>and

DESCRIPTION:	Logical and.

SYNTAX:  	x = <value1> and <value2>

RESULT:		x will be true if <value1> and <value2>
		are both non-zero, false if one or both is
		zero.


*>anything

DESCRIPTION:	Object specifier in grammar syntax
		line, indicating that any nameable
		object in the object tree is valid.


*>array

DESCRIPTION:	When used as a data type modifier,
		specifies that the following value is
		to be treated as an array address.

EXAMPLE:	<var1> = array <var2>[5]

		The variable <var2> will be treated as an
		array address.


*>break

DESCRIPTION:	Terminates the immediate enclosing
		loop.

EXAMPLE:	while <expression1>
		{
			while <expression2>
			{
				if <expression3>
					break
				...
			}
			...
		}

		The break statement, if encountered, will
		terminate the innermost loop.


*>call

DESCRIPTION:	Calls a routine indirectly, i.e.,
		when the routine address has been
		stored in a variable, object
		property, etc.

SYNTAX:		call <value>[(<arg1>, <arg2>,...)]

		or

		x = call <value>(...)

		where <value> is a valid data type holding
		the routine address.

VALUE:		When used as a function, returns the value
		returned by the specified routine.


*>capital

DESCRIPTION:	Print statement modifier, indicating
		that the next word should be printed
		with the first letter capitalized.

SYNTAX:		print capital <address>

		where <address> is any dictionary word,
		such as, for example, an object.name
		property.


*>case

DESCRIPTION:	Specifies a conditional case in a
		'select' structure.

SYNTAX:		select <val>
			case <case1>[, <case2>,...]
				...
			case <case3>[, <case4>,...]
				...

		where <val> is value such as a variable,
		routine return value, object property,
		array element, etc., and each <case> is a
		single value for comparison (not an
		expression).


*>child

SYNTAX:		x = child(<parent>)

RETURN VALUE:	The object number of the immediate
		child object of <parent>, or 0 if
		<parent> has no children.


*>children

SYNTAX:		x = children(<parent>)

RETURN VALUE:	The number of child objects possessed
		by <parent>.


*>cls

DESCRIPTION:	Clears the current text window
		repositions the output coordinates at
		the bottom left of the text window.

SYNTAX:		cls


*>color
*>colour

DESCRIPTION:	Sets the display colors for text
		output.

SYNTAX:		color <foreground>[, <background>]

		where <background> is optional

PARAMETERS:	Standard color values for
		<foreground> and <background> (from
		HUGOLIB.H) are:

			0	Black
			1	Blue
			2	Green
			3	Cyan
			4	Red
			5	Magenta
			6	Brown
			7	White
			8	Dark gray
			9	Light blue
			10	Light green
			11	Light cyan
			12	Light red
			13	Light magenta
			14	Light yellow
			15	Bright white


*>dict

DESCRIPTION:	Dynamically creates a new dictionary
		entry at runtime.

SYNTAX:		x = dict(<array>, <maxlen>)

		x = dict(parse$, <maxlen>)

		where <array> or parse$ holds the string
		to be written into the dictionary, and
		<maxlen> represents the maximum number of
		characters to be written.  Returns the new
		dictionary address.  (NOTE:  Space should
		be reserved for any dictionary entries to
		be created at runtime using the
		$MAXDICTEXTEND setting during
		compilation.)


*>do

DESCRIPTION:	Marks the starting point of a do-
		while loop.

SYNTAX:		do
		{
			...
		}
		while <expr>

		The loop will continue to run as long as
		<expr> holds true.	


*>elder

SYNTAX:		x = elder(<object>)

RETURN VALUE:	The object number of the object
		preceding <object> on the same branch
		in the object tree.  The reverse of
		'sibling'.


*>eldest

Same as 'child'.


*>else

DESCRIPTION:	In an if-elseif-else conditional
		block, indicates the default
		operation if no previous condition
		has been met.

SYNTAX:		if <condition>
			...
		else
			...


*>elseif

DESCRIPTION:	In an if-elseif-else conditional
		block, indicates a condition that
		will be checked only if no preceding
		condition has been met.

SYNTAX:		if <condition1>
			...
		elseif <condition2>
			...
		elseif <condition3>
			...


*>false

DESCRIPTION:	A predefined constant value:  0.


*>for

DESCRIPTION:	Loop construction.

SYNTAX:		for (<initial>; <test>; <mod>)
		{
			...
		}

		for <var> in <object>
		{
			...
		}

		For the first form, where <initial> is the
		initial assignment expression (e.g. a =
		1), <test> is the test expression (e.g. a
		< 10), and <mod> is the modifying
		expression (e.g. a = a + 1).  The loop
		will execute as long as <test> holds true.

		The second form loops through all the
		children of <object> (if any), setting
		<var> to each child object in sequence.


*>held

DESCRIPTION:	Object specifier in grammar syntax
		line, indicating that any single
		object possessed by the player object
		is valid.


*>hex

DESCRIPTION:	Print statement modifier signifying
		that the following value is not a
		dictionary address, but should be
		printed as a hexadecimal number.

SYNTAX:		print hex <var>

		where, for example, <var> is equal to 26,
		will print "1A".


*>if

DESCRIPTION:	A conditional expression.

SYNTAX:		if <condition>
			...

		where <condition> is an expression or
		value, will run the following statement
		block only if <condition> is true.


*>in

DESCRIPTION:	When used in an object definition,
		places the object in the object tree
		as a possession of the specified
		parent.  When used in an expression,
		returns true if the object is in the
		specified parent.

SYNTAX:		in <parent>

		or, for example:

		if <object> [not] in <parent>
			...


*>input

DESCRIPTION:	Receive input from keyboard, storing
		the dictionary addresses of the
		individual words in the word array.
		Unrecognized words are given a value
		of 0.

SYNTAX:		input


*>is

DESCRIPTION:	Attribute assignment/testing.

SYNTAX:		<object> is [not] <attribute>

USAGE:		When used as an assignment on its own,
		will set (or clear, if 'not' is used) the
		specified attribute for the given object.
		May also be used in an expression.

RETURN VALUE:	When used in an expression, returns
		true if <object> has the specified
		attribute set (or cleared, if 'not'
		is used).  Otherwise, it returns
		false.


*>jump

DESCRIPTION:	Jumps to a specified label.

SYNTAX:		jump <label>

		where a unique <label> exists on a
		separate line somewhere in the program, in
		the form:

		:<label>


*>local

DESCRIPTION:	Defines one or more variables local
		to the current routine.

SYNTAX:		local <var1>[, <var2>, <var3>,...]


*>locate

DESCRIPTION:	Sets the cursor position within the
		current text window.

SYNTAX:		locate(<row>, <column>)

NOTE:		The maximum horizontal/vertical cursor
		position is constrained by the boundaries
		of the current text window.  The cursor
		position is calculated in fixed-width
		character coordinates.


*>move

DESCRIPTION:	Moves an object with all its
		possessions to a new parent.

SYNTAX:		move <object> to <new parent>


*>multi

DESCRIPTION:	Object specifier in grammar syntax
		line, indicating that multiple
		available objects are valid.


*>multiheld

DESCRIPTION:	Object specifier in grammar syntax
		line, indicating that multiple
		objects possessed by the player
		object are valid.


*>multinotheld

DESCRIPTION:	Object specifier in grammar syntax
		line, indicating that multiple
		objects explicitly not held by the
		player object are valid.


*>music

DESCRIPTION:	Load and play a song (if audio output
		is available).

SYNTAX:		music [repeat] "file", "song"[, vol]
		music 0

		where <file> is a compiled Hugo
		resourcefile, and <song> is a music module
		in MOD, S3M, or XM format.  The optional
		<vol> argument, if given, ranges from 0 to
		100 and gives a percentage of volume for
		playback.  If the 'repeat' token is used,
		the song continues to loop until either a
		new song is played, or the current song is
		stopped (using "music 0").


*>nearby

DESCRIPTION:	Used in an object definition to place
		the object in the specified position
		in the object tree.

SYNTAX:		nearby <object>

		Gives the current object the same parent
		as <object>.

		nearby

		Gives the current object the same parent
		as the last-defined object.


*>newline

DESCRIPTION:	Print statement modifier, indicating
		that a line feed and carriage return
		should be issued if the current
		output position is not already at the
		start of a blank line.

SYNTAX:		print newline


*>not

DESCRIPTION:	Logical not.

SYNTAX:  	x = not <value>

		<object> is not <attribute>

RESULT:		In the first example, x will be true if
		<value> is false, or false if <value> is
		true.
	
		In the second, the specified attribute
		will be cleared for <object> when used
		alone as an assignment.  As part of an
		expression, it will return true only if
		<object> does not have <attribute> set.


*>notheld

DESCRIPTION:	Object specifier in grammar syntax
		line, indicating that a single object
		explicitly not held by the player
		object is valid.


*>number

DESCRIPTION:	When used in a grammar syntax line,
		indicates that a single positive
		integer number is valid.

		When used as a print statement
		modifier, indicates that the
		following value is not a dictionary
		address, but should be printed as a
		positive integer number.

SYNTAX:		(usage as a print statement modifier)

		print number <val>

		where, for example, <val> is equal to 100,
		will print "100" instead of the word
		beginning at the address 100 in the
		dictionary table.


*>object

DESCRIPTION:	Global variable holding the object
		number of the direct object, if any,
		specified in the input line.

		When used in a grammar syntax line,
		indicates that a single available
		object is valid.


*>or

DESCRIPTION:	Logical or.

SYNTAX:  	x = <value1> or <value2>

RESULT:		x will be true if either <value1> or
		<value2> is non-false, or false if both
		are false.


*>parent

(Usage 1)

SYNTAX:		x = parent(<object>)

RETURN VALUE:	The object number of <object>'s
		parent object.

(Usage 2)

DESCRIPTION:	When used in a grammar syntax line,
		indicates that the domain for
		validating the availability of the
		specified direct object should be set
		to the parent object specified in the
		input line.


*>parse$

DESCRIPTION:	Read-only engine variable that
		contains either the offending portion
		of an invalid input line or any
		section of the input line enclosed in
		quotes.


*>pause

DESCRIPTION:	Pauses until a key is pressed.  The
		ASCII value of the key is stored in
		word[0].


*>picture

DESCRIPTION:	Load and display a picture in the
		current text window (if graphics are
		available).

SYNTAX:		picture "<resourcefile>", "<picture>"
		picture "<picturefile>"

		where, while <resourcefile> is optional,
		it is very highly recommended (otherwise,
		<picturefile> will likely not be named in
		a cross-platform portable format).


*>playback

DESCRIPTION:	Plays back recorded commands from a
		file in place of keyboard input.

SYNTAX:		x = playback

RETURN VALUE:	True if successful, false if not.


*>print

DESCRIPTION:	Print text output.

SYNTAX:		print <output>

		where <output> can consist of both test
		strings enclosed in quotation marks
		("..."), and values representing
		dictionary addresses, such as object
		names.  Separate components of <output>
		are separated by a semicolon (';').  Each
		component may also be preceded by a
		modifier such as 'capital', 'hex', or
		'number'.


*>printchar

DESCRIPTION:	Prints a character or series of characters
		at the current cursor position.  No
		newline is printed.

SYNTAX:		printchar <val1>[, <val2>,...]


*>quit

DESCRIPTION:	Terminates the game loop.

SYNTAX:		quit


*>random

DESCRIPTION:	Engine function which generates a
		random number.

SYNTAX:		x = random(<val>)

RETURN VALUE:	Where <val> is a positive integer
		number, will return a random number
		between 1 and <val>, inclusively.


*>readfile

DESCRIPTION:	A structure that allows values to be
		read from a file written using
		writefile.

SYNTAX:		readfile <filename>
		{
			...
		}

		The file is opened and positioned to the
		start at the beginning of the readfile
		block, and closed at the end.


*>readval

DESCRIPTION:	Reads a value in a readfile block.

SYNTAX:		x = readval

VALUE:		The value read, or 0 in the case of an
		error.  Use the FILE_CHECK constant
		defined in HUGOLIB.H to determine if a
		readfile block has been executed
		successfully.  See the section above on
		"Reading and Writing Files".


*>recordoff

DESCRIPTION:	Ends recording commands to a file.

SYNTAX:		x = recordoff

VALUE:  	True if successful, false if not.


*>recordon

DESCRIPTION:	Begins recording commands to a file.

SYNTAX:		x = recordon

VALUE:		True if successful, false if not.


*>remove

DESCRIPTION:	Removes an object from the object
		tree.

SYNTAX:		remove <object>

		(The same as:  move <object> to 0)


*>restart

DESCRIPTION:	Reloads the initial game data and
		calls the Init routine.

SYNTAX:		x = restart

NOTE:		'Restart' does not technically restart the
		engine; the game loop continues
		uninterrupted after Init is called, only
		with the game data restored to its initial
		state.

VALUE:		True if successful, false if not.


*>restore

DESCRIPTION:	Restores a saved game's state data by
		calling the engine's restore routine.

SYNTAX:		x = restore

VALUE:		True if successful, false if not.


*>return

DESCRIPTION:	Returns from a called routine.

SYNTAX:		return [<expression>]

RETURN VALUE:	Returns <expression> if provided,
		otherwise returns false.


*>run

DESCRIPTION:	Runs an object property routine if
		one exists.

SYNTAX:		run <object>.<property>

RETURN VALUE:	None; any value returned by the
		property routine is discarded.


*>runevents

DESCRIPTION:	Calls all events which are either
		global or currently within the event
		scope of the player object.

SYNTAX:		runevents


*>save

DESCRIPTION:	Saves the current game state by
		calling the engine's save routine.

SYNTAX:		x = save

VALUE:		True if successful, false if not.


*>scriptoff

DESCRIPTION:	Turns transcription off.

SYNTAX:		x = scriptoff

VALUE:		True if successful, false if not.


*>scripton

DESCRIPTION:	Turns transcription (i.e., recording
		output to a file or to a printer) on
		by calling the engine's transcription
		routine.

SYNTAX:		x = scripton

VALUE:		True if successful, false if not.


*>select

DESCRIPTION:	Specifies the value for comparison in
		a select-case conditional structure.

SYNTAX:		select <val>
			case <case1>[, <case2>,...]
				...
			case <case3>[, <case4>,...]
				...

		where <val> is value such as a variable,
		routine return value, object property,
		array element, etc., and each <case> is a
		single value for comparison (not an
		expression).


*>serial$

DESCRIPTION:	Read-only engine variable that
		contains the serial number as written
		by the compiler.


*>sibling

SYNTAX:		x = sibling(<object>)

RETURN VALUE:	The number of the object next to
		<object> on the same branch of the
		object tree.


*>sound

DESCRIPTION:	Load and and play an audio sample (if
		waveform audio output is available).

SYNTAX:		sound [repeat] "file", "sample"[, vol]
		sound 0

		where <file> is a compiled Hugo
		resourcefile, and <sample> is a waveform
		sample in RIFF/WAV format.  The optional
		<vol> argument, if given, ranges from 0 to
		100 and gives a percentage of volume for
		playback.  If the 'repeat' token is used,
		the sample continues to loop until either
		a new sample is played, or the current
		sample is stopped (using "sound 0").


*>string

DESCRIPTION:	When used in a grammar syntax line,
		indicates that a string array
		enclosed in quotation marks is valid.

		When used as a function, stores a
		dictionary entry in a string array.

SYNTAX:		x = string(<array>, <dict>, <maxlen>)

		x = string(<array>, parse$, <maxlen>)

		where <array> is an array address, stores
		the either the dictionary entry given by
		<dict> or the contents of parse$ as a
		series of characters, to a maximum of
		<maxlen> characters.  Returns the length
		of the string stored in <array>.


*>system

DESCRIPTION:	Built-in function to call low-level system
		functions.

SYNTAX:		system(<function>)

Function  Label               Description
	
11        READ_KEY            Read keypress (key value)
21        NORMALIZE_RANDOM    Make random values predictable
22        INIT_RANDOM         Restore "random" random values
31        PAUSE_SECOND        Pause for one second
32        PAUSE_100TH_SECOND  Pause for 1/100th of a second

(Labels are defined as a constants in SYSTEM.H.)

If <function> is unavailable, the engine may set
system_status to -1 (STAT_UNAVAILABLE).


*>text

	text to <val>	Sends text to the array table,
			beginning at address <val>.

	text to 0	Restores normal printing.


*>to

DESCRIPTION:	In a print statement, prints blank
		spaces in the current background
		color to the specified position.

SYNTAX:		print to <val>

		where <val> is a positive integer less
		than or equal to the maximum column
		position


*>true

DESCRIPTION:	Predefined constant:  1.


*>undo

DESCRIPTION:	Attempts to recover the state of the
		game data before the last player
		command.

SYNTAX:		x = undo

VALUE:		True if successful, false if not.


*>verb

DESCRIPTION:	Begins definition of a regular verb.
		Upon returning true from the verb
		routine, Main is called.

SYNTAX:		verb "<word1>"[, "<word2>",...]


*>while

DESCRIPTION:	Component of while or do-while loop
		construct.

SYNTAX:		while <expr>
			...

		(or)

		do
			...
		while <expr>

		where the loop will run as long as <expr>
		holds true.


*>window

DESCRIPTION:	Switches output to the status window.

SYNTAX:		window a[, b, c, d]
		{...}

		or

		window
		{...}

		or

		window 0

		If only a single value <a> is given, a
		window of <a> lines from the top of the
		screen is created.  If more values are
		given, a window from top-left (a, b) to
		bottom-right (c, d) is created.  If no
		values are given, the last-defined window
		is recreated.  The new boundaries apply
		for the length of the following "{...}"
		code block.

		"window 0" restores full-screen display.
		There is no following code block.


*>writefile

DESCRIPTION:	A structure that writes values to a
		file that may be read using readfile.

SYNTAX:		writefile <filename>
		{
			...
		}

		The file is opened and positioned to the
		start at the beginning of the writefile
		block, and closed at the end.


*>writeval

DESCRIPTION: 	Writes one or more values in a
		writefile block.

SYNTAX:		writefile value1[, value2, ...]


*>xobject

DESCRIPTION:	Global variable holding the object
		number of the indirect object, if
		any, specified in the input line.

		When used in a grammar syntax line,
		indicates that a single available
		object is valid.


*>xverb

DESCRIPTION:	Begins definition of non-action verb.
		Upon returning from the verb
		routine, Main is not called.

SYNTAX:		xverb "<word1>"[,"<word2>",...]


*>younger

Same as 'sibling'.


*>youngest

SYNTAX:		x = youngest(<parent>)

RETURN VALUE:	The number of the object most
		recently added to parent <parent>.
------------------------------------------------------------





------------------------------------------------------------
APPENDIX B:  THE LIBRARY (HUGOLIB.H)


ATTRIBUTES

*>known
if an object is known to the player

*>moved
if an object has been moved

*>visited
if a room has been visited

*>static
if an object cannot be taken

*>plural
for plural objects (i.e., some hats)

*>living
if an object is a character

*>female
if a character is female

*>unfriendly
if a character is unfriendly

*>openable
if an object can be opened

*>open
if it is open

*>lockable
if an object can be locked

*>locked
if it is locked

*>light
if an object is or provides light

*>readable
if an object can be read

*>switchable
if an object can be turned on or off

*>switchedon
if it is on

*>clothing
for objects that can be worn

*>worn
if the object is being worn

*>mobile
if the object can be rolled, etc.

*>enterable
if an object is enterable

*>container
if an object can hold other objects

*>platform
if other objects can be placed on it

(NOTE:  container and platform are mutually exclusive)

*>hidden
if an object is not to be listed

*>quiet
if container or platform is quiet
(i.e., the initial listing of contents is suppressed)

*>transparent
if object is not opaque

*>already_listed
if object has been pre-listed
(i.e., before, for example, a WhatsIn listing)

*>workflag
for system use

*>special
for miscellaneous use


GLOBALS, CONSTANTS, AND ARRAYS

GLOBALS:

The first 10 globals are pre-defined by the compiler:

*>object
direct object of a verb action

*>xobject
indirect object

*>self
self-referential object

*>words
total number of words

*>player
the player object

*>actor
player, or another char. (for scripts)

*>location
location of the player object

*>verbroutine
the verb routine

*>endflag
if not false (0), run EndGame

*>prompt
for input line

*>objects
the total number of objects

*>player_person
first (1), second (2), or third (3)

*>MAX_SCORE
total possible score

*>MAX_RANK
up to x levels of player ranking

*>FORMAT
specifies text-printing format

*>DEFAULT_FONT
initially 0; could be, for example, PROP_ON

*>STATUSTYPE
0=none, 1=score/turns, 2=time

*>TEXTCOLOR
normal text color

*>BGCOLOR
normal background color

*>BOLDCOLOR
color for boldface printing

*>SL_TEXTCOLOR
statusline text color

*>SL_BGCOLOR
statusline background color

*>INDENT_SIZE
for paragraph indenting

*>AFTER_PERIOD
string of spaces following a full-stop

*>counter
elapsed turns (or time, as desired)

*>score
accumulated score

*>verbosity
for room descriptions

*>list_nest
used by ListObjects

*>light_source
in location

*>event_flag
set when something happens

*>speaking
if the player is talking to a char.

*>old_location
whenever location changes

*>last_object
set by Perform to value of object

*>obstacle
if something is stopping the player

*>best_parse_rank
for differentiating like-named objects

*>customerror_flag
true once CustomError is called

*>need_newline
true when newline should be printed

*>override_indent
true if no indent should be printed

*>number_scripts
number of active character scripts

*>it_obj
to reference objects via pronouns

*>them_obj
to reference objects via pronouns

*>him_obj
to reference objects via pronouns

*>her_obj
to reference objects via pronouns

*>general
for general use


ARRAYS:

*>replace_pronoun
*>oldword
*>scriptdata
*>setscript
*>ranking

replace_pronoun[4]
for it_obj, him_obj, etc.

oldword[MAX_WORDS]
for "again" command

scriptdata[48]
for object scripts

array setscript[1024]
the actual scripts

array ranking[10]
in tandem with scoring


CONSTANTS:

*>BANNER
should be printed in every game header

*>MAX_SCRIPTS
that may be active at one time

*>MAX_WORDS
in a parsed input line


Color constants:

*>BLACK			*>DARK GRAY
*>BLUE			*>LIGHT_BLUE
*>GREEN			*>LIGHT_GREEN
*>CYAN			*>LIGHT_CYAN
*>RED			*>LIGHT_RED
*>MAGENTA		*>LIGHT_MAGENTA
*>BROWN			*>YELLOW
*>WHITE			*>BRIGHT_WHITE

*>DEF_FOREGROUND	*>DEF_BACKGROUND
*>DEF_SL_FOREGROUND	*>DEF_SL_BACKGROUND
*>MATCH_FOREGROUND


Printing format masks (for setting FORMAT global):

*>LIST_F
print itemized lists, not sentences

*>NORECURSE_F
do not recurse object contents

*>NOINDENT_F
do not indent listings

*>DESCFORM_F
alternate room description formatting

*>GROUPPLURALS_F
list plurals together where possible


Font style masks (for use with the Font routine):

*>BOLD_ON
*>BOLD_OFF
boldface

*>ITALIC_ON
*>ITALIC_OFF
italics

*>UNDERLINE_ON
*>UNDERLINE_OFF
underline

*>PROP_ON
*>PROP_OFF
proportional printing


Additional constants:

*>UP_ARROW
*>DOWN_ARROW
*>LEFT_ARROW
*>RIGHT_ARROW
*>ENTER_KEY
*>ESCAPE_KEY
*>MOUSE_CLICK
for reading keystrokes


*>AND_WORD
("and")

*>IN_WORD
("in")

*>ARE_WORD
("are")

*>IS_WORD
("is")

*>HERE_WORD
("here")

*>ON_WORD
("on")


*>FILE_CHECK
for verifying writefile/readfile operations


(The following are used only by specific routines:


ARRAYS:

*>_temp_array
*>menuitem

_temp_array[256]
used by string manipulation functions

menuitem[11]
required by the Menu function


GLOBALS:

*>MENU_TEXTCOLOR
normal menu text color

*>MENU_BGCOLOR
normal menu background color

*>MENU_SELECTCOLOR
menu highlight color

*>MENU_SELECTBGCOLOR
menu highlight background color)


PROPERTIES

The first 6 properties are pre-defined by the compiler:

*>name
basic object name

*>before
pre-verb routines

*>after
post-verb routines

*>noun
*>nouns
noun(s) for referring to object

*>adjective
*>adjectives
adjective(s) describing object

*>article
"a", "an", "the", "some", etc.

*>preposition
*>prep
"in", "inside", "outside of", etc., used generally for room
objects in order to give a grammatically correct description
if necessary; also for containers and platforms

*>pronoun
"he", "him", "his" or equivalent, so that an object is
properly referred to

*>short_desc
routine; basic "X is here" description

*>initial_desc
routine; same as above, but if object has not been moved and
an initial_desc exists, it is called in place of short_desc

*>long_desc
routine; detailed description

*>found_in
in case of multiple virtual (not "physical") parents,
found_in may hold one or more object numbers; in this case,
an "in <object>" specifier should not be included in the
object definition, since found_in values are unrelated to
"object in parent" relationships

*>type
to identify the type of object, used primarily by class
definitions in OBJLIB.H

*>size
for holding/inventory purposes, contains a value
representing the size of an individual object

*>capacity
contains a value representing the capacity of a container or
platform

*>holding
contains a value representing the current encumbrance of a
container or platform

*>reach
for enterable objects such as chairs, vehicles, etc., if the
accessibility of objects outside the object in question is
limited, reach contains a list of the objects which may be
accessed; if access is limited to the object in question
only, reach must still contain at least one non-false value
(i.e., the parent object itself)

*>list_contents
a routine that overrides the normal contents listing for a
room or object; normal listing is only carried out if it
returns false

*>in_scope
contains a list of actors or objects to which the object is
accessible beyond the use of the object tree or the found_in
property; generally contains either the player object (or,
less commonly, another character) and is set or cleared
using PutInScope or RemoveFromScope

*>parse_rank
when there is ambiguity between similarly named objects, the
parser will choose the one with a higher parse_rank over one
with a lower (or non-existant) value--used when
FindObject(<obj>, 0) is called

*>exclude_from_all
returns true if the object should be excluded from actions
such as "get all"

*>misc
miscellaneous use


For room objects only:

*>n_to
*>ne_to
*>e_to
*>se_to
*>s_to
*>sw_to
*>w_to
*>nw_to
*>u_to
*>d_to
*>in_to
*>out_to
If a player can move to another room object in direction X,
then x_to holds the new room object
			
*>cant_go
routine; message instead of default "You can't go that way."


For non-room objects only:

*>door_to
for handling "Enter <object>", holds the object number of
the object to which an object enters (where the latter
behaves as a door or portal)

*>key_object
if lockable, contains the object number of the key

*>when_open
*>when_closed
Routines; short descriptions for openable objects. If they
exist, the appropriate when_open or when_closed routine is
called instead of short_desc (if an initial_desc does not
exist, or if the object has been moved)

*>ignore_response
for characters, a routine that runs if the character ignores
a player's question, request, etc., instead of the default
"X ignores you."

*>order_response
also for characters, a routine that processes an imperative
command addressed to the character by the player; it should
return false if no response is provided

*>contains_desc
a routine that prints the introduction to a list of child
objects, instead of the default "Inside <object> are..." or
"<character> has..."; contains_desc should always conclude
with a semicolon (';') instead of a new line

*>inv_desc
a routine that prints a special description when the object
is listed as part of the player's inventory; inv_desc should
conclude with a semicolon (';')

*>desc_detail
a routine that prints a parenthetical detail following an
object listing, such as:  " (which is open)"; the leading
space is expected, as are the parentheses, and the print
statement should conclude with a semicolon (';')


NOTE:  It is recommended for property routines that print a
description--such as short_desc, initial_desc, etc.--that
the routine not simply return true without printing anything
as a means of "hiding" the object; such a method may throw
text formatting into disarray.  The proper means of omitting
an object from a list is to set the hidden attribute.


For the display object only:


Read-only:

*>screenwidth
width of the display, in characters

*>screenheight
height of the display, in characters

*>linelength
width of the current text window

*>windowlines
height of the current text window

*>cursor_column
*>cursor_row
horizontal and vertical position of the cursor in the
current text window

*>hasgraphics
true if the current display is graphics-capable


Read/writable:

*>title_caption
dictionary entry giving the full proper name of the program
(optional)


Defined in HUGOLIB.H:

*>statusline_height
of the last-printed status line


(While screenwidth through title_caption are technically
defined by HUGOLIB.H as constants, they are used as property
numbers to reference data on the display object.)


ROUTINES

VERB ROUTINES:

VERBLIB.H (included by HUGOLIB.H) contains a fairly
extensive set of basic actions, each of which takes the form
Do<verb>, so that the action for taking an object is DoGet,
the action for basic player movement is DoGo, etc.

Each is called by the engine when a grammar syntax line
specifying the particular verb routine is matched.  Globals
object and xobject are set up by the engine, and the routine
is called with no parameters.

Here is a list of the provided verb routines for action
verbs:

*>DoAsk, *>DoAskQuestion, *>DoClose, *>DoDrop, *>DoEat,
*>DoEnter, *>DoExit, *>DoGet, *>DoGive, *>DoGo, *>DoHit,
*>DoInventory, *>DoListen, *>DoLock, *>DoLook,
*>DoLookAround, *>DoLookIn, *>DoLookThrough, *>DoLookUnder,
*>DoMove, *>DoOpen, *>DoPutIn, *>DoShow, *>DoSwitchOff,
*>DoSwitchOn, *>DoTakeOff, *>DoTalk, *>DoTell, *>DoUnlock,
*>DoVague, *>DoWait, *>DoWaitforChar, *>DoWaitUntil,
*>DoWear

Here are the non-action verb routines:

*>DoBrief, *>DoQuit, *>DoRestart, *>DoRestore, *>DoSave,
*>DoScore, *>DoScriptOnOff, *>DoSuperbrief, *>DoVerbose

(NOTE:  A set of verb stub routines is also available,
including the actions:

*>DoBurn, *>DoClimb, *>DoCut, *>DoDig, *>DoFollow, *>DoHelp,
*>DoJump, *>DoKiss, *>DoNo, *>DoPull, *>DoPush, *>DoSearch,
*>DoSleep, *>DoSmell, *>DoSorry, *>DoSwim, *>DoThrowAt,
*>DoTie, *>DoTouch, *>DoUntie, *>DoUse, *>DoWake,
*>DoWakeCharacter, *>DoWave, *>DoWaveHands, *>DoYell,
*>DoYes

The default response for each of these stub routines is a
more colorful variation of "Try something else."  Any more
meaningful response must be incorporated into before
property routines.

To use these verbs, set the VERBSTUBS flag before compiling
HUGOLIB.H.


UTILITY ROUTINES, ETC.:

Routines may be treated as procedures or functions, given
the idea that procedures are more like commands, while
functions are expected to return a value, as in:

	Procedure(a, b)
	x = Function(y)
	if Function()...

Library routines that do not return a value are generally
meant to be treated as procedures; those that do return a
value may be treated as either functions or procedures.

First, the junction routines:


*>EndGame

called by the engine via:
	EndGame(end_type)
				
If end_type = 1, the game is won; if 2,
the game is lost.  (Since endflag may be
any value, a value of, for example, 3 will
still call EndGame, but with no additional
effects via the default PrintEndGame
routine.)  The global endflag is cleared
upon calling.  Returning false from
EndGame terminates the Hugo Engine.

Also calls:  PrintEndGame and PrintScore


*>FindObject

called by the engine via:
	FindObject(object, location)

Returns true (1) if the specified object
is available in the specified location, or
false (0) if it is not.  Returns 2 if the
object is visible but not physically
accessible.

The <location> argument is 0 during object
disambiguation performed by the engine.

Also calls:  ObjectisKnown, ExcludeFromAll


*>Parse

called by the engine via:
	Parse()

Returning true forces the engine to re-
parse the modified input line.

Also calls:  PreParse, AssignPronoun and
	     SetObjWord


*>ParseError

called by the engine via:
	ParseError(errornumber, object)

Returning false signals the engine to
print the default error message.  Return 2 to
force the existing line to be reparsed as is.

May also call:  CustomError


*>SpeakTo

called by the engine via:
	SpeakTo(character)

Globals object, xobject, and verbroutine
are set up as in a normal verb routine
call.

Also calls:  AssignPronoun


And the routines for grammatically-correct printing:


*>The

calling form:  The(object)

Prints the definite article form of the
object name, e.g. "the apple"


*>Art

calling form:  Art(object)

Prints the indefinite article form of the
object name, e.g. "an apple"


*>CThe

calling form:  CThe(object)

Prints the capitalized definite article
form of the object name, e.g. "The apple"


*>CArt

calling form:  CArt(object)

Prints the capitalized indefinite article
form of the object name, e.g. "An apple"


*>IsorAre

calling form:  IsorAre(object[, formal])
where the parameter formal is optional

Depending on whether or not the specified
object is plural or singular, prints "'re"
or "'s", respectively (or " are" or " is"
if the formal parameter is specified as
true).


*>MatchPlural

calling form:  MatchPlural(object, w1, w2)

Prints the dictionary entry given by w1 if
the supplied object is not plural, or w2
if it is.


*>MatchSubject

calling form:  MatchSubject(object)

Matches a verb to the given subject
<object>.  If the object is plural,
nothing is printed; if the object is
singular, an "s" is printed.


NOTE:  None of the above printing routines prints a
carriage return, and all return 0 (the null string).
Therefore, either of the following usages are valid:

	CThe(apple)
	print " is here."

or

	print CThe(apple); " is here."


Other routines:


*>Acquire

calling form:
	Acquire(parent, object)

Checks to see if parent.capacity is
greater than or equal to
parent.holding plus object.size.  If
so, it moves object to the specified
parent, and returns true.  If the
object cannot be moved, Acquire
returns false.

Also calls:  CalculateHolding


*>AnyVerb

calling form:
	AnyVerb(object)

Returns object if the current
verbroutine is not an xverb;
otherwise it returns false.


*>AssignPronoun

calling form:
	AssignPronoun(object)

Sets the appropriate global it_obj,
them_obj, him_obj, or her_obj to the
specified object.


*>CalculateHolding

calling form:
	CalculateHolding(object)

Properly recalculates object.holding
based on the sizes of all held
objects.


*>CenterTitle

calling form:
	CenterTitle(text[, lines])

Clears the screen and centers the
text given by the specified
dictionary entry in the top window.
The default height of the title
(i.e., one line) can be overridden
with a second argument given the
number of lines.


*>CheckReach

calling form:
	CheckReach(object)

Checks to see if the specified object
is within reach of the player object.
Returns true if accessible; returns
false--and prints an appropriate
message--if not.	


*>Contains

calling form:
	Contains(parent, object)

Returns <object> if the specified
object is present as a possession of
the specified parent, even as a
grandchild, otherwise returns false.


*>CustomError

calling form:
	CustomError(errornumber, object)

Replace if custom error messages are
desired.  Is called by ParseError
whenever errornumber is greater than
or equal to 100, specifying a user
parser error.  Should return false if
no user message is found.


*>DarkWarning

calling form:
	DarkWarning

Is called by MovePlayer whenever the
player object is moved into a
location without a light source.  The
default library routine simply prints
a message; for a more sinister
response or action, such as the death
of the player, replace the default
with a new DarkWarning routine.


*>DeleteWord

calling form:
	DeleteWord(wordnumber[, number])

Deletes the number of words given by
the second argument--or only one word
if no second argument is given--
starting with word[wordnumber].
Returns the number of words deleted.


*>DescribePlace

calling form:
	DescribePlace(location[, long])

Prints the location name and, when
appropriate, a location description
(i.e., its long_desc).  Including a
non-false long parameter will always
force a location description.


*>ExcludeFromAll

calling form:
	ExcludeFromAll(object)

Returns true if, based on the current
circumstances (verbroutine, etc.),
the supplied object should be
excluded from actions using "all"--
such as multi, multiheld, and
multinotheld grammar tokens.


*>FindLight

calling form:
	FindLight(location)

Checks to see if a light source is
available in the player's location;
if so, it sets the global
light_source to the object number of
the source and returns that value.

Also calls:  ObjectIsLight


*>Font

calling form:
	Font(bitmask)

Sets the current font attributes as
specified by bitmask, where bitmask
is one or more font-style constants
(see library constants, above)
combined with '|' or '+'.


*>GetInput

calling form:
	GetInput([prompt string])

Receives input from the keyboard,
storing individual words in the word
array; unknown words--i.e., those
that are not in the dictionary--are
assigned the null string, 0 or "".
If an argument is passed, it is
assumed to be a dictionary address
for the prompt string.  If no
argument is passed, no prompt is
printed.


*>HoursMinutes

calling form:
	HoursMinutes(counter[, military])

Prints the time in hh:mm format given
that the global counter represents
the time in minutes from 12:00 a.m.
If the optional military value is
given as a true value, time is in 24-
hour "military" format.


*>Indent

calling form:
	Indent

If the NOINDENT_F bit is not set in
the FORMAT mask, Indent prints two
spaces without printing a newline


*>InList

calling form:
	InList(object, property, value)

If <value> is in the list of values
held in <object>.<property>, returns
the element number of the (first)
property element equal to <value>;
otherwise returns 0.


*>InsertWord

calling form:
	InsertWord(wordnumber[, number])

Makes space for either the number of
words given by the number argument--
or one word if no second argument is
given--if possible, at
word[wordnumber], shifting upward all
words from that point to the end of
the input line.  Returns the number
of words inserted.


*>ListObjects

calling form:
	ListObjects(object)

Lists all the possessions of the
specified object in the appropriate
form (according to the global
FORMAT).  Possessions of possessions
are listed recursively if FORMAT does
not contain the NORECURSE_F bit.
Format masks are combined, as in:

FORMAT = LIST_F | NORECURSE_F | ...

Also calls:  WhatsIn


*>Menu

calling form:
	Menu(number, [width[, selection]])

Prints a menu, given that the
possible choices (up to 10) are
contained in the menuitem array, with
menuitem[0] is the title of the menu.
A starting selection number is
optional.  Returns the number of the
item selected, or 0 if none is
chosen.

Also calls:  CenterTitle


*>Message

calling form:
	Message(&routine, num, a, b)

Used by most routines in HUGOLIB.H
for text output, so that the bulk of
the library text is centralized in
one location.  Message number num for
the specified routine is printed; a
and b are optional parameters that
may represent objects, dictionary
entries, or any other value.

(NOTE:  Similar routines are provided
in VMessage in VERBLIB.H and OMessage
in OBJLIB.H.)


*>MovePlayer

calling form:
	MovePlayer(loc[, silent[, none]])
	MovePlayer(dir[, silent[, none]])

Moves the player to the new location,
properly setting all relevant
variables and attributes.  If
<silent> is specified (as a true
value), no room description is
printed following the move.

A direction object (i.e., n_obj,
d_obj) may be specified instead of a
location; in this instance,
MovePlayer moves in that direction
from the player object's present
location.

If <none> is true, before/after
routines are not run.

Can be checked in a location's before
or after property as "location
MovePlayer" to catch a player's exit
from or entrance to a location.

Returns the object number of the
player object's new parent.

NOTE:  MovePlayer does not check to
see if a move is valid; that must be
done before calling the routine.

May also call:  DarkWarning


*>NumberWord

calling form:
	NumberWord(number[, true])

Prints a number in non-numerical word
format, where <number> is between
-32768 to 32767.  Always returns 0
(the null string).  If a second
(true) argument is supplied, the word
is capitalized.


*>ObjectIs

calling form:
	ObjectIs(object)

Lists certain attributes, such as
providing light or being worn, of the
given object in parenthetical form.


*>ObjectisKnown

calling form:
	ObjectisKnown(object)

Returns true if the object is known
to the player.


*>ObjectisLight

calling form:
	ObjectisLight(object)

Returns true if the object or one of
its visible possessions is providing
light.  If so, it also sets the
global light_source the object number
of the source.


*>ObjWord

calling form:
	ObjWord(word, object)

Returns either adjective or noun
(i.e., the property number) if the
given is either an adjective or noun
of the specified object.


*>PreParse

calling form:
	PreParse

Provided so that, if needed, this
routine may be replaced instead of
the more extensive library Parse
routine.  The default routine defined
in the library is empty.


*>PrintEndGame

calling form:
	PrintEndGame(end_type)

Depending on whether end_type is 1 or
2, prints "*** YOU'VE WON THE GAME!
***" or "*** YOU ARE DEAD ***".


*>PrintScore

calling form:
	PrintScore(end_of_game)

Prints the score in the appropriate
form, depending on whether or not
end_of_game is true.
					

*>PrintStatusLine

calling form:
	PrintStatusLine

Prints the statusline in the
appropriate format, according to the
global STATUSTYPE.


*>PropertyList

calling form:
	PropertyList(obj, property)

Lists the objects held in
obj.property (if any), returning the
number of objects listed.


*>PutInScope

calling form:
	PutInScope(object, actor)

Makes <object> accessible to <actor>,
regardless of their respective
locations, and providing that the
in_scope property of <object> has at
least one empty slot--i.e., one that
equals 0.  Returns true if
successful.


*>RemoveFromScope

calling form:
	RemoveFromScope(object, actor)

Removes <object> from the scope of
<actor>.  Returns true if successful,
or false if <object> was never in
scope of <actor> to begin with.


*>SetObjWord

calling form:
	SetObjWord(position, object)

Inserts the specified object in the
word array in the format:

"adjective1 adjective2...noun"


*>ShortDescribe

calling form:
	ShortDescribe(object)

Prints the short description
(short_desc) of the given object,
first checking to see if it should
run initial_desc, when_open, or
when_closed, as appropriate.  Then,
if no short_desc property exists, it
prints a default "X is here."

Also calls:  WhatsIn


*>SpecialDesc

calling form:
	SpecialDesc(object)

Checks each child object of <object>,
running any appropriate initial_desc
or inv_desc property routines
(depending on the calling situation).
Sets the global variable list_count
to the number of remaining (i.e.,
non-listed) objects.


*>WhatsIn

calling form:
	WhatsIn(parent)

Lists the possessions of the
specified parent, according the form
given by the global FORMAT.  Returns
the number of objects listed.

Also calls:  SpecialDesc, ListObjects


*>YesorNo

calling form:
	YesorNo

Checks to see if the just-received
input is "yes", "y", "no", or "n".
If none of the above, it prompts for
a yes or no answer.  Once a valid
answer is received, it returns true
(if yes) or false (if no).


AUXILIARY MATH ROUTINES:


*>abs

calling form:
	abs(a)

Returns the absolute value of <a>.


*>higher

calling form:
	higher(a, b)

Returns the higher number of <a> or <b>.


*>lower

calling form:
	lower(a, b)

Returns the lower number of <a> or <b>.


*>mod

calling form:
	mod(a, b)

Returns the remainder of <a> divided by <b>.


*>pow

calling form:
	pow(a, b)

Returns <a> to the power of <b>.
(The return value is unpredictable if
the result is outside the boundary of
-32768 to 32767.)


STRING ARRAY ROUTINES:


*>StringCompare

calling form:
	StringCompare(array1, array2)

Returns 1 if <array1> is lexically
greater than <array2>, -1 if <array1>
is lexically less than <array2>, and
0 if the strings are identical.


*>StringCopy

calling form:
	StringCopy(new, old[, len])

Copies the contents of the array at
the address given by <old> to the
array at <new>, to a maximum of <len>
characters if <len> is given, or the
length of <old> if it isn't.


*>StringDictCompare

calling form:
	StringDictCompare(array, dictentry)

Performs a StringCompare-like
comparison of a string array given by
<array> and the dictionary entry
<dictentry>, returning 1, -1, or 0 if
<array> is lexically greater than,
less than, or equal to <dictentry>,
respectively.


*>StringEqual

calling form:
	StringEqual(array1, array2)

Returns true only if <array1> and
<array2> are identical.


*>StringLength

calling form:
	StringLength(array)

Returns the length of the string
stored as <array>.


*>StringPrint

calling form:
	StringPrint(array[, start, end])

Prints the string stored as <array>,
beginning with <start> and ending
with <end> if given.


FUSE/DAEMON ROUTINES:

(See the earlier section on fuses and daemons for more
information.)


*>Activate

calling form:
	Activate(object[, setting])

Activates the specified fuse or
daemon object.  The setting value is
only specified for fuses, where it
represents the initial value of the
timer property.


*>Deactivate

calling form:
	Deactivate(object)

Deactivates the specified fuse or
daemon object.


CHARACTER SCRIPT ROUTINES:

(See the earlier section on character scripts for more
information.)


*>CancelScript

calling form:
	CancelScript(character)

Immediately cancels the character
script associated with the object
<character>.  Returns true if
successful, i.e., if a script for
<character> is found.


*>PauseScript

calling form:
	PauseScript(character)

Temporarily pauses the character
script associated with the object
<character>.  Returns true if
successful.


*>ResumeScript

calling form:
	ResumeScript(character)

Resumes execution of a paused script.
Returns true if successful.


*>SkipScript

calling form:
	SkipScript(character)

Skips execution of the script for
<character> during the next call to
RunScripts only.


*>Script

calling form:
	Script(character, steps)

Initializes space for the requested
number of steps in the setscript
array, sets up the data for the
script in the scriptdata array, and
returns the location of the script in
setscript.  Returns -1 if MAX_SCRIPTS
is exceeded.


*>RunScripts

calling form:
	RunScripts

Runs all active scripts, calling them
in the form:

CharRoutine(character, object)


CHARACTER ACTION ROUTINES:

*>CharWait
*>CharMove
*>CharGet
*>CharDrop
*>LoopScript

As a starting point, the library also provides a limited
number of routines for character objects to use in scripts.
They are:

	&CharWait, 0
	&CharMove, direction_object (requires OBJLIB.H)
	&CharGet, object
	&CharDrop, object
and
	&LoopScript, 0


CONDITIONAL COMPILATION:

*>NO_AUX_MATH
*>NO_FUSES
*>NO_MENUS
*>NO_OBJLIB
*>NO_RECORDING
*>NO_SCRIPTS
*>NO_STRING_ARRAYS
*>NO_VERBS
*>NO_XVERBS

A number of compiler flags may be set which exclude certain
portions of HUGOLIB.H from compilation if these functions or
objects are not required.

	FLAG:				EXCLUDES:

	NO_AUX_MATH		Auxiliary math routines
	NO_FUSES		Fuses and daemons
	NO_MENUS		Use of the Menu function
	NO_OBJLIB		OBJLIB.H
	NO_RECORDING		Command recording functions
	NO_SCRIPTS		Character scripting routines
	NO_STRING_ARRAYS	String array functions
	NO_VERBS		All action verbs
	NO_XVERBS		All non-action verbs
------------------------------------------------------------





------------------------------------------------------------
Hugo Compiler, Engine, Debugger, Library,
and the Hugo Manual
Copyright (c) 1995-1990 by Kent Tessman

<kent@generalcoffee.com>
http://www.generalcoffee.com
------------------------------------------------------------
