			--------------------------
			Some Usage Notes for std.i
			--------------------------
				 (version 0.3.1)


Three steps to using the library
--------------------------------
 1 - Store all the std.i library files in a separate subdirectory or file 
folder from your game's files


 2 - Add an 'include' statement for the main 'std.i' file at the top of your 
game's main sourcecode file. ('std.i' contains include statements for all the 
rest of the library '.i' files so they're automatically added to your game.)
 - an example showing the start of your game sourcecode file might be


		-- "My Game" by Fred Smart

		-- add the code from the std.i library to this game
		$INCLUDE 'std.i'

		-- beginning of your game's actual code
		LOCATION abc
			etc etc ......


 3 - Compile your game with an 'include' parameter for the 
subdirectory or file folder where you stored the std.i library files
 - eg:
		alan   -include c:\alan\stdlib   mygame.ala




study the library files
-----------------------
The documentation for the std.i library consists of 
	the 'readme' file, 
	the 'index.txt' file,
	this 'notes.txt' file.

The secret to using std.i is to study the actual library files - the '.i' 
files - as the documentation about the library is scanty the best way to 
learn how things should be defined in your own code is to check how the 
relevant verbs etc are defined in the library itself. 

Use the index.txt file to find which '.i' files contain the attributes or 
verbs or whatever that you wish to investigate. 

For example, perhaps you have an object that you want to be able to talk. 
You note while play-testing that only actors can talk in games using the 
std.i library but you don't want to make your object an actor because, other 
than being a talkative object, it is otherwise more convenient to code it as 
an object. So you look through the index.txt file and find that 'not 
can_talk' is a default attribute defined in the talk.i file. So you look in 
the talk.i file and find by viewing the source code for the talk verbs that 
if an individual object is given the 'can_talk' attribute then all the 
talk/ask/etc verbs will now work for that object. Ah ha! So you add the 
line 'IS can_talk.' to your object's definition and, hey presto, your problem 
is solved.




modify the library files when you have to
-----------------------------------------
Keep the library '.i' files in their own subdirectory or file folder. If you 
find you need to modify the contents of a '.i' file (as you probably will 
because most games will have some unique characteristic or another that's 
not catered for by the standard library behaviour) use a *copy* of that '.i' 
file stored in your game's sourcecode directory. (See the 'readme' file for 
a fuller explanation of why you should do this.) Don't hesitate to modify the
'.i' files to meet your requirements.

If you find bugs or stupid things in the library or you have ideas to 
expand or improve it, let the library maintainer know. The library is in the 
early stages of development so there is certain to be many areas requiring 
improvement.




equivalent verbs
----------------
note that some verbs have different syntaxes but do the same thing (eg: 
"look at thing" "examine thing".) Such verbs should be listed together in 
DOES statements in your game sourcecode so that the player can use any of 
the different syntaxes.

 - eg:
	OBJECT rock AT somewhere
		DESCRIPTION "etc etc"

		VERB examine, look_at, search
			DOES
				"Its a pretty dull rock, actually"
		END VERB.
	END OBJECT.


The most important of these groups of different-but-equivalent verbs are:

	examine.i:  VERB examine, look_at, search
	take.i:     VERB take, pick_up1, pick_up2
	take.i:     VERB drop, put_down1, put_down2
	turn.i:     VERB turn_on1, turn_on2, switch_on1, switch_on2
	turn.i:     VERB turn_off1, turn_off2, switch_off1, switch_off2

Note that you may not always want to have these equivalent verbs 
defined the same as each other. For example, you might prefer 'search 
object' to have different results to 'examine object' and 'look at object' 
in particular circumstances or perhaps throughout the whole game.



named attribute
---------------
The 'named' attribute (defined in global.i) records whether an actor or 
object has a real 'proper' name or a generic name - eg 'Fred' is a real 
name, 'the bus-driver' is not a real name. The library uses the attribute to 
format text messages properly

 - eg: 
	x fred
 should return a phrase with Fred's name with a capital first letter 
	You see nothing unusual about Fred.
 whereas
	x driver
 should return a phrase with a 'the' added
	You see nothing unusual about the driver.

By default in std.i, actors are 'named', objects are not.

If you want an object to have a name you must define two names for that 
object - the first one with a capital letter for Arun to use when formatting 
text, the second all in lower case so the player can refer to the object in
player commands (because all player commands are read as lowercase by the Arun
game interpreter)
 - eg:
	OBJECT robot AT spaceship NAME 'Floyd' NAME floyd 



Inventory and Container Capacity Limits
---------------------------------------
All objects and actors have a default 'weight' of 5 and of 50 respectively. 
I think of the default object weight of '5' being about equivalent to that 
of a book. You can give objects and actors different weights to reflect 
their 'real world' sizes to ensure they are or aren't easy to pick up or to 
put in containers of various sizes.

The default capacity limits for carrying and wearing are ten 
items and a maximum total weight of 50. You can tweek these limits in the 
invent.i file to meet the requirements for your game.

If you have container objects in your game you should give them capacity 
limits appropriate to their sizes - eg: a chocolate box might require a 
weight limit of 4 so that even objects of the default size can't be put in 
it.
 -eg:

	object cbox name chocolate box at somewhere
		is 
			not closed.
			closeable.

		container
			limits
				count 10 then
					"You can't put anything more in there." 
				weight 4 THEN
					"You cannot fit that item in there."

		description 
			"etc etc....



Scenery Objects
---------------
By default objects have several attributes that allow the player to 
manipulate the object in various ways. For some objects at a location these 
verbs (eg push <obj>, etc) may not make any sense. So, for example, make 
distant but examinable objects not takeable, pushable, touchable, or 
searchable
 - eg:

	object mountains at somewhere
		is 
			not searchable.
			not takeable.
			not pushable.
			not touchable.

		description
			"From here you can see a range of rugged snow-capped mountains 
			to the west."

		verb examine
			does only
				describe mountains.
		end verb.

	end object.




================================
Stephen Griffiths, February 2001
  (sg@xtra.co.nz)
