                         *** ReportDirection v1.22 ***

                      By Olethros <olethros@broadpark.no>


	DESCRIPTION

ReportDirection is a mutator for UnrealTournament that will enable players to 
tell teammates the direction to a sighted enemy. Basically, whenever a player 
sends a "mutate reportcontact" command, he/she will send a teammessage 
containing the word "Contact!" and his/her current heading. If, f.ex. a player 
is facing 173 degrees and sends a "reportcontact" command, the message "Contact! 
Bearing 173 (S)!" will be sent to either the whole team, or only to a previously 
specified teammate.

The command "mutate direction <message>" will enable you to include your
current heading in any text message you may want to send. Using C-style
replacement tags you can interleave text and headings nearly any way you want.

The replacement tags are as follows:
	%n - Your three-digit (N)umerical heading. F.ex. "318"
	%c - Your (C)ardinal heading. F.ex. "northwest"
	%a - Your (A)bbreviated cardinal heading. F.ex. "nw"
	%r - Your (R)eversed cardinal heading. F.ex. "southeast"
	%v - Your re(V)ersed abbreviated cardinal heading. F.ex. "se"
	%l - Your heading as a clock direction. F.ex. "12"
	%o - Toggle old 8-way cardinal names.

The %n, %c, %r and %v tags are case-sensitive in relation to their replacement
text. I.e. %n may give "north" while %N will give "NORTH" and so on.

The replacement tags can be in any order and repeated as many times as you wish 
(except sound message tags, where only the one appearing LAST will be heard), 
provided that neither the message- nor the resulting string are more than 255 
characters long. If your message does not contain any '%'-characters, the 
numerical and abbreviated cardinal heading will be added to the end of it. I.e. 
the same result as "mutate direction <message> %n (%A)!"

From version 1.20 the tag "%o" (case insensitive) can be added to the 
'direction' message to make any subsequent cardinal heading tags use the old 8 
direction names (N-NE-E-SE-S-SW-W-NW) rather than the new 16-direction system 
introduced in v1.19. The tag will by itself not produce any output. (Note: The 
%o tag must come BEFORE any %n, %c, %r or %v tags you want to use the 8-way 
direction names.) Example: If you are facing 20 degrees, %c will produce "north 
by northeast" while %o%c will produce "north."

Sound tags will send a pre-defined sound to be played along with the text 
message. The tags themselves will not appear in the message, and can be placed 
anywhere. All message sound tags have the format of	"%S<hex digit>" where
<hex digit> can range from "0" to "F".

There are four kinds of sound tags:
    %b           Message beep ON.
    %SY          Play Sender.voiceType.AckSound[0] to sender and receiver(s).
    %S0 to %SF   Play Sender.voiceType.OtherSound[0] through OtherSound[15] to
                 sender and receiver(s).

And from v1.21 on, extended sound tags can be used with the %S parameter:
	0x00 to 0x1F - Play Sender.voiceType.Othersound[0] through [31]
	0x20 to 0x2F - Play Sender.voiceType.AckSound[0] through [15]
	0x30 to 0x3F - Play Sender.voiceType.OrderSound[0] through [15]
	0x40 to 0x4F - Play Sender.voiceType.FFireSound[0] through [15]
	0x50 to 0x6F - Play Sender.voiceType.TauntSound[0] through [31]
	
Example: "Mutate direction Copy that!%S0x21" will play the AckSound[1] voice
message along with the text.
	
Just remember to use EXACTLY two hex digits after '0x' or shit will happen.

Use the command "mutate rdsound" in-game to get a list of available sounds in
your voicepack.

Most sound tags should be available under any UnrealTournament-derived games, but
their actual contents may differ. (Except %SY and %SB, which should always be
the same.)

Some example commands that could be useful:
	"mutate direction Enemy flag, bearing"
		=> "Enemy flag, bearing 355 (N)!"
	"mutate direction Look out! Sniper at %l o' clock!"
		=> "Look out! Sniper at 12 o' clock!"
	"mutate direction I'm in position, facing %C."
		=> "I'm in position, facing NORTH."
	"mutate direction I'm heading %C. %n degrees."
		=> "I'm heading NORTH. 355 degrees."
	"mutate direction Watch out for enemies coming from the %C."
		=> "Watch out for enemies coming from the NORTH."
	"mutate direction Nade the building %c of my position.%b
		=> "Nade the building north of my position."
	"mutate direction My health is below 50%%. I'm retreating %c."
		=> "My health is below 50%. I'm retreating north."

Notice that in the last example I wrote '50%%'. Whenever you want a '%'
character in your message, you'll have to write '%%'.

This mutator contains no compass display feature. It is designed to work with 
any compass mutators that use the Unreal engine's Object property Rotation.Yaw=0 
for "North". INFCompass and INFNewCompass by Cpt. Pathetico, INFCompass2 by The
Keganator and my own INFMovementLocator are three such mutators.

At the start of a game your recipient will by default be set to the entire team. 
The command "mutate changefreq" will let you select a teammate to whom your 
subsequent "Contact" or "Direction" calls are made exclusively. Each time the 
"changefreq" command is issued your recipient will be set to your next teammate 
as they occur in the level's pawnlist. If the end of the pawnlist is reached, 
your recipient will be reset to "Entire Team" and the next call to "changefreq" 
will traverse the pawn list from the beginning again. The main purpose of this 
feature is to cut down on unnecessary "radio chatter" when players operate in 
pairs, f.ex. as sniper/spotter teams.

From v1.11 on, you will have the ability to select degree or gradian compass
factors. By default, your preferred factor will be set to Degrees.

If you transmit to the entire team, your own factor will be used. If you 
transmit to a specific team mate, his preferred factor will be used. Likewise, 
if you receive a transmission from a teammate who has "tuned" to your specific 
"frequency", you will receive the call in your preferred compass factor. 
Cardinal headings are, naturally, not affected by this.


	INSTALLATION

To install, simply copy the files "ReportDirection.u" and "ReportDirection.int" 
to your "UnrealTournament\System" directory.

To set up key bindings for direction reporting and "frequency changing", open 
UT's key config window and scroll down until you see the "ReportDirection" 
section. To set these keys manually, open up a console window and type:
	set input <key> mutate reportcontact
	set input <key> mutate changefreq
Where <key> is the key you want to bind the commands to. If you type "mutate 
rdhelp" you will get a list of available commands if you need a reminder.

NOTE TO ADMINS: This mutator is server-side ONLY. To avoid those pesky
"Version Conflict" errors, ReportDirection.u should NOT be included in
the "Serverpackages=" statements.


	UPDATING

From all previous versions: Replace "ReportDirection.u" in your
UnrealTournament\System directory with the new one in this archive.


	TECHNICAL INFO

*	The maximum number of human players in a game supported by the
	"frequency selection" feature is 32. This means that only the first 32 
	players in a game will be able to select a specific teammate with
	whom to communicate. The rest will be stuck with "Entire Team" as
	recipients.
	
	
* Complete list of commands:
mutate reportcontact
	Sends a "Contact! Bearing <direction>!" message.
mutate direction <message>
	Sends a message that can either have the sender's direction embedded using
	C-style replacement tags or - if no such tags are used - appended in the
	format of "<message> <degrees> (<abbreviated cardinal heading>)!".
mutate changefreq
	Cycles through teammates to whom contact messages should be 
	sent exclusively.
mutate rdfactor
	Toggles between Degree (360) or Gradian (400) compass factors.
mutate rdhelp
	Prints a list of the mutator's available commands.
mutate help
	Reminds you that you should type "mutate rdhelp" to get help with this
	particular mutator.
mutate rdsound
	Prints a list of the player's voicepack's available sound tags for use
	with the %S<hex-digit> tag.
mutate rdinfo
	Prints the current server configuration options.
mutate rdoffset <number>
	(Admins only.) Sets the current map's definition of "North" (e.g. 0
	degrees.) I.e. "rdoffset 90" would literally turn the compass rose
	clockwise ny 90 degrees, making east the new north.
mutate rddebug
	Prints some debug info. Specifically, who all players have selected as
	recipients of messages. You must be logged in as administrator to use
	this command.
mutate rdtest <number>
	Used during development to convert numbers form hex do decimal or
	vice-versa. (Hex numbers always start with '0x') Examples:
	'mutate rdtest 16000' will give you the hex number 0x3E80 and
	'mutate rdtest 0xFF' will give you a decimal number of 255.


	COPYING

As long as the original archive remains intact and NOTHING is charged for it,
this program can be distributed freely.

If you want the source code, decompile it with ucc's -batchexport commandlet
or, failing this, drop me a mail and ask me nicely for it.

Anybody can use parts of the source code in their own programs PROVIDED THEY
ARE ABSOLUTELY 100% FREEWARE. Not shareware, not adware, not 'nagware,' nothing
of the sort! Voluntary donations are acceptable, but ONLY if donating makes NO
functional difference whatsoever to the distributed program. 'Personalised'
versions (i.e: copies 'branded' with donator's name) are OK, though.)


	HISTORY
1.22
	* Added map-specific compass adjustmend option. For maps where the visuals
	  (i.e. position of the sun, sea level et al) don't confirm to using
	  rotation.X = 0 as north. 
	
1.21
	* Added extended hex digits to the %S tag. Now RD is capable of playing
	  every single message that exists in the player's voicepack.
	* Completely rewritten hex parsing routines.
	
1.20
	* Added the %o tag to decrease number of cardinal headings.
	* Changed the %l tag to output clock directions.
	* Limited number of tags available per message to 32. Just in case some
	  disturbed individual gets the idea to send absurdly long messages to
	  strain the server.
	
1.19
	* Adapted the "mutate reportcontact" command for Infiltration 2.9.
	* Added more cardinal headings to compensate for the lack of a numerical
	  compass in Infiltration 2.9.
	* Made cardinal and abbreviated heading tags case-sensitive. Mainly to
	  reduce message string lengths as they appear on the HUD.
	* Added the %v/%V tag for reverse abbreviated heading.
	* Added the "mutate rdsound" command to list the player's voicepack's
	  otherString[] array rather than the normal help text.
	
1.18
	* Cleaned up the help text. Added generic listing of player's voicepack's
	otherString[] array to list available vocal messages no matter what
	voice type the player uses. All custom voicepacks should be supported.

1.17
	* Added the %SY tag for the "Acknowledged" voice message.
	* The "mutate direction" command is now usable in normal UT games as well,
	unless the player is using a custom voicepack.
	* Changed: Some more safeguards against overlap in voice messages.
	Basically, you'll have to wait 2.5 seconds after sending a voice message
	until you send another one, or it will be without sound.

1.16
	* Added: Sounds. The first 16 sounds, as defined in the ChallengeVoicePack
	variable OtherSound[] may now be broadcast along with the text messages.
	* Added: The %r tag.
	* Changed: The "mutate reportContact" command now uses the form
	"Contact! <cardinal direction> at <numerical direction> degrees!"
	and will also send the sound defined in ChallengeVoicePack.otherSound[2],
	which is the word "Contact" in INF voice packs.

1.15
	* Fixed: The %b tag not having any effect when broadcasting to a
	particular teammate.

1.14
	* Added: The %x, %y and %z tags.

1.13 BETA
	* Changed: The cardinal headings are more closely matched to those
	reported by INFNewCompass and INFNewCompass2.
	* Added: The %b tag.
	* Dead players should no longer be able to send messages to living ones.
1.12 BETA
	* Fixed: Resetting yaw value now correct. Should no longer receive
	negative yaw values and interpret them as "North".
	* Added: A new replacement tag for debugging purposes. %l will be
	replaced by the sender's heading in "Unrealdegrees".
1.11 BETA
	* Added: The ability to use either degree or gradian compass factors.
	* Added: Mutate command "direction" which accepts C-style replacement
	tags.
	* Changed: Assigning frequency slots is more "dynamic".
	* Changed: "mutate rddebug" no longer prints empty frequency slots.
	
1.10 BETA
	* Fixed: "Contact" calls made to a specific teammate should now be
	echoed to the sender correctly.
	* Changed: The "mutate rddebug" command is no longer limited to admins.

1.10 ALPHA
	* Fixed: An ever so slight typo that caused Sender.direction.yaw to be
	  divided by 182.4 rather than 182.04 which caused the occasional 1
	  degree difference between INFMovementLocator's compass and the
	  "Contact!" messages.
	  * Added: The ability to select an exclusive recipient of the
	  "Contact!" messages.

1.0
	* Original release.


	ACKNOWLEDGEMENTS
(In totally random and probably severely unjust order)
	
* {GD}Ghost for putting this mutator on {GD}1 mere hours after its release.
* The people on {GD}1 who helped iron out the bugs in v1.10 ALPHA.
* The Keganator for including this in R.A.I.L.
* C.E.R.T. Boy for making me realize there was a demand for this  mutator.
* MadWoffen for requesting the "mutate direction" feature and general nagging.
* The mappers who gave me the info on Unreal maps maximum sizes.


	FUTURE PLANS
	
* Whatever suggestion I deem worthy that's either sent to olethros@broadpark.no
  or posted in the INF forums at forums.beyondunreal.com
