####################################################################################################
##
##  Nexgen Player Lookup System
##  [NexgenPlayerLookup112 - For Nexgen 112]
##
##  Version: 1.0
##  Release Date: March 2012
##  Author: Patrick "Sp0ngeb0b" Peltzer
##  Contact: spongebobut@yahoo.com  -  www.unrealriders.de
##
####################################################################################################
##   Table of Content
##
##   1. Introduction
##   2. About
##   3. IMPORTANT NOTICE
##   4. Additional information
##   5. Server Install
##   6. Credits and thanks
##   7. NexgenPlayerLookup vs. UniversalUnreal
##   8. Info for programmers
##
####################################################################################################


####################################################################################################
##
##  1. Introduction
##
####################################################################################################
This is a plugin which I have developed for more than a year now. I never released it to the public,
I ran it only on my server and over the time I added more and more features, elimiating bugs and more.
I just thought now is the right time to give it to you guys out there, benefit from it just as I did.


####################################################################################################
## 
##  2. About
##
####################################################################################################
Nexgen Player Lookup System is a plugin for the NexgenServerController which collects many
information about all players who ever connected to your server. The saved information consists of:

- Player Names
- Player IPs
- Player Hostnames
- Actions against this player (amount of warnings/mutes/kicks/bans)
- Number of visits on your server
- Last visit timestamp

For identifying, NexgenPlayerLookup uses the unique Nexgen ID of every player.

... but wait, this is not all:

The main advantage of NexgenPlayerLookup is that it doesn't require any additional resources (like
a web database), ofcourse except Nexgen. You can run this directly and only on your server!
The database is able to store a maximum of 15.000 entries. Besides this, the plugin comes with a
powerful in-game tab located in the NexgenServerController. You can give your admins the right to
use this tab, which will give them access to the complete database, including searching modes for
Nexgen IDs, Player Names, Player IPs, and Player Hostnames!


####################################################################################################
##
##  3.IMPORTANT NOTICE (PLEASE READ THIS CAREFULLY BEFORE INSTALLING/COMPLAINING)
##
####################################################################################################
The fact that the plugin's database with more than 10.000 (!) possible entries is saved on the
gameserver directly has positives- as well as negatives aspects for the user. As stated before,
no additional requirements are needed to run this mod (except Nexgen). As a plus, searching
through the database is faster and more efficient than requesting the data first from a webserver.
These are the most positive aspects, now come the negative ones.

____________________________________________________________________________________________________
PLEASE READ THIS CAREFULLY, BECAUSE I DON'T WANT TO BE ASKED THIS OVER AND OVER AGAIN:

UnrealTournament's netcode wasn't created to replicate such huge arrays of data. Therefore, you will
most likely suffer from one of these issues:

- When requesting ALL data, the gameplay seems to stop and you are feeling like lagging out. THIS IS
  COMPLETELY NORMAL! As I said, the netcode isn't able to handle the replication of that many data
  in such a short time, and therefore the replication of other things (like the gameplay) has to be
  stopped for the time the data is sending. This ONLY affects the requester of the data (= the admin),
  the server and the other players will neither suffer from lag nor performance issues.
  Usually, the lag will end a few moments after all data has been transfered. I say usually because
  there are many things influencing the transfer and the lag: Your connection, the server's
  connection, your specified transfer speed and (important) the size of your database. The larger it
  gets, the longer will be the transfer time and so will be the lag. On my database, which now
  consists of more than 8000 entries, my loading time to receive all data is around 1 minute, while the
  lag still remains for 30 seconds after the transfer has completed.
  Therefore I advise you, be prepared for the lag if you want to receive all data, best thing is to
  go in spectator mode so you don't idle in the game.
  Note that you can directly influence the transfer speed by changing the slider in the panel. This
  will slow/speed up the transfer and the resulting lag.
  
Due to this lag I implemented another feature: The online Player Data transfer. This feature will
only send the data of the players who are currently online (which is a max. amount of 32 players
+ spectators), and therefore will speed the transfer up a lot (~ 1-10 secs total transfer time) and
also minimize the lag if not even eliminate it completely. You can either request the data manually
from the control panel (Button 'Request online data'), or you can keep the data in syncronisation
by selecting the 'Send online player data' checkbox. This will automatically transfer the data of
the current online players on your join to you, plus it will automatically update if a new player joins.

- Again depending on the connections, the database size, and the individual entry size you may suffer
  from a very very small lag spike when a new player joins and his data is automatically synced.
  If you have problems with it, you can simply deactivate it by deselecting the checkbox in the control
  panel.
  


####################################################################################################
##
##  4. Additional information
##
####################################################################################################
'HOSTNAMES':
To allow the plugin to save the hostnames of the players, you need to have IpToCountry installed!
You can grab the latest version from here: http://www.unrealadmin.org/forums/showthread.php?t=29924
(Developed by [es]Rush and MSuLL).
Note that you don't have to run IpToCountry in order to use this plugin, if you don't use it
hostnames will not be saved, but all other functions will still work!

'WARNINGS':
As you may have wondered, I mentioned 'warnings' when I was talking about the feature of saving the
amount of actions against a player. If you ask yourself 'There is a warning feature integrated in
Nexgen?!' - Well, here's your answer: Over the last years, I developed some plugins for Nexgen,
which I only used on my own server (just as this plugin). One of them is also a simple warning plugin
for Nexgen, so I integrated this feature so it also safes the amount of warnings.
Stay tuned, I'm planning to release the plugin soon, so you can also use it and benefit from the
compatibility between the two plugins. Check www.unrealadmin.org regulary! ;)
  



####################################################################################################
## 
##  5. Server Install
##
####################################################################################################
 1. Make sure your server has been shut down.

 2. Copy the NexgenPlayerLookup112.u file to the system folder of your UT
    server.

 3. If your server is using redirect upload the NexgenPlayerLookup112.u.uz file
    to the redirect server.

 4. Open your servers configuration file and add the following server package:

      ServerPackages=NexgenPlayerLookup112

    Also add the following server actor:

      ServerActors=NexgenPlayerLookup112.NexgenPlayerLookup

    Note that the actor should be added AFTER the Nexgen controller server actor
    (ServerActors=Nexgen112.NexgenActor).
    
    Also note that if you want to use the Hostname lookup feature, the plugin's ServerActor must be
    loaded AFTER the IpToCountry.LinkActor ServerActor.

 5. Restart your server. If the installation was succesful, you can now assign a new admin right
    to the registered accounts on your server ('Perform player lookups'). The Lookup control panel
    will then be located under Nexgen's 'Game' tab.


####################################################################################################
## 
##  6. Credits and thanks
##
####################################################################################################

- Defrost for developing Nexgen. Without his previous work I would have never come so far, many
  thanks!

- Thanks to Matthew "MSuLL" Sullivan for giving me the idea of a lookup database with his original
  UniversalUnreal mod (which I can highly recommend, check -> 7.). Also a big thanks to him for his
  work on IpToCountry (as well as to [es]Rush) and for letting me use parts of his hostname detector
  code which is part of his HostnameBan.
  
- To my admin team from the 'ComboGib >GRAPPLE< Server <//UrS//>', for their intensive testing, bug-
  finding and feedback, and ofcourse for simply beeing the best team to have. Big thanks guys! :)



####################################################################################################
##
##  7. NexgenPlayerLookup vs. UniversalUnreal
##
####################################################################################################
You might see parallels between this plugin and UniversalUnreal, created by MSull, which you can get
here : http://www.unrealadmin.org/forums/forumdisplay.php?f=199.
In fact, I mostly oriented on Matthew's idea to collect additional data belonging to each player,
like the names and also the admin actions against him. I tried to provide a solution which doesn't
require any additional resources just like a webserver, which gives some pros but also some conts
(read IMPORTANT NOTICE above). If you are the owner of a community with more than one server and
also got access to a webserver, you would probably go better with UU. But if you just got one server
and you would like to perform detailed player lookups, I hope NexgenPlayerLookups fits you the best :)




####################################################################################################
##
##  8. Info for programmers
##
####################################################################################################
This mod is open source. You can view/and or use the source code of it partially or entirely without
my permission. You are also more then welcome to recompile this mod for another Nexgen version.
Nonetheless I would like you to follow these limitations:

- If you use parts of this code for your own projects, please give credits to me in your readme.
  (Patrick 'Sp0ngeb0b' Peltzer)
  
- If you recompile or edit this plugin, please leave the credits part of the readme intact, as well
  as the author line in the panel. Also note that you have to pay attention to the naming of your
  version to avoid missmatches. The number in the name stands for the Nexgen version the plugin was
  compiled for, so if you want to recompile the plugin for e.g. 'Nexgen112K', name the plugin
  'NexgenPlayerLookup112K'. Multiple versions of the plugin for one Nexgen release can be shown via
  '_X', where the X stands for your current version number (e.g. 'NexgenPlayerLookup112K_2').





Bug reports / feedback can be send directly to me.



Sp0ngeb0b, March 2012

admin@unrealriders.de / spongebobut@yahoo.com
www.unrealriders.de
#unrealriders @ QuakeNet