README for plugin_yak, version 0.2

WHAT IT IS:

	1: yak (noun)
	      A wild, shaggy-haired ox (Bos grunniens) of the mountains of 
	      central Asia. 

	2: yak (noun. also yack. slang)
	      Prolonged, sometimes senseless talk; chatter. 


This script is about the 2nd one. It's an attempt to make it easier to have
custom words in the game. Not for map/mod designers but for admins who are
bored and want "prolonged, sometimes senseless talk; chatter."

In a nut-shell, the script uses a text file that describe individual sounds
and another that describes how to combine those sounds to make up words. For
example, the sounds file contains these lines..

	bir           birdwell(e30)
	th            three(e30)
	dA            day

..and the words file contains this line..

	birthday      bir th dA

When an admin types "admin_yak birthday" into the console, the script looks
through the words file until it finds a line that begins with "birthday".
Once it finds that, it uses the rest of the line to build a command to pass
to Half-Life.

There's also a "lines" file that contain sequences of words. Currently, this
file only contains this line..

	!jif	some times you feel like A nut

..that can be "spoken" by typing "admin_yak !jif" into the console.

Other commands exist that allow admins to display lists of known words and
commands that make it easier to add new words and sounds without exiting
the game.

Several people I've tried explaining this to seem confused. Remember: you
combine sounds to make words. You combine words to make lines.



BACKGROUND:

Anybody who's played TFC is familiar with The Announcer. He's the guy who
says stuff like "your team has the enemy flag." He's also heard in other
places: other mods use him, commands like "timeleft" on some servers will
"speak" the amount of time left on the current map.

Internally to Half-Life, the different things that The Announcer can say
are split up into WAV files (one for each word) and stored in the PAK0.PAK
file. There's actually a whole bunch of sounds in there for things Barny's
(the policeman/guard), scientists, G-Men, aliens, and almost every other
sound something makes in Half-Life. The PakExplorer (freeware) program lets
you look through PAK files if you're curious about what's in there. Sounds 
that The Announcer can make are stored in the Sounds\VOX folder.

Anyway, mod and map designers can pick and choose from the supplied sounds and
speak them when certain events occur. You can mess around with this in the 
console if you're bored. Just type "speak adios" in the console (no quotes) 
and you'll hear The Announcer say "adios."

This is really cool but there's only a certain number of words that are built
into Half-Life. Say, for example, a map designer wanted to say the word
"announce." This is a problem because there is no wav for announce. There is
a word for announcement but that's not quite the same thing.

Turns out that this really isn't that much of a problem because the guys at
Valve were thinking ahead. They added support so that the map designer can
tell Half-Life to only say part of a word. 

This is done by using the "s" and "e" qualifers on the speak command. These
tell Half-Life to only play a certain percentage of the file. For example,
to end up with the word "announce" you would use something like this..

	speak "announcement(e60)" 

..which tells Half-Life to stop playing the WAV file once it gets 60% of the
way through it. The "s" qualifier is similar but tells Half-Life to start
playing the WAV a certain percentage into the file. For example..

	speak "yourself(s65)" 

..would produce just the sound for "self." These qualifiers can also be com-
bined. If you wanted to hear the word "ounce" You might try..

	speak "announcement(s30 e60)


I'm just guessing at the numbers above (too lazy to test them) but they're 
probably pretty close.


FILES:

The package for this plugin contains:
	README.yak.txt: this file
	plugin_yak.sma: the plugin source
	yak_sounds.txt: the list of sounds that the plugin knows how to make. This
		file is only read at startup - all others are read every time an
		admin_yak command is given.
	yak_words.txt:  the list of words that the plugin knows how to say.
	yak_lines.txt:  frequently used sequences of words
	vox_words.txt:  list of words built-in to Half-Life.

The plugin ignores leading whitespace when parsing the txt files. Also, it
ignores blank lines and lines that start with //. Unlike C/C++, it will
NOT notice these in the middle of a line - either entire line is ignored or
none of it is.

The yak_*.txt files all have the same format. The first word is the "key"
and the rest of the line is the "value" of that key. Whitespace (tabs &
spaces) separates the key and the value. For example, 

	birthday      bir th dA

The word "birthday" is the key and "bir th dA" is the value. 

Also, everything in the text files is treated as case-sensitive - 'dA' is
NOT the same as 'da'.



COMMANDS:

admin_yak
admin_yak -help
	Both of these will display a list of commands available to the user.
	
admin_yak <words>
	Will try to "speak" the <words>. The plugin first tries to find each word
	in the unsaved words list (see below). If it's not in there, it will look
	for it in the yak_words.txt file. If it still can't find it, it passes it
	straight-thru to Half-Life. 

	If <words> begins with a !, the script searches yak_lines.txt first. If no
	match is found there, the command (including the !) is processed normally
	per the above. Note that lines from yak_lines.txt can NOT be combined; they
	are one per admin_yak command.

admin_yak -reload
	Causes the yak_sounds.txt file to be re-loaded. All unsaved sounds are
	cleared. Unsaved words are not cleared.

admin_yak -match <text>
	Useful for finding out what the script knows how to say. This will display
	any words matching the <text>. The search order is yak_lines.txt, unsaved
	words, yak_words.txt then vox_words.txt.

admin_yak -words <line>
	Displays entries from the yak_words.txt file starting at line <line>. If
	<line> is not given, the script starts at line 1. If the output of this
	command is over 20 lines long (which might be 60-70 words), a message is
	displayed telling the user how to get the next set of lines.

admin_yak -vox <line>
	Exactly the same as the -words option above but displays words from the 
	vox_words.txt file.

admin_yak -sounds <text>
	Displays all sound keys (not values) that contain <text>. Unsaved sounds
	are preceeded by a * character.

admin_yak -trysound <key> [<value>]
admin_yak -addsound <key> <value>
	These commands are useful if you are adding new sounds. Instead of exiting
	Half-Life and messing with the yak_sounds.txt file, you can use these to
	try out a new sound while stil in the game. The -addsound option appends
	the key and value to the yak_sounds.txt file, the -trysound option does
	not.

	For example..

		admin_yak -trysound bir birdwell(e30)

	..will speak the first 30% of the word birdwell. If it's not quite what you
	want, just try it again with different values.

	Both commands "speak" only to the player issuing the command - nobody else
	will hear it.

	For the -trysound command, if the key is given without a value, the script
	will try to speak an existing sound.

	See also -savesounds, -flush and -unsaved below.


admin_yak -tryword <key> [<sounds>]
admin_yak -addword <key> <sounds>
	Identical to -try/-addsound above but is used for words. For example..

		admin_yak -tryword antman ant man

	..will speak the sounds "ant" and "man". This, like the commands above, is
	only heard by the player issuing the command.

	For the -tryword command, if the key is given without a value, the script
	will try to speak an existing word.

	See also -savewords, -flush and -unsaved below.		

admin_yak -savesounds
admin_yak -savewords
	These commands simply write any unsaved sounds or words to their respective
	file.

admin_yak -flush
	This command deletes any sounds or words that are in-memory but have not
	yet been saved.

admin_yak -unsaved
	This command displays all the keys and values of all unsaved sounds and
	words that are in-memory. This, in combination with condump, is useful if
	the server has "file_access_write" disabled.



CONFIGURATION:

Two config file variables are added with this plugin. These control the access
level needed by a user to run its commands. These should probably live in your
server.cfg and/or listenserver.cfg files in the mod directory.

	yak_access_level : access needed to run "admin_yak"
	yak_write_access_level : access needed to run the try/add/save commands.

Both variables default to ACCESS_SAY - the same level needed to use "admin_chat".

To function properly, the server MUST have both the allow_client_exec and the
file_access_read configuration variables enabled. 

To use the -addsound, -addword, -savesounds and -savewords options, the server
must also have file_access_write enabled. If you don't want to do this, you can
use the -unsaved option to display unsaved sounds and words then type "condump"
in the console. This will produce a txt file with the current console text.
From this, you can manually (and carefully!) edit the yak_sounds/yak_words txt
files.



LIMITS:

Current limits are:
	256  Maximum number of sounds possible
	 16  Maximum length of a sound key
	128  Maximum length of a sound value
	 24  Maximum length of a word key
	128  Maximum length of a word value
	 32  Maximum number of unsaved words
