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 Will try to "speak" the . 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 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 Useful for finding out what the script knows how to say. This will display any words matching the . The search order is yak_lines.txt, unsaved words, yak_words.txt then vox_words.txt. admin_yak -words Displays entries from the yak_words.txt file starting at line . If 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 Exactly the same as the -words option above but displays words from the vox_words.txt file. admin_yak -sounds Displays all sound keys (not values) that contain . Unsaved sounds are preceeded by a * character. admin_yak -trysound [] admin_yak -addsound 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 [] admin_yak -addword 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