#-- JRPLInfo --#

Version 0.1; revision 1

1 - INTRODUCTION
2 - LAUNCHING THE PROGRAM
2.1 - IN CASE OF DIFFICULTIES
3 - THE JRPLINFO TAB
3.1 - EXTRA FUNCTIONALITY IN JRPLINFO 
4 - THE RACE VIEW TAB
5 - CAR AND NAME DICTIONARIES
6 - LICENSING
7 - RELEASE NOTES
8 - CONTACT

1 - INTRODUCTION

JRPLInfo is a Java-based contemporary take on the replay checking programs so
useful to Stunts racers and competition managers - the most famous of these
being, of course, Lukas Loehrer's classic RPLInfo for DOS and Windows. To the
classic RPLInfo feature set of replay info extraction and keystroke logging it
adds a convenient interface for replay file browsing and a feature for
tabulation of race results and .HIG scoreboard generation. Please keep in mind
that this is a pretty early release of the program, and thus it is quite
unpolished in parts (particularly when it comes to the race tabulation
interface).

2 - LAUNCHING THE PROGRAM

In order to use JRPLInfo, extract JRPLInfo.jar and one of the provided shortcuts
(either Run_JRPLInfo_Windows or Run_JRPLInfo_Linux depending on your operating
system) to a directory of your choice (for added convenience it may be a good
idea to place the files inside your Stunts directory). To start the program,
just (double)click the shortcut. The files within the ExampleFiles directory,
which will be described further along this document, are *not*
necessary to run JRPLInfo.

2.1 - IN CASE OF DIFFICULTIES

The most likely cause of trouble when starting JRPLInfo is Java not being
properly installed on the system. JRPLInfo is a Java program and therefore you
will need to have the Java Runtime Environment installed or otherwise available
in your machine (version 1.5 minimum). In case you do not have it, it can be
easily downloaded and installed
from http://www.oracle.com/technetwork/java/javase/downloads/index.html (look
for "Download JRE"). Linux users may, of course, prefer the packages
provided by their distribution. Another point is that the launcher shortcuts
assume the Java directory is included in your system's executable path (which
should be the case if the JRE was properly installed). Finally, the option of
launching the program directly from a command prompt or terminal. The command
for doing so would be (from the directory where JRPLInfo.jar is):

java -jar JRPLInfo.jar

Again, this assumes the Java directory is included in the path. Even if it is
not, though, the 'java' command may be replaced by the full path of the java
executable - in Windows, typically Program Files/Java/(...) .

THE JRPLINFO TAB

The interface of JRPLInfo is organized around two tabs. The leftmost one,
JRPLInfo, holds the regular replay browsing commands. The basic command is the
"Load .RPL" button, through which the file to be presented is chosen. After a
file is selected, the replay info is displayed on the fields on the upper half
of the tab. The other commands are explained below:

* The "<" and ">" arrows cycle through the replay files in the current
directory.

* The "Open dir" button allows you to choose, instead of a replay file, a
directory. The first replay within that directory will be loaded, and the other
ones can be displayed through the arrows.

* The "Use ZSC Bonuses" checkbox turns on usage of ZakStunts-style car-bonus
corrections to the times. How that functionality works will be explained on the
next section.

* The "Log keystrokes" button performs the classic replay analysis, showing in
how many frames each input possibility (accelerate, brake, etc.) was used.

3.1 - EXTRA FUNCTIONALITY IN JRPLINFO 

In order to allow for the display of more complete replay information as well as
to support better historical record-keeping, JRPLInfo has a few extra features
which take data from files other than the current replay. These are:

* The "Matches reference .TRK?" checkbox, whose answer is obtained by looking
for a track file which matches the track name declared on the replay file and
comparing it byte-by-byte to the track contained within the replay file (only
the horizon byte is ignored).

* The "Laptime with penalty" fields allows for users to add penalty time to the
replays. The penalties should be declared in a text file named penalty.txt,
which must be placed in the same folder as the replays. The file should be
written like this:

ABUTAR.RPL 12
AYRTAR.RPL 6
MLRTAR.RPL 27

Each line contains a replay file name, then a space and the number of seconds to
be added. The penalty.txt file is optional; if it is missing the penalty
correction step will be skipped by the program.

* If the "Use ZSC Bonuses" option is on, correction factors corresponding to the
car used to drive the lap will be applied to the laptimes displayed in the
"Corrected time" field. These factors should be entered in a text file named
carbonus.txt, which must be placed in the same folder as the replays. The file
should be written like this:

ANSX	23
AUDI	4
VETT	23
P962	4

Each line contains the 4-letter car ID, a whitespace or tab mark and the factor,
entered as a ZakStunts bonus percentage. In the example above, for instance, an
Acura NSX replay (abbreviation ANSX) would have its time multiplied by (100 -
23)/100 = 0.77 . Like the penalty time file, carbonus.txt is optional. If the
file is missing (or if the car of the replay is not included in the file) the
corrected time will be merely the unmodified laptime.

4 - THE RACE VIEW TAB

The "Race View" tab provides functionality aimed at competition management and
record keeping. The main commands on the tab is the "Load root dir", which
opens a directory, parses the replays inside it and makes a scoreboard from the
gathered data. There is also the convenience "Open RPLInfo dir", which submits
the directory currently open in the other tab. How the parsing will take place
is defined by the opttions described below:

First of all, "Race directory structure" specifies how the program will proceed
to locate the replay files. There are three possible options:

* "All files in root directory": Runs through all replays in the chosen
directory (but not its subdirectories), assigns each of them to a racer name
according to its filename (as will be explaned shortly) and picks the best
replay from each racer. Additionally, if there is only one track file in the
directory replays that do not match that track are rejected.

* "All files in root directory, include all replays": Same as before, but
including all replays by skipping both the selection of the best replay from
each racer and the track checking.

* "Root dir with racer subdirectories": Subdirectories within the root dir are
assigned to different racers and the best replay within each directory is
included on the scoreboard. If it is desired to use a reference track should be
on the root dir - and the only track file there.

The racer identification is based on the usage of tagging abbreviations,
similarly to the conventions seen in both ZakStunts and UnskilledStunts
competition archives. For races with all replays in root dir, the abbreviation
will be taken from the file name. The "Char limits for racer IDs on filenames"
fields allow to choose which part of the filename will be used as abbreviation.
Once the abbreviation is retrieved, the program will attempt to match it with a
racer name dictionary (see section on dictionaries ahead). If there is a match,
the retrieved name will be used on the scoreboard; otherwise, the bare
abbreviation will be used instead. For instance, if a replay filename is
ABUTAR.RPL and the limits are set from 1 to 3 the abbreviation will be "ABU". On
races with individual racers subdirectories the process is similar, except that
the abbreviation is taken to be the subdirectory name itself. An example root
directory using this hierarchical scheme might look like this:

scr0105 <root directory>
|
|\abu <racer subdirectories>
|\dup
|\gut
|\mlr
|\rei
|\sbr
|
 \CYDONIA.TRK <reference track file>

(a sample of this directory is included in the ExampleFiles directory of the
zip package as the subdirectory racedir)

The hierarchical scheme provides one clear advantage to a competition manager:
namely, it frees him/her from the need of manually renaming replays so they fit
into some convention. All that is necessary is to download every new replay from
a racer to his/hers own subdirectory.

Both penalty time and car bonus correction are supported in Race View. They are
included by the same procedure used with RPLInfo - the penalty.txt and
carbonus.txt listings being placed inside the directory where the replays are.
That means, depending on the chosen type of race structure, etiher the root
directory or the racer subdirectories. A consequence which follows is that when
using an hierarchical race directory with bonuses it becomes necessary to create
a copy of carbonus.txt in each of the racer subdirs (such behaviour is clearly
not the ideal one, and is a possible area for improvement in future versions of
JRPLInfo). Usage of car bonuses is activated by the "Replay parsing type"
option. If bonuses are in use, the "Print corrected times" option becomes
available. If enabled, the generated scoreboard will be built with corrected
times; otherwise the uncorrected lap times will be used (the ordering of laps
will, however, be done according to corrected times anyway).

The generated scoreboard will be displayed in a separate window. In that window,
there is an additional "Write .HIG" option, which allows to build a .HIG file
for, by default, the current track from the top 7 entries (if there is more than
a track within the directory the first track name in alphanumerical order will
be deployed).

5 - CAR AND NAME DICTIONARIES

Racer names, car names and car colours are, whenever possible, retrieved by the
program using plain text dictionaries similar to penalty.txt and carbonus.txt .
The raw data used in each case consists of racer name abbreviations, car IDs and
colour indices, respectively. There are overall four dictionaries in use by the
program:

* carabbrevs.txt : Car IDs --> .HIG opponent car abbreviations
* carcolours.txt : Car IDs --> Colour names (arbitrary number of entries per
car, ordered by index number)
* carnames.txt : Car IDs --> Car names
* racernames.txt : Racer abbreviation --> racer names

Columns in these dictionaries must be separated by tab characters. The program
has an initial version of these dictionaries built-in (a copy of these is
include in the ExampleFiles directory within the zip package). Additional
entries may be included (and default ones replaced) by creating supplementary
dictionary files with the extra entries on the directory where the replays are
(or in the race root directory).

6 - LICENSING

JRPLInfo is formally released under the terms of the GPL v3 (see COPYING file),
and is meant for the benefit of the Stunts community - so please be my guest:
hack and redistribute it to your heart's desire. Source files are packaged
within the jarfile, and are also distributed in a more convenient way through
http://scr.stunts.hu/mods.php

7 - RELEASE NOTES

v0.1, r1 (07-Mar-2011): Initial release

8 - CONTACT

Feedback is always appreciated! For bugs and suggestions, look for me (Duplode)
at forum.stunts.hu, or mail me at scrstunts_AT_yahoo.com.br (replace _AT_ with
the usual sign).

---

See you on the scoreboards,

Daniel Mlot (aka Duplode)
Southern Cross Racing Developments
07-Mar-2011
