DOCO

										CHANGES/UPDATES
                 					---------------


10/13/88	Jeff:

	The isStopped: method of Actor has been fixed so that it works
	properly.  You should now be able to vary cycleSpeed and moveSpeed
	independently for Actors on a Walk and have it work properly.


9/22/89	Pablo:	GOTOSAID: The end of "not close enough".

	TurnIfSaid is a new version of Mark Hood's procedure for making ego 	
	face whatever was mentioned. For example if the user types "look chair" 
	ego will	turn in place to face the chair before getting a response.
	
	GoToIfSaid is similar but, as the name implies, it moves ego to a 
	specified point or object vicinity before reprocessing the Said event.
	
	These procedures are only useful if sortedFeatures are in use. Grooper 
	and avoider are used to turn and move.
	
	* This takes up ZERO bytes if you don't use it.


9/22/89	Pablo:	AVOIDER: Great taste, less filling!

	* 28 bytes SMALLER!
	* Improved ability to get around convex obstacles (the most	common kind).
	* No longer tries to reach illegal destinations. This means that you can 
	leave an avoider on ego without it trying forever to get inside a table 
	if the user happened to click there. In such cases you get the same 
	behavior as if the avoider weren't even attached. The same is true for 
	cursor key presses: since off-screen destinations are not in the 
	avoider's department it leaves it all up to the mover, as it should!
	
	* This takes up ZERO bytes if you don't use it.


9/22/89	Mark Hood:	GROOPER: Great taste, less filling!

	* 112 bytes SMALLER!
	* More functional, restores arbitrary old loopers.
	* Now works correctly with avoiders.
	
	* This takes up ZERO bytes if you don't use it.
	

9/19/89	Jeff

	Joystick related stuff:
	There is a new kernel call named 'Joystick' to do things to the joystick.
	At present, it only has one function, 'JoyRepeat', which sets the joystick
	repeat rate.  Usage is

		(Joystick JoyRepeat n)

	where n may have the following values:

		-1		Just return the current repeat rate without changing it.
		0		Turn off joystick repeat.  In this case, the joystick will
				only return a direction event when the direction is changed.
		n		Have the joystick return a direction event (except for the
				'stopped' direction, 0) every 'n' system ticks (which occur
				at 1/60th of a second).

	The default repeat rate is 0, i.e. the joystick only reports direction
	changes.  For selecting items with the joystick (as in the MenuBar),
	setting the repeat rate to 30 (two direction events per second) gives
	a controllable repeat for selection.

	The JoyRepeat function always returns the previous value of the repeat
	rate.  Remember to set it back to this value when you're done!

		(= oldValue (Joystick JoyRepeat 30))
		... some user selection ...
		(Joystick JoyRepeat oldValue)



9/4/89	Pablo

	GRAMMAR and VOCABASE change.
	
	The bad news: the words "to", "from" and "about" were being improperly 
	handled, forcing programmers into some kludges to solve the problem. The 
	most infamous example was the need to use TWO said specs to trap the 
	sentences "ask about beer" and "ask bartender about beer"; ie. 
	'ask/beer<about' and 'ask//beer<about' (yeech!). Also, to and from were 
	sometimes modifiers to the verb and sometimes to the indirect object, 
	adding to the hit-and-miss nature of said-spec writing.
	
	The good news: This is fixed, so 'ask//beer' is enough to trap ALL 
	questions about beer, and to/from are always modifiers to the VERB. Life 
	is simpler...
	
	The price: You will want to grep through your code looking for 
	'ask/beer<about' and 'give/gold/dwarf<TO' style cases; and change them.
	My initial grep uncovered less than a dozen such cases per project, so 
	it's not so bad. If you were covering all bases by writing all possible 
	specs then the changes are largely optional. You will need to rebuild 
	regardless, since word numbers have changed...


8/29/89  Corey

	Added "track" method to Cat class.  Allows Cat to be init'ed after
	the appropriate mouse event has already occurred, and for cursor
	keys emulating mouse.  (External module invokes "track", which is
	equivalent to an existing Cat object receiving a mouse down.)
	Ask Pablo or me for details.


8/28/89	Pablo

	User now has a "curEvent" property which points to the last event 
	processed by User. This is especially useful for following the mouse.
	
	Demo Demon now has FakeMouseUp as well as FakeMouseDown, both of which 
	are really defines that use FakeMouse, which is now tied into User 
	curEvent.
	
	Cat changed to track (User curEvent?) in its doit unless doCast is TRUE 
	in which case it hogs processing. This is a safer implementation for 
	allowing background animation while tracking. Also helps programmatic 
	control of Cats.
	

8/28/89	Pablo

	Class Cat now accepts a caller that gets cue'd when the mouse is 
	released.
	
	Class Track of Motion has been added.
	
	;;	keep client at a certain x and y offset relative to position of
	;;	object who
	;;
	;;	client should come AFTER "who" in the cast
	;;
	;;	Usage: 
	;;		(theTracker setMotion: 
	;;				Track theTrackee xOffset yOffset zOffset theCaller)
	;;
	


8/11/89	Jeff

	Buttons other than the left button on multi-button mice are now
	supported:

		right button	->		shift-click of left button
		center button	->		ctrl-click of left button


8/10/89	Pablo

	QSOUND: Queued sounds now respond to the new sound protocol for cues, 
	where 1-127 are for ad-hoc cues (as before) and 128-64k are for 
	sequential cues. Sequential and ad-hoc cues may be mixed within a song, 
	although the check method of the QueuedSound instance would have to be 
	specialized. This change is backward-compatible.
	
	CAT: Is now a subclass of Actor instead of View, fixing a conceptual bug 
	in the first implementation. This will require you to rebuild.


8/7/89	Pablo

	New files FORCOUNT and LASTLINK
		
	;; Usage:
	;;			(LastLink #client thisScript)
	;;			(LastLink #script thisActor)
	;;			etc...

	;; ForwardCounter Cycle Class
	;; Saves states in scripts by cycleing a given number of times
	;; then cueing on completion.
	;; Usage : propName setCycle:ForwardCounter numOfCycles whoCares
		


8/3/89	Corey

	Corrected some of the comments in the StopWalk class.  There was
	an error in the StopWalk usage originally described here.  Correct
	usage example:

		(actor  setCycle: StopWalk stoppedView)

	The "walking view" is determined from actor's walking view when
	StopWalk invoked, not passed as an argument.


7/28/89	Bob

	The program, INSTAL.EXE has been modified to adapt to games
	that do not wish to support a joystick.  If the program finds
	a file named JOYSTICK.DRV on the disk, it will display the use
	options as normally.  If this file is NOT present, the use dialog
	will NOT be presented.
	PLEASE NOTE: This represents a significant deviation from standard
	Sierra policy, so be sure to inform Garuka of your decision, so that
	it can be coordinated with documentation and QA.


7/21/89	Bob
	
	OOPS!	
	On the 14 of June of the year 1989 I, Robert E. Heitman,
	made a change to the priority band placement in SCI.
	The absolute Y coordinate of every other priority band
	shifted down one pixel.  This has given rise to one problem
	in an older game, where a stop updated door was placed
	directly on a priority band in order to minimize the size
	of the control block.
	If you have experienced un-reconcilable priority problems
	with existing artwork that predated this change, please contact
	me.

7/20/89	Jeff

	A new compiler/SCI combination now lets SCI know whether to load the
	text.xxx resource when it loads script.xxx.  This should speed up disk
	access in general when loading a far-textless script, and prevents disk
	access when accessing a far-textless script which is in hunk.  You should
	rebuild your game as soon as possible.  If you can't do so right now, the
	old interpreter is in x:sciold.exe and x:scivold.exe.  The old interpreter
	will run files compiled with the new compiler just fine...

7/20/89	Bob

	A minor flaw in the debugger has been fixed.  The problem related
	to "crashing" when you bring up the debugger.  The crash could
	be manifested in many ways, the most common was "packhandles failure".
	Bringing up the debugger could have also caused delayed memory
	failures that are hard to pinpoint.  Please let me know if things
	appear to be less fragile memory wise.

7/18/89	Pablo

	QSCRIPT: fixed a couple of bugs in script overlaying mechanism, looks 
	much more solid now. Required minor bug fixes in game.sc and actor.sc as 
	well. There is no need to rebuild.

	LOADMANY: New procedure LoadMany allows you to load or unload several 
	resources with a single line of code.
	
	Loading examples:
		(LoadMany VIEW 123 232 433)
		(LoadMany SCRIPT 123 232 433)
		
	Unloading example (performs DisposeScripts):
		(LoadMany FALSE AVOIDER REVERSE TIMER)
		
	
7/13/89	Pablo

	INTRFACE: New method check added to Dialog, fixes bug that kept 
	modelessDialogs from going away upon expiration of seconds.


7/12/89	Pablo

	(class QueuedSound kindof Sound
	
		(properties name "QSnd")

	;;Author: Pablo Ghenis, 7/12/89
	;;
	;;A QueuedSound assumes that the absolute values of the cues it receives
	;;form a sequence, ie. 1,2,3... QueuedSounds eliminate the risk off having 
	;;the animation loop overrun by rapid sound cues since it catches up by 
	;;cueing its client as many times as the latest increment in signal, thus 
	;;faking a "queue of cues" (sorry, I can't resist a pun!)
	
	;;size=160 bytes, should save its own weight in ad-hoc code
	
	)


7/10/89	Pablo

	INTRFACE has been modified to avoid loading TIMER, a 650-byte savings for 
	users of the demo demon or anyone using #time in a Print. Since this 
	involves some new properties it will require a rebuild.
	
	New class TimedCue in script TIMEDCUE. This is a very small substitute 
	for timers that will provide a cue after a specified number of seconds or 
	cycles; it is a subclass of Script and takes 150 bytes or so. What you 
	give up for the 500 bytes is the ability to specify game time, which is 
	more appropriate in many situations. No free lunch, but it may be useful.


6/30/89	Pablo

	DPath = D(yanamic)Path and RelDPath motion classes
	
	This is an alternative to Path, which requires allocation of a static 
	array and specialization of the "at" method.	D(ynamic)PATH uses a 
	dynamically created list to keep path points.
	
	RelDPath interprets its coordinate pairs as relative instead of absolute 
	targets.
	
	Usage is like other motion classes:
	
		(anActor setMotion DPath x1 y1 x2 y2 ...  anOptionalCaller)
		(anActor setMotion RelDPath x1 y1 x2 y2 ...  anOptionalCaller)
		

6/28/89	Pablo

	SCIP Parse tree viewer
	
	To figure out what said spec to write for a sentence you can now run SCIP 
	and type it in. SCIP will display the parse tree in a form that is easily 
	translatable to said-ese.
	
	Example: 
	
		1-	type "get big rock" where get is a noun, big is an adjective and 
			rock is a noun.
		
		2-	SCIP echoes (the indentation is very significant)
			(Root
				(Root
					(Root	.w123))		;get is root of Root
				(DObj
					(<	.w456)			;big is modifier of DObj
					(Root	.w789)))		;rock is root of DObj
					
		3-	Said spec template is 'Root<modifier/DObj<modifier/IObj<modifier'
			so this case is 'get/rock<big'.
			
	Use SCIP next time your favorite author demands the ability to parse 
	"how do squrrels get into trees?"

6/28/89  Corey

	* Added StopWalk class (STOPWALK.SC).  Use in place of Walk if you
			have an alternate view to use when ego is stopped/blocked.
			Behaves just like Walk otherwise.  Should be compatible with
			GROOPER, but not with SMOOPER.
	;;;
	;;; Usage example:
	;;;	(actor setCycle: StopWalk walkingView stoppedView)


6/28/89	Pablo

	* classes Ego, MouseDownHandler and Script updated.
	* new file QSCRIPT
	* new versions of SIGHT, TEXTRA, SMOOPER, GROOPER
	
	Ego: fixed bug that caused ego to respond to mouseDowns even when (User 
	controls) was 0.

	MOUSER: The MouseDownHandler class now has a property name shiftParser 
	which should point to an instance of Code whose doit method will be 
	responsible for putting together a string to be parsed. This opens up the 
	architecture for translating shift-clicks into saidEvents.
	
	;;	Usage:
	;;	
	;;	(instance MyMouseSays of Code
	;;		(method (doit what event)
	;;			(Parse {look} event)	;or (Parse (what name) event)
	;;		)
	;;	)
	;;	(instance MyMouseDownHandler of MouseDownHandler)
	;;	
	;;	(instance FooQuest of Game
	;;		...
	;;		(method (init)
	;;			...
	;;			((= mouseDownHandler MyMouseDownHandler)
	;;				shiftParser: MyMouseSays
	;;				,add: cast features
	;;			)
	;;			...
	;;		);init
	;;		...
	;;	);FooQuest
	
	
	The Script class now has a "next" property which allows chaining of 
	scripts. 
	
	;;	Usage:
	;;	
	;;	(QueScript anObj scriptToChainTo optionalWhoToCallWhenDone optRegister)
	;;	
	;;	this will trigger the following when anObj is done executing its current
	;;	script if any:
	;;	(anObj setScript scriptToChainTo optionalWhoToCallWhenDone optRegister)
	;;	
	;;	scriptToChainTo can be the number of a module which has a real script
	;;	as public entry zero. This mechanism provides an easy route for 
	;;	"overlaying" portions of long or mutually exclusive scripts to save
	;;	memory.
	
	
	
6/22/89	Pablo

	SCPP, the pretty indenter for SCI, now treats comment lines as follows:
	
;;; triple semicolon comments are left-justified
(instance commentExample of FooBar
	;;double semicolon comments are indented just like code
	(properties
		foo	BAR	;this is a comment
						;and this is a single-; continuation
						;which SCPP leaves right where it is
						;hopefully aligned with a previous end-of-line comment
	)
)
			
6/9/89	Bob

	Certain masochists requested the ability to have alternate
	palettes contained within the same picture. I have acceeded
	to their demands.  The palettes are specified in PE version
	6.000 or higher by pressing 'P' at the color selection window.
	All palettes are thereafter saved & loaded with that picture.

	An SCI programmer can request one of those palettes (0 - 3) as
	yet another parameter to the DrawPic kernel routine.  She may
	also access an alternate palette by setting the global variable
	"currentPalette" to the proper value BEFORE drawing the picture
	via the drawPic method of the room. (NOTE  - This method is called
	in the Room's super init: method)  
	The full DrawPic protocol: 

	(DrawPic 
		picNumber	; pic.xxx etc.
		showStyle	; how to show it 
		clearPic 	; TRUE will clear pic, FALSE will overlay
		palette		; 0 - 3 No error if palette not in data.
	)


6/7/89	Bob

	I hate writing in this file, so...
	If you want an Icon to cycle in a Print window, you
	need merely tell Print about it using the same tired old
	#icon: parameter. This time, however, instead of passing
	view, loop, and cel numbers, you pass an objectID of class
	DCicon.  The class DCIcon is in a file called DCICON.SC, and
	should be consulted for any further guidance.  The following
	code snippet will do something.

	(instance myIcon of DCIcon
		(properties
			view: 120
                                                                                                                                               


6/2/89	Jeff

	Compiler enhancement:  variables can now be initialized (but NOT assigned)
	to far strings.  When this is done, the variable becomes a two element
	array, with the first element being the first word which needs to be
	passed to (Print) and the second element being the second word.  Thus,
	if you write

		(local
			foo = "This is a far string."
		)

	you print it with

		(Print [foo 0] [foo 1])

	This can be used to set up arrays of far strings for indexed printing
	of messages.  You define the array as

		(local
			message =
				[
				"This is far string #0"
				"This is far string #1"
				"This is far string #2"
				"This is far string #3"
				...
				]
		)

	and print the nth message with the procedure

		(procedure (PrintMsg n)
			(Print [message (* 2 n)] [message (+ (* 2 n) 1)])
		)

	This allows you to do a switched print of far strings:

		(PrintMsg
			(cond
				((Said 'eat/rock')
					0
				)
				((Said 'swim/tree')
					1
				)
				...
			)
		)

	which is much less space-consuming than a print for each.  Note, however,
	that it is also much less intelligible -- only do it when you're REALLY
	tight on space.

	This feature ONLY applies to variable initialization.  Assigning a far
	string to a variable or assigning or initializing properties will cause
	the string to be compiled as a near string.


6/1/89	Bob

	GReAnimate has been added to KGraph functions.  
	It's used as follows:

		(Graph GReAnimate top left bottom right)

	This will have the same affect as a ShowBits, BUT will re-animate
	the cast members that are inside the shown rectangle.


6/1/89	Pablo

	MORE HEAP!!! The following classes have been taken out of motion.sc and 
	system.sc and  placed in their own files: reverse, chase, follow, wander, 
	timer and timeout. This saves 1700 bytes (!!!) in rooms that don't use  
	these classes.
	
	MODULARITY is the word of the day, if you find other system code that 
	should be in a file of its own please bring it up, everyone may benefit.
	
	------------------
	
	The DEMO DEMON is here! To run a game in demo mode, set global variable 
	demoScripts to some convenient offset, ie. 400. Then for each room to be 
	demo'ed create a script of actions, make it public entry 0 in its file 
	and make the script number equal to the room number plus the value of 
	demoScripts. The following procedures are provided to fake out user 
	interactions: FakeInput, FakeDir, FakeKey and FakeMouseDown. The demo 
	demon locks out the real keyboard and mouse to protect your demo from 
	klutzy showgoers. Overhead is about 380 bytes plus the size of the demo 
	code, which can range from 100 to 500 bytes typically. Did I mention that 
	the point of this is to be able to demo your actual UNMODIFIED game?
	
	For internal details see file DEMO.SC, for examples see 
	\games\ice\source\demo*.sc (especially demo011.sc).
	
	
	------------------
	
	If you need to refer to specific objects in you demo you can use 
	procedure NameFind. Example (NameFind {agent} cast) will return the ID of 
	an object with name property "agent" if it is a member of list cast, 0 
	otherwise. NameFind can also be used as a poor substitute for public 
	objects.
	
	------------------
	
	New and useful procedure added to system.sc: OneOf
	Example:
	(OneOf 23 10 20 23 30) returns TRUE because 23 (the first arg) IS one 
	of 10, 20, 23 or 30
	Also legal is (OneOf client badGuy worseGuy)
	
	------------------
	
	CATS: A Cat is an object that follows the mouse, ie. a mouse-draggable 
	gadget. It can be confined to a rectangle or even to one of a 
	rectangle's diagonals, in which case it can be made to track either the 
	mouse x or y coordinate. Animation can be optionally enabled during 
	dragging, although the default of disabling it provides smoother 
	interaction. A cat can be made to affect other objects or variables by 
	customizing its posn method. For examples see \games\ice\source\rm027.sc.

	------------------
	
	The setLoop method of Actor now also accepts an object as an argument, in 
	which case it will set the actor's looper property and invoke its init 
	just like setMotion does for movers.

	------------------
	
	GROOPERs a.k.a. GradualLoopers are here.
	example: (ego setLoop GradualLooper) will cause ego to go through all 
	intermediate loops when making turns, ie. no more 180 degree "flips". it 
	also works for eight loop views, which can be used for even smoother 
	animation. From system.sh:
			
			;Standard loop order for actors
			(enum
				loopE
				loopW
				loopS
				loopN
	
				loopSE	;new, for 8-loop actors
				loopSW
				loopNE
				loopNW
			)
	

	------------------
	
	SMOOPERs a.k.a. SmoothLoopers are also here
	use same as groopers. Smoopers allow an actor to 'cut away' to a 
	transition view  when performing turns, this is especially nice for long 
	actors. See comments in smooper.sc for details, teleport to Iceman 
	room 56 for live example.

	------------------
	that's all folks!	--Pablo
	------------------
	
		
5/10/89	Corey:

	You can now do room transitions and picture drawing with no special
	effects.  This is the new default option for picture drawing style.
	Simply set your room "style" property to PLAIN (defined in system.sh).
	This is the fastest way to draw a new picture.

5/4/89	Pablo:	VCPP

	The VCPP vocabulary preprocessor has been enhanced so that the following 
	lines are equivalent:
	
	(#synonyms foo bar)
	(#syns foo bar)
	(#syn foo bar)
	(foo bar)
	
	The final form is obviously the most concise and is recommended for 
	foreign language vocabulary extensions.
	
	VCPP's internal stack size has been increased in hopes of eliminating 
	occasional reported crashes.

4/19/89	Pablo
	
	To take advantage of heading, a new script SIGHT has been created to 
	provide procedure (CantBeSeen theSight theSeer theAngle theDepth), which 
	tells use whether theSight is within theAngle from theSeer's heading and 
	within theDepth distance. theSeer defaults to ego, theAngle defaults to 
	the right thing based on egoBlindSpot and theDepth defaults to INFINITY, 
	which is defined in system.sh as a very large number.

	SortedFeatures: said events now go to all members of cast and features, 
	the burden is on the programmer to use procedures IsOffScreen and 
	CantBeSeen to discriminate an objects responses. Doing so provides a lot 
	more flexibility in said event handling.
	
	INTRFACE has a new procedure called MousedOn which tells whether an event 
	took place within an object's rectangle.
	
	New file MOUSER provides a class of EventHandler that on a simple click 
	can move ego towards the click and then pass a copy of the mouse event to 
	the clicked object if any.
	
	New file RFEATURES provides classes RFeature and RPicView that add 
	properties nsLeft, etc to Feature and PicView respectively. A must if 
	using MousedOn.
	
	New file TEXTRA provides a class TalkingExtra of Extra that defers to a 
	surrogate feature or rfeature if addToPic'd, so that the Extra's 
	responses are guaranteed to be around even on a slow machine.
	
	Class Ego has been moved to USER. User has been simplified so that events 
	are handed to the menu bar, then game, then ego; except for saidEvents 
	which go to menu, sortedFeatures, then game. keyDown events no longer go 
	automatically to the cast, which should speed things up. If anyone 
	needs keyDowns to be sent to the cast (?) then they should add a line to 
	their game's handleEvent to do so.
	
	ACTOR setLoop method now accepts a looper as it's argument, in which case 
	it will behave like setMotion, setCycle, etc. If given a number (ie. all 
	past code) it behaves like it always has.



4/4/89	Bob

	Lots of stuff:

	Windows are an object that can be modified/customized to
	let YOU the programmer create that certain look that will
	sell an addition 100,000 copies of your program.
	
	There is so much to tell and so little time to tell it, but
	the one thing that every one must do is add the following line
	as the first statement in your game's init method.

		(= systemWindow SysWindow)

	this provides the bare minimum "template" for Print to produce
	windows that are very similar to what you have had for the last
	year or so.

	I will be working with Mark Hood to produce some the proper 
	documentation that this needs.  If you wish, you may read ahead
	by looking in save.sc for SysWindow and see what properties you
	may change.  For the painfully advanced you may read the full
	blown defintion of Window in the file window.sc.

	As always, "Write, when you get it to work!"



3/13/89	Jeff, Bob, and Stuart

	Two new kernel functions allow you to determine something about
	the hardware on which you're operating.:

		(DoSound NumVoices)

	returns the number of voices in the sound hardware.  This lets you
	know when you're on a single voice PC speaker, for example, so you
	can only play a song once.

		(Graph GDetect)

	returns the number of colors supported by the video hardware, so you
	can load a different picture for those mono- and four-color screens.


3/8/89	Bob
	
	The Z property of Actors is now used in Animate to resolve
	priority/drawing order of objects AND will affect the visual
	placement of objects on screen. The Z property is a measure of
	how far UP (above the ground) an Actor is. 
	For any objects that share the same Y the object with the 
	greatest Z will be drawn last. By the same token for any objects 
	that share the same Y the one with the greatest Z will 
	appear HIGHER on the screen. 

	By way of example, consider a car and its door.
	The car is at Y = 100, and to APPEAR properly aligned, the door
	is at y = 90. This will cause a problem in that Animate will
	draw the door and THEN draw the car, erasing the door. Many
	solutions exist for this problem, but the PROPER one is to
	set the door to y = 100 (same as the car), z = 10. Now the door
	will be drawn at the same priority as the car BUT it will be
	draw after, so it shows.


3/8/89	Bob

	All components of a shipping volume based game that USED to reside
	in \GAMES\SCI\SYSTEM\INSTALL have been moved up one level to
	\GAMES\SCI\SYSTEM. The affected files are:
		INSTALL.exe
		space.com
		exists.com
		godir.com
		drvcopy.com

	An additional file has been added to your shipping disk needs.
	This file is called INSTALL.HLP, and contains information on
	drivers in a form useable by INSTALL.EXE.

	Please ensure that all of your "make disk" batch files are
	updated properly.

			
3/2/89	Pablo

	The heading property of Actor has been moved down to Feature, so that now 
	it is also shared by classes PicView, View, Prop and Extra. This reflects 
	the fact that things like chairs have a front and a back side, which does 
	matter when we decide whether to let ego sit down.
	
	To take advantage of heading, a new script SIGHT has been created to 
	provide procedure (IsVisible theSight theSeer theAngle theDepth), which 
	tells use whether theSight is within theAngle from theSeer's heading and 
	within theDepth distance. theSeer defaults to ego, theAngle defaults to 
	the right thing based on egoBlindSpot and theDepth defaults to INFINITY, 
	which is defined in system.sh as a very large number.


2/28/89	Jeff

	There are two new motion classes: Path and RelPath.  These allow you
	to move an Actor along a pre-defined path specified as an array of
	points.  Using these classes to follow a path requires less memory
	than creating a script to do it, and is considerable easier to boot.

	You set the motion for an Actor to be a Path or RelPath in the same
	way as for other motion classes, but the parameter to setMotion: must
	be an instance of one of the classes, rather than the class itself
	[for reasons discussed later]:

		(ego setMotion: squarePath self intermediate)

	sets ego's motion to the path 'squarePath' and requests that the caller
	be cue:ed when the path is completed.  The optional 'intermediate'
	parameter specifies an object to be cue:ed at each intermediate endpoint
	along the path.  The intermediate object's cue: method is passed a
	parameter specifying which endpoint caused the cue (first endpoint = 0,
	second = 1, etc.).

	For both classes of path, two things are required: the array of points,
	terminated by PATHEND, and an instance of the class with a redefined
	at: method.  The redefined at: method is called with one parameter, n,
	and returns the nth element of the path array.

	The difference between the classes is the interpretation
	of the points in the array: Path reads them as absolute coordinates to
	which it should move, RelPath reads them as offsets of the next point
	relative to the end point of the previous path segment.
	
	To create a square Path (assuming that ego is positioned at 100,100) we
	do the following:

		(local
			sPath =	[
						100	60
						160	60
						160	100
						100	100
						PATHEND
						]
		)

		(instance squarePath of Path
			(method (at n)
				(return [sPath n])
			)
		)

	The following will make ego walk the path once:

		(ego posn:100 100, setMotion: squarePath)


	The following uses a RelPath to make ego do loop-the-loops across the
	screen:

		(local
			lPath =	[
			 			-10	-10
			 			0		-10
			 			10		-10
			 			10		0
			 			10		10
			 			0		10
			 			-10	10
			 			PATHEND
			 			]
		)

		(instance loopPath of Path
			(method (at n)
				(return [lPath n])
			)
		)


		(instance rm1 of Room
			(properties
				picture 1
			)

			(method (init)
				(ego
					posn: 60 100,
					init:,
					setMotion: aPath self
					)
				(super init:)
			)

			(method (cue)
				(ego setMotion: aPath self)
			)
		)



2/23/89	Bob

	Fixed an obscure bug in menu selection. Bug caused a phantom
	selection of the first item in the menus that did NOT have a
	key equivalent, whenever certain keys (ctrl page-up for one)
	were pressed.


2/18/89	Bob

	The internal modularity of graphics routines has been shuffled
	in order to implement VGA graphics smoothly.  This change is
	of most importance to interpreter programmers, but game programmers
	should be aware that subtle bugs may have been introduced in the
	process.


2/15/89	Bob

	Sounds need not be paused while a menu selection is in process.
	A new OPTIONAL second argument to the handleEvent of MenuBar
	will (if present and FALSE) allow sounds to play during the
	actual selection.  If this argument is not present, then things
	will behave as they have up until now.

	NOTE - This will not affect the various (sound pause:) lines
	that you probably have sprinkled around in your menu code.
	I suggest passing the value of (User blocks?) as the second
	argument to handleEvent AND as the value to all pause: methods.


2/14/89	Pablo

	New class EventHandler of Set, adds a handleEvent method that passes teh 
	event on to its members and returns as soon as the event is claimed. 
	regions, locales, cast and features are now instances of this class. Also,
	system-level  default handleEvent methods now return TRUE if the event is
	claimed so, for example, the following code can now be written for an
	event handler:
	
	(method (handleEvent event)
		(if (not (super handleEvent: event))
			(switch  (event type) 
				(saidEvent
					(cond
						((Said 'look')			(Print "you see"))
						......
					)
				)
			)
		)
	)


2/14/89	Pablo for Bob

	New "mapKeyToDir" property of User controls whether key events get mapped 
	to directions.


2/14/89	Pablo, Bob & Jeff 

	obscure change: on addToPic Views only get init'ed if they are NOT in 
	the cast.


2/13/89	Pablo

	Scripts now have properties script and caller, plus a setScript method.
	This allows one to give sub-scripts to a script, so that scripts can be 
	used in a fashion similar to procedures calling procedures. setScript for 
	all classes that support it now accepts an extra argument to fill the 
	caller property of the script. A script's caller is cue'd when a script 
	is disposed, imitating the behavior of completed motions and cycles. 
	Scripts should self-dispose in their final state to take advantage of 
	this capability.
	
	Also, a third argument is accepted to fill a script's register at init 
	time.
	
	A script's handleEvent passes events to its sub-script.
	
	example:
	
			(instance foo of Script
				(method (changeState newState)
					(switch (= state newState)
						(0	(Print "foo: punting to foo1...")
							(self setScript foo1 self self)	;<-- NOTE EXTRA ARGS!
						)
						(1	(Print "foo: back from foo1...")
							(self dispose)
						)
					)
				)
			)
			
			(instance foo1 of Script
				(method (changeState newState)
					(switch (= state newState)
						(0	(Printf "foo1: hi\nclient %s\ncaller %s\nreg %s" 
								(client name) (caller  name) (register name) 
							)
							(= seconds 10)
						)
						(1	(Print "foo1: bye...")
							(self dispose)					;<-- SELF-DISPOSING SCRIPT
						)
					)
				)
			)
	

2/9/89	Bob

	Sometime in the recent past, the OnControl kernel procedure was
	changed to REQUIRE a first argument of which bitmap you were
	interested in examining.  The first argument should be either
	CMAP or PMAP or VMAP.  
		The statement (= bits (OnControl x y))

	must be changed to 
		The statement (= bits (OnControl CMAP x y))
	to achieve the same results.

		The statement (= bits (OnControl PMAP x y))
	will return the bits of the priority bitmap (similarly for VMAP)


1/27/89 Bob

	The kernel procedure, AddToPic, has been redefined.  It now takes a
	list of PicViews (or sub-classes of PicView) as its sole argument.
	This change will NOT affect programs that do not explicitly re-draw
	the addToPics.  If you do need to re-draw the addToPics, use the
	following line: 
		(addToPics doit:)

	If anyone out there is using the old AddToPic kernel routine, please
	see me on possible alternate implementations.


1/26/89 Pablo

	New method for collections (and lists and sets) called "release":
	it deletes all elements from a collection in order to deallocate the list 
	nodes. Unlike dispose, it does NOT dispose the elements.
	
	Used "release" to fix fragmentation caused by use of sorted features in 
	User.


1/17/89 Bob

	Hide/Show of stop updated actors should now work much better.
	Please inform me of any problems you may still encounter.


1/5/89 Jeff

	The time at which you receive a cue: upon completion of a motion or cycle
	class has been changed.  It used to be that you would be cue:d at the
	beginning of the animation cycle following the motion completion.  Now
	you are cue:d during the animation cycle in which the motion completes,
	but after the animation is shown on the screen.

	The main game loop looks something like

		(1)	execute doit:s of cast
		(2)	update screen
		(3)	execute Game's doit:
		(4)	execute doit:s of regions
		(5)	execute User's doit:
		(6)	go to 1

	Before, if a motion were completed in (1), you would not receive the
	cue: until (1) of the NEXT animation cycle, after all the other doit:s
	were executed.  Now, the cue: comes between steps (2) and (3) of this
	loop on the SAME cycle in which the motion was completed.  This lets
	you know when the motion completes on the screen in time to set up
	to do something on the next animation cycle.


1/3/89 Pablo

	YET ANOTHER WORD VOCAB FORMAT!
	By popular demand I have changed the format accepted by the vocab 
	preprocessor to use a free-form prefix syntax like SCI itself. 
	The vocab.vc file should now consist of arbitrarily nested 
	parenthesized expressions.  Each expression should start with one 
	or more preprocessor directives.  A directive can be one of the 
	following:
	
	#synonyms:					all words within list have same word number.
	#number:						arbitrary jump in numbering.
	#<any part of speech>:	all words within list will carry this P.O.S.
	
	In addition, the special word ++ will increment the word number 
	without outputting a record. This should be used to avoid 
	rebuilding the entire game when a word gets deleted from the 
	middle of the word list.
	
	Example vocab.vc:
	
	(#noun #number 100
		car
		(#synonyms stone (#verb rock))	;rock is both a noun and a verb
		++
		clock
	)
	
	(#number 3000)
	(#verb
		look
		feel
	)
	
	For more complete examples, see \games\sci\system\vocabase.vc and 
	\games\ice\source\vocab.vc
	
	To compile your vocab.vc incorporating the basic system word list,
	type "vcomp vocab.vc".


12/21/88 Pablo

	Avoider offScreenOK
		new property, defaults to FALSE, if set to TRUE then 
		the avoider will allow its client to move off screen.
		
	Feature z
		new property, represents elevation of an object. This is important 
		because (+ y z) gives the y of a feature's PROJECTION on the ground.
		
		The reason we care about this is that if ego is facing south and is 
		in front of a counter, any object on the counter has a y smaller than 
		ego's, so it is computationally BEHIND him. If we take z into account, 
		then (+ y z) can be greater than ego's y, so the object can be 
		correctly considered to be IN FRONT of ego.
		
		Actor's distanceTo has been modified to take z into account.
		Default z is 0.
	

12/21/88 Pablo

	NEW WORD VOCAB FORMAT
	There is a new preprocessor for vocabulary files that allows one to 
	create a file (vocab.vc) in a friendlier format, without word numbers and 
	specifying parts of speech for entire groups of words. There is also a 
	basic vocabulary in \games\sci\system that contains words with parts of 
	speech other than adj, verb or noun, which are game-specific.
	
	New format:
	
	-	No parenthesis are used.
	
	-	Words with the same word number go on contiguous lines, blank lines
		cause the word number to increment.
		
	-	The default part of speech for all following words can be set with a 
		line like
					#SPEECH noun
		This is a vcpp (vocab preprocessor) directive, flagged by an inital #.
		If a given word following this directive is also a verb then just 
		follow the word with the additional part of speech.
		
	-	The current word number can be set with the NUMBER directive, for 
		example
					#NUMBER 1000
					
	-	Recommended procedure for all games in development:
	
		Use the new base vocab, define ONLY adjectives, verbs and nouns.
		Use s:bones.vc as a template for your new vocab, starting adjectives 
		at 500, verbs at 1000 and nouns at 2000.
		1-499 and 4000-4095 are word numbers reserved for system use.
		
	INSTRUCTIONS
	
		Create a file named vocab.vc in the new format and copy 
		\games\sci\system\vcompcfg.bat to your vocab directory. Use s:bones.vc 
		as a template and look at s:vocabase.vc for a complete example of new 
		format syntax.
		
		To help you convert your old vocab.txt files to the new format, I have 
		posted two utilities that can be invoked through the following batch 
		files:
		
			vocabare:	strips parenthesis and word numbers from each line
			vocwords:	leaves only the words on each line.
			
		If you organize A COPY of your current vocab.txt by parts of speech 
		and insert enough meaningful comments, you can then use one of these 
		utilities to do most of the conversion grunt work. The resulting file 
		should be mush easier to maintain.
		
		Type:
				vcomp vocab.vc
				
		this will invoke the preprocessor to create a partial vocab.txt, 
		concatenate it to vocabase and hand the result to good old vc.exe to 
		produce vocab.000
		
		If you have any questions I'll be glad to answer them and help out 
		with your vocab conversion.


12/12/88 Pablo

	There is a new global variable called "egoBlindSpot" which should contain 
	the size of ego's blind spot in degrees, ie. how many degrees from 
	"straight  behind" are not visible to ego. Default is zero (360 degree 
	vision), recommended value is 90 (ego only sees ahead). If 
	useSortedFeatures is TRUE then objects in ego's blind spot do not have 
	their handleEvent method invoked on Said events.


12/1/88
	(Jeff) Disk errors (no disk in drive, non-formatted disk in drive, etc.)
	are now handled better.  The user has the option to retry or quit in all
	cases but save/restore, where he has the option to retry or cancel the
	save/restore.  Let me know if you encounter any odd behavior.


11/23/88

-	(Jeff) Added the overlay: method to class Room to overlay the current
	picture with another.  Usage is

		(curRoom overlay: picNumber [showStyle])

	This restores correctly, whereas overlaying with a direct kernel call
	will not.  This supports only one overlay.  Let us know if you need more
	than one.


11/22/88

-	(Pablo) Perspective handling has changed to a hopefully cleaner paradigm.
	Instead of specifying Tilt* properties for rooms, one may now provide 
	values for vanishingX and vanishingY, the coordinates of the picture's 
	vanishing point. The default vanishing point is at 160,30000 to provide 
	the old behavior as a default. By specifying a vanishingY of say -200 one 
	can get more intuitive response to the vertical cursor keys, thus 
	avoiding ego's bumping against walls.


11/21/88

-	(Jeff) Initialized global and local variables are now a reality.  Some
	examples of syntax:

		(local
			foo1							;just as before
			[foo2 3]						;just as before
			foo3	= 1
			foo4	= [1 2 3 4 5]
			[foo5 5] = [1 2 3]
			[foo6 3] = -1
			foo7 = [{a string} {another string}]
			foo8 = 'look/rock'
		)

	which will generate the following initial values:

		foo1		0
		foo2		0
					0
					0
		foo3		1
		foo4		1
					2
					3
					4
					5
		foo5		1
					2
					3
					0
					0
		foo6		-1
					-1
					-1
		foo7		pointer to {a string}
					pointer to {another string}
		foo8		pointer to 'look/rock'

	Syntax for globals is similar, though as usual you can't declare a global
	as an array with square brackets.

	The script.xxx files generated by the new compiler will be larger than
	before because they now contain the local variables (which used to be
	allocated at run time).  However, since most variables will be the default
	of 0, compression will pretty much reduce them to the same size as before
	for your volumes.

	A WORD OF CAUTION: Whenever compiling multiple modules which include your
	room 0, you must compile your room 0 first.  All knowledge of the global
	variables other than their number is discarded after the first module, so
	
		sc rm001 rm000

	would not generate the global variables in room 0 as it should.

		sc rm000 rm001

	would, however, work.


11/19/88

-	(Pablo) New AVOIDER:
	A completely new avoider is in, rewritten from the ground up. It now 
	lives in its own file avoider.sc, separate from motion.sc
	
-	Class Motion has two new methods:
	
		setTarget:	updates the x and y properties, doing nothing else
		onTarget:	returns TRUE or FALSE
		
-	Class Room has five new properties:
	
		picAngle		0	;how far from vertical is our view? 0-89
		xTiltTop		0	;clockwise tilt from x-axis at y-0 (degrees)
		xTiltBottom	0	;same at y=SCRNHIGH
		yTiltLeft	0	;clockwise tilt from y-axis at x=0
		yTiltRight	0	;same at x=SCRNWIDE
		
	picAngle is useful to make distanceTo: behave more realistically, and 
	Orbit motions will follow an ellipse instead of a circle for non-zero 
	values
	
	The Tilt* properties completely describe the point of view used to draw a 
	room. Actor's setDirection: has been rewritten to take these values into 
	account so that hitting a cursor key will cause ego to follow the room's 
	apparent directions instead of strict screen coordinates.
	
	To figure out what values to use for these properties, use your 
	eyeball-meter and then trial-and-error to fine-tune. As far as I can 
	tell, typical values are roughly:
		
		picAngle		60
		xTiltTop		0
		xTiltBottom	0
		yTiltLeft	20
		yTiltRight	-20
		
	Finding good values for these properties will make it a lot easier for 
	people to play the game without a mouse.
		

11/16/88

-	(Jeff) A relatively major change in the way selectors are handled by the
	compiler and interpreter has been made and will require a change in
	syntax of your source code.  Fortunately, there is a conversion program
	which will do the syntax change for you, though you will need to learn
	a few new habits for writing new code.

	The nature of the change is that there is no longer a distinction between
	the various forms of a selector, i.e. "state:", "state?", and "state"
	are identical in all respects except visually.  The interpreter now deals
	with the message

		(anObject aSelector [args ...])

	in the following way:

		(cond
			(- aSelector is a method of anObject
					The method aSelector is invoked with args.
			)
			(- there are no arguments
					The value of the property aSelector is returned.
			)
			(- else
					The value of the property aSelector is set to the
					value of the first argument.
			)
		)

	This leads to several niceties:

		-	The selector symbol table in sc will now be only a third as large
			as it is currently, so you'll have a bit more space for your compiles.

		-	You can now convert between properties and active values with no
			source code changes outside the class involved.  An 'active value'
			is a value which has some sort of side effect when accessed.  See
			the document "/games/sci/system/doc/active.doc" for a further
			explanation.

		-	System code has been reduced in size by 300 bytes since (for esoteric
			reasons) we now have 128 more byte-length selectors.  Don't be usin'
			that space, though -- a new Avoider is on the way once Pablo gets
			well which will eat it all back up.

	What this requires in terms of syntax is the following:

		-	Multiple messages to the same object in an expression must now
			be delimited by commas, so that the compiler can tell where each
			message ends.  Thus,

				(ego
					view: 5
					posn: 100 200
					setMotion: MoveTo y x self
					init:
				)

			becomes

				(ego
					view: 5,
					posn: 100 200,
					setMotion: MoveTo y x self,
					init:
				)

		-	All 'pseudo-selectors' such as 'at:', 'title:', etc. in Print,
			SetMenu, and other function calls must be preceeded with a '#' to
			let the compiler know that you're just passing a number rather
			than trying to access a property.  Thus,

				(Print "This is a pain." at: 100 100)

			becomes

				(Print "This is a pain." #at: 100 100)

	The good news is that there is a conversion program, cvtsci.exe, which
	will do all this syntax conversion for you.  Usage is

		cvtsci file_spec [file_spec ...]

	You probably just want to 'cvtsci *.sc'.  This program can also be run
	over already converted source, so if you forget to use the new syntax
	while modifying an already converted file, just cvtsci it again.

	Note to the sceptical: the entire source of Leisure Suit Larry II has
	been converted, compiled with the new compiler, and played to completion
	on the new interpreter.  You really shouldn't encounter problems.  If
	you do, I'm sure you'll let me know.


11/14/88

-	If the set:, setReal:, and setCycles: messages are sent to an instance
	of class Timer, that instance will be used.  If they are sent to the
	Time class itself, the class will create a new: instance and set that
	instance, returning its ID:

		(instance myTimer of Timer)
		(local
			anotherTimer
		)

		(myTimer set: 10)							;uses myTimer as is
		(= anotherTimer (Timer set:10))		;creates a new: Timer

-	The stop: and dispose: methods of Sound now take an optional argument
	which tells the sound whether or not to cue: its client.  A value of
	FALSE means not to cue:.  No argument retains the current behavior,
	which is to cue: the client.

-	A fade: method has been added to class Sound.  For those with sound
	systems which have volume controls, this will fade the sound into
	oblivion, then cue: the Sound's client.  For the rest of us, it is
	equivalent to stop:.


11/11/88

-	Class User has acquired 3 new properties. They are:
		blocks: If TRUE, sounds will be stopped when User is getting input.
		x: 	Same behavior as X component of Print 'at:' command
			If set to -1 the user input window is centered horizontally
			Any other value specifies the X coord of the left edge.
		y: 	Same behavior as Y component of Print 'at:' command
			If set to -1 the user input window is centered vertically
			Any other value specifies the Y coord of the top edge.

		If your game wants to keep playing sounds while getting input
		from a window centered horizontaly at the bottom of the screen,
		send this message to User in your init:

			(User blocks:FALSE x: -1 y: 160)

		(Bob H)
					
11/03/88

-	I haven't documented the new structure of MAKEVOLS yet, so in the
	meantime, look at \games\pq2\sci\play\resource.txt and puzzle it out.
	By the by, Friday, Nov 4 is my 37th birthday so don't hassle me.


10/25/88

-	Notes on the use of &rest:
	There is a bug in &rest which is not likely to be fixed right away, but
	there is a fairly simple workaround.  The problem arises when &rest is
	used in an message send with a computed reciever, as in:

		((expression) arguments &rest)

	The above expression will be evaluated as

		((expression &rest) arguments)

	which is clearly not what is intended.  The work around is to do the
	message send in two steps using a variable to contain the computed
	reciever:

		(= reciever (expression))
		(reciever arguments &rest)


10/24/88

-	Changes have been made to both the kernel and the compiler to speed
	up critical sections of kernel code.  They should be transparent to
	game programmers except that you will now need vocab.994 (on s:) in
	order to run your game.

	NOTE TO SYSTEM PROGRAMMERS: when remaking the system from now on,
	use the -O option of sc to cause it to write vocab.994.  This contains
	the offsets to certain properties of certain classes, allowing the
	kernel to look them up much more quickly.  The classes and properties
	which are affected are in "offsets.txt", which must be kept in synch
	with the enum in "i:selector.h".


10/20/88

-	To change pictures within a room, you should use the drawPic: method
	of Room (curRoom drawPic: 100).  This method NOW disposes of any
	addToPics that have been accumulated.  This cures a symptom of
	restoring a room with the alternate picture up and seeing disembodied
	views on the screen.


10/19/88

-	The SC compiler now has a -a option which aborts the compile immediately
	if the class database is locked.

-	The debugger now has full command-line editting, using the same routines
	as those used by edit items in dialogs.  You can even use your mouse.
	Also, stepping across sends & calls (using Tab) works again.


10/17/88

-	&rest should now work with kernel functions.  Let me (Jeff) know if you
	have any more problems.

-	(Printf) now works.  Syntax is just like C's function:

		(Printf formatString [parameter parameter ...])

	Note that if you want to do anything fancy (like titles, fonts, centering,
	etc.), you'll still need to use (Print (Format @str ...)).  However, for
	simple print windows (particularly for debugging), Printf works just fine.


10/04/88

-	A class browser (a la Smalltalk) is now available as the BRIEF macro
	"browse.m" in s:.  Compile with "cm browse".  I believe that it will only
	compile for BRIEF v2.xx.  For those running v1.xx, try changing such
	things as "(+= foo bar)" to "(= foo (+ foo bar))", etc.  Or upgrade to
	v2.xx!

	To run the browser, assign a key to run the macro "BrowseClasses" or
	use the "execute macro" function to run the macro.  The browser needs
	an environment variable, "browse", which is the path along which to
	search for the source code for the classes.  You'll probably just want
	to "set browse=s:".  The browser also uses a small file, ro.com (in y:
	on the net), to determine whether or not a file is read-only.  This
	program, invoked as "ro file", returns a DOS exit code of 1 if the file
	is read-only, 0 otherwise.

	When you invoke the browser, there will be a small delay, then a menu
	of the system and user-defined classes will appear on the left of your
	screen.  This menu (generated by the new sc compiler in the file "classes")
	also shows the hierarchical relationships of the classes.  Select a class
	by using the arrow keys, Home, and End or typing in the name of the class
	you want to inspect (an incremental search is done based on what you've
	typed).  When the highlighted bar is on the class you want, press Enter.
	If you want to bail out, press Esc or Alt-minus (this applies to all
	windows in the browser).

	A new menu will be displayed which contains the selections "DOCUMENTATION",
	"PROPERTIES", and the names of any methods which the class defines or
	redefines.  Select an item as above and again press Enter.  What happens
	next depends on what you selected:

		PROPERTIES
			A new window pops up showing the properties which the class either
			defines or whose value it redefines.  This is a display-only window
			-- you can't edit in it.

		DOCUMENTATION
			Pops up a window displaying the class heading of the class, which
			is where we will be documenting the class.  This is a quick way of
			finding out what the class is about.  Any suggestions on improving
			the documentation might be welcome.  This is a full editing window,
			allowing you to scroll through and edit the source file containing
			the class.

		method name
			Pops up a window displaying the selected method.  Again, this is
			where documentation on the method will be kept and the window
			is a full editing window.

	If the source file which is found for the class is read-only (those on
	s: are), the browser will beep and display the message "File is readonly."
	to let you not to make any changes which you expect to save.

	If you make any changes in the file and then press Esc, you will be asked
	if you want to save the changes: your options are (a)bort [forget the
	changes], (w)rite [save the changes], and (c)ontinue [dont' leave the file
	yet].

	One caution: BRIEF claims to only support three pop-up windows at a time.
	When you're browsing a class you'll have that limit on the screen, so
	popping up another window (todo list, game.sh, buffer list, etc.) might
	blow you away.  Not knowing the internals of BRIEF (would that I did!),
	I can't say what will occur.


10/03/88 "Feature" class (Pablo)

-	A new class call Feature is now available. A feature is an object with 
	properties x and y and a HandleEvent method. Its purpose is to respond to 
	Said events (user input). Features must be static instances, and get 
	added to the global features list by using a new room method called 
	SetFeatures. A room's dispose method now disposes of all features, since 
	they are conceptually room-local.
	
	The x and y properties are only used if a procedure called sortedCpy in 
	user.sc is uncommented (in a private copy of course). What this does is 
	cause actors, props and features to get a shot at the said event in order 
	of decreasing proximity to ego, which is more realistic. However, 
	enabling this capability takes up a few hundred bytes of space so I have 
	left it out of the system-wide version of user.sc. See me if you want to 
	enable it.
	
	Example:
	
	Create a simple feature with:
	
	(instance Table of Feature
		(properties
			x	100
			y	120
		)
		(method (handleEvent event)
			
			(cond
				((or	(event claimed?)	(!= (event type?) saidEvent)) 
					(return)
				)
				((Said 'look/table')
					(Print "there is an empty cup on the table")
				)
			)
		) 
	)
	
	and activate it in a room's init method with:
	
	(self setFeatures: Table Chair Pot)	;this room has three features
	
	

10/03/88 TRIGONOMETRIC FUNCIONS (Pablo)

-	GetDistance now takes an optional 5th argument, perspective, which 
	is the users point of view of the room in degrees away from the vertical 
	along the y axis. The typical value for Sierra games seems to be about 60 
	degrees. This argument defaults to zero if absent. What this change does 
	is to make each y-pixel represent a greater distance than an x-pixel, a 
	behavior closer to reality.
	
	I suggest modifying the distanceTo: method to use a global variable
	called perspective that could be reset in each room init.
	
-	Four kernel calls have been added to perform integer trigonometry.
	All four take as args an angle in degrees and a number.
	
	(SinMult anAngle aNumber) returns aNumber*sine(anAngle)
	(CosMult anAngle aNumber) returns aNumber*cosine(anAngle)
	(SinDiv anAngle aNumber) returns aNumber/sine(anAngle)
	(CosDiv anAngle aNumber) returns aNumber/cosine(anAngle)
	
	CosDiv, for example, is used in the new GetDistance.
	
	All other trig operations can be built from these four calls.
	

10/03/88

-	Class Game has notify: and setScript: methods and a 'script' property
	just like Region and Room.  Thus, your room 0 can now have a script and
	communicate with Regions and Rooms.

-	The class Locale has been added (in game.sc).  A Locale is similar to
	a Region, but only has a handleEvent: method.  It is the object of choice
	for handling default responses to user input which used to go in Regions
	(e.g. 'look/meadow', 'look/tree', etc.).

-	The source code in s: is now much more heavily commented.  We'll try to
	keep the comments up to date and useful enough to replace the documentation,
	which just never seems to be current.



09/27/88

-	Resource usage tracking is now available with the '-u' option on sci.
	When resource tracking is enabled, the interpreter will write a line
	to the file "resource.use" each time a resource is loaded from disk.
	The line is of the form

		rmxxx  resType.yyy

	which indicates that resource type resType, number yyy, was loaded in
	room xxx.  Since the resource cache is flushed on each newRoom: when
	resource tracking is on, this will indicate which resources each room
	uses.

	A more useful report than "resource.use" can be generated by

		sort <resource.use | uniq >uses

	which prepares a sorted list with duplicate lines removed.

	Note that "resource.use" is APPENDED to each time you run sci with
	resource tracking on -- it is not overwritten.  You will want to delete
	it periodically to keep it from growing too large or to keep the
	usage patterns current.



09/26/88

-	The order in which various elements of your game get control has been
	changed.  It used to be that control went first to the cast, then the
	user, then the regions.  One sort of problem which was created by this
	was the following from KQ4:

		-	The cast gets control and advances ego to the edge of a cliff
			where ego is positioned on the control line at the edge.
		-	The user gets control next and types 'wear crown'.  This is
			duly parsed and passed to the handleEvent: methods, which decide
			to start ego's transformation to a frog.
		-	Control now passes to the regions, which note that ego is on a
			control line and attempt to start ego falling.
		-	Much confusion on screen.

	The modification just made now passes control first to the cast, then
	to the regions, then to the user.  This should solve problems arising
	from the scenario above.  It might, however, lead to other problems of
	a timing-related nature which we haven't anticipated.  If you suspect
	that this change has done you in somehow, please talk to one of us --
	we may be able to come up with a way around your problem, or the change
	can be backed out (it only involves swapping two lines of code).


09/25/88

-	The 'o' and 'O' commands in the debugger now display all objects in
	one window in which the new: objects are preceeded with a '*'.  This
	gives you a better feel for where objects are positioned in relation
	to each other.

-	Many changes have been made to the Sound class.  The 'keep' property no
	longer exists -- to stop a sound from playing without disposing it,
	just invoke the stop: method:

		(mySound stop:)

	The dispose: method still exists, and not only stops the sound but
	disposes its soundNode (an internal kernel structure) and the sound
	itself if it is a new: object.

	The play: method of Sound now sets the 'loop' property to 1 if it is
	0 when play: is invoked.  Thus, the expression

		(mySound loop:1 play:)

	may now be written

		(mySound play:)

	if you can be sure that the loop property is either 0 or 1.

	Sounds now have an 'owner' property, which can either be left empty (= 0)
	or set to the ID of a Region or Room.  When a Region or Room is disposed,
	the system disposes all sounds with either no owner or which are owned
	by the Region or Room being disposed.
	
	Sounds are no longer automatically disposed when they finish, only on
	room/region changes.  Because of this, a sound which might be played many
	times in a room (e.g. a non-fatal fall or playing an instrument) should
	be an instance rather than a new: Sound.  Since the new: sound will only
	be disposed on a room change or if you explicitly dispose: it, (Sound new:)
	can potentially fill the free heap.

	To minimize heap fragmentation of sounds in regions, make them instances
	of Sound, initialize them in the init: of the Region, and set their
	owner to the region, e.g.

		(mySound owner:thisRegion init:)

	Do not dispose: sounds in regions -- only stop: them.  Since dispose:
	frees several sound structures in the heap, the next time the sound
	is played it will reallocate them ABOVE the current room, leading to
	fragmentation when you leave the room.

	The general rules of thumb for sounds are:

		-	Always make sounds instances of Sound -- don't use (Sound new:).
		-	Never explicitly dispose: a Sound unless you're sure you know
			what you're doing -- use stop: to turn it off.  Sounds will be
			automatically disposed on Room/Region changes using their 'owner'
			property.


09/21/88

-	Sci accepts a '-d' command line option to enable debugging.  This
	means that you will get a 'PMachine' error rather than an 'Oops!',
	and be dropped into the debugger as before.  As time marches on,
	more of the debugging facilities will be added to this switch.


09/18/88

-	The debugger is now invoked by pressing the "grey minus" (numeric pad)
	while both shift keys are down.  Also, PMachine errors are reported
	in a shippable manner UNLESS you have invoked debug via the keyboard
	prior to encountering the error.  This is subject to change, stay tuned
	for developments.

	NOTE: On the TANDY 1000, the proper minus key is the one also marked
	DELETE.  You must have numlock OFF to access it.

09/16/88

-	Prioritized sounds are now a reality.  The 'priority' property of Sound
	is a signed integer which defaults to 0.  If you tell a sound to play:
	and a lower priority sound is already playing, the new sound will interrupt
	it, play to completion, and then restart the old sound at the point of
	interruption.  If the new sound has a priority equal to or lower than the
	old sound, it will wait for completion of the old sound before it plays.

	There are three properties of interest for coordinating sounds with each
	other or with animation.

		signal
			This gets set to the value of an animation cue for one animation
			cycle, after which it is reset.
		prevSignal
			This gets the value of signal when signal gets set, but retains it
			until the next sound cue.
		state
			This is the state of the sound, and is one of the following:
				SND_NOTREADY
					The sound has not been initialized.  Default for Sounds.
				SND_READY
					The sound has been initialized, but not submitted for playing.
				SND_BLOCKED
					The sound has been submitted for playing, but either the
					sound is paused or a higher priority sound is presently
					playing.  (Note that since the debugger pauses sounds, an
					active sound will always appear as blocked in the debugger.)
				SND_ACTIVE
					The sound is currently playing.

	The changeState: method allows changing the priority or loop count of a
	sound which has been initialized (or is playing).  Just set the appropriate
	properties of the sound, then do a (mySound changeState:).

	You can use priorities to chain sounds together without the 'next sound'
	stuff (which will probably be eliminated soon).  Just submit the sounds
	with decreasing priorities:

		(firstSound loop:1 priority:2 play:)
		(secondSound loop:2 priority:1 play:)
		(thirdSound loop:1 priority:0 play:)

	Will play one loop of 'firstSound', two loops of 'secondSound', and one
	loop of 'thirdSound' in that order.

	To terminate a sound at the end of its loop rather than immediately, just
	set its 'loop' property to 1 and do a changeState:

		(mySound loop:1 changeState:)

	There are times when you will want to play a sound only if no higher
	priority sound is playing (like the 'got item' music in KQ4).  Submitting
	it at a lower priority will keep it from playing when a higher priority
	sound is present, but will play the sound when that higher priority
	sound is finished.  What we want is to either play the sound immediately
	or not at all.  To do this, use the 'playMaybe:' method:

		(mySound playMaybe:)



09/14/88
-	The EndGame class and the end method of Game are kaput.
	Following is an example of how to end your game.  This example
	uses a "dead" global var to detect the need for ending.

	; this may or may not already be in your rm000
	(method (doit)
		(if dead
			(repeat
				(switch
					(Print
						"\"Thank	you for playing\n
						King's Quest IV,\n
						`The Perils of Rosella.'\n\n
						Next time... be more careful!\""
						icon: 100 0 0
						mode: teJustCenter
						title: {Roberta says:}
						button: {Restore} 1
						button: {Restart} 2
						button: {____Quit____} 3
		 			)
					(1
						(theGame restore:)
					)
					(2
						(theGame restart:)
					)
					(3
						(= quit TRUE)
						(break)
					)
				)
			)
		else
		; your normal code
			...
			...
			...
			...

			; this must be here
			(super doit:)
		) ; end of NOT dead
	)	; end of DOIT:



09/07/88

NOTE: 
	The two following changes were not arbitrary, and I will be
	willing to justify them to anyone who cares.

-	The selectors to the (Display) kernel procedure have changed.
	The following selectors are valid:
		p_at:
		p_mode:
		p_color:
		p_back:
		p_style:
		p_font:
		p_width:
		p_save:
		p_restore:

	NOTE: The colon must be included.

-	The selectors to the (SetMenu/GetMenu) kernel procedures have changed.
	The following selectors are valid:
		p_said:
		p_text:
		p_key:
		p_state:
		p_value:

	NOTE: The colon must be included.
		

-	Added code to MenuBar to respect "state" property.  If "state is
	FALSE, then handleEvent returns FALSE.


09/06/88

-	Added a new property to User.  "inputLineAddr" is the address of
	the input line being used by User to get input (sort of circular logic).
	One possible use is as follows:

	(Print 
		(Format 
			"%s, %s...\nBoy! listen to that echo!"
			(User inputLineAddr?) (User inputLineAddr?)
		)
	)



09/05/88

-	In order to get the sound state to display properly in your menus after
	a restore game, you'll need to make several changes to your code (we'd
	do it for you in the system, but the system doesn't know the details of
	your menus).

	1) Break the enum for your menu items out into a "menu.sh" file.  This
		has the added advantage of letting you include the file in any module
		in which you wish to do something to your MenuBar.

	2)	Include "menu.sh" in the file which includes your instance of Game
		(rm000, kq4, or whatever).

	3)	Redefine your Game's 'replay' method as

			(method (replay)
				(SetMenu soundI
					text:
						(if (DoSound SoundOn)
							{Turn sound off}
						else
							{Turn sound on}
						)
				)
				(super replay:)
			)

	'Replay' is the method which is invoked by the system instead of 'play'
	when a game is restored.  If you need to do any setup on a restore (versus
	a restart, which invokes 'play'), put it in this method.  The
	(super replay:) must ALWAYS come at the end of 'replay', since it contains
	the main game loop.

-	Ego should be able to leave a room under diagonal motion now.  In order
	to do this, class Ego now ignores the horizon.  Let me know if this
	causes any problems.



09/02/88
-	The initialization of the menu bar hase been removed from the
	(theGame init:) method.  Each game must now init it at the proper
	time.  You can achieve the behavior that you're accustomed to by
	adding the following line to your room 0 right after the call to
	super init: in your game init:

		(TheMenuBar init:)

	If you wish to defer the drawing of the menubar, you should remove
	the line (self draw:) from your menu init and place the following line
	where you want the menubar to first become visible:
		(TheMenuBar draw:)

	NOTE: an undraw menubar will still respond to user input. ie.. ESC
		clicks, key strokes and typed input.

-	MoveTo has been fixed to not skip over control lines.  The fix
	reduces the effective speed of motion of Actors that fit this
	general set:

		xStep <> yStep - The greater the difference, the greater the affect
		heading NEAR nw, ne, sw, or se.

	This may cause some skating in actors with vastly different step sizes.
	Please see Bob H. for more details.

-	Sound volume is now in.  See the volumeI item of s:menu.sc for how
	to implement it.




08/30/88

-	ShakeScreen is now supported.  The kernel call is as follows:
	(ShakeScreen n [d])
		n = 	number of shakes, 1 to 64K
		d = 	direction to shake; 1 = down, 2 = right, 3 = down/right
			default direction is down
			
-	Save/restore dialogs have been modified.  Should handle full-disk
	conditions, disk changes, etc. much better.



08/30/88

-	There is a global variable named 'version' which should now point to
	the version string for your game.  In the init: of your game, put the
	line

		(= version {x.yyy.zzz})

	if you're using incver.exe to maintain your game version number (you
	should be).

	This will allow more stringent checking for validity of games before
	restoring them.



08/29/88

-	There is a new basic Sierra menu (menu.sc) on the net.  It contains
	the code for echoing the input line (using modifications to User outlined
	below) and for setting animation speed and sound volume (using class
	Gauge outlined below).
	It also contains modifications to the said specs for various items.  A lot
	of caution must be exercised in writing menu said specs, since the MenuBar
	gets the first shot at events.  For example, using 'save' as the said spec
	for saving a game means that if the user types 'save man' he will get the
	save-game dialog.  The said spec should be 'save[/game]'.

-	Class User has a new property, 'prompt', and a new method 'getInput'.

		prompt
			This is the text which will be displayed above the edit box when
			the user starts typing.  Its default is 'Enter input', but it can
			now be changed (e.g. to 'Give her your best line, Larry').

		getInput:char
			Collects a line of input from the user and passes it on to the
			parser.  The first character of the input line is 'char' unless
			'char' is (User echo?), in which case the previous input line
			is echoed.  The default value of 'echo' is now the spacebar.
			The use of F3 for echoing is done through the menu, which invokes
			(User getInput:(User echo?)).

-	A new class, Gauge, has been added to the system.  A Gauge is a dialog
	which uses a thermometer-like gauge to allow the user to adjust something
	(animation speed, sound volume, etc.)  A kindof Dialog, it has the
	following added properties and methods:

		description
			This is the text which appears above the thermometer and tells
			the user what is being adjusted and how to adjust it.  E.g.
					"Use the mouse or right and left arrow keys to
					select the speed at which characters move."

		higher
			This is the text which goes in the button which increases the
			value of whatever is being adjusted.  Its default is "up".

		lower
			This is the text which goes in the button which decreases the
			value of whatever is being adjusted.  Its default is "down".
			
		minimum
			The minimum allowed value of whatever is being set.  Defaults
			to 0.

		maximum
			The maximum allowed value of whatever is being set.  Defaults
			to 15.

		normal
			This is the value of whatever is being adjusted which you, the
			game programmer, consider the normal value.  Defaults to 7.

		update:
			A method used internally.

	As for Dialogs, the 'text' property is the title of the Gauge.  To use
	the gauge, do

		(= newValue (Gauge doit:currentValue))

	where 'currentValue' is the current value of whatever you want adjusted.
	The doit: method of Gauge returns the value selected by the user.

	Gauges for animation speed and sound volume are now built into the
	standard menu.

	A Gauge needs about 1K of heap to run, and can be disposed immediately
	after use: (DisposeScript GAUGE).  The class should be included on all
	volumes.

-	The inventory dialog now supports up- and down- arrows as well as Tab
	and Shift-Tab.


08/23/88

-	save: and restore: methods of Game now prompt for disk changes if
	the current device is the target and is removable.  In support of
	this, the following kernel calls have been added:

-	(StrAt string position [char])
		StrAt returns the character at 'position' in 'string'.  If the optional
		'char' is specified, it replaces the character with 'char', returning
		the old contents.  Use this rather than the mask-and-shift method
		which I expounded to Teresa (sorry...), since byte order in a word
		will vary between machines.

-	(DeviceInfo function @string [@string])
		DeviceInfo returns information about file system devices.
		The functions are:

			(DeviceInfo GetDevice @path @device)
				Puts the string describing the device component of 'path'
				into the string pointed to by 'device'.  Thus, if
				path = "g:/games/kq4/sci", device = "g:".  If there is no
				device component in 'path', puts the current device in 'device'.

			(DeviceInfo CurDevice @device)
				Puts the string describing the current device in 'device'.

			(DeviceInfo SameDevice @dev1 @dev2)
				Returns TRUE if the strings pointed to by 'dev1' and 'dev2' are
				the same physical device, FALSE otherwise.

			(DeviceInfo DevRemovable @device)
				Returns TRUE if 'device' is removable, FALSE otherwise.



08/22/88

-	Class Extra is now officially part of the system.  Like
	Jump, etc., it takes no overhead unless you use it.



08/19/88

-	New stuff has been added to allow semi-automatic adjustment of animation
	to the speed of a machine.  Here's how it works:
	
	A global variable called 'aniThreshold' contains the animation interval
	(see 'aniInterval' below) which you consider to be just barely acceptable
	(the default system value is 10).  After the startRoom: method of the
	Game has been invoked in the process of doing a newRoom:, the checkAni:
	method is called.
	
	checkAni: does animation cycles (only drawing objects, not calling their
	doit: method) and checks aniInterval against aniThreshold.  If aniInterval
	is too large, checkAni: looks for the first member of the cast which is
	marked as an 'extra object' and does an addToPic: on it.  It continues to
	do so until either aniInterval drops below aniThreshold or it runs out of
	'extra objects' in the cast.

	To mark an object as 'extra' (not to be confused with the class Extra in
	development by Al Lowe et. al.), use the isExtra: method:

		isExtra: TRUE			;marks the object as an extra
		isExtra: FALSE			;unmarks it
		isExtra:					;returns the current status

	Things such as sparkles or ripples on water, woodpeckers in trees, etc.
	could all be dropped out in this manner.  Note, though that if an object
	is added to the picture in this manner, it will no longer be accessible
	through any object ID you had before.  The class Extra (below) is, by
	default, marked as extra.

-	A new class, Extra, developed by Al Lowe is in s:extra.sc.  It will be
	made a part of the system on Monday (which will require a recompile of
	the world).  An Extra is a subclass of Prop which waits for a random
	time interval, then cycles for a random interval and repeats.  It's great
	for people reading magazines in waiting rooms, woodpeckers pecking trees,
	etc.  It has the following extra properties:

		pauseCel
			Cel to pause on when not cycling: -1 for random cel, -2 for last cel
		minPause
			Minimum number of animation cycles of no action when paused.
		maxPause
			Maximum number of animation cycles of no action when paused.
		minCycles
			Minimum number of animation cycles of cycling when active.
		maxCycles
			Maximum number of animation cycles of cycling when active.

	This class is, by default, an 'extra' in the sense used above in regard
	to animation speed, and so will be added to pic if the machine is too
	slow.

-	'O' and 'o' work in the debugger again -- the stack size reduction had
	killed them.  In fixing that, I also added code to keep inventory items
	from being displayed, so the static object display won't be so cluttered.

-	The old global variable named 'overRun' has been renamed to 'aniInterval'
	(animation interval) and now contains the number of timer ticks that it
	took to do the most recent animation cycle, rather than how much longer
	than 'speed' it took.  This is a much more useful value.

-	Icons are now centered in a Print window if there is no accompanying text.

-	Edit window length now more closely matches the number of characters
	which can be typed.  Also, the input line and save-game description
	have been lengthened.

-	The parser recognizes modifiers once again.



08/15/88

-	Several new PMachine opcodes have been introduced, leading to more
	space efficient code.  The system object code size was reduced by
	about 1200 bytes.



08/12/88

-	Menu stuff, which doesn't seem to have been written up before:

	You can modify an existing menu with the 'SetMenu' kernel command, which
	has the following syntax:

		(SetMenu itemName selector value [selector value ...])

	where itemName is the name by which you refer to your menu item and the
	the available selectors are

		said: newSaidSpec			change the said spec for the menu item
		text: newText				change the text displayed in the menu
		key: newKey					change the key which selects the menu item
		state: newState			= dActive to enable menu item
										= 0		 to disable menu item
		value: newValue			change the value to return when selected

	For example, you can disable the save-game menu item (which we'll assume
	is refered to by 'saveI') with

		(SetMenu saveI state:0)

	The 'GetMenu' kernel function returns the current values of a menu item
	corresponding to the selectors listed above.  Thus,

		(GetMenu soundI text:)

	would return a pointer to the text corresponding to the soundI menu item.


08/11/88
-	Install no longer passes the colon ":" to instgame.bat.

-	New debugger command: 'S' shows the size and maximum and current stack
	usage of both the processor ('Proc') and PMachine ('PMach') stacks.

-	New constants for show styles
	;Picture change style constants
	(define	HWIPE			0)
	(define	HSHUTTER		0)
	(define	VSHUTTER		1)
	(define	WIPELEFT		2)
	(define	WIPERIGHT	3)
	(define	WIPEUP		4)
	(define	WIPEDOWN		5)
	(define	IRISIN		6)
	(define	IRISOUT		7)
	(define	DISSOLVE		8)
	(define	BLACKOUT		9)

	adding the "BLACKOUT" constant to any of the styles
	will blacken the screen in the converse manner before showing
	picture.
		(curRoom drawPic: PIC23 (+ IRISOUT BLACKOUT))
	
			
08/10/88

-	Save/Restore game and sounds should now work much better together.
	Let me know if there are any restore game problems from now on (1 PM).


08/09/88 

-	PARSER, VC.EXE: Word derivation rules are now kept in a text file
	called DERIV.TXT, with a syntax similar to that of VOCAB.TXT. The 
	vocabulary compiler has been modified so that it will compile both of 
	these files when invoked. Comments are allowed in .TXT files following
	SCI syntax, ie. starting with a semicolon ";". 
	
	A rule to handle plurals might be:
	
	(*men noun *man noun) ; ie. firemen/noun -> fireman/noun
	
	Multiple parts of speech can be specified for each pattern.There is a
	sample DERIV.TXT in the system directory. 
	
	For the parser to function correctly, you must now have VOCAB files
	.000 (dictionary), .900(grammar) and .901(derivations)  present at 
	runtime.[Pablo]


8/08/88

-	The restore: method of Game now takes an optional parameter.  If this
	parameter is TRUE, the restore game dialog will be displayed only if
	there are saved games in the current save-game directory.  This allows
	you to put up a restore dialog at the beginning of the game, which is
	a great convenience to the user.  Just put the following in the init:
	method of your game:

		(if (not (GameIsRestoring))
			(theGame restore:TRUE)
		)

-	The setCursor: and setSpeed: methods of Game now return the old values
	of the properties which they are replacing.

-	New debug features!
		-	Variables displayed in the debugger are now editable.
		-	Breakpoint is back in an object-oriented reincarnation.  Pressing
			'b' in the debugger prompts for an object name (or ID), then for
			a method name.  Once those are entered, execution begins and
			continues until execution enters the indicated method of the object,
			at which point the debugger is invoked.  If no method name is
			entered (i.e. if you press Esc at the 'in method' prompt), a
			breakpoint is invoked whenever the indicated object becomes
			current.




8/05/88

-	When adding a button to a Print, you MUST supply a value to return
	when that button is selected.  This WILL make it possible for a
	TRUE/FALSE test instead of a switch.
	(if 	
		(Print 	"May I have a K of code please?" 
			button: {Be my guest} 1
			button: {Kiss my node pool!} 0
		)
		; take a K of code and smile
	else
		; sulk and be moody
	)
	[Note that through no fault of either the compiler or the Print code,
	the above test will always test false.]

-	Display default width is NOW, the required width of the message
	with NO word wrap.  To enable word wrap, you must pass a WIDTH:
	argument that is greater than or equal to 0.  If you pass 0, the
	width will be determined in the same ratio as the (Print) procedure.

-	StatusLine should now be redisplayed on restart: and restore:.

-	(GameIsRestarting) now returns RESTARTING/RESTORING if you're in the first
	animation cycle after a restart:/restore:.

-	The wordFail: method of Game now gets two parameters: the word which
	was not recognized and the user input line.

		(method (wordFail word input)
			...



8/04/88

-	Added command line switch (-r) to sciv.  When used, will
	Alert user when a new volume is opened on the same physical
	media.  Has no bearing on the file based version.


8/03/88

-	Redefined "buttons" and their handling in Print procedure.  
	You may add up to 5 buttons to a print message.  They are 
	added to the window, aligned horizontally, from left to right
	in the order that you specified them.  If one of them is selected,
	Print returns the number of the button (1 through n) to you.  You must
	take action accordingly as below:
	(switch (Print "Please click on button A." 
				button: {A} button: {B} button: {C})
		(0
			(Print "You pressed ESC")
		)
		(1		
			(Print "Very good!")
		)
		(else
			(Print "Wrong button")
		)
	)

	PLEASE NOTE: This change saved 142 bytes of memory.

-	Refined modeless dialogs (Print dispose:).  A "dispose:" print
	sets the global, modelessDialog to point to it.  This variable,
	if not zero, WILL point to a dialog that can be disposed of via
	(modelessDialog dispose:)  A timed dialog will also ensure that
	this global is zeroed when the timer times out.  If a game is 
	SAVEd, RESTOREd or RESTARTEd, SOMEBODY must dispose of this window
	or it will hang around forever OR in the case of save, not be valid
	when the game is restored.
			
8/2/88

-	New save game interface, with more error checking.

-	New kernel procedure (CoordPri yCoord).  Returns the priority
	that corresponds to yCoord. 
		; make body the same priority as the feet in a split actor
		(body setPri: (CoordPri (feet y?)))

-	Additional command line editing keys:
		CTRL-C clears entire line
		HOME   moves to beginning of line
		END    moves to end of line
 
7/28/88

-	Sound now has the 'prevState' property which reflects the state of
	the most recent animation cue from the sound.

-	Sound has a (currently non-functional) pause: method to pause and
	restart a sound.  More details as the method becomes functional.

-	Game now has an end: method, which you should invoke when the game
	is over due to ego's death, etc.  The method is invoked as

		(theGame end: msg [view [loop [cel]]])

	This will put up a dialog with 'msg' at the top and buttons to
	select restore, restart, or quit at the bottom.  If the optional
	view, loop, and cel are specified, the specified icon will be drawn
	between the message and the buttons.  An example of use:

		(theGame
			end:
				{Damn! As you lie in a gelatinous heap at the bottom of
				the cliff, you realize just how stupid that was.}
			vEgoSplatted
		)

-	A new class, EndGame, has been added in support of the end: method
	of Game.  You can set the title of the end dialog by setting the 'text'
	property of EndGame, and set default view, loop, and cel for icons
	by setting those respective properties.  View, loop, and cel are
	overridden by explicit parameters to the end: method of Game.  A view
	of -1 means 'do not display an icon', and is the default.




7/27/88

-	Save/restore game interface was been changed.  Most recently saved
	game is now first.



7/20/88

-	Support for stopping ego by pressing the arrow key which started him
	moving is back.  The keypad '5' key also stops him.

-	The canControl: property of User is now a method.  In most cases, this
	will not affect existing source code -- you still say

		(User canControl:FALSE)

	to take control away from the user.  The only difference when if you want
	to find out the current state of the User's control -- (User canControl?)
	will not work.  The way to determine the state is to invoke the method
	with no arguments:

		(User canControl:)

	returns the current control state.

-	Class Actor now has a setDirection: method which will move an Actor off
	screen in a given direction.  Valid directions (dirStop, dirN, dirNE,
	dirE, etc.) are enumerated in system.sh.



7/19/88

-	The various failure methods invoked when we're unable to parse the
	user's input now get pointers to the offending input.  The following
	get invoked depending on why we failed to parse/respond to the input:

		(theGame wordFail:word)	 		;'word' is pointer to unknown word
		(theGame syntaxFail:input)		;'input' is pointer to input line
												;which can't be parsed with the grammer
		(theGame pragmaFail:input)		;'input' is pointer to input line
												;which wasn't responded to
	
	These, in conjunction with judicious use of the File class will allow
	you to log input which, for one reason or other, was not handled
	appropriately.  For example:

		(instance logFile of File
		)

		(procedure (LogIt what why &tmp [str 100])
			(logFile
				write:
					(Format @str
						"Room %d: %s:\r
						____\"%s\"\r"
						curRoomNum
						why
						what
					)
				close:
			)
		)

		(method (wordFail word)
			(super wordFail:word)
			(LogIt word {Unknown word})
		)

		(method (syntaxFail input)
			(super syntaxFail:input)
			(LogIt input {Couldn't parse input})
		)

		(method (pragmaFail input &tmp [str 100])
			(super pragmaFail:input)
			(LogIt input {Input not responded to})
		)

	Note that in order for pragmaFail: to work, you'll want to suppress
	all the default "You can't get that here.", "It's just as it appears.",
	etc. handling.  Otherwise, someone HAS responded to the input,
	pragmaFail: will not be invoked, and the input won't be logged.



7/17/88

-	Class Sound now has a 'keep' property which prevents the Sound from
	being deallocated when it is finished.  This allows a Sound to be
	initialized in a Region and used (with no memory fragmentation) in
	several Rooms in the Region.  Just be sure to eventually set 'keep'
	to FALSE!

-	There is now a BRIEF macro which acts as an SCI class browser in
	/games/sci/system/browse.m.  Basically, it's an easy way to look at
	the properties and methods of the various SCI classes.  Talk to me
	about installing it in BRIEF - I'm not sure whether or not it uses
	macros specific to my system.



7/6/88

-  PARSER (Ghenis) : new patterns added for word derivation:
   *er     example: slow (ADJ) -> slower (ADJ)
   *er     example: buy (VERB) -> buyer (NOUN)
   *est    example: slow (ADJ) -> slowest (ADJ)
   
-  PARSER (Ghenis) : new clauses added to grammar:
   
   A sentence can lack a leading verb: "burger" and "burger with fries" are
   now acceptable as user input
   
   CVERBS (compound verb forms) have been extended so that several verbs can 
   be strung together just like nouns. The user may now type sentences like
   "say do you have a ticket" or "do you have a ticket" both of which would 
   be matched by (Said 'have<do/ticket') or (Said 'have/ticket'). "Say hello 
   also is allowed now. These examples assume that "you" is declared as a 
   PRON and "hello" as a NOUN.
   
    			
7/5/88

-  Animate kernel procedure now calls "doit:" for the members of the cast.
   This was changed to speed processing of "Static Views" (those without
   a script).  The doit: method is only called if a second TRUE parameter
   is passed to Animate eg  (Animate (cast elements?) TRUE).  If you need
   to Do an animate cycle without calling "doit" you must pass a second FALSE
   parameter eg  (Animate (cast elements?) FALSE).

-  CanBeHere kernel procedure now checks for actor intersections as well
   as control violations.  This does not affect the canBeHere method of
   Actors.  The new protocol requires that CanBeHere gets the elements of
   the cast list in addition to the actor you desire to check.

-  View classes are now stop updated by default AND have a bit set in their
   signal property that identifies them as "staticViews" (the symbolic
   name defined in SYSTEM.SH). Added the yStep property to views to standard-
   ize base rectangle setting.  This property defaults to 2 and the base
   rectangle is set using the standard kernel BaseSetter when the View is
   inited and whenever it is "posn'ed".
			
			

7/5/88

-  PARSER UPGRADES

-  Said now claims the SaidEvent so SCI coders do not have to explicitly
   claim it in their scripts. (ref. Bob Heitman)
   
-  VOCAB hints: In the past. many nouns were also tagged as adverbs to allow
   parsing of, for example, "castle bridge", where "castle" is a modifier to 
   "bridge". The new parser allows nouns to be modified by other nouns so in 
   the above case "castle" should NOT be made an adjective.
   (ref. Pablo Ghenis)  NOTE - The "old" parser also allowed nouns to modify
   nouns, so there should be few repercutions. (ref. Bob)
   
-  GRAMMAR hint: There was a bug reported in KQ4 where articles were not 
   being ignored, so "get the rock" would not match 'get/rock[<black]'
   The solution was to edit the grammar (NLPGRMR.TXT)	so that articles 
   (NLART) were always accepted as an NLIGNR word. (ref. Pablo Ghenis)
   
-  Noun plurals and verb derivatives are automatically recognized. The 
   following transformations are attempted in order to find a word's root
   whenever there is no match in VOCAB.TXT. All of these derived forms can 
   now be deleted from our VOCAB.TXT files. In the case of KQ4 this shrunk 
   the file by almost 20% while doubling the number of words we can 
   recognize. (ref. Pablo Ghenis)
   
           USER       TEST       TEST NEW
           PATTERN    PATTERN    TAGS TAGS       SAMPLE TRANSFORMATION
           -------    -------    ---- ----   --------------------------------
   
   tryRoot("*s",      "*",       NOUN,NOUN); /* books -> book */
   tryRoot("*es",     "*",       NOUN,NOUN); /* boxes -> box */
   tryRoot("*ies",    "*y",      NOUN,NOUN); /* fairies -> fairy */
   tryRoot("*men",    "*man",    NOUN,NOUN); /* women -> woman */
   tryRoot("*ves",    "*fe",     NOUN,NOUN); /* knives -> knife */
   tryRoot("*ves",    "*f",      NOUN,NOUN); /* leaves -> leaf */
   tryRoot("*people", "*person", NOUN,NOUN); /* chairpeople -> chairperson */
   tryRoot("*a",      "*um",     NOUN,NOUN); /* ova -> ovum */

   tryRoot("*ing",    "*",       VERB,NOUN|ADJ|VERB); /* playing -> play */
   tryRoot("*ing",    "*e",      VERB,NOUN|ADJ|VERB); /* living -> live */
   tryRoot("*nning",  "*n",      VERB,NOUN|ADJ|VERB); /* running -> run */
   tryRoot("*pping",  "*p",      VERB,NOUN|ADJ|VERB); /* shopping -> shop */
   tryRoot("*mming",  "*m",      VERB,NOUN|ADJ|VERB); /* swimming -> swim */
   tryRoot("*tting",  "*t",      VERB,NOUN|ADJ|VERB); /* batting -> bat */
   tryRoot("*rring",  "*r",      VERB,NOUN|ADJ|VERB); /* sparring -> spar */
   tryRoot("*gging",  "*g",      VERB,NOUN|ADJ|VERB); /* digging -> dig */
   
   tryRoot("*ed",     "*",       VERB,ADJ ); /* painted -> paint */
   tryRoot("*ed",     "*e",      VERB,ADJ ); /* closed -> close */
   tryRoot("*nned",   "*n",      VERB,ADJ ); /* runned -> run */
   tryRoot("*pped",   "*p",      VERB,ADJ ); /* shopped -> shop */
   tryRoot("*mmed",   "*m",      VERB,ADJ ); /* dimmed -> dim */
   tryRoot("*tted",   "*t",      VERB,ADJ ); /* batted -> bat */
   tryRoot("*rred",   "*r",      VERB,ADJ ); /* sparred -> spar */
   tryRoot("*gged",   "*g",      VERB,ADJ ); /* rigged -> rig */
   tryRoot("*ied",    "*y",      VERB,ADJ ); /* tried -> try */

   tryRoot("*ly",     "*",       ADJ ,ADV ); /* slowly -> slow */

   tryRoot("*y",      "*",       NOUN,ADJ ); /* rocky -> rock */
   tryRoot("*ish",    "*",       ADJ ,ADJ ); /* yellowish -> yellow */
   
   

7/1/88

Parser
-  must go from specific to generic
		if 			'look' 
		followed by 'look/tree'
		and type 	'look tree'
	"look" will catch and not "look tree."

-  must have < before [] (modifier before optionals)

-  to get only a verb to match (and not a verb followed by a noun), type
			'eat[/!*]'
	"eat" will match but not "eat tree"

-  Error messages indicate bad formatting:
	ERROR TROUBLE
		f0	,
		f1 and (a space)
		f2 slash
		f3 (
		f4 )
		f5 [
		f6 ]
		f7 #
		f8 <
		f9 >
		
		## word#


-  Plurals are now unnecessary.  Parser automatically lops off s, es; 
ies becomes y; men becomes man; ves becomes fe or v; people becomes person.

-  Genurds are changed to root words.  Parser changes running to run; 
swimming becomes swim.

-  Parser lops ly off adverbs (slowly becomes slow) and ish off adjectives
(yellowish becomes yellow).

-  A string of nouns becomes only the last noun:  
	look at the prison guard's jacket becomes 'look/jacket'.




6/23/88

-	All properties of class Game have been moved to global variables, so that
	such constructs as (theGame timers?) are no longer necessary.  The new 
	variables are

		score
		possibleScore
		speed
		timers
		theCursor

	This should not affect much code, since you should be accessing these 
	through methods rather than directly anyway.

-	The Region class now has a newRoom: method which does nothing, but is 
	available to hook into if a Region needs to know about a room change.  
	The newRoom: method of all regions which are active due to a setRegions: 
	will be invoked from the newRoom: method of the current room with the new
	room number as the parameter.

-	The List class now has the method addAfter:, which may be used as 
	follows:

			(aList addAfter: anElement obj1 obj2 ...)

	This adds the objects obj1, obj2, ... to the list aList following the 
	object anElement in the list.  If anElement is not in the list, nothing 
	happens.  The objects are added in the order in which they are specified.
	Obviously this method cannot be used to add to the front of a list -- use 
	addToFront instead.

-	The sound kernel calls have been changed.  There is now only one 
	sound-related call, (DoSound parameters...), which takes as the first 
	parameter the function to call (the old kernel call symbols are now the 
	function names).  Thus (SoundOn TRUE) translates to
	(DoSound SoundOn TRUE).
		play
		setNext
		delete
		check

-	Memory information kernel calls have changed in a manner similar to 
	sounds -- there is now one call (MemoryInfo parameter) which takes the 
	old kernel function call name as a parameter.

-	I fixed a subtle optimization-related bug in the compiler.  
	Unfortunately, my experience has been that such fixes can sometimes 
	introduce bugs elsewhere.  Be forewarned.

-	The new parser is here!  There are two new symbols which can be used in 
	Said specs:

		*	matches any word
		!*	matches no word

	The first of these probably gives you readablity more than anything, 
	allowing you to say

		'look/*/telescope'

	rather than

		'look//telescope'

	to mean "look at (anything) with the telescope".

	It also, however, allows you to specify mandatory, but unspecified 
	modifiers:

		'look/rock<*'

	will require a modifier to rock, but not be picky about what it is.  If 
	anybody finds a use for this, let us know -- we can't think of why you 
	might want it...


	The second symbol, which will not match any word, is used when you do NOT 
	want a word in a specific place.  Thus, 

		'look/rock[<!*]'

	will match "look at the rock" but not "look at the slimy rock".  [Think
	of the construct [<!*] as meaning "the modifier, if present, must not
	be a word".
	
	In keeping with the spirit of "when nothing is specified, anything is
	acceptable", the Said spec

		'look'

	now is interpreted as 'look/*', so that it will match "look tree" as well 
	as just plain old "look".  The Said spec which will match "look" but NOT 
	"look tree" is

		'look[/!*]'

	I will be constructing a Brief replace string which will allow you to 
	make any necessary conversion to this form with a minimum of hassle.


	One other Said spec issue: any occurances of the construct <[...] must be 
	replaced with [<...], e.g.

		'look/rock<[heavy]'

	must become

		'look/rock[<heavy]'

	The former spec basically says "there MUST be a modifier, and if present 
	it must be 'heavy'", which is just a description of

		'look/rock<heavy'

	If, as is probably the case, what was meant was "if a modifier is 
	present, it must be 'heavy'", the latter spec is the appropriate one.



6/20/88

-	New debugger commands while inspecting:

		up & down arrows move the inspection address 16 bytes lower (up arrow) 
			or 16 bytes higher (down arrow).
		left & right arrows move the inspection address 2 bytes lower (up 
			arrow) or 2 bytes higher (down arrow).




6/16/88

-	Class User has the property 'echo', which is the key which echos the
	previous input line.  It defaults to F3 (which won't work if you're using 
	the standard F3 = priority screen in menu.sc).

-	New debugger commands for use when inspecting:

		c -	If the object is a Collection (i.e. List or Set), inspect, in 
				turn, each of its elements.

	The following are more for the interpreter progammers than the game 
	programmers, as you never see a doubly-linked list at the Script level.

		[ - 	Inspect the next node of a doubly-linked list.

		] -	Inspect the previous node of a doubly-linked list.

	The following are the names of system Collections which may be inspected
	with the 'i' command followed by the 'c' command:
	
		cast			-	The cast
		timers		-	The currently active timers
		sounds		-	All sounds which have been init:ed
		regions		-	The current regions
		addToPics	-	All addToPics for the current room
		blocks		-	All blocks which have had an 'observeBlocks' done on them
		controls		-	All controls in the room

6/15/88

-	Class View now has the method 'lastCel', which returns the cel number of
	the last cel in the current loop of the View's current view.  You can
	replace all those (- (NumCels who) 1) with (who lastCel:).

-	The restart: method of Game no longer asks the player if s/he really
	wishes to restart.  That prompt is now the game programmer's 
	responsibilty.

-	Class Inventory has two new properties:

		carrying
			This is the string which appears in the title bar of the inventory 
			dialog.  It defaults to "You are carrying...".

		empty
			The string to print when there is no inventory to display.  Default 
			is "To date, you have acquired nothing!".

-	Class User has the property 'stop', which is the key (other than the 
	numeric keypad '5') which can be used to stop ego.  It defaults to the
	spacebar.  This is necessary because not all keyboards have a numeric 
	keypad.






6/13/88

-	The interpreter now uses a keyboard driver rather than reading the 
	keyboard directly.  The line

		kbdDrv=/games/sci/system/ibmkbd.drv

	should be included in your 'where' file.
	The '5' key in the numeric keypad is now the 'stop' key.



6/8/88

-	Changed the way that regions are dispose:d on a newRoom:. Your regions
	should now be getting the dispose: message.

-	Both class Motion and class Jump now have a triedToMove: method which
	returns TRUE if it was time for the mover to move (based on moveSpeed),
	FALSE otherwise.  The isStopped: method of Actor now uses this.

-	Class Object now has the isKindOf: method.  This is used as

		(object isKindOf: Class)

	and returns TRUE if object is an instance of a class which is either
	Class or a sub-class of Class, FALSE otherwise.  This method, while not 
	really computationally expensive, isn't cheap either -- don't use it for 
	each member of the cast on each animation cycle unless you're willing to 
	take a 1-2% speed hit for it.

-	As we go along, I'm going to be trying to realign our method names
	and semantics with those of Smalltalk, upon whose Class system ours is
	somewhat loosely based.  In the first round of this, the following
	method names have changed:
	
				old					new
				
			isInstanceOf	->	isMemberOf
			understands		-> respondsTo
			myself			-> yourself

	System.sh defines 'myself' as 'yourself' to ease the transition, but new 
	code should use 'yourself'.



6/6/88

-	A help screen has been added to the debugger.  Press '?' when in the 
	debugger to see it.  One of the commands in the help screen is the new 'c' 
	command, which allows you to inspect the current object (the one whose 
	method is being executed).

-	The SoftBlock class is no more.  It has been replaced by the Block class
	(which works with the observeBlocks and ignoreBlocks methods below).  The 
	Block class keeps an Actor OUT of an area.  To keep an Actor in an area,
	use the Cage class, which also works with the following methods.

-	Two methods have been added to the Actor class:

		observeBlocks: block [block ...]
			Causes the Actor to observe the listed Blocks or Cages.

		ignoreBlocks: block [block ...]
			Causes the Actor to ignore the listed Blocks or Cages.
			
	Default is for all Actors to ignore all blocks.

-	The JumpTo class will now work even for jumps across the entire screen.




5/23/88

-	A 'setCursor' method has been added to the Game class to set the mouse 
	cursor form.  Use it rather than the kernel SetCursor function.  This 
	method puts the current cursor form in the property 'cursor' of Game, so 
	that you can change the cursor to something and then restore it to its
	original form:
	
		(method (foo &tmp oldCursor)
			(= oldCursor (theGame cursor?))
			(theGame setCursor:NEW_CURSOR)
				.
				.
				.
			(theGame setCursor:oldCursor)
		)
		
-	Version 1.000.586 of the sc compiler has support for unsigned arithmetic 
	comparisons.  The unsigned operators are

		u<
		u<=
		u>
		u>=

	(no, u== and u!= don't exist!)
	
-	Save and restore game should now work as advertised (i.e. don't expect to 
	restore games across a code change).  User interface is not completed -- 
	in particular the non-mouse interface sucks.  But it should be enough to 
	allow testing/QA of games.

-	The global variable 'smallFont' contains the font used to display the 
	save/restore game dialogs, and any other system dialogs in which space is 
	at a premium.  Recommended fonts for this are fonts 3 or 4.
	
-	The numbers for the two standard cursor forms are now kept in the global
	variables 'normalCursor' (which defaults to the arrow) and 'waitCursor'
	(which defaults to the hand).  If you want different cursors, just put 
	their numbers in these variables and the system will respect your 
	choices (though the system designers may not!).



5/11/88

-	Far strings are now in place.  In general they should be fairly 
	transparent, though now and then you may get bitten by the difference 
	between far and near strings.
	
	First, the syntax:  far strings are enclosed in the standard double
	quotes
	
		"This is a far string."
		
	whereas near strings are enclosed in braces
	
		{This is a near string.}
	
	Note that this means that you may not use braces instead of parentheses 
	for enclosing expressions.  I don't think anybody is using braces, so 
	this should not be much of a burden.
	
	The basic rules of thumb for when you can use double-quoted strings are:
	
		-	Double-quoted strings can appear in the primary text position of 
			Print or Format statements:
			
				(Print "This is a far string.")
				(Format @buffer "You have %d gold coins." moneyCount)
				
		-	Double quoted strings can appear in property or variable
			assignments, but in this case the compiler will compile them as
			near strings rather than far.

	The basic difference between far and near strings is that far strings 
	require two words of storage whereas nears only require one.  Since 
	variables and properties are only one word, this means that the pointer 
	to a far string cannot be assigned to varibles or properties.  Also, such 
	expressions as
	
		(if test "True" else "False")
		
	will not work, since the if statement can only return a word.  This must 
	be written as
	
		(if test {True} else {False})

	to use near strings.
	



4/29/88

-	Some changes have been made to the Sound class, but since it's not done
	yet there's no point in documenting them.
	
-	The 'inspect' debug command has been modified to allow inspection of 
	arbitrary memory.  Entering a heap offset at the "Inspect" prompt will 
	display a hex dump of some 63 bytes starting at that address (unless the 
	address is an object, in which case it will be displayed as an object).

	A new command, 'O', has been added to the debugger.  It does the same 
	thing as (ShowObjs TRUE), i.e. it shows the addresses of the objects as 
	well as their names.

-	Four methods have been added to the Game class in preparation for
	integration of parsing.  The methods are error handling methods in
	case we can't handle user input for some reason.  They are:

		wordFail: word
			Called if 'word' is not in the dictionary.  You can print a
			message such as "I don't understand ____".  Return zero if the
			parse should fail, non-zero if you want the word to be accepted
			as legitimate despite it not being in the dictionary.  The
			latter case would be used if, for example, you wanted the user
			to try and guess a name -- you don't want the guesses raising
			errors just because they're not in the dictionary.  [The return
			value is not presently being looked at -- later...]

		syntaxFail:
			This is called if the sentence isn't a properly formed English
			sentence (at least as far as we're concerned -- there will be
			a number of proper sentences which will raise this error).  For
			example, "give dwarf the" would raise this error.

		semanticFail:
			This is called for properly formed sentences which don't make
			sense -- i.e. the cases (we'll talk about this later) don't
			match.  An example of this would be "give dwarf to gold" since
			you can't give something to an inanimate object.

		pragmaFail:
			If, after passing the said event to everyone, it is still not
			claimed, this method is invoked.  This will probably do
			something highly intelligent, such as print "I don't know what
			you're talking about."  In order for this to work properly,
			the 'claimed' property of the said event must be properly 
			conditioned.  The easiest way to do this to for the handleEvent 
			method to have the following structure:
			
				(method (handleEvent event)
					(if (event claimed?) return)
					
					(switch (event type?)
						(...
						)
						(saidEvent
							(event claimed:TRUE)
							(cond
								((Said ...)
								)
								...
								(else
									(event claimed:FALSE)
								)
							)
						)
					)
				)
				
			
			
4/28/88

-	New debugging command!  When inspecting an object, you can now type 'e' 
	edit its properties.  After being prompted for the property to edit, you 
	will be shown the current value of the property, which you can change.  
	While you CAN type in the name of an object whose ID is to be put in the 
	property, this will not generally be of much use, since the object will 
	in all likelihood not be properly initialized for its role.  The edit 
	command is really only useful for numeric properties.




4/20/88

-	Fixed compiler so that it will compile bitwise nots of non-constant 
	expressions.  Thus, if foobar is a variable, (~ foobar) will now compile 
	properly.
	
-	When changing rooms under keyboard (vs. mouse) control, ego's motion now 
	continues as it should.
	
-	A new method has been added to the Object class:

		(object isInstanceOf: class)
			Returns TRUE if object is an instance of class, FALSE otherwise.
	
-	New methods have been added to Actor:

		(actor observeControl: c1 [c2 ...])
			Makes actor observe (i.e. be blocked by) controls c1, c2, etc.
			
		(actor ignoreControl: c1 [c2 ...])
			Makes actor ignore (i.e. be able to cross) controls c1, c2, etc.
			
		(actor setStep: xs [ys])
			Sets an Actor's xStep to xs and yStep to ys (if present).  If 
			either xs or ys are -1, the corresponding step size is not changed. 
			This method should be used rather than setting xStep and yStep 
			directly, as it will recompute the actor's motion parameters based 
			on the new step sizes.





4/18/88

-	The square root function is now available to the Script language:

		(Sqrt n)
		
	returns the integer square root of n.
	
-	Real-time is now more real -- your system clock should only change 
	by 0.1% as opposed to the prior change of about 9%.
	
-	Save/restore game now works, though it won't do you too much good.
	To save a game, do
	
		(theGame save:)
		
	and to restore it, do
	
		(theGame restore:)
		
	The problem with save: is that you can't restore a game if you have
	made ANY change in your code -- the old code, not the changed code
	will be restored.  The user interface is waiting for changes to the 
	dialog manager before it is completed.
	
-	There are two new motion classes: Jump and JumpTo.  Jump gives you
	motion under the influence of gravity for falling, jumping, etc.
	The simplest use of Jump, that of making an object fall from its
	current position to a given y coordinate (endY), is done by writing
	
		(actor setMotion:((Jump new:) y:endY))
		
	Many more complex jumps can be constructed, and a Jump menu has been 
	added to the testing room to aid in doing this.  The properties 
	relevant to constructing a Jump are:
	
	gy	The component of gravitational acceleration in the y 
		direction.  If you want to truely simulate gravity, the 
		value of this can be computed from
		
			gy = .098h
			
		where h is the height, in pixels, of a 1 meter tall object 
		(ego is about 1 meter).  The default value of gy is for an 
		ego which is 33 pixels tall, which gives a gy of 3.  If 
		you're doing an inside scene with a taller ego, you'll need 
		to change this.  You can make an actor fall upwards with a 
		negative value for gy, or simulate weaker or stronger 
		gravity by making gy smaller or larger.
		
	gx	The x component of gravitational acceleration.  The default 
		is 0, but a non-zero value will make ego fall in the x 
		direction as well.  Probably only useful for Space Quest and 
		its ilk.
		
	dy	The actor's initial y velocity (step size).  The default is 
		0, which is the best value for a fall.  If you want ego to 
		jump up, set this to a negative value.
	
	dx	The actor's initial x velocity (step size).  The default is
		the actor's step size, which is the best value for a fall.
		You may want to set this larger for jumping.
		
	y	The y coordinate at which the actor is to complete the jump. 
		If this is set and the actor crosses the line specified by 
		this property, the actor will be set to this y coordinate 
		and the jump motion will be completed.
		
	x	The x coordinate at which the actor is to finish jumping.  
		If this is set and the actor crosses the line specified by
		this property, the actor will be set to this x coordinate
		and the jump motion will be completed.

		Note:  When both x & y are set, whichever of x & y is
		crossed first is where the object will be set without change 
		in the other coordinate.


	JumpTo is a sub-class of Jump which requires much less involvment on 
	your part.  It jumps an actor to a specified position as best it 
	can.  Currently, jumps of greater than about 200 pixels horizontally 
	don't work too well, but I'll work on that.  To jump to a position
	(endX, endY), just write
	
		(actor setMotion:JumpTo endX endY)
		
		
		
		
4/4/88

-	Rather than perpetuate a misspelling, kernal.sh has been changed to
	its correct spelling of kernel.sh.  Change it in the include in your
	copy of game.sh.
	
-	The 'who' property of the Event class has been changed to 
	'modifiers', since that is what it was being used for.
	
-	You should no longer call the kernel routine 'DrawPic' directly.  
	Instead, use the 'drawPic:' method of Room, e.g.
	
		(curRoom drawPic:myPic [style])
		
	This allows us to keep track of the current picture for save/restore 
	game.
	
-	The 'understands:' method has been added to class Object.  The 
	expression
	
		(anObject understands:#selector)
		
	is TRUE if selector is a method or property of anObject, FALSE 
	otherwise.
	
-	Class List now has an 'indexOf:' method, which returns the index of 
	an object in the list, or -1 if the object is not in the list.  
	Usage is
	
		(aList indexOf:anObject)



											 BIT HELP
											 ========

Sample:	11110000
Mask:		10001001

NAME	SYMBOL	RESULT		EXPLANATION
--------------------------------------------------------------
XOR		^		01111001		set if either (but not both) is set
OR			|		11111001		set if either is set
AND		&		10000000		set if both are set
NOT		~		00001111		toggle all bits of Sample


To    SET a bit,  OR it with Mask.
To TOGGLE a bit, XOR it with Mask.
To  CLEAR a bit, AND it with the NOT of Mask.



										The SCI Debugger
										================


The SCI debugger is invoked by pressing Alt-D.  The debugging window
will pop up in the upper right corner of the screen, and you may start
issuing commands to the debugger.  To put the debugger away, just press
Alt-D again.

The debugging window looks something like this:



     ---------------------------------
     |                               |
     |   current object              |
     |                               |
     |   opcode                      |
     |                               |
     |   acc:xxxx                    |
     |                               |
     |                               |
     |    Stack           Parms      |
     |     xxxx            xxxx      |
     |     xxxx            xxxx      |
     |     xxxx            ----      |
     |     xxxx            ----      |
     |     xxxx            ----      |
     |                               |
     ---------------------------------



The fields are:

current object
	The name of the object whose method is currently executing.

opcode
	The next pmachine opcode to be executed.  While I won't go into the
	details of all the opcodes, the critical ones for debugging are
	'send' and 'callk', and 'ret'.
	
	send
		Sends a message to the object whose ID is in the accumulator
		of the pmachine (acc in the window above).  The selector and
		arguments of the message are on the stack, the first five
		elements of which are displayed in the 'Stack' column in the
		window.  Sometimes a send is just a call to set or get the
		value of a property, in which case you will not enter a method.
		
	callk
		Calls the kernal routine displayed in the opcode.

	ret
		Returns to the caller of the current method or procedure.

acc
	The value in the pmachine accumulator.

Stack
	The first five elements on the pmachine stack.  A ---- here indicates
	the end of the stack.

Parms
	The first five parameters to the current method or procedure.  A ----
	here indicates the absence of a parameter.



										Debugging Commands

Commands to the debugger are single-key commands, sometimes followed by
a prompt for a number or string.  The commands are:


Return or mouse click
	Single step to the next pmachine instruction.

Tab
	Step across a send or procedure call (not necessary in the case
	of callk).  This is not always reliable.  One of these days, I'll
	look into it.

q
	Quit, exitting to DOS.

s
	Toggle the send stack on/off.  While on, the send stack updates
	when stepping in the debugger.

i
	Inspect an object.  You will be prompted for the object to inspect.
	Enter either the name of the object (such as 'ego', without the quotes)
	or its ID (remember to preceed hex numbers with a '$').  The property
	names and values of the object will be displayed.

	Pressing 'i' again (while the inspector window is up) will prompt you
	for one of the object's selector names.  It will then display the
	property corresponding to the selector either as a number/string pair
	or as another inspector window.  Inspector windows can be nested
	three deep.

	To put away an inspector window, press any key but 'i'.

a
	Inspect the object whose ID is in the accumulator.  This is a quick
	way to see which object a send opcode is about to send to.

o
	Display all objects in the heap.  (Same as (ShowObjs FALSE).)

f
	Display the free blocks in the heap.  (Same as (ShowFree).)

g
l
t
	Display the value of a global, local or temporary variable.  You will
	be prompted for the number of the variable.




                    Script Classes for Adventure Games
						  ==================================


                               Introduction


An interesting feature of object-oriented languages is that simply knowing
the syntax and the primitive procedures (kernel calls) of the language does
not help you all that much in the actual process of sitting down and
embodying an idea using the language.  The basis of object oriented
programming is in the hierarchical class system -- the properties of the
classes, the methods which operate on them, and the inter-relationships of
the classes.  Thus this document, which attempts to describe the class
system for the Script development system.

Note that describing the class system for Script is like trying to shoot a
moving target -- the classes are constantly changing, though the rate of
change does seem to be slowing down somewhat.  As we gain experience, the
class hierarchy will stabilize, but until then keep your seatbelts fastened,
since the ride is likely to be a bit bumpy.

The most important principal to keep in mind when programming in an OOPL is
that classes should be embodiments of abstract concepts, not kludged code to
do something that you don't feel like thinking through.  Purity of
programming and concept is very important in an OOPL.  Since the structure
and methods of a class are inherited by all its subclasses, small changes
may have wide-ranging effects.  On the positive side, a well thought-out
class system almost seems to program itself -- objects and classes which are
accurate representations of the world which they are supposed to model
behave logically in response their inputs.  The programming process becomes
a matter of telling objects how to behave rather than writing masses of
complex code.

One rule of thumb is to not add a property or method to a class if it
doesn't logically belong there -- create a subclass instead.  As an example,
consider the problem of moving a number of things around the screen in
unison.  We might decide to represent this as a Collection of Actors (see
the class descriptions below) and move the Collection around the screen. 
This, however, requires that we add positional properties and a move method
to the class Collection and write some fairly kludgy code to keep the actors
in the proper positional relationship.  If we do this, however, all
Collections and subclasses of Collection carry around all this baggage,
which really has nothing to do with the concept of a group of things.

A better way to implement this would be to define a subclass of Collection,
say a Gang, which is a kind of Collection but with the positional and
movement aspects incorporated.  This leaves the concept of a Collection
unsullied, but still leaves us with the problem of how to keep the Actors
positioned properly.  But by calling this concept a Gang and thinking of it
in that respect rather than as just a Collection, it occurs to us that gangs
are often a collection of followers following a leader.  So we add a leader
property to the Gang class, which will be the object ID of the Actor which
is to be the leader.  Now moving the group around the screen is easy -- we
just move the leader and tell the followers (the elements of the Gang) to
follow him:

     (method (moveTo nX nY)
          (leader moveTo: nX nY)
          (elements eachElementDo: #setMotion: Follow leader)
     )

We could even go on to further refine the Gang class by including code which
handles a Gang without a leader by having the followers wander aimlessly
about a point which is considered to be the position of the Gang.

The point here is that rather than mucking up the Collection class with a
lot of irrelevant code, we created a subclass of it with the desired extra
properties and methods.  In doing so, we stopped thinking of it as just some
sort of abstract collection and started thinking of it as a gang, inspiring
the thought of adding a leader to the gang and opening the way to many
possibilities.

DON'T THINK OF CODE -- THINK OF CONCEPTS!



                             The RootObj Class

A RootObj is the most fundamental object possible in the Script language --
it has an identity as an object, but that's it.  It is defined in the
kernel, not in Script, and is the ultimate super-class of all objects. 
Since it is such a minimal object, it is only used as a basis for those
objects in which memory size is a major consideration and which are hidden
away in other objects in such a way that the fuller identity given by making
them sub-classes of Object is not necessary.

In file:            in the kernel
Inherits from:      nothing
Inherited by:       Object
                    InvItem


Properties:


     species
          This is a pointer to the property dictionary for an object, which
          is contained in the defining class.  Thus if two objects have
          equal species properties, they are both instances of the same
          class.  Do not change this property, or the object will stop
          working.

     superClass
          This is a pointer to the method dictionary of the object's
          superclass, and is used to look up a method which is not defined
          locally.  Don't change it, or the object will stop working.

     -info-
          This is esoteric bit-mapped information about the object.  It is
          currently used to tell whether the object is a static instance or
          was created with new:.



                             The Object Class

Class Object is the super-class of the majority of the classes in Script. 
It defines the default behavior for these classes, ensuring that all objects
will respond to a certain basic set of messages.

In file:            system.sc
Inherits from:      RootObj
Inherited by:       All classes

Properties:

     name
          This is a string representation of the name of the object or
          class.  It is used by showSelf: to display the object.  The
          compiler will use the symbol for an instance or class as its name
          unless name is explicitly set.


Methods:

     new:
          Returns the ID of a new instance of the class or object.  This new
          instance has the same methods and property values as the parent. 
          The property values can be changed, the methods cannot.

     init:
          Initializes the object.  If the object is to show up on the
          screen (Views, Props, Actors and Egos), this is the message which
          will make the it show itself.  The default does nothing.

     doit:
          Do your thing, whatever that may be.  Sometimes this is sent when
          the object is selected, sometimes (as for Actors) it is sent for
          each animation cycle.  The default does nothing.

     dispose:
          Dispose of the object.  If the object was created using new:, this
          reclaims the memory occupied by that object.  In this case it is
          an error to refer to the object ID being disposed of once the
          dispose: message has been sent.  Subclasses of Object should make
          sure that they dispose of any objects which they created before
          doing a (super dispose:).

     showStr: where
          Format a string describing the object at the storage pointed to by
          where.  The default string is the object name.

     showSelf:
          Display this object in a meaningful way.  This is primarily used
          for debugging, in order to find out which objects are present. 
          The default is to print the string produced by showStr:.

     perform: code [args...]
          Execute code.  Code must be an object of class Code with a doit:
          method whose first argument will refer to the object which is to
          perform the code.  Thus, one way to implement showSelf: would be
          to create the Code object

               (instance showMe of Code
                    (method (doit theObj)
                         (Print (theObj name?))
                    )
               )

          You could then make the object foo show itself even if it did not
          have a showSelf: method by writing

               (foo perform: showMe)

          Up to four arguments (besides the Code object ID) may be passed to
          perform:.

     myself:
          Returns the object ID of the receiver.  This is useful as the last
          in a series of messages to an object to force the entire send to
          return the ID of the object.  For example, if you wish to add a
          newly created and initialized Actor to a List, you could write

                    (list add:
                         ((Actor new:)
                              posn:100 100
                              view:5
                              setCycle: EndLoop
                              myself:
                         )
                    )

     understands: selector
          Returns TRUE if the object has a method corresponding to selector,
          FALSE otherwise.



                           The Collection Class

The Collection class provides the ability to manipulate collections of
objects.  Objects which belong to a Collection are said to be elements or
members of it.  The Collection class has no particular order defined for its
elements, so it should not be used for situations in which the objects
should be ordered -- use a List instead.

In file:            system.sc
Inherits from:      Object
Inherited by:       List
                    Set

Properties:

     elements
          A pointer to a kernel list (kList) of the elements of the
          Collection.

     size
          The number of elements in the collection.


Methods:

     add: element [elements ...]
          Add elements to the Collection.

     delete: element [elements ...]
          Delete elements from the Collection.

     eachElementDo: action [args...]
          Send the message action [args...] to each element of the
          Collection.  There may be from zero to four arguments (args).

     firstTrue: action [args...]
          Send the message action [args...] to each element of the
          collection in succession.  When an object replies a non-zero value
          to the message, firstTrue: returns the object ID of that object
          and does not send the message to any more objects.  Up to four
          arguments are allowed.

     allTrue: action [args...]
          Returns TRUE if all objects in the collection reply a non-zero
          value to the message action [args...], FALSE otherwise.  Up to
          four arguments are allowed.

     contains: anObject
          Returns TRUE if anObject is an element of the collection, FALSE
          otherwise.

     isEmpty:
          Returns TRUE if the collection has no elements, FALSE otherwise.

     first: (private)
          Returns a pointer to the kernel node kNode which has the 'first'
          object in the collection as its value.  The object can be obtained
          with the kernel call (NodeValue kNode).  Note that since there is
          no order associated with a collection, the object which will be
          returned by first is unspecified.

     next: kNode (private)
          Returns a pointer to the kNode following kNode.  As in first:, the
          object may be obtained with (NodeValue kNode).  Also as in first:,
          the lack of ordering in a Collection means that the object which
          will be returned is unspecified.  It is guaranteed, however, that
          it will not be an object which has been returned since the most
          recent call to first: (unless the object has been added to the
          Collection more than once -- see Set).  If all elements in the
          Collection have been returned since the last call to first:, 0 is
          returned.




                              The List Class

A List is just a Collection which has a specified order to its elements.

In file:            system.sc
Inherits from:      Collection
Inherited by:       Inventory
                    Set


Properties:


Methods:

     add: element [element ...]
          Adds elements to the end of the list in the order specified.

     first:
          Returns the kNode of the first element in the List.

     next: kNode
          Returns the kNode of the element which follows kNode in the List,
          0 if kNode is the end of the List.

     at: n
          Returns the element (not the kNode) at position n in the List.

     last:
          Returns the kNode of the last element in the List.

     prev: kNode
          Returns the kNode of the element preceding kNode in the List, 0
          if kNode is the first element of the List.

     addToFront: element [element ...]
          Add elements to the beginning of the List.

     addToEnd: element [element ...]
          Add elements to the end of the List.

     indexOf: element
          Return the index of element in the list.  If the element is not in
          the list, return -1.



                                  The Set Class

A Set is a kind of List which does not contain duplicate elements: adding an
object to a Set which already contains the object does not change the Set. 
The cast of an adventure game is a Set consisting of Actors and Egos (see
class descriptions below).

In file:            system.sc
Inherits from:      Collection
Inherited by:       none


Properties:


Methods:

     add: element [element ...]
          Adds each element to the set only if it is not already a member
          of the set.



                            The Inventory Class

The Inventory class is a List of all the objects (see the InvItem class)
which may be collected by ego in a game.  There are two steps to setting up
the inventory.

First, in the main header file for the game (typically game.sh), create an
enum statement listing all the symbols which you will use to refer to the
inventory items.  In order to avoid name conflicts, these are traditionally
the names preceded by an 'i': a rock might be referred to as "iRock".

Next, in the main game file (the file in which you define your instance of
Game), you create the instances of InvItem which are the inventory items. 
These are added to the Inventory (whose ID is in the global variable
inventory) in the init: of the game after the (super init:).  The InvItems
must be added to the inventory in the order in which they are listed in the
enum statement above (a block copy works wonders...).

From now on you may get the object ID of any InvItem with the at: method of
Inventory by using the symbol for the item defined in the enum statement: 
If you wanted to move the rock from its current position to room number 15,
you could write

          ((inventory at:iRock) moveTo:15)

The get:, put:, and has: methods of the Ego class use the enumed symbols
rather than the object ID.  Thus, to see if ego has the rock, you would
write

          (ego has:iRock)


In file:            invent.sc
Inherits from:      List
Inherited by:       none


Methods:

     showSelf: whom
          Display the items possessed by whom.  This is done by putting up a
          window with all currently possessed items in it.  By clicking the
          mouse on an item, the user may see a picture of it and receive a
          more detailed description of it.  Ego's possessions are done with

               (inventory showSelf:ego)

     saidMe:
          Return the object ID of the first item in the inventory whose said
          property matches what the user typed.



                             The Script Class

A Script is a kind of Object which has a state, methods to change that
state, and code to execute when the state changes.  It is used to model a
sequence of actions which should be executed by an object, such as an Actor
walking to the base of some stairs, walking up the stairs, and opening a
door.

In file:            system.sc
Inherits from:      Object
Inherited by:       none


Properties:

     client
          The object (a Prop, Actor, Ego, Room, etc.) whose Script this is. 
          Used to communicate with the Script's client.

     state
          The state of the Script.

     start
          The desired initial state of the Script.

     timer
          The ID of a timer which has been set to cue: the Script after a
          certain interval.


Methods:

     init: [client]
          Initialize the Script entering the initial state by doing a
          (self changeState:start).  Set the Script's client to client if
          present.

     changeState: newState
          Change the Script's state to newState.  This method is where to
          put the code to be executed on state transitions.  It should store
          the new state in the state property, then switch to the
          appropriate code based on the new state:

               (method (changeState newState)
                    (switch (= state newState)
                         transition code...
                    )
               )

     cue:
          Do a changeState: to the next state.  Default is to invoke       
          (self changeState:(+ state 1))

     handleEvent: event
          This method of an active script is called whenever there is an
          input event (see class Event).  If (event claimed:) is TRUE,
          someone else has already responded to the event.  Whether or not
          someone else has responded, if the Script responds to the event it
          should claim it by doing an (event claimed:TRUE).



                              The Timer Class

The Timer class implements the concept of an alarm clock, allowing you to
create an object which will cue: another object after a certain interval. 
Timers dispose: of themselves after cue:ing their client, and always check
to see if their client is still present before cue:ing it.

An important concept relating to Timers is that of game time versus real
time.  Real time is just what it sounds like -- real time in real seconds. 
Game time is time adjusted to the performance of the user's computer -- it
is the same as real time on a computer which is able to keep up with the
animation demands of the game, but slows down in proportion to the speed of
the user's computer when it is not able to keep up.

An example may help clarify this.  Say that you're writing a game in which
ego has only five seconds to leave a room before a bomb blows up.  If you
set this time interval as real time, it may give you just enough time to
get out on your nice fast 286 or 386 machine.  But on a Tandy 1000, where it
takes 1/5th of a second to complete an animation cycle instead of the
standard 1/10th of a second, the user will only be able to go half as far
and thus has no chance of leaving the room before the bomb blows.  The time
interval should really have been set in game time, which would have given
the user the same number of animation cycles to get out.

As a rule of thumb, time intervals which are meant to be a constraint on how
long the user has to do something should be set in game time, whereas time
intervals which are just meant to be a delay between two events should be
real time.  A user with a slow machine has no desire to watch a banner
screen twice as long as one with a fast machine.

In file:            system.sc
Inherits from:      Object
Inherited by:       none


Properties:

     client
          The object which the Timer will cue: at the end of its interval.

     cycleCnt
          The number of animation cycles remaining until the Timer cue:s its
          client.  This is used by Timers which are timing either animation
          cycles or game time.

     seconds
          The number of seconds remaining until the Timer cue:s its client. 
          This is used by Timers which are timing real time.

     lastTime
          Private.  Used by a timer timing real time.


Methods:

     set: who nSec [nMin [nHrs]]
          Create a timer to cue: who after a specified interval in game
          time.  Set it to cue: in nSec seconds.  nMin and nHrs are
          optional minutes and hours until the cue:.

     setReal: who nSec [nMin [nHrs]]
          Like set:, but the time interval is in real time.

     setCycle: who cycles
          Create a timer to cue: who after cycles animation cycles.

     delete:
          Private.  Does the actual deletion of a Timer.  You should use
          dispose:, which sets the Timer up for a delete: by the system
          later on.



                              The View Class

The View class contains the minimum functionality to put a visible object on
the screen in a reversible manner.  Thus, as a View, a particular view,
loop, and cel may be drawn on the screen and later erased.  A View, however
neither cycles (like a Prop) nor moves (like an Actor).

In file:            actor.sc
Inherits from:      Object
Inherited by:       Prop


Properties:

     x
     y
          The position of the View on the screen.

     view
          The number of the View's current view.

     loop
          The number of the View's current loop.

     cel
          The number of the View's current cel.

     priority
          The visual priority of the View.

     underBits
          A handle to the storage for saving the background of the View. 
          Don't monkey with this.

     nsTop
     nsLeft
     nsBottom
     nsRight
          The coordinates of the top, bottom, left, and right edges of the
          rectangle which encloses the current (nowSeen) cel of the View. 
          Don't monkey with this.

     lsTop
     lsLeft
     lsBottom
     lsRight
          The lastSeen rectangle for the View -- its nowSeen rectangle from
          the previous animation cycle.  Once again, do not touch.

     brTop
     brLeft
     brBottom
     brRight
          This is the base rectangle (or baseRect) -- the rectangle which is
          considered to be the base of the View for detecting collisions
          with it.  This you can monkey with.  The default for the base of
          a View is a rectangle whose left and right sides are the sides of
          the nowSeen rectangle, and whose bottom and top are the y
          coordinate of the View's origin.

     signal
          A bit-mapped word for communicating with the kernel animation
          routines and various methods.  Handles start- and stop- updating,
          fixed priorities, etc.  This property should not generally be
          manipulated directly -- the various methods (setPri:, setCel:,
          stopUpd:, etc.) should be used instead.


Methods:

     init:
          Sets the baseRect of the View and adds it to the cast so that it
          will be drawn on the screen at its current position.

     posn: x y
          Position the View at (x, y).

     stopUpd:
          This method sets the signal property to indicate to the
          interpreter that the image of the object on the screen is not to
          be updated anymore.  This is done to speed up program execution by
          reducing the number of things to be animated.

     startUpd:
          This undoes a previous stopUpd: of an View.

     forceUpd:
          This does a one-animation-cycle startUpd: of the View, making a
          change in the View's view, loop, cel, or position visible, but
          leaving it in a stopUpd: condition if it was so before.

     setPri: [newPri]
          This is used to set the priority of a View, based on the value of
          newPri.  Normally, a View is assigned a visual priority by the
          kernel based on its y position on the screen.  If a call to
          setPri: is made with no newPri specified, the priority is fixed at
          the current priority of the View.  If a value of newPri is
          specified, the priority is set to that value.  A newPri of -1 is
          used to undo a setPri:, returning control of the priority to the
          kernel.

     setCel: newCel
          Sets the cel of the View to newCel.

     setLoop: newLoop
          Sets the loop of the View to newLoop.

     ignoreActors: [n]
          If n is absent or TRUE, this allows the View's baseRect to
          intersect that of Actors.  If n is FALSE, the View's baseRect may
          not intersect that of any Actors -- the Actor will collide with it
          (unless the Actor has itself done an ignoreActors:).  The default
          state of a View is equivalent to ignoreActors:FALSE, i.e. an Actor
          may not intersect its baseRect.

     hide:
          Remove the View from the screen, but not from the cast.

     dispose:
          Tell the kernel to remove the View from the screen.  Also set a
          bit in signal to tell the main animation loop to remove this View
          from the cast after animation has been completed.

     delete:
          If the proper bit is set in signal, remove this View from the cast
          and do a (super dispose:).

     showStr: where
          Format a string describing the View in the storage pointed to by
          where.  This method gives classes inheriting from View the
          ability to inherit the View part of showSelf: rather than
          reimplement it.

     check: other
          This method is used to check for intersection of the baseRect with
          other.  It returns TRUE if the object does not intersect anything. 
          The method for a View or Prop always returns TRUE.

     handleEvent: event
          All elements of the cast get the handleEvent: message whenever a
          non-direction event is produced.  Only the User's alterEgo is sent
          direction events.

     addToPic:
          Add this View to the picture in an irreversible manner, then
          delete the View.



                              The Prop Class

Props are Views which can cycle but not move.

In file:            actor.sc
Inherits from:      View
Inherited by:       Actor


Properties:

     cycleSpeed
          The number of animation cycles between successive cels of the
          Prop.  Normally this is 0, meaning that the Prop cycles each
          animation cycle.  If you want the Prop to cycle more slowly, set
          this to a larger value.

     cycler
          This is the object ID of an instance of a Cycle class which
          determines the next cel to display for the Prop.  Don't modify it
          directly, but use the setCycle: method to install an instance of
          one of the cycling classes.  The object pointed to by this
          property is sent the message (cycler doit:) by the Prop each
          animation cycle.

     script
          The object ID of a Script associated with a Prop.  If a Prop has
          a script, it will be called with (script doit: self) by the doit:
          method of the Prop each animation cycle.

     timer
          The object ID of any timer which is set to cue: the Prop.


Methods:

     doit:
          If the Prop has a script, send it the message doit: self.  If the
          Prop has a cycler, send it the message doit:.

     cue: [newState]
          If the Prop has a script and newState is absent, cue: the script. 
          If newState is present, execute (script changeState:newState).

     setScript: script
          Sets a Prop's script to script and initializes the script.  Doing
          a setScript:0 disposes any current script without installing a new
          one.

     setCel: [newCel]
          Normally, the cel is set by the code pointed to by cycler. 
          Sending the setCel: message with no newCel specified overrides
          cycler and fixes the cel at its current value.  Sending a message
          with a value of newCel fixes the cel at that value.  A newCel of
          -1 returns control to cycler.

     setCycle: cycle [caller]
          Sets the Prop's cycler property to an instance of a Cycle class
          deleting any former instance.  Doing a setCycle:0 disposes any
          current cycle class without installing a new one.  The optional
          caller argument may be provided for Cycle classes which terminate,
          in which case the caller will be cue:ed when the Cycle terminates.



                              The Actor Class

The Actor class is the embodiment of an animated object.

In file:            actor.sc
Inherits from:      Prop
Inherited by:       Ego


Properties:

     xLast
     yLast
          The coordinates of the Actor's previous position.

     xStep
     yStep
          The x and y step sizes for the Actor.  Default is (= xStep 3) and
          (= yStep 2).

     heading
          The compass direction in which the Actor is headed.  North (toward
          the top of the screen) is 0, south 180.

     moveSpeed
          The number of animation cycles between motions of the Actor. 
          Normally this is 0, meaning that the Actor moves at each
          animation cycle.  If you want the Actor to move more slowly, set
          this to a larger value.  By playing with this and cycleSpeed, many
          strange effects may be discovered.

     illegalBits
          A bit-mapped word which specifies which controls an Actor CANNOT
          be on.  The low bit ($0001) corresponds to control 0 and the high
          bit ($8000) to control 15.  By convention, control 0 is generally
          accessible to all Actors, whereas control 15 is off-limits to all
          Actors -- thus, the default value of illegalBits is $8000.

     baseSetter
          The object ID of an instance of BaseSetter which is used to
          compute the base rectangle of the Actor.  The default for the base
          of an Actor is a rectangle whose left and right sides are the
          sides of the nowSeen rectangle, whose bottom is the y coordinate
          of the Actor's origin, and whose top is the Actor's yStep above
          the bottom.  This default is used if baseSetter is 0.

     mover
          The ID of an instance of a Motion class which is used to
          determine an Actor's path of motion.  Don't modify this directly,
          but use the setMotion: method to set the type of motion to be
          executed by the Actor.  The code pointed to by this property will
          be invoked with (mover doit: self) by the Actor in each animation
          cycle.

     looper
          The object ID of an instance of class DirLoop which sets the
          Actor's loop based on the direction in which it is headed.  The
          code is called with (looper doit: self theAngle) by the Actor
          during the initialization period of any setMotion:.  It uses the
          current position of the Actor and the direction in which the Actor
          is heading (theAngle) to determine which loop to display.  The
          default, which gets installed during the init: phase of an Actor,
          will handle virtually every case you'll encounter.

     viewer
          The object ID of an instance of class Code which sets the Actor's
          view.  This is used, for example, when an Actor should wade or
          swim when on certain controls.  The code pointed to by viewer is
          called with (viewer doit: self) and can test for the Actor being
          on a control and set the view accordingly.

     avoider
          The object ID of an instance of class Avoider.  If a moving Actor
          collides with something (control in the picture, another Actor,
          etc.) which prevents it from moving, the avoider attempts to find
          a way around it.


Methods:

     init:
          Does the usual setup for a Prop, sets looper to DirLoop, and sets
          avoider to an instance of class Avoider for all but ego.

     doit:
          If an Actor has any of the following, it invokes them in order: a
          script, a viewer, an avoider or mover (the avoider, if present
          will call the mover), and a cycler.

     setLoop: [newLoop]:
          Normally, an Actor's loop is set by invoking the looper method,
          which does so based on the Actor's direction.  Sending the
          setLoop: message with no argument fixes the loop at its current
          value.  If newLoop is present, the loop is set to its value.  If
          the newLoop is -1, loop determination is returned to the looper
          method.

     ignoreHorizon: [n]
          If n is absent or TRUE, this allows the Actor to be above the
          current Room's horizon.  If n is FALSE, the Actor will not be
          allowed to go above the horizon of the current Room and will be
          repositioned to the horizon if an attempt is made to position it
          there.  The default state of an Actor is equivalent to
          ignoreHorizon:FALSE.

     setMotion: motion [caller]
          Sets the Actor's motion property to an instance of a Motion class,
          deleting any former instance.  Doing a setMotion:0 disposes any
          current motion without installing a new one.  The optional caller
          argument is the object to be cue:ed when the motion is completed.

     setAvoider: avoider
          Set the Actor's Avoider to avoider.  To remove an Avoider from the
          Actor, do a setAvoider:0.

     isStopped:
          Return TRUE if the Actor is in the same position as it was during
          the previous animation cycle, FALSE otherwise.

     isBlocked:
          Returns TRUE if the Actor tried to move, but was unable to because
          of something blocking it.  If this is TRUE, the avoider will
          generally be invoked.

     canBeHere:
          Return TRUE if the Actor can be in its current position, FALSE
          otherwise.  This checks to see whether the Actor's baseRect is on
          any illegal controls (specified by illegalBits), whether it has
          collided with a View, Prop, Actor or Ego, and whether it has
          collided with one of the Room's SoftBlocks.  In any of these
          cases, FALSE will be returned.

     findPosn:
          Reposition the Actor until canBeHere: returns TRUE.  This is
          called whenever canBeHere: returns FALSE during animation.  It
          searches in concentric rectangles outward from the Actor's
          position for a legal position.

     check: other
          Check to see if the Actor's baseRect intersects that of other. 
          Return TRUE if it does not, indicating that the Actor has not
          collided with other.

     distanceTo: anObject
          Returns the distance (in pixels) to anObject (which had better
          have x and y properties).  [Note: this is the real distance, not
          the kludge used in the previous interpreter.  Because this uses
          the square-root function, it is slow -- don't use it 100 times per
          animation cycle, or you'll notice a degradation in performance.]

     inRect: left top right bottom
          Returns TRUE if the Actor's x and y are within the bounding
          rectangle, FALSE otherwise.

     onControl: [origin]
          Returns a bit-mapped word (mapped like the illegalBits property)
          indicating which controls the baseRect of the object encloses. 
          If the optional origin argument is used (just use the word
          "origin"), the control under the x, y coordinate of the object is
          returned.



                               The Ego Class

The Ego class is the class of Actors which can be controlled by a User.

In file:            actor.sc
Inherits from:      Actor
Inherited by:       none


Properties:

     prevDirKey
          The key pressed by the User to start the Ego moving in its current
          direction.  This property is needed to implement the "press the
          same key a second time to stop" control of an Ego, and set to -1
          when a joystick or mouse starts the motion.

     edgeHit
          This property is set to the edge of the screen which the Ego has
          moved off of, or to 0 if the Ego is still on the screen.  The
          edges are NORTH, SOUTH, EAST, and WEST.


Methods:

     init:
          Does the standard Actor init:, then a (self setCycle:Walk).

     doit:
          This just passes the doit: message along to the Actor doit:, then
          sets edgeHit based on where the Ego is on the screen.

     get: item [item ...]
          Make the Ego the owner of items.

     put: item [where]
          Assuming that the Ego is the current owner of item, if where is
          specified, it is made the owner of item.  Otherwise, the item is
          put in "limbo" (equivalent to a where of -1).

     has: item
          Return TRUE if the Ego is the current owner of item, otherwise
          FALSE.



                             The PicView Class

Objects of class PicView keep information on Views which have been added to
the picture with addToPic: so that they will be present in a restored game.

In file:            actor.sc
Inherits from:      Object
Inherited by:       none


Properties:

     view
     loop
     cel
     x
     y
     priority
     signal
          The values of the corresponding properties in the View which was
          the progenitor of this PicView.


Methods:

     init:
          Add this PicView to the picture.  Used by restoreGame:.



                            The Cycling Classes

The Cycle class is the basic class which implements cycling behavior in
Actor and its sub-classes.  Sub-classes of Cycle implement specific cycling
behavior.


                                   Cycle

In file:            motion.sc
Inherits from:      Code
Inherited by:       Forward
                    Reverse
                    CycleTo



Properties:

     caller
          The object to be cue:ed when the Cycle completes.

     client
          The Prop, Actor, etc. which is being cycled by an instance of
          Cycle.

     cycleDir
          The direction in which the client's cels are to be cycled.
               1    forward (cel numbers should increase)
               -1   backward (cel numbers should decrease)

     cycleCnt
          The number of animation cycles since the current cel of the client
          was displayed.  When this equals the cycleSpeed of the client, the
          nextCel: method is invoked.


Methods:

     init:
          Do any necessary initialization of the Cycle class and ensure that
          the client is updating.

     doit:
          Called by the client as doit: self, this method sets the cel of
          the client to the appropriate value based on the particular Cycle
          class.

     nextCel:
          Used by the doit: method to move the cel number in the direction
          indicated by cycleDir.

     cycleDone:
          This is invoked when the client's cel reaches a destination cel. 
          If the Cycle class is one of the cyclic ones, this just wraps the
          cel to either the beginning or end of the current loop.  If it is
          a terminating Cycle class, this cue:s the caller.



                                  Forward

Cycles an Actor through its cels in the 'normal' order -- from 0 through the
end of the loop and back to 0.  Set with (actor setCycle:Forward).

In file:            motion.sc
Inherits from:      Cycle
Inherited by:       Walk



                                   Walk

This is a Forward cycle type which only cycles an Actor when the Actor is
moving.  Set with (actor setCycle:Walk).

In file:            motion.sc
Inherits from:      Forward
Inherited by:       none



                                  Reverse

Cycles an Actor through its cels in the reverse order of that in Forward,
i.e. from the highest cel number to 0 and then repeating.  Set with
(actor setCycle:Reverse).

In file:            motion.sc
Inherits from:      Cycle
Inherited by:       none



                                  CycleTo

This class allows you to cycle to an arbitrary cel and stop.  It is set by
(actor setCycle:CycleTo toCel direction [caller]).  

In file:            motion.sc
Inherits from:      Cycle
Inherited by:       EndLoop
                    BegLoop


Properties:

     endCel
          The number of the cel at which the cycling is to complete.



                                  EndLoop

This sub-class of CycleTo advances the cel of an Actor from the current cel
to the cel which is the end of the current loop for the Actor, then stops
and cue:s its caller (if it has one).  Set with
(actor setCycle:EndLoop [caller]).

In file:            motion.sc
Inherits from:      CycleTo
Inherited by:       none



                                  BegLoop

This sub-class of CycleTo decrements the cel number from its current value
to 0, then stops and cue:s its caller, if any.  Set with
(actor setCycle:BegLoop [caller]).

In file:            motion.sc
Inherits from:      CycleTo
Inherited by:       none




                            The Motion Classes

The sub-classes of class Motion implement the various kinds of motion which
Actors can execute.



                                  Motion

The Motion class is the basis for all the specialized motions.  If a caller
is specified in the setMotion: for a motion, it will be notified of the
motion's completion by being sent the cue: message.

In file:            motion.sc
Inherits from:      Object
Inherited by:       MoveTo
                    Wander
                    Chase
                    Follow


Properties:

     x
     y
          The coordinates towards which the Actor is moving.

     client
          The Actor being moved by the instance of motion.

     caller
          The object to cue: when the motion is complete.

     dx
     dy
     b-moveCnt
     b-i1
     b-i2
     b-di
     b-xAxis
     b-incr
          These properties are used internally by the modified Bresenham
          line algorithm which moves the Actors.


Methods:

     moveDone:
          Executed when the motion completes or is blocked.  Cue:s the
          caller, if there was one, and dispose:s of the motion class.



                                  MoveTo

The MoveTo class just moves an object to a particular position.  An Actor is
moved to a position with (actor setMotion: MoveTo x y [caller]).

In file:            motion.sc
Inherits from:      Motion
Inherited by:       none



                                  Wander

The Wander motion class implements a random wander for Actors.  It is
invoked for an Actor by (actor setMotion: Wander [distance]) where the
optional argument, distance, is the maximum distance of a leg of the wander
(default is 20 pixels).  This motion never completes -- the Actor will keep
wandering until a new motion type is set.

In file:            motion.sc
Inherits from:      Motion
Inherited by:       none


Properties:

     distance
          The maximum distance to be wandered on a given leg of the wander.



                                  Follow

This class is for making one Actor follow another.  It is invoked for an
Actor with (actor setMotion: Follow anotherActor [distance]), where
anotherActor is the Actor to be followed and the optional distance specifies
how closely to follow.  If actor is further from anotherActor than distance,
it will start moving towards anotherActor.  Otherwise it will stop moving. 
The default distance is 15 pixels.  As for Wander, this motion never
completes.

In file:            motion.sc
Inherits from:      Motion
Inherited by:       none


Properties:

     who
          The ID of the Actor being followed.

     distance
          The distance to try and maintain from the Actor specified by who.




                                   Chase

This class implements the concept of trying to catch another Actor.  It is
invoked with (actor setMotion: Chase anotherActor distance [caller]).  As in
Follow, anotherActor is the Actor to chase.  Distance is the distance from
anotherActor at which it is considered to be caught.  When anotherActor has
been caught, caller is cue:ed.

In file:            motion.sc
Inherits from:      Motion
Inherited by:       none


Properties:

     who
          The ID of the Actor being chased.

     distance
          The distance from who at which who is considered caught.



                             The Avoider Class

The Avoider class is a class which helps Actors get around obstacles.  If
an Avoider is installed in avoider in an Actor, it gets called instead of
the usual motion class when it is time to move the object.  The Avoider then
calls the motion and checks to see if the Actor was able to move.  If the
Actor is blocked by something ((client isBlocked:) is TRUE), the Avoider
takes over and attempts to get around whatever is blocking the Actor.  In
some cases it looks really smart, in others astoundingly stupid.  As we work
on it, it should get better.

In file:            motion.sc
Inherits from:      Object
Inherited by:       none


Properties:

     client
          The Actor to whom this Avoider is assigned.

     heading
          The direction (clockwise or counter-clockwise) in which the
          Avoider turns while trying to get around the obstacle.  This is
          picked randomly when the Actor first encounters the obstacle and
          remains constant as long as the Avoider is in control.  The
          Avoider attempts to get around the obstacle by turning in 45
          degree increments in the chosen direction until it is able to
          move.



                              The Event Class

The Event class is the class of user input events (key presses, mouse
clicks, etc.)

In file:            system.sc
Inherits from:      Object
Inherited by:       none


Properties:

     type
          The kind of input event.  The event types are defined in
          kernel.sh:
               mouseDown
                    Mouse button was pressed.
               mouseUp
                    Mouse button was released.
               keyDown
                    Key was pressed.
               keyUp
                    Key was released.
               direction
                    A direction event, meant to move the player.
               saidEvent
                    User typed a line of input, which has been parsed.
               menuStart
               menuHit

     message
          The 'value' of the event.  For a key, this is the ASCII value
          corresponding to the key which was pressed.

     modifiers
          Bit-mapped property containing any modifier keys which were down
          when the event occurred.  Bits are shiftDown, ctrlDown, and
          altDown.

     x
     y
          The coordinates of the mouse when the event occurred.

     claimed
          TRUE if some object has already responded to the event, FALSE
          otherwise.  You should set the claimed property of the event to
          TRUE whenever you respond to an event.  In general, you will not
          want to respond to an event whose claimed property is TRUE
          (although there may be exceptions), so you'll want to test its
          value before doing anything based on the event.


Methods:

     new:
          If an input event is in the event queue, return it.  Otherwise,
          return 0.




                              The User Class

A User is an object which corresponds to the person playing the game and
acts as the intermediary between the person and the other objects in the
game.  In the current games there is only one User, and thus we use the
class User rather than an instance of the class.

In file:            user.sc
Inherits from:      Object
Inherited by:       none


Properties:

     alterEgo
          The ID of the Ego which is controlled by the User.

     canInput
          TRUE if the User should accept input lines from its player, FALSE
          otherwise.  Any time you don't want the player to be able to type
          an input line, just set canInput to FALSE.  Default at startup is
          FALSE.

     canControl
          Set to TRUE to let the User control the alterEgo with direction
          keys, mouse, etc.  Anytime you want to set the alterEgo on a pre-
          programmed motion, set canControl to FALSE to prevent the player
          from interrupting the motion and taking control.  Default at
          startup is FALSE.


Methods:

     doit:
          The doit: method for User checks for an event.  If one is present, 
          User sends the handleEvent: event message in succession to
          TheMenuBar (the game's menu bar), alterEgo, and regions (the list
          of regions, beginning with the current room).  If any of these
          objects respond to the event, they should set the claimed property
          of the event to TRUE to let the other objects receiving the event
          know that it has been dealt with.

          If, after everyone has had a look at it, the event is still
          unclaimed, User puts up an input line and waits for the player to
          type a line of input.  If a line is entered and the kernel is able
          to parse the line, the User turns the event into a saidEvent,
          indicating that valid input has been entered, and again sends the
          handleEvent: event message to the above objects.  Once it has done
          so, it disposes of the event and returns.



                              The Game Class

The Game class implements the game which is being written.  The game author
creates a source file with script number 0 which contains the instance of
the class Game which is the game.  This instance is where, for example,
input not handled by any Actor, Room, Region, etc. will be handled.  

In file:            game.sc
Inherits from:      Object
Inherited by:       none


Properties:

     score
          The user's current score.

     possibleScore
          The maximum number of points possible in the game.

     speed
          The number of timer ticks (1/60th of a second) between animation
          intervals.  Don't set this directly -- use changeSpeed:.

     timers
          A Set of the currently running Timers.  The doit: method of the
          Game is what runs the timers.


Methods:

     play:
          Your game is started by the kernel issuing the play: message to
          the object whose ID is in entry 0 of script.000.  The play:
          method, as defined in the Game class, is basically

               (self init:)
               (while (not quit)
                    (self doit:)
                    (Wait speed)
               )

     init:
          Initializes the game, setting up some global variables and
          initializing the menu and inventory.

     doit:
          This method is invoked once per animation cycle and passes the
          doit: method along to the rest of the game.  It is responsible for
          changing rooms when a newRoom: has been done by the current Room.

     newRoom: n
          Make room number n the current room.  This should not be called
          directly from user code.  This method deletes the cast and the old
          Room from the heap, then invokes the startRoom: method to load
          and initialize the new Room.

     startRoom: n
          Load and initialize room number n.  When this method is invoked,
          the heap has been cleaned up from the previous room.  Reimplement
          this to load any Regions which will span several Rooms and create
          heap fragmentation problems.  Loading such regions below the Rooms
          lets them stay in the heap without fragmenting it.

     changeScore: n
          Add the number n (which may be negative) to the user's current
          game score.  If the StatusLine is being displayed, update the
          score shown there.

     handleEvent: event
          After passing an event to the MenuBar and the cast, the User class
          sends the handleEvent: event message to the game, which in turn
          sends it to the regions.  This method may be modified in the game
          instance to do a (super handleEvent:event) followed by processing
          to handle unclaimed events by printing an "I don't understand you"
          message.

     setSpeed: n
          Set the number of timer ticks (1/60th of a second) between
          animation cycles to n.  This also resets any Timers in the timers
          Set to account for the change in speed.

     restart:
          This restarts the game at the beginning, allowing the user to
          start again without rebooting the game.

     save:
          Saves the current state of the game to disk, allowing the user to
          quit the game and restart at the same point later using restore:. 
          Not implemented.

     restore:
          Restores a saved game state.  Not implemented.

     showMem:
          Displays the amount of memory remaining in heap and hunk space.



                             The Region Class

A Region is an area of a game which is larger than a Room (see below) -- for
example a forest, island, or a planet.  It is used to provide standard
behavior (i.e. responses to user input) in an area of the game without
having to code the behavior into each room in the region.  For example in
Space Quest, we might define the town of Ulence Flats and the planet of
Kerona as regions.  The Ulence Flats region would be used to handle the
response to 'look city' while in the town, whereas the Kerona region would
handle the response to 'look sky'.  Regions take the place of the 'dynamic
logics' of the AGI interpreter.


In file:            game.sc
Inherits from:      Object
Inherited by:       Room


Properties:

     script
          The ID of a Script for the current room.

     number
          The region number.  Set by the setRegions: method discussed in
          class Room below, it is used when we dispose the region.

     timer
          The ID of a Timer set to cue: this Region.

     keep
          Set this to TRUE if you want the Region to remain in the heap
          through a newRoom:, to FALSE if you want the Region unloaded.

     initialized
          This property is set to TRUE when the Region is sent the init:
          message after a setRegion: involving it has been done.  The init:
          method is not invoked once initialized is TRUE, so a Region will
          only be initialized once for the Rooms which require it.


Methods:

     init:
          When a Region is added to the region list regions by the
          setRegions: method discussed in the class Room below, it is sent
          the init: message in case any setup is needed.  The default init:
          method does nothing.

     doit:
          Each active Region is sent the doit: message in each animation
          cycle.  The default method passes the doit: message along to the
          script, if there is one, but does nothing else.

     handleEvent: event
          The default method for this sends handleEvent: event to the
          Region's script, if there is one.  You may handle events either in
          the Region itself or its script.  Remember that in general you
          will not want to handle an event which is claimed, and that you
          should set the claimed property of the event to TRUE if you
          respond to it.

     setScript: script
          Set the script of the Region to script and init: it.

     cue: newState
          Cue this Region's script.  If the optional newState is present,
          invoke (script changeState:newState) instead.



                              The Room Class

The Room class is the most specific Region.  It is the point at which a
picture, or 'scene' is defined for the player to walk around in.

In file:            game.sc
Inherits from:      Region
Inherited by:       none


Properties:

     picture
          The number of the picture corresponding to the room.  Usually,
          this will just be the room number.

     style
          If style is specified, it overrides the global showStyle when
          picture is drawn during the Room's init:.  Any other picture drawn
          once the Room is running must have its show style explicitly
          specified.

     horizon
          The y coordinate which is considered to be the room's horizon. 
          Actors which have not had an ignoreHorizon: done on them cannot be
          positioned above this coordinate.  Also, an Ego which hits this
          coordinate will have its edgeHit property set to northEdge.

     blocks
          A Set of software blocks (SoftBlocks), rectangles which Actors are
          not allowed to enter.

     north
     east
     south
     west
          The number of the room to which you wish to automatically change
          when ego hits the specified edge of the room.  If you wish to
          control the room change yourself when ego hits a certain edge, do
          not specify the room for that edge in the Room instance and check
          (ego edgeHit?) yourself.  The edgeHit property will have the value
          northEdge, southEdge, eastEdge, or westEdge if ego hit one of the
          edges.

     controls
          A set of dialog items (DItems) which are push-buttons for this
          room.


Methods:

     init:
          The default init: for a Room is to create an empty Set of
          SoftBlocks, draw the picture specified by picture, and set ego's
          position based on its position in the previous room.  You will
          want to supplement this with the following:

               Load all views, sounds, pictures, etc. which will be required
                    by the room so as to get all disk access done at Room
                    initialization time.
               Initialize all Actors and Actors which are to be in the Room
                    initially.
               Set a script for the Room.
               Add any required SoftBlocks to the Room.

     doit:
          Send the doit: message to this Room's script, if it has one, then
          check to see if ego has hit the edge of the Room.  If ego has hit
          an edge and there is a room number specified for the edge, invoke
          the newRoom: method to change to that room.

     dispose:
          This is called by the game when changing from this Room to a new
          Room.  The game handles disposing of the current cast, then does a
          (curRoom dispose:).  The default dispose: simply disposes of the
          Room's script, blocks, and controls.  You will want to supplement
          this to dispose: of anything else which you have created which is
          specific to the Room, and any modules which the Room has loaded.

     setRegions: region [region ...]
          Sets the Regions which contain this room.  This should be invoked
          in the init: method of the room. The parameters region are the
          script numbers of the regions.  They should be listed from most
          specific to most general, since the order in which they are listed
          is the order in which they will be invoked.  Thus, for a room in
          Ulence Flats in Space Quest, we might write

               (self setRegions: ULENCE_FLATS KERONA)

          to say that we are in the town of Ulence Flats on the planet
          Kerona.

          The global variable regions contains the ID of a List of regions
          which are sent the doit: and handleEvent: messages in order when
          appropriate.  The newRoom: method of Game puts the current room at
          the head of this list, and setRegions: adds Regions to the end of
          the list in the order in which they are listed in the parameter
          list.  If the Region was used in the previous Room, it will be
          neither reloaded nor reinitialized.  At the end of the newRoom:
          method, all Regions in the list which do not refer to the current
          Room are deleted.

     handleEvent: event
          The default Room method passes the event along to the Room script
          (if there is one) and then to any controls in the room.

     newRoom: n
          This method is the one to use when changing Rooms.  It is invoked
          when the Room automatically changes to a new Room when ego hits
          the edge.  Reimplement this method if you need to do some
          processing (such as dispose:ing a Region) before changing rooms.



                              The Timer Class

The Timer class implements the concept of an alarm clock -- you can set it
to cue: an object at some future time.

In file:            system.sc
Inherits from:      Object
Inherited by:       none


Properties:

     cycleCnt
          The interval to be timed measured in animation cycles.  This is
          set by the set: and setCycle: methods, and should not be
          manipulated directly.

     seconds
          The interval to be timed measured in seconds.  This is set by the
          setReal: method and should not be manipulated directly.

     lastTime
          Used internally when timing seconds.

     client
          The object to cue: when the timer goes off.


Methods:





                             The InvItem Class

InvItems are the items which ego can gather and use as he moves through the
game.  As described in the description of the Inventory class, they are
generally referred to by their position in the Inventory list rather than by
their object ID (which is not known in all modules).

In file:            invent.sc
Inherits from:      RootObj
Inherited by:       none


Properties:

     name
          The string which is the InvItem's name.  This is what will be
          shown in the inventory window if you do an
          (inventory showSelf:ego) and ego has the item.

     said
          A said-string describing the way in which the User may refer to
          the item.

     description
          The description of the object to be displayed if the User clicks
          the mouse on the item's name in the inventory window.

     view
     loop
     cel
          The view, loop, and cel to be displayed for the item if the User
          clicks the mouse on the item's name in the inventory window.

     owner
          The current 'owner' of the item.  This is either a room number
          (the item is in the room) or an object ID of an Ego (the Ego
          possesses the item).

     script
          The object ID of a Script for the item.  This can be used to keep
          track of the state of a changeable item and to change the view,
          loop, cel, and description of the item.  Thus, an electronic
          device might have the following script attached to it:

               (instance deviceScript of Script
                    (method (changeState newState)
                         (switch (= state newState)
                              (deviceOn
                                   (client
                                        description:"The device is on."
                                        cel:0
                                   )
                              )
                              (deviceOff
                                   (client
                                        description:"The device is off."
                                        cel:1
                                   )
                              )
                         )
                    )
               )

          Thus, in response to user input of 'turn device on', you can write

               ((inventory at:iDevice) changeState:deviceOn)


Methods:

     saidMe:
          Return TRUE if the user input referred to this item, FALSE
          otherwise.

     ownedBy: whom
          Return TRUE if the item is owned by whom (either a room number or
          an object ID), FALSE otherwise.

     moveTo: whom
          Set the item's owner to whom (either a room number of object ID).

     showSelf:
          Display the item's view, loop, cel, and description in a window.

     changeState: newState
          Send the changeState:newState message to the item's script.



                            The SoftBlock Class

The SoftBlock class implements ability to keep Actors out of certain areas
on the screen without controls being added to the picture.  In particular
they are the only way of preventing an Actor who is allowed to have his
baseRect off the bottom of the screen from walking into something, since the
Actor's baseRect will not encounter any blocking controls.

In file:            game.sc
Inherits from:      Object
Inherited by:       none


Properties:

     active
          Set to TRUE if the SoftBlock is active, FALSE otherwise.  Actors
          can move into inactive SoftBlocks.

     top
     bottom
     left
     right
          The bounding coordinates of the SoftBlock rectangle.


Methods:
     
     init:
          Add the SoftBlock to the set of blocks for the current room and
          enable the SoftBlock.

     doit: actor
          Return TRUE if actor is outside of the SoftBlock (and is thus in a
          legal position) or FALSE if it is inside the SoftBlock (and thus
          must be moved out).  This is called in each Actor's canBeHere:
          method.

     dispose:
          Delete the SoftBlock from the set of blocks for the current room
          and dispose of it if it is a dynamic instance.

     enable:
          Set the active property of the SoftBlock to TRUE, so that Actors
          cannot enter it.

     disable:
          Set the active property of the SoftBlock to FALSE, so that Actors
          can enter it.




                              The Sound Class

This is the class which allows sound to be played.

In file:            game.sc
Inherits from:      Object
Inherited by:       none


Properties:

     done
          Set to TRUE after the sound has finished playing, FALSE while it
          is playing.

     number
          The number of the sound.

     priority
          The priority of the sound if multiple sounds are playing.  Most
          sound effects should have the default priority of 0.  More
          important sounds (say an error beep) should have positive
          priorities -- the more important the higher the priority.  Less
          important sounds (background music) should have negative
          priorities.  This will allow sound effects to override background
          music (which will resume at the appropriate point) and error beeps
          to override sound effects.

     signal
          This is a bit-mapped property used to set characteristics of the
          sound.  Its bits are defined in base.sh.  Only one bit,
          blockingSnd, is currently defined.  When it is set, the sound
          blocks when it is playing -- all game play stops until the sound
          is complete.  Sampled sound effects are blocking sounds by
          default, and needn't have this bit set.


Methods:

     init:
          Initialize the sound and set any appropriate bits in signal to
          indicate the sound's nature.

     play:
          Start the sound playing and add it to sounds, the list of sounds
          which are playing.

     dispose:
          Stop the sound.




                           The StatusLine Class

The StatusLine class provides a status line at the top of the screen which
is programmer-definable.  When enabled, it overlays the menu bar.  The user
may still access the menu by pressing Esc or positioning the mouse pointer
in the status line end pressing the mouse button.  The status line usually
shows the player's score.  To use a status line in a game, create an
instance of class Code which has the interface described in code below and
set the code property of StatusLine to it.  To display the status line,
execute (StatusLine enable:).

In file:            game.sc
Inherits from:      Object
Inherited by:       none


Properties:

     state
          Whether or not the status line is being displayed.  Do not
          manipulate this directly.

     code
          An instance of Code which formats the status line.  It will be
          called from StatusLine's doit: method with a pointer to string
          storage as a parameter:

               (code doit: @theLine)

          The code should format the status line into the provided string.


Methods:

     doit:
          Format the status line and display it if it has been turned on.

     enable:
          Turns the status line on.  Invokes the doit: method.

     disable:
          Turns the status line off.  Invokes the doit: method.



                              The File Class

The File class allows you to open and write to a file on disk.  This is
useful for logging user input for which you have no response in the
development or beta-test phase, writing utilities which allow you to
position Actors on a picture and then write out the coordinates, etc.

In file:            file.sc
Inherits from:      Object
Inherited by:       none


Properties:

     name
          The name of the file.  Defaults to "gamefile.sh".

     handle
          The handle by which the operating system refers to the opened
          file.  Don't monkey with this, or you may blow away the OS.


Methods:

     open: [flag]
          Open the file whose name is name for writing.  The optional
          parameter flag may be either fAppend, in which case writing
          begins at the end of an existing file, or fTrunc, in which case
          the contents of the file are deleted before writing to it.  If
          flag is not present, fAppend is assumed.

     write: str [str ...]
          Write the strings pointed to by str to the file.

     close:
          Close the file.



                              The Code Class

The class Code encapsulates the concept of a subroutine into an object which
can be executed or passed to an object for execution.

In file:            system.sc
Inherits from:      Object
Inherited by:       none


Properties:


Methods:

     doit: [args...]
          The doit: method of a Code object is the code to be executed.  Any
          number of arguments is allowed.



                             Global Variables
Global variables 0 through 49 are reserved for use by the system classes. 
Game-specific global variables start at 50.  The following global variables
are defined by the system.

ego
     The ID of a static instance of class Ego defined in game.sc.  This is
     the protagonist of the game.

curRoom
     The ID of the current Room.

userFont
     The number of the font to be used in Print statements, etc.  Default is
     1.  Set it to the font you wish to use in the init: method of your
     Game, or change it at will in the game.

cast
     The ID of a Set of Actors and Egos which constitutes the characters on
     the screen.

quit
     The main loop of the game is

          (while (not quit)
               (theGame doit:)
               (Wait speed)
          )

     so setting quit to TRUE breaks out of the main loop and terminates the
     game.

addToPics
     A Set of PicViews which have been added to the current picture.

debugOn
     A generic debugging flag.  I usually have a Debug menu item to set it,
     and trigger any debug display that I want off of it, rather than
     creating a special trigger whenever I want to debug something.

sounds
     The Set of Sounds currently playing.

inventory
     The ID of the Inventory class or instance which is the Set of all
     InvItems (inventory items) in the Game.  Inventory related issues are
     not well defined yet...

theGame
     The ID of the Game instance.

regions
     The Set of Regions currently in effect.

curRoomNum
     The number of the current Room.

prevRoomNum
     The number of the previous Room.  (So you know how you got where you
     are.)

newRoomNum
     Used by a Room to signal to the Game that it should change to a new
     Room.

showStyle
     The global style for the transition from one picture to another.  This
     may be overridden by the style property of a given room.  See the
     DrawPic kernel function for the possible styles.

overRun
     The number of timer ticks more than the Game's speed which it took to
     complete the last animation cycle.  A non-zero overRun means that the
     system is not keeping up.







                      The Script Programming Language
							 ===============================

                               Introduction



The Script adventure game language is an object-oriented language with a
Lisp-like syntax.  It is compiled by the sc compiler into the pseudo-code
which is used by the interpreter, sci.

We will begin our discussion of the language with its basic Lisp-like
characteristics, then go on to the object-oriented parts of the language.

As is Lisp, Script is based on parenthesized expressions which return
values.  An expression is of the form

     (procedure [parameter parameter ...]).

The parameters to a procedure may themselves be expressions to be
evaluated, and may be nested until you lose track of the parentheses.

Unlike Lisp, the procedure itself may NOT be the result of an evaluation. An
example of an expression is

     (+ (- y 2) (/ x 3))

which would be written in infix notation as

     (y - 2) + (x / 3).


All expressions are guaranteed to be evaluated from left to right.  Thus,

     (= x 4) 
     (= y (/ (+= x 4) (/= x 2)))

will result in y = 2 and x = 4.


Comments in Script begin with a semi-colon, ';', and continue to the end of
the line.


                         Files


Source files for the script compiler have the extension .sc, header
(include) files have the extension .sh.  Source files may have any filename
-- banner.sc and castle.sc are two examples.  The output file from the
compilation will have the name script.nnn where nnn is determined from the
script# command (covered below) which is present in the file.

There are six files besides the source file and any user-defined header
files which are involved in a compilation.

classdef
     This file contains the information about the structure of the classes
     which have been defined in the application.  It is read automatically
     by the compiler and is rewritten by the compiler after a successful
     compilation in order to keep it up to date.  The user need not be
     concerned with it.

selector
     This contains definitions of selectors which are used in object-
     oriented programming.  It is automatically included in a compile and,
     like classdef, is rewritten after a successful compile.  Any symbol in
     a properties or methods statement or in the selector position in a send
     to an object is assumed to be a selector and is assigned a selector
     number in included in selector.

kernel.sh
     This contains the definitions for interfacing with the kernel (the
     machine language interpreter).  It is maintained by the kernel
     programmers and is automatically included in system.sh.

system.sh
     This contains the definitions for interfacing with the various system
     classes.  It is initially provided by the kernel programmers.  If you
     wish to tweak the system scripts yourself, you will also be
     responsible for maintaining your copy of system.sh.  It should be
     included in all compiles.

vocab.000
     This is the compiled output of vocab.txt, generated by the vocabulary
     compiler vc.  It is automatically included in a compile.

classtbl
     This is an output file of the compiler which is used by the kernel to
     determine which script a given class is defined in.  You needn't do
     anything to it other than not delete it.



There are two sc commands for dealing with source code organization:

script#:

The script# command sets the script number of the output file:

     (script# 4)

sets the output file name to script.004, regardless of the actual name of
the source file.

include:

This includes a header file in the current source file at the current
position.

     (include "/sc/foo.sh")
or
     (include /sc/foo.sh)

include the file /sc/foo.sh.  Include files may be nested as deeply as
desired.

When including a file, the compiler first looks for the file in the current
directory.  If it fails to find it there, it then looks for it in the
directories specified in the environment variable SINCLUDE.  This variable
is just like the DOS PATH variable -- the directories to search are
separated by semi-colons.  Thus, if you want the compiler to look for
include files in f:/games/sci/system and c:/include if it doesn't find them
in the current directory, you put the line

     set sinclude=f:/games/sci/system;c:/include

in your autoexec.bat file.


     Definitions


define:

The define statement allows you to define a symbol which will stand for a
string of text:

     (define symbol lots of text)

will replace symbol, wherever it is encountered as a token, with lots of
text and then continue scanning at the beginning of the replacement text. 
Thus, if we write

     (define symbol some text)
     (define some even more)

then

     (symbol)

will become

     (some text)

which then becomes

     (even more text)


enum:

A construct for easing the definition of various states of a state-variable
is enum.  Say you want to walk an actor from the door of a room across the
floor, up the stairs, and through another door.  You have a state-variable
called actor-pos which will take on a number of values, which could be
defined with defines:

     (local    actor-pos
          (define at-front-door    0)
          (define in-room          1)
          (define on-stairs        2)
          (define top-of-stairs    3)
          (define upper-door       4)
     )

or you could get the same result with enum:

     (local    actor-pos
          (enum
               at-front-door
               in-room
               on-stairs
               top-of-stairs
               upper-door
          )
     )

Enum defaults its first symbol to 0.  If you want a different starting
value, put it right after the word enum:

     (enum 7
          at-front-door
          in-room
          on-stairs
          top-of-stairs
          upper-door
     )

sets at-front-door to 7, in-room to 8, etc.


synonyms:

The synonyms statement defines synonyms of words.  All words must have been
defined in the vocabulary file (see separate Vocabulary documentation).  The
statement

     (synonyms
          (main-word  synonym1 synonym2 ...)
          ...
     )

defines the words synonym1, synonym2, etc. to be synonyms of main-word.  In
input being interpreted by the script in which the synonym statement is
defined, user input of synonym1 will be interpreted as if the user had typed
main-word.



                        Data Types and Variables

Numbers:

All numbers in Script are 16 bit integers, giving a range of -32768 to
+32767.   Numbers may be written as decimal (1024), hex ($400), or binary
(%10000000000).


Variables:

Variables hold numbers.  Variables can be either global, local, or
temporary, depending on when they are created and destroyed:

Global variables are created when the program starts and destroyed when it
     ends, and are thus accessible to all scripts at all times.

Local variables are created when a logic script is loaded and destroyed
     when it is purged.  They are thus only available when the logic script
     is loaded and will not retain a value through a purge-reload cycle. 
     You will find that, as your programming takes on a more object-oriented
     flavor, you will use fewer and fewer local variables.

Temporary variables are created when a procedure or method is entered and  
     destroyed when it is left.  They are thus only available to the       
     declaring procedure and do not retain a value between calls to the
     procedure. 

In order to throw the 'link' out of the traditional 'edit-compile-    
link-test' cycle of software development, YOU, rather than the linker, must
define the address (i.e. variable number) of global variables.  This is done
with the global definition:

     (global
          var-name var-number
          var-name var-number
          ...
     )

This defines var-name to be global variable number var-number.

Local variables, not being accessible outside of the scripts in which they
are declared and thus not requiring linking, can have their addresses set by
the Script compiler.  There are two ways of defining locals:

     (local
          var-name
          var-name
          ...
     )

defines a single variables with the names var-name.

     (local [array-name n])

defines an array of n elements with the name array-name (the brackets in
this do NOT mean 'optional' -- they are required).

Multiple local variable definitions may be combined in one statement:

     (local
          var1
          [array1 10]
          [array2 5]
          var2
               .
               .
               .
     )

Temporary variables will be discussed in the section on user-defined  
procedures.

Define and enum statements may be included within both global and local
variable definitions.


Arrays:

To access element n of the array anArray, write

     [anArray n]

Despite the syntactic difference between local variable declarations and
local array declarations, there really is no distinction between variables
and arrays -- any variable may be indexed as an array.  Thus, if we have the
local variable declarations

     (local
          var1
          var2
          var3
          var4
     )

we can set the value of var1 to that of var4 by any of the following  
statements:

     (= var1 var4)
     (= var1 [var2 2])
     (= var1 [var3 1])
     (= [var2 -1] [var1 3])

The first method is obviously the preferred method for clarity, but this
array property of all variables allows access to variable numbers of
parameters in a user-defined procedure (see section on user-defined
procedures).

This property of variables is also the basis of the method by which you
declare global arrays -- you simply leave an array-sized gap in the global
variable numbering sequence.  To declare var2 as a global array of 10
elements, write

     (global
          var1      23
          var2      24
                         ;10 element array
          var3      34
     )

and access var2 as an array:

     [var2 7]


Pointers:

Some kernel calls require pointers to variables, rather than the value of a
variable.  A pointer to a variable is created by preceding a variable
reference with the '@' sign.  Pointers may be created to array elements as
well as to simple variables:

          @ego           ;pointer to the variable ego
          @[foo 3]       ;pointer to fourth element of array foo

Since there is currently no way in sc to dereference a pointer, this is only
useful for passing pointers to kernel calls.


Text:

Text strings are strings of characters enclosed in double quotes, and may be
used anywhere you like:

     (Print "This is immediate text.")

prints the text string,

     (= textToPrint "This text is referenced through a variable.")

sets the variable to a pointer to the text string, and

     (instance foo of Bar
          (properties
               name:"fooBar"
          )
     )

sets the name property of foo to be a pointer to the text string.

When sc goes to squirrel a text string away, it first checks to see if it
has seen the string before.  If so, it just uses the previous text, rather
than duplicating the text.  For long text strings which are used in several
places, however, the likelihood that you will manage to type the text
identically in each case is small.  In this case you can simply put the text
in a define statement

     (define lotsOftext  "This is a long text string. I am using a 
                         define statement to avoid having to type 
                         it repeatedly.")

This introduces another aspect of text strings: If text is too long fit on a
single line, you may enter it on several lines.  Multiple white-space
(spaces, tabs, and newlines) gets converted to a single space, so the text
above ends up with just one space between the words on each line.  If you
want multiple spaces, enter them as underbars, '_'.  These are converted to
spaces in the string, but are not compacted.

To include a '_' in text, type '\_', where '\' is the escape character. 
Explicit newlines are entered just as in C: '\n'.  A CR/LF pair is entered
as '\r' (the '\r' should be used in place of '\n' in all strings destined
for a file).  Characters which are not on the keyboard, but are defined in a
font (such as the Sierra symbol in the menubar) can be included in the
string by preceding the two-digit hex value of the character with the '\'. 
Thus, "This is the Sierra symbol: \01" would put the value 1 at the end of
the string, and this character in the font is the Sierra symbol.

The maximum length of a text string is 2000 bytes.


Word-strings:

Word-strings are used to represent templates for user input in Said
statements.  A word-string is a string enclosed in single quotes which
contains meta-characters describing the content of a sentence.  The meta-
characters and their meanings are described in the separate Vocabulary
documentation.

     (if (Said 'give/pirate/gold coins<#' @howMany)
          (Print "Get lost creep.")
     )

As with text strings, identical strings are stored only once.



Characters:

Characters are single ASCII characters, and are denoted by preceding the
character with the reverse single quote ("tick") character:

     `A   represents uppercase A and
     `?   represents the question mark

Several character sequences represent special key combinations:

     `^a  represents ctrl-A
     `@b  represents alt-B
     `#4  represents the F4 key


Literal selectors:

Sometimes, as in the code

     (cast eachElementDo: #showSelf:)

you want to send the value of selector rather than use the selector as the
start of another message to an object (these terms will be described in
Object Oriented Programming in Script).  Preceding the selector with a '#'
produces the literal value of the selector rather than using it as a
message.


                  Primitive Procedures


Arithmetic primitives:

In the following, e1, e2, ... are arbitrary expressions.

(+ e1 e2 [e3...])
     Evaluates to e1 + e2 [+ e3 ...]

(* e1 e2 [e3...])
     Evaluates to e1 * e2 [* e3 ...]

(- e1 e2)
     Evaluates to e1 - e2

(/ e1 e2)
     Evaluates to e1 / e2

(mod e1 e2)
     Evaluates to the remainder of e1 when divided by e2.

(<< e1 e2)
     Evaluates to  e1 << e2  where the << operation shifts its left hand
     side left by the number of bits specified by its right hand side.  (As
     in C).

(>> e1 e2) 
     Evaluates to  e1 >> e2  as in << except a right shift.

(^ e1 e2 [e3 ...]) 
     Evaluates to  e1 ^ e2 [^ e3 ^ ...] where '^' is the bitwise
     exclusive-or operator.

(& e1 e2 [e3 ...])
     Evaluates to e1 & e2 [& e3 & ...] where '&' is the bitwise and
     operator.

(| e1 e2 [e3]) 
     Evaluates to e1 | e2 [| e3 | ...] where '|' is the bitwise or
     operator.

(! e1) 
     Evaluates to TRUE if e1 == 0, else FALSE.

(~ e1)
     Evaluates to the bit-wise not of e1, i.e. all 1 bits are changed to 0
     and all 0 bits are changed to 1.


Boolean primitives:

These procedures are always guaranteed to evaluate their parameters left to
right and to terminate the moment the truth value of the expression is
determined.  If the truth value of the boolean is determined before an
expression is reached, the expression is never evaluated.

(> e1 e2 [e3...])
     Evaluates to TRUE if e1 > e2 [> e3 ...], else FALSE.

(>= e1 e2 [e3...])
     Evaluates to TRUE if e1 >= e2 [>= e3 ...], else FALSE.

(< e1 e2 [e3...])
     Evaluates to TRUE if e1 < e2 [< e3 ...], else FALSE.

(<= e1 e2 [e3...])
     Evaluates to TRUE if e1 <= e2 [<= e3 ...], else FALSE.

(== e1 e2 [e3...])
     Evaluates to TRUE if e1 == e2 [== e3 ...], else FALSE.

(!= e1 e2 [e3...])
     Evaluates to TRUE if e1 != e1 [!= e3 ...], else FALSE.

(and e1 e2 [e3...])
     Evaluates to TRUE if all the expressions are non-zero, else FALSE.

(or e1 e2 [e3...]) 
     Evaluates to TRUE if any of the expressions are non-zero, else FALSE. 

(not e)
     Evaluates to TRUE if the expression is zero, else FALSE.


Assignment primitives:

All assignment procedures store a value in a variable and return that value
as the result of the assignment.  In the following, v is a variable and e an
expression.

(= v e)
     v = e

(+= v e)
     v = v + e

(-= v e)
     v = v - e

(*= v e)
     v = v * e

(/= v e)
     v = v / e

(|= v e)
     v = v | e

(&= v e)
     v = v & e

(^= v e)
     v = v ^ e

(>>= v e)
     v = v >> e

(<<= v e)
     v = v << e

(++ v)
     v = v + 1

(-- v)
     v = v - 1



                              Control Flow

In the following, code1, ..., codeN are arbitrary sequences of expressions. 
There are no BEGIN ... END blocks as in Pascal or progn forms as in Lisp.

The value of a control flow expression is the value of the last expression
in the control body which was evaluated.  Thus, if we execute the following
code:

     (= x 3)
     (= y 2)
     (= y (if (> x y)
               (- x y)
          else
               (+ x y)
          )
     )

y will have the value 1.


Return:

     (return [expression])

The return statement returns control to the procedure which called the
currently executing procedure.  If the optional expression is present, that
value is returned as the value of the current procedure.  There is an
implicit return at the end of all procedures, and the value returned in that
case is the value of the last expression evaluated.  A return from the main
procedure of script 0 returns to the operating system.


Conditionals:

(if expression code1 [else code2])

     If expression is not FALSE, execute code1, else execute code2.  (The
     else clause is optional).


(cond (e1 code1) (e2 code2) ... [(else codeN)])

     Evaluate e1.  If it is not FALSE, execute code1 and exit the cond
     clause.  If it is FALSE, evaluate e2 and continue.  If all of the
     expressions are FALSE and the optional else clause is present, execute
     codeN. 


(switch expression (exp1 code1) (exp2 code2) ... [(else codeN)]) 

     Evaluate expression.  If it is equal to exp1, execute code1 and exit
     the switch.  If it is equal to exp2, execute code2 and exit.  If it
     doesn't equal any of the expressions and the optional else clause is
     present, execute codeN. 


Iteration:

(for (initialization) condition (re-initialization) code)

     Evaluate the expressions comprising initialization.  Then evaluate
     condition.  If the result is FALSE, exit the loop.  Otherwise, execute
     code, then the expressions comprising re-initialization, and loop back
     to condition.

(while condition code)

     Evaluate condition.  If not FALSE, execute code and loop back to
     evaluate condition again.  Exit the loop when condition is FALSE. 
     (Note that this means that the value of a while condition is always
     FALSE.)  This is equivalent to

          (for () condition () code)


(repeat code)

     Continually execute the code until some condition in the code (a
     break) causes the loop to be exited.  This is equivalent to
          (while TRUE code)
     or
          (for () TRUE () code)


Supporting constructs for iteration:

(break [n])

     Break out of n levels of loops.  If n is not specified break out of the
     innermost loop.

(breakif expression [n])

     If expression is not FALSE, break out of n levels of loops.  If n is
     not specified, break out of the innermost loop.




(continue [n])

     Loop back to the beginning of the nth level loop.  If n is not
     specified, loop to the beginning of the innermost loop.

(contif expression [n])

     If expression is not FALSE, loop back to the beginning of the nth
     level loop.  If n is not specified, loop to the beginning of the
     innermost loop.



                               Procedures


Procedures are created with the procedure construct:

     (procedure (proc-name [p1 p2 ...] [&tmp t1 t2...])
          code
     )

This defines the procedure with the name proc-name.  This procedure takes
parameters p1, p2, ... and allocates temporary variables (which disappear on
exit from the procedure) t1, t2, ....  Note that the procedure may take no
parameters and have no automatic variables.  In this case, the definition
would be

     (procedure (proc-name)
          code
     )

You can define temporary arrays in the same way as you would local arrays:

     (procedure (proc-name &tmp [array n])
          code
     )

Code in these examples is any list of valid expressions.

All procedures have at least one parameter, the compiler defined variable
argc (argument count), which gives the number of parameters passed to the
procedure.


For example, you might define the procedure square, to square a number, as
follows:

     (procedure (square n)
          (* n n)
     )

or the procedure max to find the maximum of an arbitrary number of numbers
passed to the procedure:

     (procedure
          (max
               p         ;parameters (will be accessed as an array)
               &tmp
               biggest   ;temporary variable containing maximum
               i         ;index into parameter array
          )

          (for ((= i 0) (= biggest 0))
               (< i argc)     ;compare to number of parameters passed.
               ((++ i))       ;note that this is a LIST of expressions,
                              ;not a single expression.

               (if (> [p i] biggest)
                    (= biggest [p i])
               )

          )

          (return biggest)
     )


The call

     (max 3 -4 -9 0 -2 7 12 4 3 5)

will return the value 12.

In order to use a procedure before it has been defined in a source file (for
example making a call to max before the actual definition of max), the
compiler must be told that the procedure's name corresponds to a procedure,
not an object.  This is done with another form of the procedure statement:

     (procedure
          procedure-name
          procedure-name
          ...
     )

Tells the compiler to compile code for procedure calls when it encounters
procedure-name, rather than code for send messages to an object.


&rest:

Argc, as discussed above, makes it easy to write procedures (or methods,
discussed in Object Oriented Programming in Script) which handle a variable
number of arguments.  If a procedure or method has received a variable
number of arguments and wants to pass them on to another procedure or
method, things get messy.  The only way to do this given only argc is to
build a switch statement on argc which looks like

     (procedure (foo arg)
          (switch argc
               (0   (mumble))
               (1   (mumble arg))
               (2   (mumble arg [arg 1]))
               (3   (mumble arg [arg 1] [arg 2]))
               ...
          )
     )

This not only involves a lot of typing and generates a lot of code, it
limits the number of arguments which can be passed to the next function (you
can only type a finite number of clauses in the switch statement).

&rest exists to solve this problem -- it stands for the rest of the
parameters not specified in the procedure or method definition.  The above
procedure could then be written simply as

     (procedure (foo)
          (mumble &rest)
     )

which is not only easier to type and read but also produces smaller, faster
object code.

A variant of &rest allows you to specify all parameters starting at any
point in a parameter list of a procedure or method definition:

     (procedure (foo arg1 arg2 arg3 arg4)
          (mumble (&rest arg3))
     )

passes all arguments starting with arg3 to procedure mumble.


Extern:

Calling a procedure in another script is another matter.  Since there is no
link phase in the development cycle, one procedure cannot know the address
of a procedure in a different script.  The extern statement allows a script
to know where the external procedure is:

     (extern
          procedure-name script-number entry-number
          ...
     )

This says that the procedure referred to by the symbol procedure-name in
this script is to be found in script number script-number at entry number
entry-number in the script's dispatch table.  kernel.sh and base.sh both use
the extern statement to let all other scripts know where their public
procedures are.


The dispatch table for a script is defined by the public statement:


Public:

All procedures within a script which are to be accessed from outside the
script must be entered in the dispatch table for the script with the public
statement:

     (public
          procedure-name entry-number
          ...
     )

puts the procedure procedure-name in the dispatch table at entry number
entry-number.  The entries need not be in numeric order, nor do the numbers
need to be continuous (though if they're not continuous the table will be
larger than it needs to be).



                                Using SC


The sc compiler is invoked with the command

     sc file_spec [file_spec] [options]

Any number of file specifications may be entered on the command line, and a
file specification may include wild-card names.

Options are:

-l
     Generate an assembly language code listing for the file.  This is
     useful when using the built-in debugger of sci, which lists only the
     assembly language code, not the source.  When compiling filename.sc,
     the list file is named filename.sl

-n
     Turns off 'auto-naming' of objects.  As described in Script Classes for
     Adventure Games, each object has a name, or 'print-string' property,
     which is how to represent the object textually.  Unless the property is
     explicitly set, the compiler will generate the value for this property
     automatically, using the object's symbol string for the name.  The
     object names, however, take up space in the heap.  While they are
     useful (almost vital) for debugging, if you're running out of heap in a
     room, it might help to compile with the -n option to leave the names
     out.

-oout-dir
     Set the directory for the output file (script.nnn) to out-dir.

-v
     Turns on verbose mode, which prints the number of bytes occupied by
     various parts of the output file (code, objects, text, etc.).

-z
     Turn off optimization.  Not a particularly useful option except for
     those of us who must maintain the compiler.






                   Object Oriented Programming in Script
						 =====================================

                        Object Oriented Programming


Object oriented programming (OOP) is a relatively new paradigm in
programming.  The Smalltalk language, developed at Xerox PARC, was the
first language to fully use the concept of OOP.  Since then, many languages
(such as C++, Scheme, Objective C, and Actor) have incorporated the concepts
to different degrees.  Because of the power of OOP for things such as
simulations (and after all, what are adventure games?), Script was designed
with the intention that much of the programming would use this concept. 
Those of us using the language over the last several months have found
ourselves moving more and more away from its procedural aspects and toward
the OOP aspects -- rooms, dialogs, menus, everything is now an object of one
sort or another.

OOP languages basically turn the data/procedure relationship in
conventional programming inside out: instead of sending data to a procedure
for the procedure to act upon, we send a message to data (an object) telling
it what to do.  This allows the sender of the message to obtain a service
from the receiver object with no knowledge of how this service is performed,
something which is not possible in procedural languages.

As an example, consider displaying the 'value' of data elements in a
program in a procedural language and then an OOP language.  In this example,
we'll assume that the procedural language is untyped (as opposed to the
current direction of strong typing in C, Ada, Pascal, etc.).  Strong typing
would make the follow exercise even harder.  To make the example more
concrete, we'll imagine that we want to be able to display one of two data
element types: a list of strings or an array of integers.

Procedurally, we'll use a C-like language (with lots of extensions which
don't exist in C) and write

     Show(data)
     /* Here's one place C would have a problem -- data could either be
      * a list of strings or an array of integers.  What type does one
      * declare?
      */
     {
          switch (typeof(data)) {       /* how is typeof() implemented? */
               case stringList:
                    for (str = ListStart(data) ;
                         str != NULL ;
                         str = ListNext(data)
                        )
                              printf(str);
                    break;
               case integerArray:
                    for (i = 0 ; i < sizeof(data) ; ++i)
                         printf("%d", data[i]);
                    break;
               }
     }

Note that one could not easily write this in C because of strong data typing
and the difficulty of implementing both typeof() and this particular use of
sizeof().  What usually ends up happening in a procedural language is that
instead of one general-purpose Show() procedure, one writes a lot of
special purpose ShowStringList() and ShowIntegerArray() procedures and
whoever wants to display something has to be aware of the type of data being
displayed and call the appropriate procedure.

Contrast this with object-oriented programming.  Either type of data can be
displayed by simply sending the data object the show message:

     (data show:)

Since both Arrays and Lists are sub-types of the Collection type they
implement this in the same way (they actually share the code):

     (method (show)
          (self eachElementDo: #show:)
     )

Both the list and the array simple send each of their elements the message
requesting the element to display itself.  The elements, strings and
integers, implement the show method in different manners.  The show method
for a string might be

     (method (show)
          (Print str)
     )

whereas that for the integer might be

     (method (show)
          (Print "%d" number)
     )

Note how much simpler the OOP code is than the procedural code.  This is
because the responsibility for displaying something is delegated to the
object being displayed, freeing the calling code from knowing anything
about it.  In fact, because of this passing on of responsibility, the above
code will also handle lists which contain elements of several data types --
(data show:) would also work if data were a list which contained a string,
an integer, a list of integers, an array of strings, and a list of arrays of
lists of strings.  No change in code is necessary.

Another benefit of the OOP code is that adding a new data type is as easy as
writing the show method for the data type.  In the procedural code, the
Show() procedure would need re-writing, as would the typeof() and sizeof()
procedures -- the addition of the new type propagates throughout the code
rather than remaining isolated in the new type.


Rather than continuing to give examples in an unspecified language, we will
first define the terms to be used in discussions of OOP languages and then
give the syntax and commands which Script uses.  Following that will be more
examples of the use of OOP in adventure game coding.


Object Oriented Terminology

Property:
     Properties are data associated with an object.  A door object might
     have such properties as the room number into which it opens, its state
     (open or closed), and its position on the screen.

Method:
     A method is a procedure which is internal to an object or class.  A
     door object might have a method open which causes the door to change
     state from closed to open.

Message:
     Methods of an object are invoked by sending the object messages.  In
     Script a message is sent to an object by enclosing the object name,
     then the message, in parenthesis (much like a procedure call):

          (doorToCloset open:)

     sends the open: message to the object doorToCloset.

Selector:
     Selectors are used in messages to indicate the method which is to be
     invoked.  The symbol open: in the above example of messaging is the
     selector for the open method.

Object:
     An object is a collection of properties and methods bundled together,
     and should be considered to be a distinct entity (hence the use of the
     word 'object').

Class:
     A class is a 'generic' object of a certain type.  It has no real
     existence of its own, but provides the default methods and property
     values to those objects which are instances (see below) of it.  Classes
     may have sub-classes, which are more specific types of a class (for
     example, the class SlidingDoor is a sub-class of the class Door) and
     super-classes, which are generalizations of the class (the class
     Opening might be a super-class of the class Door).

Instance:
     An instance of a class is a 'concrete' object which has the properties
     and methods of the class, but whose properties are distinctly its own. 
     For example the object doorToCloset is an instance of the class Door
     which is different from the object doorToPatio, another instance of
     class Door.  Changing the property values of an instance (object) of a
     class will not affect the property values of other instances of the
     class.

Inheritance:
     Inheritance is one of the most important concepts in OOP, and is
     responsible for much of its power.  A sub-class inherits all the
     methods and properties of its super-class, then goes on to add its own
     distinct properties and methods, or to modify an inherited method from
     its super-class.  We might define the class ElevatorDoor as a sub-
     class of the class Door.  It would thus inherit the properties of Door
     but would add a property to tell whether the light associated with the
     door is on or off.  It would also inherit Door's methods, but would
     modify the open method to not only change the state of the ElevatorDoor
     to open, but also to change the state of the light property to on. 
     All other methods work just the same as for the Door class.

Self:
     Often, an object needs to invoke one of its own methods, without really
     knowing who it is (it may be executing code inherited from its super-
     class).  This is done by sending a message to the object self, which is
     always the object which invoked the current method.

Super:
     An important factor in using inheritance to define new methods is being
     able to get access to the super-class's code for a method within the
     newly defined method.  The class super is provided for this purpose --
     sending a message to class super invokes the method within the super-
     class of self, rather than the method within self.  Thus, the open
     method for the class ElevatorDoor might contain the code

          (super open:)
          (= lightState on)

     which calls upon the open method of the class Door to do its stuff,
     then sets the light state to on.


                             A Note on Naming

There are a number of conventions which are normally (but not universally)
followed in naming things in object oriented programming.  Properties, being
data, usually have names which are nouns; methods, being actions on data,
usually have names which are verbs; classes and instances, which may
represent either concrete objects or actions, may have either nouns or verbs
as names.

The first letter of property, method, and instance names is lowercase,
whereas the first letter of class name is uppercase.  In both types of
names, succeeding words in the names are set off in the name by capitalizing
the first letter of the word, e.g. AutomaticDoor or elevatorDoor.




                                  Classes


                             Defining Classes

The first step in any object-oriented programming project is to define the
classes which will be used in the project.  Generally there is already a
large library of classes to draw on (in this case the classes documented in
Script Classes for Adventure Games), and often these classes are all one
will need in the project.  However, in order to define new classes and to
understand the old ones, it is necessary to understand the class statement
for defining a class.

The form of the class statement is:

     (class aClass kindof superClass
          (properties
               aProperty value
               ...
          )

          (methods
               aMethod
               ...
          )

          (method (aMethod [p1 p2 ...] [&tmp t1 t2 ...])
               code
          )
          ...

          [(procedure ...)]
     )

This statement defines aClass as a sub-class (kindof) superClass.  This
means that it inherits all of superClass' properties and methods, and will
either modify or add to them.  In order for the sc compiler to compile this
class definition, superClass must either have been defined earlier in the
current source file or in another file which will be compiled before this
file will be compiled, adding the super-class definition to the file
classdef (more on this at the end of this section).

The properties section of the class statement is where new properties are
introduced and old default property values redefined.  All entries in this
section are of the form aProperty value where aProperty is a symbol and
value is a constant expression.  If aProperty is not a property of
superClass, it is added as a new property in the class being defined and its
default value is value.  If the property exists in superClass, its default
value for the class being defined is just changed to value.

The methods section of the class statement lists any symbols which will be
the names of methods added to superClass to create the class being defined. 
Listing a method which is already defined in superClass does nothing, and a
method name need not be listed in the methods section if it is only being
redefined.

The method statement in the class statement is almost identical to the
procedure statement described in The Script Programming Language.  It
differs in that the properties of the class in which the method is defined
can be accessed as if they were variables, i.e. by simply using their names. 
Also, code in a method definition is the only place in which sends to the
objects self and super are valid.  Only methods inherited from the super-
class or listed in the methods section may be defined.  As in procedures,
the compiler-defined variable argc gives the number of parameters passed to
the method.

Note that procedures may also be included in a class statement.  These
procedures can be used by the methods defined within the class, but cannot
be accessed from outside the class definition.


                             Compiling Classes

Source files containing class definitions are compiled with the sc compiler
just like any other source file.  There are some subtleties involved where
class definitions are concerned, however, arising from the fact that all
sub-classes of a class must be defined after the class' definition.  Thus
the order of source file compilation is very important -- the files
containing the lowest level classes (such as Object) must be compiled first,
followed by successive sub-classes.  An understanding of how the compiler
maintains information on all the classes will clarify how the class
compilation process works.

Two files, classdef and selector constitute the database in which the
compiler tracks the classes being defined.  The first thing that the
compiler does when compiling a file is to read in the file selector, which
defines the symbols which are known to be selectors and the selector numbers
corresponding to them.  From this it also obtains the largest selector
number currently defined, which will mark the point from which it will
assign new selector numbers when they are needed.  If you are compiling on a
network, this file will be locked when you start compiling.  This prevents
anyone else from starting a compile (and possibly changing the information
in the database) while you are using it.

The compiler next reads the file classdef (if it exists), from which it
obtains information about the classes which have already been compiled.  The
information in classdef includes the class number (assigned by the
compiler), the number of the script in which it is defined, the class number
of the class' super-class, the names of the class' methods, and the names of
the class' properties with their default values.

The compiler now gets around to reading your source code.  As the compiler
encounters each class definition, it records in its class symbol table the
characteristics of the class.  If the class already has an entry in the
symbol table because it has been previously defined, that entry is cleared
and the class is redefined using the current source code.  This guarantees
that the compiler is always using the most current class definition.

The class definition is built from the information contained in the methods
and properties sections -- the selectors encountered here are added to those
inherited from the class' super-class to arrive at the structure of the
class being defined.  Any symbol encountered in a properties or methods
section of a class definition is looked up in a special symbol table for
selectors.  If it is not present there, it is entered in the selector table
and assigned the next available selector number.  Symbols are also entered
in the selector symbol table if they are undefined symbols encountered in
the position which a selector would occupy in a message to an object.

Assuming that the source file compiles with no errors, the compiler rewrites
classdef and selector from its class and selector symbol tables.  On multi-
files compilations this is done after each successful compilation.  The
external database is thus kept as up-to-date as possible.  Along with these
files, the compiler rewrites classtbl and vocab.001 after each successful
compilation.  Classtbl is a table which gives the script number in which
each class is defined, and is used by the kernel to load the appropriate
script when a class is referenced.  Vocab.001 is a file which contains the
names of all the selectors in a format which can be used by the kernel to
display selector names in error and debugging messages.

At the start of a project, you start with no classdef file and a selector
file which is a copy of the file selector.new.  The latter file contains the
definitions of those selectors which the kernel needs to know about and
which thus must have particular numbers.  As you compile files, beginning
with system.sc, the files classdef and selector grow with the addition of
new classes and selectors.  This growth is a one-way street, though --
nothing you do to your source code will cause a class or selector to be
removed from these files.  Thus, by the end of the project you are likely to
have a number of obsolete classes and selectors hanging around in the
database.  To winnow the chaff from these files you should, near the end of
the project, delete classdef, copy selector.new over your existing selector,
and recompile all your files (in the proper order, of course!).  This leaves
you with a class/selector database with only those classes and selectors
which you are using.


             Objects


Objects are specific instances of a class, and are defined using the
instance statement:

     (instance anObject of aClass
          (properties
               aProperty: value
               ...
          )

          (method (aMethod [p1 p2 ...] [&tmp t1 t2 ...])
               code
          )
          ...

          [(procedure ...)]
     )

This defines anObject as an instance of class aClass.  The properties and
method statements are optional and are used to over-ride the default values
and methods inherited from aClass.

The ID of an object or a class is what tells the sci kernel where to send
messages.  The object ID is obtained by simply writing the object's name
wherever an expression is valid -- it can be assigned to a variable or
passed as a parameter to a procedure.  Thus, if we define egoObj as an
instance of class Ego,

     (instance egoObj of Ego)

we can assign the ID of egoObj to the global variable ego:

     (global   ego       0)
     (= ego egoObj)

Once this has been done, the following two expressions are equivalent:

     (ego x?)
     (egoObj x?)

To find the distance from the object ego to the object wolf, we can pass
the wolf's ID as an argument to ego's distanceTo: method:

     (ego distanceTo: wolf)

Any unknown symbol encountered in a compilation is assumed to be the ID of
some object which is to be defined later in the source file.  If no object
with the symbol as its name is encountered by the end of the file, an error
will be raised.


             Sending Messages


The syntax for sending a message to an object is identical to that for a
procedure call.  The object name (or an expression which evaluates to an
object ID) is followed by the message selector and any parameters, all
enclosed in parentheses.  There are three different kinds of messages which
can be sent to objects:

Setting a property:
     A property of an object can be set by sending a message whose message
     selector is the name of the property followed by a colon (':') followed
     by the new value of the property:

          (ego x:23) or (ego x: 23)

     sets the x property of ego to 23.

Requesting the value of a property:
     The value of a property can be obtained by sending a message with no
     parameters whose message selector is the name of the property followed
     by a question mark ('?'):

          (ego x?)

     will return the value of the x property of ego.

Invoking a method:
     A method of an object can be invoked by sending a message with any
     number of parameters whose message selector is the name of the method
     followed by a colon (':'):

          (ego moveTo: x y) or (ego moveTo:x y)

     tells ego to move to coordinates x and y by invoking the moveTo method
     of ego.


Any number of messages can be sent in one fell swoop:

     (ego
          x:50
          y:50
          setMotion: MoveTo 100 100
          setCycle: Reverse self
     )

will position ego at coordinates (50, 50), start him moving to coordinates
(100, 100), and set him to cycle in reverse cel order.  When multiple
messages are sent to an object, the messager in the kernel sends them one at
a time in left to right order.  In multiple message sends, all parameters
are evaluated before the messages are sent.


An Extended Example


The only way to really understand OOP is not to read about it, but to dive
into an example and get a feel for how it is used (or better yet to actually
write code!).  The following extended example goes through the development
of a new class, the AutomaticDoor, for adventure games.  Before continuing,
it is advisable to read through Script Classes for Adventure Games in order
to become familiar with the classes upon which the AutomaticDoor is built.

The AutomaticDoor concept was inspired by Space Quest, in which there are
lots of doors which open whenever ego gets near them and close when he
moves away.  We would like the doors to do this by themselves, like good
automatic doors, rather than having to explicitly write code in each room
which checks ego's position, remembers whether the door is open or closed,
opens or closes the door, etc.

The first step in defining a class is conceptual -- determining what the
class represents and thus what properties and methods it should have in
order to carry out its role in the scheme of things.

We'll say that a door is a subclass of the Actor class, since it will be an
object visible on the screen.  A door goes somewhere, so it should have an
entranceTo property which tells us which room is on the other side of the
door.  The door may or may not be locked, so we'll need a locked property to
keep track of this, along with a key property which is the ID of a key
object which locks or unlocks the door.  Doors generally make some sort of
noise when opening and closing, so we'll add openSnd and closeSnd as
properties to tell us what sound the door makes.  Then there is the question
of keeping track of whether the door is opening, open, closing, or closed. 
This state will be kept in the property doorState.  Finally, since this is
an automatic door, it will need some way of telling when an Actor is near
enough to cause it to open.  This will be dealt with by an object of class
Code, whose ID will be kept in the actorNearBy property.

This gives us the beginnings of the class statement:

     (class AutomaticDoor kindof Actor
          (properties
               entranceTo 0
               locked FALSE
               key 0
               openSnd 0
               closeSnd 0
               doorState 0
               actorNearBy 0
          )
     )


We'll need symbolic definitions for the state of the door:

     (enum
          doorOpen
          doorOpening
          doorClosed
          doorClosing
     )



To this we now need to add the methods section.  The methods are the things
we wish to have the door do.  Thus, we will want methods open and close, as
well as lock and unlock:

     (methods
          open                ;open the door
          close               ;close the door
          lock                ;lock the door
          unlock              ;unlock the door
     )


We'll start with the init: method (inherited from Prop), which adds the door
to a room when we first enter the room.  This should handle having the door
be open if it is the door to the room which we have come from and closed
otherwise.

     (method (init &tmp doorState)
          (= doorState
               (if (== prevRoomNum entranceTo)
                    ;We just came from the room to which this door
                    ;is an entrance -- the door should be open.
                    doorOpen
               else
                    ;We didn't come through this door -- have
                    ;it closed.
                    doorClosed
          )

          ;Set the cel based on whether the door is open or closed.  This
          ;assumes that cel 0 is the cel with the door entirely closed.
          (= cel
               (if (== doorState closed)
                    0
               else
                    (- (NumCels view loop) 1)
               )
          )

          ;Pass the initialization along to the super-class to add the
          ;door to the cast, etc.
          (super init:)

          ;Stop updating the door, to reduce the burden on the animation
          ;system.
          (self stopUpd:)
     )

Note that we have not added the actorNearBy code at this point -- that will
be specific to each door.

We now want methods to open and close doors.  They should know enough not to
try opening a locked door or one which is either already opened or opening. 
Also, if a door-opening sound has been defined for the door (by putting a
the object ID of a Sound in openSnd), that sound should be played as the
door opens.  The same goes for the door closing.

     (method (open)
          (if  (and (! locked)
                    (!= doorState doorOpening)
                    (!= doorState doorOpen)
               )

               ;If the door is not opened or opening, start it doing so by
               ;having it cycle to the end of its loop.  When it is done,
               ;the cycle instance will cue us.
               (= doorState opening)
               (self setCycle: EndLoop self:)
               (if openSnd
                    (openSnd doit:)
               )
          )
     )

     (method (close)
          ;We don't have to worry about the door being locked,
          ;since in that case it wouldn't be open.
          (if  (and
                    (!= doorState closing)
                    (!= doorState closed)
               )
               (= doorState closing)
               (self setCycle: BegLoop self)
               (if closeSnd
                    (closeSnd doit:)
               )
          )
     )

When either the EndLoop or BegLoop cycle type initiated by open or close is
done, the cycle class will cue the door.  The cue method must thus handle
the change from doorOpening to doorOpen and from doorClosing to doorClosed:

     (method (cue)
          (= doorState
               (if (== doorState doorOpening) doorOpen else doorClosed)
          )
          (self stopUpd:)
     )

Note that we stop updating the door when it is no longer cycling in order to
reduce the load on the animation system.

Locking and unlocking the door may be done by anyone who has the key to it. 
Though not in the class system yet, each Actor will have a has: method which
will test to see if the Actor has a certain inventory object.  We use this
to define the lock and unlock methods, which take the Actor who is trying
to do the action as a parameter.  Note the use of a common procedure to
exploit the similarities in code:

     (method (lock who)
          (DoLock who TRUE)
     )

     (method (unlock who)
          (DoLock who FALSE)
     )

     (procedure (DoLock who newLockState)
          (if (who has: key)
               (= locked newLockState)
          else
               (Print "You don't have the proper key!")
          )
     )

Remember that the property key has the ID of the object which is the key to
this door.  

Since the init: method of the door has added the door to the cast, the door
will be sent the doit: message during each animation cycle.  This is the
ideal place to hook in the check to see if the door should be opened or
closed.  The door will check to see if any Actor is near enough (as defined
by a TRUE return from the code whose ID is in actorNearBy), and if so will
invoke the open: method.  Otherwise, it will invoke the close: method.  Note
that since these methods already check to see if the given operation is in
progress or is completed, we can invoke them blindly without creating any
problems.

     (method (doit)
          ;If there is no test for a nearby actor, don't try to test.
          (if (== actorNearBy 0) (return))

          ;See if anyone is near.
          (if (cast firstTrue: #perform: actorNearBy)
               (self open:)
          else
               (self close:)
          )
     )

The test in this method works in the following way:  we tell each member of
the cast to perform: the code whose ID is in actorNearBy.  If any member of
the cast returns TRUE from this code, the firstTrue: method will end and
return the ID of that member.  If no member returns TRUE, firstTrue: will
return NULL.  Thus the conditional statement will be TRUE if any element of
the cast returns TRUE to the code in actorNearBy.  The general structure for
this code (each door will have its own specific test for nearness) is:

     (instance nearByTest of Code
          (method (doit theObj)
               (return
                    code to test the nearness of the Actor
               )
          )
     )


Now that the methods have been defined for the AutomaticDoor class, we can
use it to define doors in any room in the game.  Say we're in a room which
has two doors (like the starting room of Space Quest).  The first is a face-
on door to a closet, which we'll call closetDoor.  Since it's face-on and
there are no obstructions, we'll use a simple position check to see whether
ego is near it:

     (instance closetDoor of AutomaticDoor
          ;Set the initial position of the object and
          ;say that it opens into the closet.
          (properties
               x:100
               y:60
               view:vClosetDoor
               entranceTo:closet
               actorNearBy:nearCloset
          )
     )

     (instance nearCloset of Code
          (method (doit theObj)
               (return
                    (and
                         (< x (theObj x?))
                         (> (+ x (CelWide view loop cel)) (theObj x?))
                         (< (abs (- y (theObj y?))) 10)
                    )
               )
          )
     )

The code in nearCloset checks to see if the object's x position is within
the bounds of the door and whether it is within 10 pixels of the door
vertically.  If all the above are true, it returns TRUE.

The second door will be an entrance to a secret room.  Let's say that the
room is so messy near the door that the only easy way to tell if ego is near
it is to draw some control into the picture and see if ego is on the
control.  Also, since the room to which this door leads is secret, we'll
need the cardKey object to unlock the door.

     (instance secretDoor of AutomaticDoor
          (properties
               x:10
               y:80
               entranceTo:secretRoom
               locked:TRUE
               key:cardKey
               actorNearBy:nearSecretDoor
          )
     )

     (instance nearSecretDoor of Code
          (method (doit theObj)
               (return
                    (OnControl theObj secretControl)
               )
          )


In the room code, we add the doors during the initialization phase:

     (method (init)
          ...
          (closetDoor init:)
          (secretDoor init:)
          ...
     )


     (if (Said 'lock / door')
          (cond
               ((closetDoor actorNearBy: ego)
                    (closetDoor lock:)
               )
               ((secretDoor actorNearBy: ego)
                    (secretDoor lock:)
               )
               (else
                    (Print "You're not near a door!")
               )
          )
     )


     (if (Said 'unlock / door')
          (cond
               ((closetDoor actorNearBy:)
                    (closetDoor unlock:)
               )
               ((secretDoor actorNearBy:)
                    (secretDoor unlock:)
               )
               (else
                    (Print "You're not near a door!")
               )
          )
     )

We use the door's own actorNearBy check to see if ego is close enough to
open the door.


Thus concludes our excursion into Object Oriented Programming.  The idea
behind this style of programming is to create abstractions of the things you
are modeling, decide how all these classes are related, and set up a
hierarchy of super- and sub-classes which encapsulates these relationships. 
In the classes are hidden the methods which do things to objects which are
instances of the classes, and the properties, which are the defining
characteristics of the class.  Objects are then instances of a given class
which have particular values for the properties and may even have different
methods for implementing a certain concept.

What all this setup gives you is the ability in your code to say

     (secretDoor unlock:)

to unlock a door, rather than having to write the code in-line or writing an
unlock routine which needs to handle all the possible cases of doors which
occur in the game.

Enjoy.






                           SCI Kernel Functions
									====================

                               SCI Overview


This document details the capabilities of the Script Interpreter (sci) and
the interface to those capabilities through the Script programming
language.  Before getting into the specific functions we'll take a look at
how sci operates in order to provide a background for the function
explanations.

When sci starts up, one of the first things that it does is set up two
memory spaces for memory management.  One is the heap, and consists of an
area smaller than 64K which can be addressed by 16 bit offsets.  This is
used for script code, variables, objects, lists, and other relatively small
things which we wish to access quickly.  When allocating memory from the
heap, a pointer is returned, which is just the offset of the allocated
memory within the heap.  Things which exist in the heap are at fixed
locations -- they are not affected by garbage collection.

The other memory space, hunk space, is much larger (128K or more, depending
on the target machine) and is used to hold resources: views, pictures, text,
background save areas, and anything else to which we do not need the access
speed of 16 bit pointers.  When a resource is loaded or allocated, sci
returns a handle, which is a 16 bit pointer to a location in the heap which
contains a 32 bit pointer to the resource.  Since all resource access is
through a handle, sci can do garbage collection in hunk space -- when there
is not enough memory to load a resource, sci will rearrange the currently
loaded resources in an attempt to create a large enough block of memory for
the new resource.  If the garbage collection is unable to create enough
memory for the resource, sci will begin purging the least recently used
resources from hunk space until there is enough room.  Purging resources
creates no problem, as any attempt to access a resource which is not in
memory will cause it to be loaded.  With garbage collection and automatic
resource purging/loading, it is virtually impossible to run out of memory --
 the worst condition which is likely to occur is constant disk access.

Once sci has initialized the memory management, graphics, etc., it turns
control over to the Script pseudo-machine (pmachine), which loads script 0
and starts executing pseudo-code (pcode) with entry 0 in that script.  From
this point on, the pmachine executes the pcode produced by the sc compiler,
making calls to the kernel routines in the interpreter to do things such as
draw pictures, animate characters, etc.

Interfaces to the kernel are in kernel.sh.  In the following descriptions,
remember that any of the arguments can be an arbitrarily complex expression
(including for example another kernel function call).

Many of the functions described here are never called directly, but are
hidden in object methods (described in Script Classes for Adventure Games). 
These calls are given here for completeness and in case they are needed for
writing new classes.


       Resource Functions

Resources are the various components of a game: views, pictures, scripts,
etc. and, except for the MEMORY resource, reside on disk, waiting to be
loaded when needed.  Resources are handled automatically by the kernel, but
two functions are provided to allow the programmer a bit more control over
how the handling is done.

(Load resType resID)
     Loads a resource of type resType and ID (number) resID into hunk space. 
     While any attempt to use a resource which is not loaded will cause the
     resource to be loaded, it is not generally a good idea to rely on this
     as it may cause a disk-access delay in the midst of a crucial animation
     sequence.  It is best to do an explicit Load of all resources during
     the initialization phase of a room to insure that everything is in
     memory.  The resource types are:

          VIEW
          PICTURE
          SCRIPT
          SOUND
          MEMORY (used internally by the kernel)
          VOCAB (used internally by the kernel)
          FONT

     Example:

          (Load SCRIPT curRoom)

     loads the script whose number is in the variable curRoom into memory.


(UnLoad resType resID)
     Purges the resource of type resType and ID (number) resID from hunk
     space.  This is not normally needed, as the kernel will automatically
     purge the least recently used resource when it doesn't have enough
     memory to load a new resource.  This function is provided for a
     situation in which it is advantageous to override this automatic
     purging.  Such a situation is unlikely.

     Example:

          (UnLoad SOUND EXPLOSION)

     purges the sound whose number is EXPLOSION from memory.



                              List Functions

Lists play a crucial role in Script code, being the basic component out of
which such classes as Collection, List, and Set are built.  The kernel list
(or kList, as it is known), is simply a block of memory with pointers to the
first and last kNodes (kernel nodes) of the list.  The kNodes are doubly
linked, each having a pointer to both the previous and next node in the
list.  The nodes also have a key and a value associated with them.  The
value is the item being stored in the list (an integer, an object ID, etc.)
and the key is a means for looking up the value.

For better or worse, all of the kernel's internal functions for handling
lists are available to the Script programmer.  Not all of them may be
useful.


(NewList)
     Returns a pointer to a new kList with no elements.

(DisposeList kList)
     Dispose of a kList.  This involves disposing of all kNodes in the list
     (but not any objects pointed to by the kNode value), then disposing of
     the kList header itself.

(NewNode)
     Returns a pointer to a new kNode.

(FirstNode kList)
     Returns a pointer to the first node in kList, or NULL if kList is
     empty.  Note that what gets returned is a pointer to a kNode, not the
     value stored in the kNode.

(LastNode kList)
     Returns a pointer to the last node in kList, or NULL if kList is empty. 
     Note that what gets returned is a pointer to a kNode, not the value
     stored in the kNode.

(InitList kList)
     Initialize kList to be an empty list.  This simply zeros the pointers
     to the first and last nodes of the list.  If the list is not empty,
     this will leave the former contents of the list lying around with no
     way of accessing them.

(EmptyList kList)
     Returns TRUE if kList is empty, FALSE otherwise.

(NextNode kNode)
     Returns the node which follows kNode in a list or NULL if kNode is the
     last node in the list.  Note that this returns the kNode, not the value
     of that node.

(PrevNode kNode)
     Returns the node which precedes kNode in a list or NULL if kNode is the
     first node in the list.  Note that this returns the kNode, not the
     value of that node.

(IsFirstNode kNode)
     Returns TRUE if kNode is the first kNode in a list, FALSE otherwise.

(IsLastNode kNode)
     Returns TRUE if kNode is the last kNode in a list, FALSE otherwise.

(SetKey kNode key)
     Set the key of kNode to key.

(GetKey kNode)
     Get the key value of kNode.

(NodeValue kNode)
     Return the node value of kNode.

(DeleteNode kList kNode)
     Remove kNode from kList and return any memory it may have occupied to
     the system.  This does not dispose of whatever may be pointed to by the
     kNode's value.

(AddAfter kList kNode aNode [key])
     Add aNode to kList immediately following kNode (which had better be an
     element of kList).  If key is present, set the key of aNode to its
     value.  Returns aNode.

(AddBefore kList kNode aNode [key])
     Add aNode to kList immediately before kNode (which had better be an
     element of kList).  If key is present, set the key of aNode to its
     value.  Returns aNode.

(AddToFront kList kNode [key])
     Add kNode to the front of kList.  If key is present, set the key of
     kNode to its value.  Returns kNode.

(MoveToFront kList kNode)
     Move kNode to the front of kList.  (kNode had better be an element of
     kList.)  Returns kNode.

(AddToEnd kList kNode [key])
     Add kNode to the end of kList.  If key is present, set the key of kNode
     to its value.  Returns kNode.

(MoveToEnd kList kNode)
     Move kNode to the end of kList.  (kNode had better be an element of
     kList.)  Returns kNode.

(FindKey kList key)
     Return the first kNode in kList to have key as its key, or NULL if
     there is no node with the key.

(DeleteKey kList key)
     Delete the first kNode in kList which has key as its key.  Return TRUE
     if a node was deleted, FALSE if no node with the given key was found.

(NodeKey kNode)
     Return the key for kNode.  If no key was set, this may be garbage.



                             Object Functions

These functions are low-level functions for manipulating and getting
information about objects.

(Clone instance/class)
     Return the object ID of a copy of instance/class.  This copy has the
     same property values and the same methods as instance/class.  The
     properties can be changed, the methods cannot.

(DisposeClone object)
     Dispose of object if it was created with the Clone function, leave it
     alone otherwise.  This does not dispose of any objects which may have
     their IDs in a property of object -- you must do that before calling
     DisposeClone.

(IsObject object)
     Returns TRUE if object is an object or class, FALSE otherwise.  Useful
     for testing to see that something is an object before sending a message
     to it in a situation in which you can't be guaranteed that a value is
     an object ID.

(CanUnderstand object selector)
     Returns TRUE if selector is a valid selector for object, i.e. if
     selector is the name of a property or method of object.

(ShowObjs withID)
     Display all static and dynamic objects which are currently in the heap. 
     If withID is TRUE, show the object IDs as well.



                             System Functions

(ScriptID script [entry])
     Return the object ID for the object which at entry number entry in the
     publics table of script number script.  This will load the script if it
     is not already in memory.  If entry is not present, this returns the ID
     of entry number 0 of script.

(DisposeScript script)
     While resources loaded into hunk space are automatically disposed of
     when no longer used, when a script is loaded it is loaded into the heap
     and remains there until disposed of by DisposeScript.  This disposes of
     script number script and should be called when you no longer need the
     script.

(Wait n)
     Wait until n timer ticks (1/60th of a second) have passed since the
     last call to Wait.  This is used to keep animation running at a
     constant speed -- each pass through the main loop ends with a call to
     Wait, so the main loop is executed at most once in a given time
     interval.  The standard value of n is 6, leading to animation every
     1/10th of a second.  If more than n ticks have occurred since the last
     call to Wait, it returns immediately.  The return value of Wait is the
     number of ticks more than n since the last call.

(RestartGame)
     This function resets the system to the state it had at the beginning of
     the game, allowing the user to restart the game without rebooting it.

(GetTime [realTime])
     With no arguments, returns the low word of the number of ticks (1/60th
     of a second) since the game was booted.  With an argument, returns real
     system time in the format:

          HHHH/MMMMMM/SSSSSS


String Functions

Strings in Script are kept in arrays, with two characters per array element. 
Thus, when allocating space for a string of 40 characters, you only need to
allocate an array of 20 elements.

(ReadNumber string)
     Returns the integer value represented by string.

(Format stringPtr formatStr arg1 arg2 ...)
     Similar to C's sprintf.  Formats a string in the storage space pointed
     to by stringPtr based on the format string formatStr and the arguments
     arg1, arg2, etc.  Formatting commands embedded in formatStr are like
     those of sprintf: they consist of the '%' character followed by
     optional justification and field width characters followed by a
     conversion character which tells how the corresponding argument is to
     be converted to a string.  Between the '%' and the conversion
     character, there may be a

          minus sign, indicating that the string representing the argument
          is to be right justified (rather than the default of left
          justified) in its field

          number, indicating the width of the field (in characters) in which
          the argument is to be printed.

     The conversion characters supported are:

          d    Print the corresponding argument as a signed decimal integer.
          u    Print the corresponding argument as an unsigned decimal
               integer.
          x    Print the corresponding argument as a hexadecimal number.
          c    The corresponding argument is taken to be the ASCII
               representation of a character, which is printed.
          s    The corresponding argument is assumed to be a pointer to a
               null terminated string, which is printed.

     Examples:
     If we have declared str somewhere as [str 40] (an 80 character string),
     then

          (Format @str "x:%4d y:%-4d" 23 45) -> "x:23   y:  45"

          (Format @str "This is a %s." "test") -> "This is a test."

(StrCmp str1 str2)
     Compares the null-terminated strings pointed to by str1 and str2. 
     Returns 0 if the strings are the same, 1 if str1 is greater than str2
     (i.e. if the first character of str1 which does not match the
     corresponding character of str2 is greater than the character in str2),
     and -1 if str1 is less than str2.

(StrLen str)
     Returns the number of characters in the null terminated string pointed
     to by str.

(StrCpy str1 str2)
     Copies the string pointed to by str2 to the storage pointed to by str1. 
     There had better be enough room in str1's storage to hold str2 -- there
     is no checking.

(StrCat str1 str2)
     Concatenates str2 to the end of str1.  Str1 had better have enough
     storage.

(StrEnd str)
     Returns a pointer to the NULL which terminates str.  This is useful for
     Formatting a string on the end of another, rather than Formatting to a
     temporary string and then using StrCat.



                             Picture Functions

(DrawPic picNum [showStyle])
     Clear the background screen, then draw picture number picNum in it. 
     The picture will not be brought to the screen until the first Animate
     call following the DrawPic.  The optional showStyle specifies the
     manner in which the kernel will bring the picture to the screen --
     current possibilities are horizontal wipe, vertical wipe, and dissolve. 
     These are not yet available from the Script language.

(Show what)
     Displays a given screen (visual, priority, or control) based on the
     value of what.  This can be used for debugging to see why an actor is
     not able to enter a given area or why priorities aren't working
     properly.  The values of what are one of

          VMAP      (visual screen -- you're generally displaying this)
          PMAP      (priority screen -- objects will have their priorities
                    displayed, and animation will continue on this screen)
          CMAP      (control screen -- animation is stopped pending a
                    keystroke when this screen is displayed, since you wont
                    be able to see the Actors)

(PicNotValid)
     Returns TRUE or FALSE depending on whether or not the picture window
     needs updating.



                            Animation Functions

(Animate cast)
     Cast is a kList of members of the cast (Actors and Props which are on
     the screen).  Animate updates the on-screen views and positions of all
     members of the cast to correspond to the current state of their
     properties.  If a picture has been drawn since the last Animate, the
     entire screen is updated.  Certain bits in the signal properties of the
     objects allow an object to be erased and removed from the cast or tell
     Animate to leave the object in the cast but not to update it (in order
     to gain speed when an object isn't changing).

(CanBeHere actor [dx dy])
     Checks to see that an Actor can be in a certain position.  Checks all
     pixels in actor's base rectangle (the baseRect property) to see if any
     are on pixels which have the controls specified by actor's illegalBits
     property.  If the actor is on illegal controls, CanBeHere returns
     FALSE.  Otherwise it returns TRUE.  If the optional dx and dy arguments
     are present, the baseRect is offset by these amounts before the check
     is made.

(NumLoops actor)
     Returns the number of loops in the current view of actor.

(NumCels actor)
     Returns the number of cels in the current loop and view of actor.

(SetNowSeen actor)
     Set the nowSeen rectangle of actor based on actor's current cel.

(CelWide view loop cel)
     Return the width (in pixels) of cel cel of loop loop of view view.

(CelHigh view loop cel)
     Return the height (in pixels) of cel cel of loop loop of view view.

(OnControl x y [rx ly])
     Return a bit-mapped word which represents the control in the background
     screen at the point x, y.  If the optional rx, ly are specified, the
     word has the bit set for each control which is within the rectangle
     (x, y) - (rx, ly).

(DrawCel view loop cel left top priority)
     Draw cel cel of loop loop of view view.  Put the upper left corner of
     the cel at (left, top).  The cel should be at priority priority.



                              Input Functions

(GetEvent eventMask event)
     Checks the input buffer for an input event of type specified by
     eventMask.  Returns FALSE if there are none.  If an event exists, it
     fills in the event record of the event instance whose ID is in event
     and returns TRUE.

     The types of events which may be specified in eventMask are:

          mouseDown      a mouse button was pressed
          mouseUp        a mouse button was released
          keyDown        a key was pressed
          keyUp          a key was released
          menuStart      the menu request key was hit
          menuHit        a menu item was selected
          direction      a direction event was received

     These event types may be 'or'ed together to request multiple event
     types.  The symbolic value

          allEvents

     requests any event type.

(Parse stringPtr)
     Parses the string pointed to by stringPtr and returns TRUE if the
     kernel could parse the string, FALSE otherwise.  The kernel can parse
     the string if all the words in the string are in the game's vocabulary
     (the file vocab.000) and the sentence structure is one recognized by
     the kernel's parser.

(Said saidStr)
     Checks to see if the parsed input sentence matches the input specified
     by saidStr (to be documented later).  Returns TRUE if the input matched
     saidStr, FALSE otherwise.



                              Menu Functions

A Script MenuBar consists of a List of Menus, each of which is a List of
MItems (see Script Classes for Adventure Games).  The menu bar is the line
at the top of the screen which contains the names of each of the menus.  A
menu is the drop-down list of menu items which can be selected.

(DrawMenuBar menuList)
     Draw the menu bar represented by the kList menuList on the top line of
     the screen in the system font (font 0).

(MenuSelect menuList)
     Drop down the first (leftmost) menu in the menu bar represented by
     menuList and let the user select an item from the menu bar using cursor
     keys.  If the user presses ESC, return FALSE; if the user presses
     ENTER, return the object ID of the item selected.

(MouseSelect menuList)
     Drop down the appropriate menu (pointed to by the mouse) from the menu
     bar represented by menuList and let the user select an item from the
     menu with the mouse.  If the user releases the mouse button when a menu
     item is not highlighted, return 0; otherwise, return the object ID of
     the highlighted item.

(DrawStatus str)
     Replace the menu bar with a status line which consists of the string
     str.  If str is 0, discard the status line, showing the menu bar once
     again.  (Note that the user can still activate the menus by pressing
     the mouse button with the cursor on the status line or by pressing the
     menu selection key.)



                         Window and Text Functions

These functions deal with the main picture window, dialog windows, and
writing text to those windows.

(GetPort)
     Returns the current grafPort.

(SetPort grafPort)
     Sets the current grafPort to grafPort.

(GlobalToLocal event)
     Convert the coordinates in the event object event from global (screen)
     to local (window) coordinates.  Event coordinates are always returned
     in global coordinates, so this call is necessary to convert to the
     coordinates within the current window.

(LocalToGlobal event)
     The reverse of GlobalToLocal -- converts the coordinates in event from
     the local window coordinates to global screen coordinates.

(TextSize rectPtr text font width)
     Fills in the rectangle (an array of four elements) which is pointed to
     by rectPtr with the bounding coordinates of the box which will hold
     text printed in the font font.  If width is non-zero, it is the maximum
     width of the rectangle.

(Display text [at: x y] [font: f] [color: c] [back: b] [style: s])
     Writes text to the current grafPort.  The optional parameters are:

          at: x y        Position the upper left corner of the first
                         character of text at coordinates x, y in the
                         grafPort.
          font: f        Write the text in font f.
          color: c       Set the foreground color of the characters to c.
          back: b        Set the background color of the characters to b.
          style: s       Set the style of the characters to s.  S may be one
                         of TPLAIN (plain text), TDIMMED (dimmed text) and
                         TBOLD (bold text).



                           Arithmetic Functions

(Random min max)
     Returns a random number n such that 0 < min <= n <= max.

(Abs number)
     Returns the absolute value of the signed integer number.

(Sqrt number)
     Returns the square root of number, which is assumed to be unsigned.

(GetDistance x1 y1 x2 y2)
     Returns the distance between the two points determined by (x1, y1) and
     (x2, y2).

(GetAngle x1 y1 x2 y2)
     Returns the angle between the two points determined by (x1, y1) and
     (x2, y2).  The angle is measured in degrees and is between 0 and 359
     degrees.



                            Debugging Functions

There a number of functions designed for debugging Script programs by
providing information about the state of the program.

(SetDebug)
     Pop up the debugging window.  At the top of the window, in red, is the
     name (if any) of the object self.  Below it is the op-code about to be
     executed.  In columns on the right side of the window are the top five
     values on the stack and the top five parameters.  On the left are the
     contents of the accumulator (acc), the address of the next instruction
     (the instruction pointer, or ip), and the address of the top of the
     stack (the stack pointer, or sp).

     A number of instructions may be issued while in the debugger:

          alt-D     Put the debugging window away.  This also can be used to
                    pop the debugging window up while the program is
                    running.
          q         Quit.  Exit to DOS.  Using alt-D to pop up the debugger
                    and q to quit will generally get you out of the program
                    even if your code is broken.
          s         Toggle the send stack on/off.
          Enter     Step to the next instruction, tracing into the procedure
                    or method referenced by a call or send instruction.
          Tab       Step to the next instruction treating a call or a send
                    as an indivisible instruction (don't trace into them).
          tn        Display the value of temporary variable number n.
          ln        Display the value of local variable number n.
          gn        Display the value of global variable number n.
          i         Open an inspector window, allowing you to inspect the
                    values of the properties of objects.  See InspectObj
                    below.

(InspectObj object)
     Open an inspector window on object.  This displays the property names
     and values for the object.  Typing 'i' when this is displayed prompts
     for a property name, whose value will be displayed either as a number,
     string, or another object depending on what it is.  If another object,
     'i' can be typed again to inspect its properties, and so on until the
     interpreter runs out of stack.

(ShowSends)
     Show the current send stack.  This allows you to see how you got where
     you are.  Entries in the display are of the form (object selector:)
     where object is the object to which a message whose selector was
     selector: was sent.  The top line in the display is the most recent
     send, the line below that is the send to the method which made that
     send, and so on to the bottom line, which is the initial send from the
     main loop in the base script.

(LargestPtr)
     Returns the size (in bytes) of the largest block of memory available in
     the heap.

(LargestHandle)
     Return the size (in bytes) of the largest hunk available in hunk space. 
     If the largest available hunk is greater than 64K, returns 64K.

(FreeHeap)
     Return the amount of memory (in bytes) which is free in the heap.

(FreeHunk)
     Return the amount of memory (in paragraphs, or 16 byte blocks) which is
     free in hunk space.

(ShowFree)
     Displays the free memory blocks in the heap in the form
          number-of-bytes@address.

(CSClear)
(CSEnable)
(CSDisable)
     Rather esoteric functions provided in order to use the CodeSifter
     execution profiler.

(StopWatch n)
     If n is non-zero, start the stopwatch.  If n is zero, stop the
     stopwatch and return the number of 60th of a second ticks since it was
     started.



                              File Functions

These functions allow access to some of the MS-DOS file functions.  They are
best accessed through the File class.

(FOpen filename [mode])
     Opens the file whose name is filename and returns a handle to it.  The
     optional parameter mode may be either fAppend, in which case the file
     pointer will be positioned at the end of the file for appending, or
     fTrunc, in which case the file will be truncated to zero length.  If
     mode is not specified, fAppend is assumed.  If there is an error in
     opening the file, a value of -1 is returned.

(FWrite handle string)
     Write the text pointed to by string to the file whose handle is handle.

(FClose handle)
     Close the file whose handle is handle.