-------------------------------------------------------------------
--   GetUSGNName - Fetch UnrealSoftware login names of players   --
-- Created by Banaan - http://servers.cs2d.nl - servers@cs2d.nl  --
--                 24/03/11 - http://www.cs2d.nl                 --
-------------------------------------------------------------------

GetUSGNName is a module for Counter-Strike: 2D which allows a server
to look up the Unreal Software username belonging to the USGN ID of
a player by extracting it from the user's profile.

If you're not interested in how it all works and just want to start
using it right away, don't read all of this file. Reading this
entire readme is totally unnecessary and incredibly boring, so
please don't waste your time.


Simple usage:
	- player(id, "usgnname")


Some examples should be included somewhere in this zip file, but I
doubt that examples of this simple usage is really necessary.

To get started, just extract the right folder into your CS2D
directory (I think you can figure out yourself which files you do
and do not need). Then add the following line to your script:
	dofile("sys/lua/usgnname/GetUSGNName.lua")

Editing the files is not needed, but you're free to do so if you
want to.





(This is where the bullshit starts. STOP READING!)
-------------------------------------------------------------------
-----------------------------THE-FILES-----------------------------
-------------------------------------------------------------------

Since CS2D does not allow a user to edit the Lua source (which is
understandable), unusual scripts (with non-standard Lua) are a bit of
a pain. Loading external modules usually gives trouble, as they cannot
link back to the integrated Lua in CS2D. Therefore, integrated network
capabilities are pretty much impossible.

That's why GetUSGNName consists out of two files (and quite some save
files for the USGN names):
	- GetUSGNName.lua, containing some functions to fetch a name,
	- GetUSGNName.pyw, taking care of the network part

The extension of the second file, .pyw, might be new to you. .pyw is
the extension of a file written in Python, a programming language.

Since most Windows users do not have the Python interpreter installed,
a so-called frozen executable is included in the Windows folder:
	- GetUSGNName.exe, for those who do not have Python installed


Since Python is included on most Linux distributions by default, a
Linux executable is not needed.


From now on, "Python" refers to both the script AND the executable.



-------------------------------------------------------------------
--------------------------GetUSGNName.lua--------------------------
-------------------------------------------------------------------

GetUSGNName.lua is just another Lua file, like you've probably seen
them before. It contains a few settings, which need not, but can be
edited, some local helper functions and some global functions you
can use in your scripts.


GetUSGNName.lua contains three global functions which are used to
fetch USGN names (through the Python script):
	- GetUNameByID   ( id )
	- GetUNameByUSGN (usgn)
	- SaveUNameById  ( id )

GetUNameByID and GetUNameByUSGN are pretty much the same, except
the former requires a player ID as parameter and the latter expects
a USGN ID.

BE VERY CAREFUL WITH THESE TWO FUNCTIONS!

Both of the functions directly return either the Unreal Software name
or the value of NO_NAME (see below), but they can cause the entire
server to hang for up to several seconds. This is caused by the direct,
but blocking pipe between Lua and Python. Lua, and thus the server,
will not react until it received a reply from Python.

Therefore a third function, SaveUNameById, is included. This function
runs Python in a seperate process and does not catch its reply. Instead,
the Unreal Software name, if available, is saved into a seperate file,
stored in the USGNNames directory. Lua will then read the name from
the file. However, this reading is delayed with a certain amount of
time (as specified by NET_DELAY, see below) if a new name has to be
fetched. Furthermore, it provides no error handling, whereas the other
two functions do.

GetUNameByID and GetUNameByUSGN return a USGN name on success and 
NO_NAME on failure. SaveUNameById returns true on success and NO_NAME
on failure.



To make it all a little easier for you, there are some functions
included by default to load and store a player's USGN name for later
use. When a player joins, the function SaveUSGNName is called, which
will either load the USGN name from an existing saved file, or fetch
the name from Unreal Software. It's then very easy to use the stored
USGN name:
	- player(id, "usgnname")


Since users can change their name on Unreal Software, there is also
the need to regularly refresh the saved names. By default, the interval
to refresh these names is 31 days, and is set by MAX_AGE (see below).

	

	SETTINGS:
DIR = "sys/lua/usgnname"  -- Directory where all files are located.
NO_NAME = "unknown"       -- The value that functions return when they
                             cannot find a name. Use a string when the
                             returned value is output directly, but you
                             can also change this to a number, a boolean
                             or whatnot when processing the value is needed.
ERROR_REPORTING = true    -- Do errors have to be logged?
MAX_AGE = 31              -- Maximum time (in days) USGN names may be
                             saved. MAX_AGE <= 0 means always
                             preserve / don't refresh.
NET_DELAY = 1500          -- The delay before trying to open the file
                             containing the USGN name (in ms). Can easily
                             be decreased on fast networks.



That was about it, at least I don't know any more nonsense to write.
If you do have any questions, feel free to ask them whereever you
see me.
