BOT  PATH  NODE  USAGE

Description

The purpose of this Unreal Tournament mod/mutator is analyzing the bot usage of the path network of a map.


Once a match is started with the BPNU mutator activated, a BPNUTrigger (I'll refer to it as Trigger from now on) will be added on top of every NavigationPoint actor (and of course all its subclasses, like PathNode, LiftExit, InventorySpot, PlayerStart, etc.).
Every time a bot passes on the trigger an internal counter (which I'll call ContactCount from now on) will increase.

A player can then use one of the different Results console commands (like "Mutate BPNU Results" or "Mutate BPNU Inventory"), to activate the following procedure:

• All the triggers of the specified category get scanned, and the minimum and maximum ContactCount values get stored
• Basing on the Min and Max values the relative percentage of each Trigger gets calculated
• Triggers are made visible and get assigned a texture that represents their percentage (those which have the Min and Max ContactCount will get a MN/MX texture, the others will get a number)

If for example you see a trigger with an 85 texture it means that the relative trigger has been touched about 85% of the times compared to the Trigger with the maximum ContactCount. Textures are color-coded, the lower percentages are blue while the higher are red.
The triggers that haven't been touched by bots will get a 0 texture (white text with black background).

The percentage for each trigger gets calculated with the formula "(ContactCount - Min) / (Max - Min)", it isn't very intuitive but it provides percentages that aren't affected by how long the match goes on.


By roaming around the map and checking the different numbers you can get an idea of which spots of the map the bots prefer to roam and which places are used rarely (or not at all). There are lots of maps where the action occurs mostly in a few places (for example in DM-Grinder the Rocket Launcher area is used way too often), reworking the pathing to make the path usage more balanced will make the map much more fun to play with bots.
The results are pretty accurate considering bots act randomly, if you let matches go on for a long time the percentages between different tests will be very similar.

The Average percent value can be used to "rate" a map's pathing, generally in my tests I noticed that maps with good balance had about 25% average in the global results and 50% in the PlayerStart results. Keep in mind that these results alone aren't indicative of a good pathing, since maps with very few pathnodes are going to score better.


An extra feature (that might cause some false positives, especially with few bots playing) is the detection of "frozen" nodes, basically the places where bots keep getting back and forth between two nodes until they sight an enemy. These nodes get marked with a F texture (white text with red background), and by default they are not taken into account when calculating the Max and Min ContactCount values.
Right now this feature works only when a single bot is stuck, so it is less effective in team games. It also creates LOTS of false positives if there is only one bot in the game in a small map (you can disable this feature by setting bFrozenDetect to False in the .ini File).


This mod has been tested online briefly, it doesn't affect gameplay in any way (I didn't add replication so triggers aren't made visible) so it would be pretty pointless to add it to a server. Be aware that every player (not only admins) will be able to access the mutate commands.


The mod is in beta state, there are some features missing (the trigger textures will also be replaced with something prettier) but I tried to polish and test it quite thoroughly.

Enjoy

Installation

Unzip BotPathNodeUsageV072.zip, then copy the files into your Unreal Tournament\System folder.

Then select Bot Path Node Usage in the mutator menu to activate it for the next match.

How To Use

First step is selecting the mutator in the mutator list when starting a match.
I recommend setting both time and score limit to 0 (infinite), and using the highest number of bots that the map supports.

Bots will have to play for a while (at least 10 mins I'd say) before producing meaningful results, the longer the match is the more reliable the results will be.
You can play the match yourself together with the bots, but I would recommend to either spectate the match or use the "ghost" command and exit the map area, so that you will not interfere with the results.

Speeding up the game with the command slomo (for example "slomo 4") is very useful, since you can get proper results in a matter of few minutes.


When enough time has passed either freeze ("playersonly" command) or kill ("killall bot" command) the bots, and check the results using one of the many commands of this mod (for example for global results use "mutate BPNU Results"). Triggers of the specified category will be made visible, and a report will be printed in the game console. Walk/Fly/Ghost around the map to see the numbers assigned on each trigger.
Check the Command List section below for a list of all the available commands. The "mutate BPNU Help" command will print a list of the commands in the game console.

This mod is handled entirely with "mutate" console commands. I recommend setting some key bindings to avoid retyping a lot of text (for example "set input y mutate BPNU Results" will set the Results command to the Y key).

Command List

This is a list of all the commands available in the Mutator, use them by writing "mutate BPNU <command>" in the game console (for example "mutate BPNU Inventory", "mutate BPNU Summary", etc.). They are not case sensitive.

Help will print on the game console the list of commands available (without the short description found here).

Results

• Results - Calculates the results, prints a report in the game console and makes all the BPNU Triggers visible
• PathNode - Works like Results but considers only triggers attached to PathNode Actors
• Inventory - Works like Results but considers only triggers attached to InventorySpot Actors
• Alternate - Works like Results but considers only triggers attached to AlternatePath Actors
• Lift - Works like Results but considers only triggers attached to LiftCenter and LiftExit Actors
• Custom - Works like Results but considers only the triggers that have been manually added by the player (either in UEd or using the "Add" command)

Other Results

• PlayerStart - Calculates and prints the results of PlayerStart Actors, but instead of ContactCount it uses the number of spawns (players included) that took place at each PlayerStart
• Unused - Counts and shows all the Navigation Points that haven't been touched by a bot
• Frozen - Works like Results but takes in account only the triggers marked as Frozen
• Summary - Prints on the console a "summary" with the number of triggers in each percentage range

Trigger Functions

• Hide - Hides all the triggers
• RealTime - Toggles the RealTime function, the triggers will get their texture updated every few seconds
• Reset - Resets all the triggers (sets their ContactCount to 0) and hides them, basically returns them to the state they were at the start of the match
• Check - If the player is touching a trigger, it will print on the console its values
• Add - Adds a new trigger at the player's location, with the "Custom" tag
• Delete - If the player is touching a trigger with "Custom" tag, it will remove it from the game
• Clear - Removes all the triggers with "Custom" tag from the game

Appearance

• Size <X> - Sets/increases/decreases the size of the triggers. Replace <X> with + and - to increase/decrease the size, or XXS/XS/S/M/L/XL/XXL/XXXL to set the specific size
• Scale <X> - Doubles the size of the triggers with the specified texture. Replace <X> with Zero, Min, Max, Frozen, Ex
• Translucent - Toggles the translucency of the triggers

Configuration File

This is a list of all the variables that can be modified in the BotPathNodeUsage.ini File. I tried to make the mod as configurable as possible, so there are quite some values.
They are mostly advanced settings that you can very well ignore.

They can also be modified in-game using the "set" command (for example "set BotPathNodeUsage.BPNUMutator bSilentResults true"), or you can run the game in windowed mode and use the "editactor class=BotPathNodeUsage.BPNUMutator" and "editactor class=BotPathNodeUsage.BPNUTrigger" commands to browse all the properties in an external window.

Mutator Variables

• bTraditionalRatio - Bool, whether to use (ContactCount / Max) without considering Min when calculating the percentage
• bAltPlayerStarts - Bool, whether to use the spawn detection instead of ContactCount in PlayerStart results
• bFrozenDetect - Bool, whether to detect frozen nodes
• bFrozenSums - Bool, whether frozen nodes are counted in the percentage calculations
• bSilentResults - Bool, if True result reports will not be printed on the game console
• bLogResults - Bool, if True result reports will be logged in the UnrealTournament.log File

• bSetSizeValues - Bool, whether to change the height and radius of the triggers
• TriggerHeight - Float, new height of the triggers
• TriggerRadius - Float, new radius of the triggers

• DrawScaleBase - Float, base default DrawScale of the triggers
• DrawScalePS - Float, multiplies the DrawScale of the triggers attached to PlayerStart Actors
• DrawScaleSpecial - Float, multiplies the DrawScale of the triggers with "special" values (Zero, Min, Max, Frozen, Ex)

• TriggerSize - String, Default trigger Size (can be XXS, XS, S, M, L, XL, XXL, XXXL)
• SizeXXS - Float, DrawScale applied on Size XXS
• SizeXS - Float, DrawScale applied on Size XS
• SizeS - Float, DrawScale applied on Size S
• SizeM - Float, DrawScale applied on Size M
• SizeL - Float, DrawScale applied on Size L
• SizeXL - Float, DrawScale applied on Size XL
• SizeXXL - Float, DrawScale applied on Size XXL
• SizeXXXL - Float, DrawScale applied on Size XXXL
• bTranslucent - Bool, whether the triggers are Translucent

• bRealtime - Bool, whether the RealTime function is active at the start of the match
• bRTSilent - Bool, if True result reports generated by the RealTime function will not be printed on the game console
• bRTNoLog - Bool, if True result reports generated by the RealTime function will not be logged in the log File
• RTFrequency - Float, time (in seconds) between each RealTime update

Trigger Variables

• ReTriggerDelay - Float, time (in seconds) to pass before a bot touch can increase the counter again
• bDetectNames - Bool, if True the trigger can be activated by a bot with a different name without waiting the ReTriggerDelay

• ChainSize - Int, Number of times a bot has to touch this trigger continuously before increasing the freeze chain number
• ChainNumber - Int, Number of freeze chains necessary to mark this trigger as Frozen
• bResetFreeze - Bool, if True the freeze chain will get reset if ResetDelay time has passed
• TimeWindow - Float, time (in seconds) in which the contact of the same bot increases the freeze chain
• ResetDelay - Float, time (in seconds) to pass before resetting the freeze chain

Mutator Extra (accessible only in-game)

• ExcessRatio - Float, multiplies the ratio of every trigger (using "percentage * (1.0 + ExcessRatio)"), useful if you want to exclude a few nodes that hog all the high percentages. The excluded nodes will get an EX texture
• RTType - String, RealTime result type (set automatically by the different Results calls)

Details

Credits

Big thanks to Feralidragon for helping me in making the spawn detection work and clearing some doubts I had about UnrealScript.

Stats

Copyright

This mod is copyright 2013, by DeathoX 8.
You may NOT decompile this mod or use it as a base for any other additional mods without explicit permission from the Original Author.
You are NOT allowed to commercially exploit this mod, i.e. put it on a CD or any other electronic medium that is sold for money without my explicit permission!
You MAY distribute this mod through any electronic network (internet (web/ftp), FIDO, local BBS etc.), provided you include this file and leave the archive intact.
Unreal® Tournament (c)1999 Epic Megagames, Inc. All Rights Reserved. Distributed by GT Interactive Software, Inc. under license. Unreal Tournament and the Unreal Tournament logo are registered trademarks of Epic Megagames, Inc. All other trademarks and trade names are properties of their respective owners.