
----------------------------------------
HOW TO USE THIS MOD:
----------------------------------------

This README provides some basic information on how to use the Field Status mod.


----------------------------------------
INPUT:
----------------------------------------

The Input interface in Field Status has changed considerably as of v5.1.  While some InputBinding keys remain, the most common functions can be performed by clicking on their icons.

When Field Status is active (meaning the HUD is displayed), the mouse cursor will be visible.  There will still be a minor conflict with some mods that have mouse functionality (Courseplay, for example).  Those mods control the visibility of the mouse cursor on their own, so there may be times when you have to show the mouse cursor manually.  You may do this by clicking the RMB.

For the remaining keys that control the program, you can change any of them before starting your savegame.  On the game's startup screen, select Options, then Controls, and you will find a list of all key assignments.  Make your changes there and be sure to save them.

To activate Field Status, press '*' on the numeric keypad.  You can hide Field Status by either pressing NUMPAD * again, or by clicking the "X" in the lower right corner of the main Field Status HUD.

Help Menu:  All of the key assignments and clickable icons can be viewed on the Help menu (click the "?" icon on the main Field Status HUD).

Icons on main HUD (from left to right):
     -  Default Scan  (also F12 key)
     -  Default Display  (also F11 key)
     -  Move HUD (create custom HUD position)
     -  Config Menu
     -  Help Menu
     -  Exit Field Status

Icons on Config Menu:
     -  Edit Field List (when "Custom" scan type is selected)
     -  Save Config file
     -  MP Config Menu (only seen by MP host; see "Bales," below)
     -  Exit Config Menu

Icon on Help Menu:
     -  Exit Help Menu

Icons on Edit Field List Menu:
     -  Accept List
     -  Erase List
     -  Exit Edit Field List Menu

Navigation:  To scroll through the screens of field data and the Help screens, use the following keys:

     First Screen:        NUMPAD '7'
     Last Screen:         NUMPAD '4'
     Previous Screen:     NUMPAD '8'
     Next Screen:         NUMPAD '9'


----------------------------------------
FEATURES OF Field Status:
----------------------------------------

Config Menu:  Here, you can configure scan and display information and save it to a master config file.
     ----------------------------------------
     AutoScan:
          Active
          Frequency (from 1 minute to 6 hours)
          Scan Type
          Field List (for Custom scan type)
          Fruit
     DefaultScan:
          Scan Type
          Field List (for Custom scan type)
          Fruit
     DefaultDisplay:
          Scan Type
          Field List (for Custom scan type)
          Fruit
     ----------------------------------------

     Scan type = All, Owned, Unowned, or Custom.

     Fruit = All, bales, or a specific fruit available on the current map.

     Default Display is used when you want to show the field data without re-scanning.  For example, after you have
     done a scan of all fields, you can then use Default Display to show only the fields you like (all, owned,
     unowned, or custom fields.)

** NOTE:  Any settings you change here will only be saved when you click on the Save Config file icon.  HUD positions will also be saved (see "HUD," below).


AutoScan:  You can configure the mod so that it scans your fields automatically at a set interval (frequency).
You can toggle AutoScan on/off by clicking on the words "On" or "Off" on the main Field Status HUD.  This will just set the status within the current game.  You will still need to save the config file before exiting the game, if you want to maintain this status for the next startup.


Scanning:  The most common way to scan the fields is to click the "Default Scan" icon on the main Field Status HUD (or press F12).  Initially, the scan type is set to "All".  The other types are Owned, Unowned or Custom.  If Custom is selected, another line will appear showing the current field list (if any) and allow you to view and edit this list.  For entering numbers, you must use the NUMPAD.  Enter field numbers exactly as they are shown on the display (without the word "Field").  For example, if the field name is "Field 3", just enter "3".  Separate individual field numbers by a space or a comma.  You can also specify a range of field numbers, separating them with a colon, e.g., "5:14".


Bales:  Field Scans will detect what type of and how many bales are on each field, and display that information with the other crop data.  I was able to get the code working that sends the bale information to all the players during a Multiplayer game, so everyone sees the same thing.  There is also a new config screen for this, which can only be accessed by the host during an MP game:

     MP Config:  BaleScan:

                            Active:  If set to "false," none of the settings below will matter; no bale data
                                     will be sent to the players.  The host will still see bales when scanning.
                                     If set to "true," then the following options can be combined in various
                                     ways to send the bale data on a schedule that fits your situation.

                         Frequency:  This is used to send the bale data after a certain period of time has passed.
                                     Values range from 2 seconds up to 1 hour, and there is also an "OFF" setting.
                                     For example, if you set Frequency to 30 seconds, the program will scan for
                                     bales and send the info every 30 seconds -OR- 30 seconds after the last scan,
                                     as determined by the other settings.
                                     If "Active" is set to "true," but "Frequency" is "OFF," then the settings
                                     below will control the sending.

                    Each host scan:  If set to "true," the bale data will be sent every time the host performs
                                     any type of scan.

                     Bale created /  If set to "true," bale data will be sent EACH TIME a new bale is created on
                           removed:  a field, and each time one is removed from the field.

                       Player join:  If set to "true," bale data is sent EACH TIME a player joins the game, and
                                     each time a player leaves the game.

     Depending on how you set these options, it can possibly create a lot of network traffic, and therefore more
     lag, so just be prudent and send data only when needed.

     Remember, even though bale data is being sent from the host, each player must still scan their fields to
     see the new information.

     Also note, this is one of the only features of Field Status that will continue to operate even when Field
     Status is not active (the HUD is not displayed).  So if you have hidden the Field Status HUD, it will
     still send the bale data (if the options are set to do so).


Field Display:  When viewing fruit data for each field, you can toggle between seeing percentages or area (acres/hectares).  Default key is NUMPAD /


HUD:  There are two default HUD positions, plus you can create one custom position by clicking the "Move HUD" icon on the main screen.  Then, you can move the HUD around the screen with the LMB (click and drag to the desired position).  When you release the LMB, the HUD's position will be the new custom position.  Then, you are able to cycle between all of the positions using the backslash key ('\').  Be sure to save your custom HUD position by saving the Config file.


Overlay:  You can display a PDA map overlay with numbered fields by pressing NUMPAD ENTER when Field Status is active.  ** NEW with version 5.4 **  If the program can't find the PDA image file used for the overlay, you can
now specify its location by using the 'altPDAPath' tag in the fieldData.xml file in the appropriate savegame directory:

     The tag should be inserted on the 3rd line of the file, the one that starts with '<map name='

     The first part of the tag should be either 'base' (mainly for DLC addon packs), or 'user' for most mod maps.

     Some examples:
          <map name="Westbridge" numFields="38" maxCoords="3" altPDAPath="base/pdlc/titaniumAddon/map/americanMap/" >

          <map name="GreatMap" numFields="42" maxCoords="1" altPDAPath="user/mods/GreatMap/" >

          <map name="WonderfulMap" numFields="112" maxCoords="2" altPDAPath="user/mods/WonderfulMap/map/extras/" >

     The filename is hard-coded in the program to be "pda_map.dds".  Therefore, only the pathname needs to be
     specified in the 'altPDAPath' tag.


Transparency:  You can now adjust the transparency of the entire HUD with the NUMPAD + and - keys.


Reload Field Definitions:  There are two situations when you may need to do this:

     1) If the field data in the xml file (savegame directory) somehow gets corrupted.
     2) If a new version of Field Status is released, and there are changes to how the fields are scanned.

     Press '[' to reload the basic information from the Field Definition database built into the map.
     Once this is loaded, the program will update the field data by performing a scan.


Saving:  The program will automatically save the field data in an xml file in the current savegame directory.  It will do this after each type of scan.  It will not save the data when you save the game itself, so you can either do a scan yourself before saving and exiting the game, or just do a scan the next time you start up that savegame.  The game's regular savegame feature will of course save the most current status of all the fields in the .grle files, like it always does.


Debug:  There is a debug feature which will print certain information to the log.txt file.  This will help me diagnose a problem you might be having with the mod.  The key combination to activate/deactivate Debug is CTRL-D.

PLEASE NOTE:  If you turn this on, it will potentially write a great deal of information to the log file, and it will definitely slow your game down, to the point where you think it has frozen.  BE SURE to deactivate it after using it.  There is a flashing indicator in the upper left part of the main Field Status HUD to let you know if Debug is activated.


----------------------------------------
In-game error messages:
----------------------------------------

"No Fields: [list of fields]"

This will appear in the message area of the menu when you have entered a field number to scan, but it doesn't match any of the fields on your map.  The field number appears in the display area of the Field Status menu, and also in the fieldData.xml file, which is in the savegame directory.  Enter the field number without the leading text "Field ".


"ERR: can't save to [xmlfile]"

If there is a problem saving the field data to the xml file in your savegame directory, this message will appear.  The cause of this is probably an operating system issue or file permissions on the directory aren't set right.


"fieldStatus: Field Definition Error: Check log"

This is a serious error, meaning the program could not find the field data in the XML file, or in the Field Definition database built into the map.  The log.txt file may contain some additional information to pinpoint the source of the error.



----------------------------------------
Log file error messages:
----------------------------------------

First, a note about how the program obtains the field data:

When Field Status is activated, it will try to load the field data from an xml file in your savegame directory.  If you just installed the program, and/or you are starting a new savegame, the file won't be there, of course.  In that case, the program will look for the field data in the Field Definition database in the map itself.  If there is a problem reading this data, the message "fieldStatus: Field Definition Error: Check log" will flash on your screen, and you won't be able to do anything with Field Status until the problem is corrected.

If you get this error, check the log file for the specific error.  It could be any one (or more) of the following:

"fieldStatus: ERR: Missing numFields for [mapname]"
"fieldStatus: ERR: Missing maxCoords for [mapname]"
"fieldStatus: ERR: No Fields found for [mapname]"
"fieldStatus: ERR: Missing Area for [fieldname]"
"fieldStatus: ERR: Missing Coordinates for [fieldname]"
"fieldStatus: ERR: could not find dimensions for Field: [fieldname]"
"fieldStatus: ERR: could not get world coordinates for [object] in Field: [fieldname]"

*** If you encounter any error not mentioned above, please post a description of your problem in the support topic on the fs-uk.com forum.  If possible, include your log.txt file to help pinpoint the exact problem.  Also, state what you were doing / trying to do when the error occurred.


================================================================================

KNOWN LIMITATIONS:
------------------

1)  Field Definition.  When Giants released FS2013, one of the new features was the Field Definition database.  This means my program can automatically get the field dimensions and provide accurate scan data, instead of having to get the data manually from each map, as I have had to do up until now.  So it's a great improvement.  HOWEVER ... and this is a big 'however' ... I have already found that some maps which have been converted to FS2013 do not have their Field Definitions correct.  The new feature is a great tool, but as with all tools, it must be used correctly to be effective.  There may be some more information concerning this in the support topic on fs-uk.com.

2)  Performance.  It appears that Giants has made some improvements in game engine performance.  I have noticed in my testing that the scans are done much faster than before, without me doing anything in the code to make them faster.  (I did do a little tweaking in v5.1 to make the scans faster)  Of course, if you have a computer or laptop that is older or maybe not considered top of the line, then things may still be slow.  The machine I have done my development and testing on is, I believe, a pretty nice machine.  But I see from some posts in the fs-uk forum that my machine is not a "gaming" machine.  Well, it's fast enough for me, and I'm pretty impatient.  :)

3)  Accuracy.  Along with the Field Definition database, Giants has made some enhancements to their code, specifically with the density functions.  This has allowed me to program the scans so that they are more accurate.  I was very pleased when I saw this, as I have always worried about how accurate the scan data was in Field Status.  I did, however, still see some exceptions to this, most all of them involving the grass that surrounds most fields.  In those cases, you may see percentages over 100%, or you may see grass mixed in with different crops on some fields.  Overall, it's not a real bother.  PLEASE NOTE:  If you change a field's size or boundaries by plowing new areas or changing it in Giant's editor, or combining two or more fields, the numbers reported will be misleading.
