===============================================================
            The EU2 Savefile Daemon
===============================================================

What is it?
-----------
The EU2 Savefile Daemon is a program that executes in the background while
a Europa Universalis II game runs in the foreground. It lies dormant until
it detects that a game savefile has been modified. When found, it parses
the data within the file, compiles and tabulates it, and writes the results
to various tab-separated text files. It will continue to append data to the
files every time the game is saved, until the program is stopped by the
player. If you have set the game to autosave every year, and use
"autosave.eug" as the savefile to watch, the output files will contain one
row of data at every year interval. A common use for these text files is to
import them into spreadsheet applications (like Excel), to perform
statistical analysis or just create pretty graphs.


Sources
-------
The latest version can be found at
http://www.katica.org/cer28/eu2/EU2SavefileDaemon/.


Version
-------
The current version is 1.0.


License
-------
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option)
any later version. For further information, read the file GPL.txt contained
in this directory, or see http://www.gnu.org/licenses/licenses.html#GPL.


Installation
------------
Simply unzip the installation file, and place the directory in a convenient
location. The files used during program execution are:

         Required
         --------
         daemon.pl
         Savefile.pm
         daemon_config.inc


         Optional
         --------
         daemon_config_agc.inc
         daemon_config_eep.inc
         daemon_config_<other name>.inc


An output directory will be created when the program starts. The default
location will be within the current directory, but can moved elsewhere
depending on local configuration.


Installing Perl
---------------
This program runs within the perl interpreter, which needs to be installed
separately. If perl is already installed and working on your system, this
program should work with no further installation. If not, download Perl
from the downloads page at http://www.activestate.com. You can assume the
default values during the installation, although the following aren't
necessary and can be unchecked if desired:

    * Perl for ISAPI
    * PerlScript
    * PerlEz

I would also recommend unchecking the "Create Perl file extension
association" option, which is checked by default. This option allows you to
run a perl script by double-clicking on it, which isn't as useful as it
sounds. Running the script from a console window or from a shortcut allows
more control over how the program executes, and both of these allow you to
pass parameters to the script, which double-clicking doesn't allow.

The Holy World Factbook program (http://www.geocities.com/lesov/) by lesov
contains an excellent set of instructions on how to install Perl.


Configuration
-------------
The various settings for the program must be defined in one or more files
with a filename pattern of daemon_config*.inc. Default settings are defined
in the file daemon_config.inc. Any of the parameters in this file can be
overridden by creating a new file, daemon_config_<string>.inc, where
<string> is a unique identifier that is passed to the program on the
command line.

For most purposes, the simplest method of configuration will be to edit the
daemon_config.inc file itself. The second method, using multiple
configuration files, can be advantageous if you plan on monitoring games
with very different configurations.

Detailed explanations on the parameters to configure are in the
daemon_config.inc file itself. To summarize here, the various values that
can be set are:

  - The full directory path and filename of the savefile
  - The full or relative path to the output data directory
  - One or more directories for the base directory of Europa Universalis II,
    in which to find game data. For a normal game, this will be the directory
    that contains EU2.exe, and has subdirectories Config and Db. If you are
    playing a modified game, such as AGC or EEP, there will be multiple
    directories listed here, and the first one named will be the one searched
    first for any required files
  - types of information to be logged. There are two lists here, one for data
    that can be summarized for the game overall, and data that are specific to
    each country
  - Timing parameters, that probably only need to be adjusted if you encounter
    problems with a savefile being analyzed before the save has completed


Running the program
-------------------
Open a Windows console window. The shortcut for this in the Start menu is
usually in Start->Programs->Accessories->Command Prompt. It can also be
accessed by running the command Start->Run... with the command
"command.com" on Windows 98, or "cmd.exe" on Windows NT, 2000, or XP.

From the command prompt, move to the EU2SavefileDaemon directory. Then type
in:

  perl daemon.pl

If you see:

    ==========================================
    daemon.pl started <current date and time>
    ==========================================

then everything is working fine. An output directory will be created in the
location specified in the configuration file (default is named output and
will be under the current directory). Within the directory, two files will
always be created. The file daemon_log.txt will log the program's ongoing
status, the same information that is being displayed in the window. The
file globals.txt will log the statistics related to the savefile as a
single entity. In addition to these, additional files will be created,
named country_*.txt, each recording a single piece of information that is
broken down by country.

To run the program with modifications from an alternate configuration file,
execute

  perl daemon.pl agc
       (uses modifications from daemon_config_agc.inc)
or

  perl daemon.pl eep
       (uses modifications from daemon_config_eep.inc)

or another identifier, where modifications are contained in the file
daemon_config_<identifier>.inc.

When passing this identifier to the program, the program will first read
the settings from daemon_config.inc, and then read in the alternative
file, using the settings to override any of the defaults defined
previously.

Multiple identifiers can be specified on the command line. The program will
first set the defaults defined in daemon_config.inc, then override those
from the modified configuration files, in the order they are specified on
the command line. One example of how this could be used is to define a
series of configuration files with different savefile names, and then
another series with different output directories. The files to invoke can
be used in different combinations, depending on the particular game being
played.


Command Line parameters
-----------------------
Currently, the only option available is '-now', which tells the program to
read in the savefile immediately after starting up, without waiting for
it's modification time and size to change. The default is to wait until the
file has changed before doing the first analysis. This is the desired
behavior when you have just started a new game, and the current savefile is
unrelated to the new game. The first savefile read will be the one that is
saved within the current game, ignoring any previous data. However, if you
are continuing a game using an existing  savefile, the -now option will
read the existing file before the game starts.

For the above scenario, the command line syntax would look like:

  perl daemon.pl -now agc mymod1 mymod2

in the case of an AGC game with two other configuration files to read.


Known problems
--------------
* The program fails to parse data when reading a savefile that hasn't
finished saving.

The daemon program makes attempts to wait for the writing of the savefile
to complete before analyzing it. Once it detects a change in the timestamp
of the savefile, it will check again in 3 seconds (or other number as
defined in the $read_wait variable) to make sure the timestamp hasn't
changed again. It will keep trying until the file hasn't changed during the
same 3 second period. This usually prevents parsing prematurely, but
sometimes things go awry, and the file is read when some important data is
still missing.

The current iteration of the analysis will abort without writing data to
the output files, but will still be able to read a new file during the next
cycle. For later debugging, a file, err_<number>.log,  will be saved in the
current directory with all the remaining tokens in the file.

In rare circumstances, the missing portion of the file will not cause an
outright error. For example, the missing data may occur exactly after a
country or province definition. In this case, the data will be corrupted.
Hopefully, it will be obvious, so that it can be corrected before
performing analysis on the results.

* Native populations may be off.

I don't know of any event that would increase the total amount of
natives in a province, but the output from the daemon can give oscillating
total native populations from year to year.

* Human player names are all "unknown"

I have not had much chance to test the program with multiplayer games. The
most reliable method of identifying players is within the initial (header)
section of the savefile, where information on playable countries is stored.
In the single player games I used for personal testing, the playername
field contains the user or machine name of the human player. However, I
have seen savefiles from other people, where this playername data is
missing, In that case, I fall back on data in the individual country
section. If there are two VP values, and both are non-zero, this seems to
be a good indicator for human players. Using this method, however, there is
no information on user identities, so the names default to "unknown".


Future Plans
------------
* Add parsing of trading post and city data. This will allow outputs for
  things like average fortress level, population, manufacturies, etc.

* Implement output suggestions by Isaac Brock:
     sum of relations with all HRE nations
     average relations with all known countries
     gold income by country
     commodity price (if obtainable)

* Implement other output functions
     stability level
     tech levels, including progress toward next one

* Allow command line options to be passed which override the defaults, for example
"-output=./mygame01" or "read_wait=5".


=======
THE END
=======


$Id: README.txt,v 1.2 2003/02/12 03:38:14 chad Exp $
