first commit

Help/IpToCountry_README.txt

@@ -0,0 +1,275 @@
+IpToCountry 1.6 for Unreal Tournament '99
+
+Initial to v1.2 by [es]Rush
+v1.6 by Matthew 'MSuLL' Sullivan
+
+Release Date: May 21, 2010
+Distributed under the terms of OpenUnrealMod license - see LICENSE.txt for details
+
+Thanks for opening this readme! Please read its contents before asking any questions.
+You can learn:
+-General information about IpToCountry and how does it work
+-How to install and set it on the server
+-How to make use of IpToCountry in your own mod
+
+IF UPGRADING (IMPORTANT!)
+-------
+If you are upgrading from an old version, please see the section 'UPGRADING'
+below. There have been a few important changes you need to be aware of!
+
+CHANGELOG
+-------
+1.6: -Workaround to prevent crashing, improve stability and efficiency.
+     -Trying to switch between query servers no longer fails
+     -Re-added DNS resolution. IP cached in the config, if it changes the mod will re-resolve.
+     -Increased number of query servers to 4.
+
+1.2: -Added a small clientside package to identify AOL's country. Will work for USA/GB/DE players.
+     -Added ErrorLimit variable.
+     -Removed dependency on the DNS resolving system in UnrealEngine which seemed to be crashing the servers.
+      Now all host based query servers have to specify an IP.
+
+1.1: -Fixed the texture package, now it is CountryFlags2, this one should be perfect.
+     -Fixed accessed nones in the Addon part while playing on the server with bots.
+
+1.0: -First version
+
+WHAT IS IT FOR?
+-------
+In short, as the name says, it can resolve a country from an IP address; it also resolves a hostname.
+IpToCountry is meant mainly to be just a shared component between many other mods, for example
+recent versions of SmartCTF, etc. Don't expect much black magic from IpToCountry itself. But to not
+make you sad I've also made a little addon which will show players' country names after doing a
+mutate command, for admins there is a similiar command showing hostnames, this addon is enabled by
+default, but you can disable it in the config.
+
+HOW DOES IT WORK?
+-------
+To your knowledge, resolving a country from an IP requires quite a big database and implementing
+it in UnrealScript would be very hard, thus IpToCountry connects to a PHP script which is located
+on a web server. This PHP script uses a database kindly distributed by www.maxmind.com
+If you want to know how the querying stuff exactly works just "Use the source Luke!"
+
+AOL is quite troublesome. AOL has all its IP ranges registered in the USA and thus it doesn't
+make identification easy. Fortunately Rush found a way to go around the problem.
+Three major countries where AOL is very popular are: USA, Great Britain and Germany. All those three have
+different timezones, so Rush just had to get a player's time and compare it to GMT. The idea maybe was Rush's
+but Cratos was the first to implement it in LeagueAS, Rush got some code from him so big thanks, mate.
+
+WHO USES IT?
+-------
+At the time of writing this readme the following mods/mutators make use of IpToCountry (that I know of...):
+-SuperWebAdmin 0.97
+-LeagueAS140
+-SmartCTF_4D (and up)
+-BTPlusPlusv097
+-Hostname Ban
+-Nexgen
+
+ZIP CONTAINS:
+-------
+README.txt - This file.
+LICENSE.txt - OpenUnrealMod License
+ipToCountry.u - The most important file, has to be in ServerActors - see INSTALLATION
+IpToCountry_AOL.u - it has to be added to ServerPackages in order to activate AOL's country detection
+CountryFlags2.utx - Country flags miniatures, has to be in ServerPackages if any mod needs it
+Source/ - using this source you can modify and adapt IpToCountry to your needs!
+MasterServer v1.6/ - anything related to hosting your own query server
+
+INSTALLATION
+-------
+Add the following line to the [Engine.GameEngine] section of UnrealTournament.ini:
+ServerActors=ipToCountry.LinkActor
+ServerPackages=IpToCountry_AOL
+ServerPackages=CountryFlags2
+
+
+restart server and go to IpToCountry.ini for past:
+
+[IpToCountry.LinkActor]
+QueryServerHost[0]=www.unrealkillers.com
+QueryServerHost[1]=www.wharthog.com
+QueryServerHost[2]=utgl.unrealadmin.org
+QueryServerHost[3]=
+QueryServerFilePath[0]=/iptocountry/iptocountry16.php
+QueryServerFilePath[1]=/iptocountry/iptocountry16.php
+QueryServerFilePath[2]=/iptocountry16.php
+QueryServerFilePath[3]=
+QueryServerPort[0]=80
+QueryServerPort[1]=80
+QueryServerPort[2]=80
+QueryServerPort[3]=
+resolvedAddress[0]=104.21.81.17
+resolvedAddress[1]=141.101.127.154
+resolvedAddress[2]=85.236.100.16
+resolvedAddress[3]=
+
+UPGRADING
+-------
+If you are upgrading from any version prior to 1.6,
+YOU MUST DELETE YOUR OLD IPTOCOUNTRY.INI AND IPTOCOUNTRY.U FILEs FIRST!
+
+I can't stress this enough so we'll do it again:
+YOU MUST DELETE YOUR OLD IPTOCOUNTRY.INI AND IPTOCOUNTRY.U FILEs FIRST!
+
+Alright, now that's taken care of. Otherwise there are no other installation
+changes (the ServerActors= line is still the same).
+
+Put the ipToCountry.u file in the /SYSTEM folder and boot the server.
+No other configuration needed, unless you absolutely want to, in which case you can look at
+the 'CONFIG' section below.
+
+CONFIG
+-------
+After the first server start, ipToCountry.ini should be created. The mod works just fine out of the
+box, but if you wish you can edit the configuration, here are the varibles you can change:
+
+QueryServerHost[0-3]       - This is where you can specify query servers to connect to. The defaults
+QueryServerFilePath[0-3]     work just fine and are updated regularly. If you want to add another
+QueryServerPort[0-3]         query server, just follow convention (eg. just look and see how its done
+                             from the other entries). Query servers are tried sequentially, so the
+                             server in the [0] slot will receive all traffic unless it can't connect.
+
+MaxTimeout  - The amount of time before IpToCountry gives up on requesting data from the server
+ErrorLimit  - IpToCountry will attempt to restart itself if the number of errors reaches ErrorLimit
+bSpawnAddon - whether to use the Addon - should be always enabled unless you want to use IpToCountry
+              in some special way - also read 'NOTE FOR ADMINS' below
+
+NOTE FOR ADMINS
+-------
+Even if you have no mod using IpToCountry yet, you can still make use of it because of the Addon.
+Mutate commands and example results:
+
+> mutate iptocountry
+[es]Rush, Country: POLAND
+LanPlayer, Country: Unknown
+OtherPlayer, Country: GERMANY
+
+And this one works only for an admin:
+
+> mutate iptohost
+[es]Rush, Host: xxx.xxx.xxx.pl
+LanPlayer, Host: 192.168.0.3
+OtherPlayer, Host: xxx.xxx.de
+
+The Addon also automatically resolves new IPs from joining players.
+
+INSTRUCTION FOR DEVELOPERS
+-------
+If you want to use IpToCountry in your mod just learn it from my example class, it is pretty simple
+and doesn't require compiling with the dependency and linking:
+
+# SOURCE STARTS HERE
+class IpDetails extends Actor;
+
+var Actor IpToCountry;
+
+function PostBeginPlay()
+{
+	BindIpToCountry();
+}
+
+function bool BindIpToCountry()
+{
+	local Actor A;
+	foreach AllActors(class'Actor', A, 'IpToCountry')
+		IpToCountry = A;
+
+	// at this point, the variable 'IpToCountry' has
+	// been set and can be used
+}
+
+function string GetIpInfo(string IP)
+{
+	if(IpToCountry != None)
+		return IpToCountry.GetItemName(IP);
+}
+# SOURCE ENDS HERE
+
+Now calling on function GetIpInfo() with a string parameter should return either the data or the status
+of resolving this data, let me show you below. The function returns status codes under a high stress
+(lots of calls). The mod may return any of these values, one after another:
+
+1) "!Added to queue"
+2) "!Waiting in queue"
+3) "!Resolving now"
+4) "!AOL - Trying to clarify"
+
+1) is always returned if IP wasn't in the database
+2) is very rarely returned
+3) is returned if querying takes some time
+4) is returned if the AOL module is currently working
+
+Now when the state 3/4 is done it should report the actual data which is returned in the following form:
+<IP>:<HOST>:<COUNTRY>:<PREFIX3>:<PREFIX2>
+for example "153.19.48.14:lux.eti.pg.gda.pl:POLAND:POL:pl"
+
+Useful data, isn't it?  Well, the function can also report an error:
+1) "!Bad Input"
+2) "!Queue full"
+3) "!Disabled"
+
+When 3) '!Disabled' is returned don't bother to query IpToCountry again, it means that IpToCountry
+is unable to contact any of the query servers or experienced a lot of errors which let to a shutdown
+of IpToCountry to prevent UT server stability issues.
+
+When you got the right data you have to do some string parsing in order to get anything in a useful form,
+you can use for example my SelElem function which is in the LinkActor.uc file in the source.
+
+Now the fun part, when you've got last part of the return string, the 2 char long prefix, for example "pl",
+you can for example display a country flag on a player's hud / scoreboard or however else you want to
+use it in your cool new mod. Use the CountryFlags2.utx file and just do DynamicLoadObject on
+CountryFlags2.<prefix>
+
+For example, CountryFlags2.pl is a small flag of Poland. The textures are of size 16x16, but the bottom 6 pixels
+are masked and shouldn't matter, so the visible size of the textures is 16x10. Remember that CountryFlags2
+will have to be added to the ServerPackages, so notify users about it in your instructions.
+*You can look at SmartCTF_4D country flags code if you don't have a clue how to make it work :)
+
+A NOTE ON THE HTTPCLIENT CLASS (FOR DEVS ONLY)
+-------
+UT's implementation of a strong, stable HTTP Client wasn't much of a success. Thankfully Rush and
+AnthraX took some time and made great progress on a UScript-based solution for the original
+builds of IpToCountry. Problem is: if both query servers went down, or the internet stopped working for
+just a little while, the entire UT server process would often die.  In September 2008 I
+(MSuLL) began working on a mod that would depend on strong HTTP communications, which became the mod
+'Universal Unreal'.  I used Rush's IpToCountry HTTP Client implentation as a base, then went about refining
+it and making it more stable and efficient.
+
+One big issue with the old client was that everything was being performed from the HTTP Client class,
+and that class was spawned as a ServerActor at startup. When something screws up, the HTTP Client class,
+which is based off of UBrowserHTTPClient, can't re-bind a port properly.  The solution is to kill the
+HTTP Client class and start another instance upon a critical bind error.
+
+For v1.6(+future editions) of IpToCountry, I've ported (or un-ported?) my HTTP Client implementation
+back into the mod where it all began.  I've separated it into three main parts.  The LinkActor class
+does error handling and general data management.  The HTTPClient class does the grunt work and can be
+killed off (and then restarted) when critical errors are encountered.  The third class is the Addon
+class, nothing major has changed in this class though.
+
+I'd encourage developers to make use of this improved HTTP Client implementation in your own
+mods.  Even though this game is 11 years old, there's still time for cool new stuff to be built :D
+The class is very modular and shouldn't be too hard to understand / modify / etc.  Feel free to
+ask for help in the UnrealAdmin.org forum, and I'd be glad to help.
+
+THANKS TO
+-------
+AnthraX - for overall help, consultations and helping UT'99 community so much, thanks mate!
+ Also thanks for updating the query server
+
+teleport*bR - thanks for the great help in putting the texture package to one, thanks also for testing
+Cratos - for supporting IpToCountry in LeagueAS and giving me some code to identify AOL's timezone
+UnrealAdmin - for keeping UT alive
+
+SPECIAL NOTE
+-------
+Starting at version 1.6, I (MSuLL) will be trying to support this mod through updates and bugfixes, as Rush
+has since moved on from UT and Unreal coding. Rush created the initial versions and did an excellent job.
+Most of us (coders) didn't even know such magic was possible until this mod was created and refined.
+To both Rush and AnthraX: thank you so very much for your contributions to this mod, and to the UT
+community in general. We, the players and admins of UT, deeply appreciate it and thank you for your efforts!
+
+CONTACT & FEEDBACK
+---------
+UnrealAdmin.org forums:
+http://www.unrealadmin.org/forums/showthread.php?t=29924

Readme.md

@@ -0,0 +1,3 @@
+# Smart ScoreBoard / SmartSB Release GIT repository
+
+checkout official release thread: https://ut99.org/viewtopic.php?f=7&t=13754

Run.sh

@@ -0,0 +1,100 @@
+#!/bin/bash
+
+SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+OUTPUT_DIR="$2"
+CFG_FILE="$3"
+DEFAULT_CFG_FILE=UnrealTournament.ini
+
+
+function install() {
+	cp $SCRIPT_DIR/Help		$OUTPUT_DIR/Help		-R
+	cp $SCRIPT_DIR/System	$OUTPUT_DIR/System		-R
+	cp $SCRIPT_DIR/Textures $OUTPUT_DIR/Textures	-R
+	
+	echo install ok
+}
+
+function enable() {
+	SSBUFile=$(find $OUTPUT_DIR/System -type f -iname "SmartSB*.u" ! -name "SmartSBStats.u" -exec basename {} \;)
+	SSBBaseName="${SSBUFile%.*}"
+	
+	# Warning: ugly hack with sed to allow multiple key instances
+	crudini --set $OUTPUT_DIR/System/$CFG_FILE 'Engine.GameEngine' _ServerPackages $SSBBaseName
+	sed -i 's/_ServerPackages/ServerPackages/g' 	$OUTPUT_DIR/System/$CFG_FILE
+	
+	crudini --set $OUTPUT_DIR/System/$CFG_FILE 'Engine.GameEngine' _ServerPackages SmartSBStats
+	sed -i 's/_ServerPackages/ServerPackages/g' 	$OUTPUT_DIR/System/$CFG_FILE
+	
+	crudini --set $OUTPUT_DIR/System/$CFG_FILE 'Engine.GameEngine' _ServerActors $SSBBaseName.SmartSBServerActor
+	sed -i 's/_ServerActors/ServerActors/g' 	$OUTPUT_DIR/System/$CFG_FILE
+	
+	echo enable ok
+}
+
+function disable() {
+	SSBUFile=$(find $OUTPUT_DIR/System -type f -iname "SmartSB*.u" ! -name "SmartSBStats.u" -exec basename {} \;)
+	SSBBaseName="${SSBUFile%.*}"
+	
+	sed -i "/ServerPackages[[:space:]]*=[[:space:]]*$SSBBaseName/d" $OUTPUT_DIR/System/$CFG_FILE
+	sed -i "/ServerPackages[[:space:]]*=[[:space:]]*SmartSBStats/d" $OUTPUT_DIR/System/$CFG_FILE
+	sed -i "/ServerActors[[:space:]]*=[[:space:]]*$SSBBaseName.SmartSBServerActor/d" $OUTPUT_DIR/System/$CFG_FILE
+	
+	echo disable ok
+}
+
+function show_help() {
+	echo
+	echo "Usage: $0 { install | enable | disable } <UT99_INSTALL_DIR> [<UT99_CONFIG_FILE>]"
+	echo
+}
+
+function check_cfg_file() {
+	if [ -z ${CFG_FILE} ]
+	then
+		echo "CFG_FILE is unset, setting it to $DEFAULT_CFG_FILE"
+		CFG_FILE=$DEFAULT_CFG_FILE
+	else
+		echo "CFG_FILE is set to '$CFG_FILE'"
+	fi
+
+	if [ ! -f $OUTPUT_DIR/System/$CFG_FILE ]
+	then
+		echo "$OUTPUT_DIR/System/$CFG_FILE does not exist"
+		show_help
+		exit 9999 # die with error code 9999
+	fi
+}
+
+function check_game_dir() {
+	### Check if a directory does not exist ###
+	if [ ! -d $OUTPUT_DIR ]
+	then
+		echo "incorrect <UT99_INSTALL_DIR>"
+		show_help
+		exit 9999 # die with error code 9999
+	fi
+}
+
+case "$1" in
+	'install')
+			check_game_dir
+			install
+			;;
+	'enable')
+			check_game_dir
+			check_cfg_file
+			disable
+			enable
+			;;
+	'disable')
+			check_game_dir
+			check_cfg_file
+			disable
+			;;
+	*)
+			show_help
+			exit 1
+			;;
+esac
+
+exit 0