mpRes - usage manual

Requirements

Basically mpRes does not require anything but a webserver that supports php5 and has mod_rewrite enabled.
Of course also enough webspace is needed to store the replays and the images produced (track images, race progress graphs ...)

Installation

Extract the zip-file to any place on your computer.
Open ".htaccess" and change "RewriteBase" (line 16; default: /) to the path on your server, where you want mpRes to reside (relative to the top level of your domain).
For a path http://yourdomain.tld/mpres/ that shouls e.g. be /mpres/
Open config.inc and adjust the default behaviour of the script, especially:
1. In line 13 provide a font-file of a unicode-font (I'd suggest arialuni.ttf from Microsoft, which the svg-script is optimised for) that is put inside the fonts directory
  NOTE: You need to put a suitable font-file into the fonts-directory. Because of licensing I cannot provide the font!
2. In line 36 set the "Force_Load_Password" used for manual overriding of results (see later).
3. Set image and link to be shown in the header of the page, when no special event/league is selected (line 23/24). The path should be relative to the main script path.
4. Depending on the header images you might want to alter their behaviour by changing the css-file located in the styles directory (mpres.css). You might also want to provide an own, alternative style. To do so provide the path to it (lines 25-30) ;)
Open event_definitions.txt and define the events, that you want to handle within mpRes. (see below)
Upload everything to the directory that you specified in .htaccess earlier
provide write access (chmod 0777) to the following directories: saves, images/rendered (and subdirs)
You're finished!

Usage

Defining events in event_definition.txt

A replay that is to be analyzed within mpRes has to be defined as belonging to either a pre-defined league (actually a season thereof) or a set of single events.

The belonging of a replay to an event will be handled by its storage path and the replay name. But the single leagues or events that appear in mpRes need to be defined using the event_definition.txt file.

Each single event or leage will be defined according to the following scheme: (sample below)

### league ### (or ### single ###)
+++ global +++
short: I_AM_A_SHORT_TAG
name: I_AM_A_STRING
headlink: I_AM_A_LINK
headlogo: I_AM_A_LOGOFILE
--- global ---
	+++ season +++
	number: I_AM_A_NUMBER
	dir: I_AM_A_DIRECTORY_PATH
	replay_prefix: I_AM_A_PREFIX
	daterange: I_AM_A_DATE(RANGE)
	logo: I_AM_A_LOGOFILE
	toc: I_AM_EITHER_TRUE_OR_FALSE
	maxleavelaps: I_AM_A_NUMBER
	minracepart: I_AM_A_FLOAT_VALUE
	keeplapsonrejoin: I_AM_EITHER_TRUE_OR_FALSE
	rejoinpenlaps: I_AM_AN_INTEGER
	appendunfinished: I_AM_EITHER_TRUE_OR_FALSE
	safetycarstart: I_AM_EITHER_TRUE_OR_FALSE
	--- season ---

The meaning of the distinct lines is:

### league ### / ### single ###: This defines the following event as being either a league (being an event that consists of multiple rounds) or a single event (a one-time event). Both of them will be handled within seasons, though, as also a one-time event may be a recurring one ;)
+++ global +++: This marks the beginning of the event's global settings, that will be valid for all seasons (such as the name for example)
short: This is a denominator for the event. As this tag is used for naming the files generated by the script as well as for the URLs, this tag is required and has to be unique within the event group. i.e. a single event an a league may have the same tag, but to leagues may not!
name: This is the full name of the event as will be displayed on the overview page and the breadcrumb menu
headlink: link to league/event main page to be followed when klicking on the site's header logo (fallback to default (see config.inc) if empty)
headlogo: logo (path relative to script main directory) to display in the header when this event/league is selected (fallback to default (see config.inc) if empty or not found)
--- global ---: This marks the end of the event's global settings.
+++ season +++: This marks the beginning of an event's season settings. Each new season will require an own set of settings, which will be appended one after the other.
number: The season's number. This value may be given in either arabic or latin numbers. Needless to say, that the number has to be unique for each event.
dir: Path to where the replays of this season are found (relative to the script's main directory with trailing "/"). This is mandatory in order to find any replay!
replay_prefix: This is a prefix that has to be put at the beginning of each replay's name prior to the mandatory nomination [(ROUNDNUMBER_)(gGRIDNUMBER_)SESSIONTYPE(SESSIONNUMBER)]. This is used to identify the replay as belonging to this specific season of the event. You might leave that blank in case you use distinct directories to store each season's replays. If not you will need a unique identifier in order not to mix up replays of different seasons.
dir: Path to where the replays of this season are found (relative to the script's main directory with trailing "/"). This is mandatory in order to find any replay!
daterange: Date or date range to be displayed on the overview page for this season. (Will be displayed as is.)
logo: Logo-image (path relative to script main directory) to display on the season's session selection screen. (Will be left empty if not found.)
toc: Are takeovers allowed (true) or not (false)? If true, you have to provide a .tocdata file along with the replay (same name and directory as replay but with "tocdata" as extention)
maxleavelaps: Up to which point is it allowed to rejoin the race? Either an integer(!) value (meaning x laps completed by the current leader) or a fraction of the race (a float bewteen 0 - 1.0 -> setting to 0.2 in a 10-lap-race will set the limit to 2 laps completed by the leader). In case of resulting odd numbers, the value will be rounded up to next integer. Any joining the race after this point will simply be ignored by the script.
minracepart: Minimum percentage of the race to be completed by a driver to get a result instead of "DNF". (A value between 0 (anyone on track will get a result) and 1.0 (you have to pass the chequered flag).) Note: Anyone who passes the chequered flag will automatically be classified as finished.
keeplapsonrejoin: If a player rejoins the race are his/her previous stints to be kept (true) or not (false)? In case of true all stints will be summed up to give the final result. If false, only the very last stint will be considered. This will mainly be interesting in case of long-run events.
rejoinpenlaps: If a player rejoins the race (after a disconnect, SHIFT+S or SHIFT+P etc.), how many laps will he/she be stripped off as penalty?
appendunfinished: Are players that did not see the chequered flag but did complete the minimum part of the race (minracepart) to be appended AFTER all finished players (true) or are they to be inserted regularly by their completed laps and racetime (false)
safetycarstart: Is the race started behind a safetycar that is the first in the starting grid (true) or not (false)? Setting this to true will eliminate the first car of the grid from all results, shifting all other cars one starting position up (thus gaining the correct values). THIS DOES NOT WORK IF THE SAFETYCAR IS NOT FIRST OF THE GRID!!!!

The effect of the combination minracepart/appendunfinished is best explained by looking at an example:

config

On the left side the last eight players did not finish the race and are therefore considered as "DNF" (lfs default). At the center minracepart is set to 70%. Therefore the four highlighted drivers did recieve a ranking, as they completed enough laps. On the right side those four drivers are appended after all those drivers, that did physically complete the race (chequered flag), although they might have completed more laps.

In case you need that for structuring purposes you may add blank lines or white spaces (including tabstops) at the beginning and/or the end of each line as you wish. Additionally each line, that begins with a ";" will be considered a comment, thus it will not be used.

Now let's have an example. We will define a league called "The awesome LFS league" or "TaLl" for short ...

It will have a logo called "TaLl_logo.png" which we will put into the "images/event_logos" directory within mpres. There also is a website, which is "http://theaewsomeleague.com".

Then there will be 2 seasons of that league (season 2014 and season 2015). There also is a logo for season 2015 (TaLl_2015.png) which we will put into "images/event_logos/TaLl/". There is no logo for season 2014.

For both seasons there will be the following rules:
Takeovers will not be alowed
You can (re-)join the race until the leader has completed his 2nd lap
You need to complete at least 80% of the race distance (or pass the chequered flag) to get a result
Whenever you rejoin a race (for example after adisconnect) your previous laps will be kept, but you get a 1-lap penalty for rejoining
Non-finished racers will be regularly included within the results, not appended
There is no safety-car start. In order to unequivocally address the replays, their names will start with "TaLl14_" (season 2014) and "TaLs15_" (season 2015) respectively, all replays will be put into a directory "replays" directly within the main directory of mpres.

All this will result in the definitions being the following:

### league ###
+++ global +++
short: TaLl
name: The awesome LFS league
headlink: http://theaewsomeleague.com
headlogo: images/event_logos/TaLl_logo.png
--- global ---
	+++ season +++
	number: 2014
	dir: replays/
	replay_prefix: TaLl14_
	daterange: 2014
	logo:
	toc: false
	maxleavelaps: 2
	minracepart:0.8
	keeplapsonrejoin: true
	rejoinpenlaps: 1
	appendunfinished: false
	safetycarstart: false
	--- season ---
	+++ season +++
	number: 2015
	dir: replays/
	replay_prefix: TaLl15_
	daterange: 2015
	logo: images/event_logos/TaLl/TaLl_2015.png
	toc: false
	maxleavelaps: 2
	minracepart:0.8
	keeplapsonrejoin: true
	rejoinpenlaps: 1
	appendunfinished: false
	safetycarstart: false
	--- season ---

Regular usage

After configuring usage is quite simple: Just put a replay into the directory specified for the event/season.

One slight drawback, that comes with the need to unambigously identify any replay is a fixed scheme, the filename has to be matched to. This scheme is as follows:

PREFIX(ROUNDNUMBER_)(gGRIDNUMBER_)SESSIONTYPE(SESSIONNUMBER)

PREFIX is the replay-prefix that is defined in event_definition.txt. This is followed by the number of the round (directly as a number) and an underscore (_). When you do not have multiple rounds, e.g. in case of a single event, this may be omitted.

If multiple grids are used, the gridnumber is added, preceeding it with a small "g" and followed by an underscore at the end.

Last part of the filename ist the sessiontype. Currently supported are:
q: qualifying
s: sprint race
r: "normal" race"
Selecting a sessiontype (e.g. q) does NOT affect the result, but is only for labelling purposes, so that for example a short race that is used as a qualifier will show up as qualifying instead of as a race in the menu.

The sessiontype may be folliwed by a number if for example multiple races where done on a single round.

If not applicable, the parts enclosed in bracket (roundnumber, gridnumber and/or sessionnumber) be omitted.

Regarding the example above, a replay of season 2014 within the TaLl-league, which belongs to the 2nd race of round 3 (a sprint race) would be called (if there are no different grids):
TaLl14_3_s2.mpr

After the replay file is uploaded, the event will be selectable from the menus. Actually it will be selectable from the moment, the upload has begun, because from that instant on the file can be found within the filesystem.

The results will be created the first time, anyone clicks on the corresponding link (for large replays allow the script a few seconds to do it's work ;)). Nevertheles the "easy usage" makes some attention necessary, as anyone clicking the link before the replay was completely uploaded will initiate the parsing, thus creating broken results (lots of DNF-people).

To prevent this there are two major pathways:
a) run the script once using "force_load" (see manual override) even without altering stuff via mprdiff-file (see below) thus reparsing the replay and creating correct results or
b) Upload the replay with a dummyname and then rename it to the desired name, once it was completely uploaded.

Manual override

In case you want or have to manually override the results as stated in the replay, you can do so by submitting a corresponding ".mprdiff"-file. This file has to reside in the same directory and to have the same filename as the replay it belongs to, but the file-extention is "mprdiff". Otherwise it is a simple textfile, for which a dummy is delivered within the package.

A typical example will be to reduce the duration of a race if for example the server crashed. In that case the race may be evaluated up to a certain point and regarded as finished.

Another capability of the procedure is to manually add penalties to a certain driver after the race such directly incorporating them into the results.

This can also be done after the replay has been extracted for the first time by using the force_load password. This is done by appending "?force_load=YOURCHOSENPASSWORD" to the url of the specific race. In such a case the replay will be reparsed, incorporating eventual changes stated in the mprdiff-file.

Takeovers (TOC)

The script is able to handle races with driver changes (takeovers). For this to work you will have to provide a ".tocdata"-file along with the replay, which has the same name (similar to .mprdiff). This file is basically a text file with team definitions.

Here you provide team data such as used car, teamname and -number. For each team you will have to provide each driver with his lfsw-account.

Stating a team-number (unique for the race) is mandatory, because this is internally used by the script to handle the different teams