vsyachepuz / jfcpi Goto Github PK

For information on how to build everything see INSTALL

At the moment the main thing this system does is to record and play back a Freeciv game. This README will therefore
focus on recording.

Recording a game can be done for many reasons. Being able to observe a game you played after it is over may help you
become a better player. Showing off your skills may be fun. Demonstrating a strategy for beginners and AI's that learn
by watching may also be interesting. It may also have potential as a real paranoid debugging tool. As you are reading
this I assume you already have your own motivation for recording a game.

========================================================================================================================
Before you start
========================================================================================================================
You will need Java 7 or later to run the recorder and play back the records. Java 7 is tested and known to work.
The helper scripts assume that Java is in a folder the system will look in when they run. If Java isn't found see
http://java.com/en/download/help/path.xml to learn how to tell your system where Java is installed.

You will also need Freeciv. As the Freeciv protocol (the way a Freeciv client talk to the server) changes between
versions you need the Freeciv version this recorder was built for. (See INSTALL to learn how to build it your self)

To make it easier for non programmers to record games helper scripts are included. If a Windows version of a helper
script exists it has the same name as the UNIX version but it ends in .bat. To start a helper script go the the folder
where it's located on a command line. Assume a script is named "nameOfHelperScript". On UNIX, including GNU/Linux and
OS X it can be launched by the command
  ./nameOfHelperScript
On Windows it can be launched by the command
  nameOfHelperScript.bat
The helper scripts takes parameters. A parameter is passed by adding a space after the helper script name followed by
"--", its name (no space before or after), "=" and its new value (without a space before the new value).

When the parameter "help" is set to "true" it will print the names of all parameters, their value and a short
description. Then it will exit. To launch the recorder and set its "help" parameter to "true"  is
  ./proxyRecorder --help=true
on UNIX and
  proxyRecorder.bat --help=true
on Windows.

========================================================================================================================
Test if it works
========================================================================================================================
It is now time to see if it works. The first test is simple but show that you have managed to get much of the system
working. Begin by starting a freeciv server. Then launch FCJTestSignIn.jar directly or run the helper script
testSignInToServer (testSignInToServer.bat on Windows). If you can see a window of text talking about packets it works.
What you see is the Freeciv protocol converted to text.

The next thing to test it the recorder and the play back. Start the recorder ("./proxyRecorder" or proxyRecorder.bat).
Start a Freeciv server listening to port 55555. Then start a client connecting to the regular port. The recorder should
now listen to the regular port and forward the commands you send via the client to the server. Don't connect using a
second client while recording the test trace.

If the recorder is forwarding from the client to the server the normal pre game screen should appear. Unfortunately it
will also appear if you forgot to make the server listen to port 55555 and the client is talking directly to the server.
See if the messages say you are connected to port 55555.

Now set the gameseed and the mapseed to a value that isn't 0. Do it from the Freeciv client so it becomes part of the
trace. This takes care of setting the server you play the record on to the same state as the server you recorded on had.
If the state of the server used for play back is different from the state of the recording server play back won't work.
Now play a few turns while you are recording. Only record a few turns until you know recording is working. When you are
done playing exit the server by typing "/quit" on its command line.

To play the trace you just recorded start a Freeciv server listening to the normal port. Then run playRecord. Don't
connect a client until the record is done. When it is done connect using the same user name as when you played. If
everything is the same as they were when you exited there is a good chance it will work during more complex use as well.

========================================================================================================================
Quick start
========================================================================================================================
This quick start assume that you run UNIX. If you use Windows use "proxyRecorder.bat" in stead of "./proxyRecorder" and
"playRecord.bat" in stead of "./playRecord". It also assume that you compiled Freeciv your self but didn't install it.
If the version of Freeciv the recorder was made for is installed launch the Freeciv server and the Freeciv client from
the command line using the normal name but keep the parameters.

In other words: If the correct version of Freeciv is installed change "./fcser -p 55555" to "freeciv-server -p 55555"
on UNIX and to "freeciv-server.exe -p 55555" on Windows.

Record a game
 * Start the Freeciv server in a way that makes it listen for clients on port 55555. You can do this using the command
     ./fcser -p 55555
   in the folder where you have compiled Freeciv.
 * Set the state to something you can recreate before play back. One way to do this is to load a saved game to start
   from. The command
     /load alienStart
   on the Freeciv server command line should load a saved game called alienStart.
   Alternatively you may set the gameseed AND the mapseed variables before the game begins. If you do this via a client
   and you record it the record it self will take care of setting them when playing it back.
 * Start the recorder. The line below use the default trace name and will overwrite previous traces.
     ./proxyRecorder
   in this folder should do it. As the play back don't use server packets you can reduce the size of the trace using
     ./proxyRecorder --trace-exclude-from-server
   but be warned that this may cause problems.
 * Connect a client to the port the proxy is listening to.
     ./fcgui -a
   in the folder where you have compiled Freeciv should do it.

Play it back:
 * Start the Freeciv server:
     ./fcser
   in the folder where you have compiled Freeciv
  * Recreate the game state from before the record began. If you used a save game called alienStart
     /load alienStart
   on the Freeciv server command line should load it. If you set gameseed and mapseed via a client while you were
   recording the record will do this for you.
 * Connect to the server using a different login name than when you played. In the connection dialog click observe.
     ./fcgui -a -n recordObserver
   in the folder where you compiled Freeciv should work unless you used the name recordObserver in the record. Remember
   to click observe.
 * Start the play back
     ./playRecord
   in this folder should start playing a record that has the default file name.


========================================================================================================================
Details
========================================================================================================================
The way proxyRecorder works is that it pretends to be the Freeciv server when it talk to the client and pretend to be
the Freeciv client when talking to the server. Before forwarding what is said to who it really was meant for it can
record it to a file. This kind of file is called a trace. The trace can later be played by a player that pretends to be
a Freeciv client and play back what was recorded. As some things aren't sent between the client and the server you have
to make sure that the server is in the same state it was when the trace was recorded to play it back.

If Freeciv have changed it may not be possible to ensure that the state is the same. Rules may be different, the built
in AI may react to to player actions in a new way and the "dice" of the game may start to give different numbers. If the
version is the same there are two ways to make sure the state is the same. One is to load the same saved game before the
recording as before the play back. The other way is to set Freecivs random seeds to the same values. If this is done
from the client after the recording have began it should be recorded like all other actions.

Where the client and server run may also influence the state. Freeciv has a protocol for a client to get "hack" access
that involves having the client write a file to a agreed upon location that the server then checks. If the server find
that the file contain what the client told it to expect it gives the client hack access. When playing back a record the
expected content will be written to the expected location.

If the client in the original record couldn't write to the correct place and the play back can or the player writes to
the wrong place during play back and the client in the original record wrote to the right place this may result in a
different state.

--- proxyRecorder ---
The quick start showed the trace-exclude-from-server option of proxyRecorder. There are more options. To change an
option write --optionName=newValue (note: no space) where optionName is the option and newValue is the new value.

You can change where proxyRecorder will expect to find the Freeciv client or the Freeciv server.
 --proxy-port - the port where the recorder will let Freeciv clients connect. The default is a port the Freeciv client
                will try without having to be told to try it.
 --real-server-port - connect to the real Freeciv server on this port. The default is 55555. Pass the option -p 55555
                      to the real Freeciv server when you start it to make it listen to this port.
 --real-server-address - the machine the real Freeciv server is on. The default is the machine you now use.

Normally the trace for the first connection is then FreecivCon0.fct, the second FreecivCon1.fct, etc.
 --trace-name-start - The start of the file name of the traces. The default is FreecivCon.
 --trace-name-end - The end of the file name of the traces. The default is .fct.

Time can be included in the trace. This makes it possible to record when something happen. It also makes it possible to
record games that has a time out. Note that the time takes a lot of extra space.
 --record-time - is set to true by default. To turn it off use the option --record-time=false

Not everything is needed to play back a trace. playRecord only use packets sent from the client that aren't connection
packets. These take a lot less space than a full trace.
 --trace-exclude-connection - don't record connection packets in the trace. This is on by default.
 --trace-exclude-from-server - don't record packets sent by the server in the trace. This is off by default.
 --trace-exclude-from-client - don't record packets sent by the client in the trace. The client send few packets
                               compared to the server so this won't save much space. It will also make the record
                               unusable in playRecord. Its value in other areas, like AI training data, also decreases.
                               This is off by default.

This file may be out of date.
 --help - will show the options, their default values and a short description and then exit

Developers may find the following options interesting
 --verbose - be verbose on the console
 --understand - interpret the packets before processing them. Warn if not understood. Can be used with trace-to-console
                to get a text trace on the console.
 --debug - print debug information to the console
 --trace-to-console - print all packets going to the trace to the console

--- playRecord ---
The options of playRecord are
 --file - the file containing the trace to play back. Defaults to FreecivCon0.fct. To play many files separate them
          using you system's path separator (":" on Unix, ";" on Windows) like this
            ./playRecord --file=FreecivCon0.fct:FreecivCon1.fct

 --address - where the Freeciv server is. Defaults to your computer
 --port - the port to connect to to find the Freeciv sever

 --ignore-time - ignore time data in the trace. Wait a bit between each action in stead.

 --help - will show the options, their default values and a short description and then exit