ECheck   V 4.1.4

What ECheck can do		What ECheck can not do		Installation of ECheck		Running ECheck		Environment Variables

ECheck Commands in Orders Template		Meta-Commands		Test Example		Miscellaneous

ECheck is a Syntax/Error-Checker for the PBeM game "Eressea". ECheck tests your orders for various possible errors and then reports the errors to you, so that you can fix the errors before you send in your orders to the Eressea Game Server.

ECheck is also found on the Eressea Game Server, but only does a limited test of you orders. Therefore, it is imperative you use ECheck at your computer to check all your orders. Here is a Test Example. shown below, that will help you understand more about ECheck..

to top of page

What ECheck Can Do

Mainly ECheck checks your orders for syntax errors, incorrect orders, and other various game related errors.

In your orders template there are notations for each unit telling ECheck how many men and how much silver the unit has. This information allows ECheck to check if your unit has enough silver to survive, if there is enough silver to do any recruiting that you have ordered, to pay the maintenance upkeep for any buildings in the region you command, or if you have enough silver to pay for learning skills (when applicable).
However, ECheck, of course, can not check how much silver you will earn nor can it check if you receive silver from an ally.

ECheck can also see from your orders template if a unit is on a ship or controls a ship. (for example, on the orders template this looks like "s124" when the unit is on ship number 124 or like "S124" when the unit is on board ship number 124 and also commands that ship.) Additionally, ECheck can also see from your orders template if a unit is in a building. controls a building, or controls a building with responsibility to pay the weekly maintenance upkeep for that building (for example, "U200" means that the unit must pay 200 silver per week to maintain the building, and U250+ would mean 250 silver per week plus some additional requirement, like 1 piece of wood per week for a Smithy.) Undead and Illusion units are noted with the "I" symbol on your orders template.

ECheck does the following error checking tests:

• Correct spelling (syntax)
• Does the unit have a long order?
• Do any TEMP units receive men by a give order or by recruiting?
• Without Option -l (Silverpool): Do TEMP units receive enough silver to do the recruiting, if so ordered ?
• Test if there is enough silver in the region to feed your people (upkeep.)
• Units ordered to do WORK automatically receive 11 Silver per man for ECheck calculating purposes, units doing TAX or ENTERTAIN earn 20 silver per man (again this is for ECheck calculation purposes). Therefore the silver needed for food for your men is calculated. Nevertheless, it is possible you receive a warning from ECheck that you do not have enough silver in the region but indeed you do have the needed silver in the region. The reason for this is that ECheck only calculates the silver you make, as stated above. Therefore, it is very possible (and probable) you earn more silver in the region than ECheck has calculated. Additionally note that ECheck does not know how much silver you give to your allies in the region per the HELP orders rules of Eressea.
• Tests whether RESERVE xxx SILVER demands more silver than is available in the region.
  Note that, if the unit wishes to give silver away, the RESERVE order occurs before the commands GIVE, SUPPLY, or @GIVE.
• Checks if units that are doing the TEACH order have too many students and if the students are indeed doing the LEARN order.
• Units that are buying luxury items spend silver based on the ground (base) price of the luxury items. However, note this might be too little, because ECheck can not see at what price these luxury items will be bought at exactly (why? perhaps others recruit in the region or others also buy luxury items in the region.)
  
• Units that learn the skills that cost silver (e.g. Espionage, Magic, Alchemy, Tactics and Herbalism) are calculated with the silver costs by ECheck.
  In regard to learning magic; in Eressea the learning costs of magic are dependent on how skilled the mage is in magic. You can write the order LEARN MAGIC silver-cost) (for example; Learn Magic 1850). In this example ECheck calculates your mage needs 1850 silver for learning, however, do note this is your input, and you, being human, may be wrong. Lastly, without a notation of the "silver-cost", as exampled above, ECheck simply calculates the cost to be 200 silver.
  Simply stated, overall, ECheck can calculate the incomes and the silver supply of the units. Therefore, ECheck can detect lack of silver, especially so because all silver out-flows (per the sequence of play) take place, except the feeding (upkeep) of units, before all of the various ways a unit can earn silver.
• Units that LEAVE a ship of which they had control of simply give the control to the first unit on the ship under them on the listing of units on the ship. Likewise a unit that enters a ship that is empty of units is considered by ECheck to gain command of the ship, however this may be not true as other units might enter the ship first!
  The safer way to do this is to use the GIVE CONTROL order. It is equally allowed to give control of a building to another unit. This can be especially important when considering who pays the building maintenance upkeep costs.
• Units that do the MOVE, RIDE (and associated CARRY) orders will be checked and the silver they carry will be calculated to be in the region to which they move to.
• Checks ship movement.
• Checks whether teacher or student units are without men in them.
• Checks if teacher units still have more student places available. This check only is done at warning level 5.

to top of page

What ECheck Can Not Do

ECheck has only limited data concerning your units. Therefore, the following checks and tests are not possible, in most situations, for ECheck to do:

• Does the unit have enough silver and men?
  ECheck reads the total of silver and men of a unit from the orders template. If other factions give you men or silver this is beyond the knowledge of ECheck.
  The actual income of a unit, for example from the order ENTERTAIN, can not be exactly calculated because ECheck does not know how much skill your units have. Therefore, ECheck can not calculate how much silver you make. There is a something you can do to help ECheck in this regard; write after your ENTERTAIN and TAX orders how much silver you believe your units will earn. (for example; TAX 2000) ECheck will then accept that number as the true value this unit will earn. However be aware that if you write an incorrect number then you risk missing a warning from ECheck!
• Does the unit have the correct skill and items?
  With MAKE and other orders, ECheck does not know if the unit has the correct talent or items to do the order per the rules. Simply stated; the orders template does not have any notation of talent or items for ECheck to read. Therefore, ECheck can not check anything regarding talent and items.
• Does the movement go as planned?
  ECheck has no idea if you have horses. As stated above, ECheck has no way of knowing if you have any item, inclusive horses. Also, ECheck can not tell if roads exist. Given these facts, ECheck can not test if your MOVE or ROUTE orders (etc.) go as planned.
  ECheck, however, does check if your ROUTE orders are in a complete loop, that is the region where your unit is now is the same region to which the route order ends. If your route order is not in a complete loop or starts with a PAUSE, ECheck gives a warning.
• Exact tests of magic spells?
  In Eressea the optional parameters of some magic spells such as REGION x y and LEVEL n must be correct, of course, in regard to syntax. However, ECheck has no knowledge about magic spells nor what spell may have these optional parameters. It is therefore the player's responsibility to check this, so be careful.

Since ECheck can not read many real unit statistics it is possible that ECheck gives you warning that is not true.

The Silverpool Mode (ECheck Option -l) is not always applicable: for example, if one's unit is on a ship that is controlled and moved by another faction! In such a case the unit actually does move but ECheck does not know it. This can also result in situations where movement by "other means" occurs, such as with magic.

Donations of silver by (HELP SILVER) and (GIVE xxx yyy SILVER) from other factions is completely unseen by ECheck. Therefore warnings based on this can result.

Also the DEFAULT order can lead to certain error results when in reality there is no error.

However, some of the effects specified above can be limited with use of the Meta-commands.

to top of page

Installation

For a complete installation of ECheck you need these Additional Data Files. These files give ECheck lists of items, talents, >and magic spells for syntax checking. The format of these files is shown to >you inside the data files (they are .txt files, simple to read).

Where you store (save) these files is really not so important, as long as ECheck can find them. In this regard there are 3 ways you can inform ECheck where these additional data files are.

• the data files folder named en must be in the subdirectory where the Echeck.exe file is found. In our opinion this is the best of the 3 options available to you (note: for a Linux user this is /usr/local/lib/echeck)
• using an environment variable (a pointer) named ECHECKPATH that tells ECheck where to look for the data files (e.g. C:\Eressea\ECheck which then indicates to ECheck that the data files are found in C:\Eressea\ECheck\en) more about this "pointer" (environment variable) is explained below.
• use the ECheck parameter -P to point to the appropriate folder (e.g. echeck -P/home/Eressea/ECheck)

to top of page

Running ECheck

      ECheck [-<Options>] orders_template_file

Options:

-

Uses stdin in place of an input file.

-b

suppresses warnings and errors (short format)

-q

suppresses other outputs (quiet)

-rnnn

Sets recruiting costs per man to nnn silver

-c

writes the warnings and errors into a compiler-similar format:
file name|(line)|warning level|text
HIGHLIGHTED text stays, the rest, in general should be fixed. Warning level 0 = Errors only.

-m

writes the warnings and errors into a format understandable for Magellan Eressea client program:
file name|line|warning level|text
HIGHLIGHTED text stays, the rest, in general should be fixed. Warning level 0 = Errors only.

-e

writes the checked file to stdout, errors sent to stderr

-E

writes the checked file to stdout, errors also sent to stdout

-h

displays this help list

-hb

displays the orders listed found in the commands.txt file

-hp

displays the parameters listed found in the params.txt file

-hr

displays the directions listed found in the directions.txt file

-hm

displays the messages listed found in the messages.txt file

-hf

displays a list of the files that ECheck tried to read.

-s

uses stderr for warnings, errors etc. not stdout

-p

(together with -e) generates a "Piping-suited" output: only the first part of the name is output for items, potions, and herbs.
This is for the DEFAULT orders necessary if the output is used by ECheck as input for a further ECheck run. This option does NOT work with magic spells as the for word is not always unique.

-n

counts lines with NameMe-comments (;;) not with

-l

Silverpool-Mode: missing silver will be taken from another unit in the region

-noship

this warning "Unit moves ship and may lack control" is disabled

-nolost

this warning "Unit %s may lose silver and/or items" is disabled

-noroute

this warning "ROUTE is not cyclic" is disabled

-w[n]

Warning Level n (default: 4)

0. - no warnings shown
1. - syntax errors
2. - level 1 + missing text, total/number missing, no long order, logical errors (e.g. TEACH without LEARN etc.)
3. - level 2 + not enough silver/men in unit/region, no command etc.
4. - level 3 + "Cautions"; all other warnings
5. - level 4 + Teacher-Student counting check

-x

Normally ECheck begins counting lines at the start of the file. If you use -x, the line counting starts with the FACTION line of the file.

-Ppfad

directory location of the additional data files.
This is written for example so: (-P c:/Eressea/ECheck/en/...).

-Lloc

Sets the ECheck location to loc.

-vMainversion.Level

Since many players use older versions of ECheck this mechanism was designed to inform them. The Eressea server to which you send in your orders template always uses the latest version of ECheck.

Examples:

echeck -r80 orders_template_file

Checks the file orders_template_file. The recruiting cost per man is set at 80 silver.

echeck -c -e orders_template_file >errors_list_file

Checks the file "orders_template_file". The error and warning messages, as well as the tested file, are written to the file errors_list_file

to top of page

Enviorment Variables

Right after starting, ECheck reads the environment variables ECHECKPATH (which points to the ECheck folder) and ECHECKOPTS (which can be used to set all options.) Examples:

  setenv ECHECKOPTS "-c -l -r75"
  setenv ECHECKPATH "~/Eressea/zug:/usr/local/lib/ECheck:."

to top of page

ECheck Commands in Orders Template

Most of the ECheck options can also be given directly in your orders template. To do so you must set the ECheck options before the first command line in your orders template that starts with the order REGION. The command line you use to set ECheck options must always begin with this:
; ECHECK

  ; ECHECK -r80 -w2

The following ECheck options can not be set inside your orders template -e, -E, -P, -s, -h und -?.

You can set the "version" of ECheck, for example directly after the line, shown above. The line will be shown on the screen and is also reported in the output from the server:

  ; VERSION .....

or

  ; ECHECK VERSION .....

In Eressea a line ends with the start of another line (started with a command or order). So that you can write very long lines, to avoid your mail program setting a false line break, ECheck recognizes the backslash \ as a "Line Continuation Punctuation Mark".

Additionally, ECheck can recognize some abbreviations or word shortcuts. But it is the player's responsibility to "correctly" write any abbreviations or shortcuts. I find NA U "Teacher" and G 76 70 Si much more difficult to understand than Name Unit "Teacher" and Give 76 7 Silver.

to top of page

There are many good "Meta-commands" for ECheck. These commands are set after a comment mark // or ; at the beginning of a line.

ECHECK NACH x y

This can be used to tell ECheck, for example, when a unit on a ship is moved to another region, so that ECheck can see this will happen.

ECHECK ROUTE

This changes the "noroute" flag to on or off, based on the previous flag setting. If that flag was off before, it will now be turned on. If that flag was on before, it is then turned off.

ECHECK CONTROL [number]

This tells ECheck that this unit is going to receive control of the ship/building it is on/in or the ship/building number listed. This prevents the warning "has no control" from being reported by ECheck.

ECHECK EMPTY

The unit is considered by ECheck to have no silver by ECheck. This helps avoiding the "loses silver" warning from ECheck when the unit gives away all of it's men.

ECHECK silver-amount

The unit is considered by ECheck to have received the silver listed. This can, for example, be set for an ambassador unit that is supplied with upkeep (food) silver from another faction that has HELP SILVER set to your faction, in order to avoid an ECheck warning.

ECHECK LOHN silver-amount

With this you can set the amount, for ECheck silver calculations, units receive in the region when they do the WORK command. This Meta-command must be listed between the REGION command line and the first UNIT command line of each region.

ECHECK NOWARN

This turns off the direct warnings for the next command line on the orders template. "Indirect warnings" such as not enough silver and the teacher-student counting check will not be effected.

to top of page

"A Test Example"

The following orders are an example. I have listed the errors and warnings as comments.

FACTION 123 "Xandrils Legacy"

 ; ECHECK -l -w4 -r100

 REGION 9,10 ; Xandrilia

 UNIT ki8;          Mr Miller [1,0$]
    Entertain
    Give 4800 1 Men
 UNIT 7530;         Mrs Miller and her son [2,60$]
    Learn Entertainment
 UNIT alf;          Alfred E. Neumann [1,0$]
    Entertain
 UNIT h3z;          A Worker [1,0$]
    Taehc 1234 uh4q Temp 77              ; syntax error: TEACH
    Enter Castle 4r
 UNIT 5045;         Trader [1,110$]
    Learn Etertinment                    ; syntax error: ENTERTAINMENT
    Give 4jL 1000 Silver                 ; unit does not that much silver
    Enter Castle 4r

 REGION 6,10 ; Scoobydo

 UNIT 43f;          Nomad [1,110$]
    Move West

 REGION 1,10 ; Summerland

 UNIT rt4a;         Gardener Lady [1,0$]  ; unit has no silver
    Make Herb
 UNIT bote;         Hero [1,$30]          ; unit has enough silver for both
    Move Southeast                        ; but it is leaving the region!

 NEXT

The errors/warnings from the server look then like this:

ECheck (Version 4.1.4, Sep 16 2001), Zug-Checker für Eressea - Freeware!

Verarbeite Datei `name@email.de,0'.

The above is the e-mail address from which the orders template was sent to the server. The number after the comma is the number of times an orders template was sent into the server from that e-mail address that week.

Recruiting cost set to 100 Silver per man, Warning Level 4.
Silverpool is active.
Error in Line 17: Unrecognized order.
        `Taehc 1234 uh4q Temp 77'
Warning in line 16: Unit h3z hasn't got a long order.
        `UNIT h3z; A Worker [1,0$]'

This is a "follow-on" error. The incorrect order Taehc, should be, of course, Teach. Because the syntax error also is a long order both of the above errors are reported to you by ECheck.

Error in line 20: Unrecognized skill.
        `Learn Etertinment '

Here the skill is not recognized, but the order Learn is correctly written and is therefore accepted as a long order.

Warning in line 21: UNIT 5045 may have not enough silver.
        `Give 4jL 1000 Silver'

You are told that you do not have enough silver to give. It is possible that this unit receives silver from another unit or faction to live (upkeep). However, that is not relevant to this error, as this unit simply does not have 1000 silver to give. If you know, for example, that this unit gets 800 silver from another faction in the region you can note that with this Meta-command ; ECHECK: 800 if you wish.

Warning in line 30: There is not enough silver in Summerland (1,10) for upkeep;
10 silver is missing.

Here we see it is "possible" that there is not enough silver in the region. Of course, it is possible you receive silver from another allied faction in the region by the silverpool.

ECheck also takes into account ship movement, but this is only with ships that your faction controls and is moving.

Units that are on ships controlled by other factions are considered to stay in the region they are at by ECheck for error checking purposes. You can, however, use the Meta-command ; ECHECK NACH x y to inform ECheck that the unit is going to be moved to Region x,y so that ECheck can check if there is enough silver in that region.

Warning in line 19: Unit 5045 has -900 Silver

This is another messages concerning Give 4jL 1000 Silver. The unit has 110 silver, from that the unit needs 10 silver for upkeep (food), therefore it can give 100 silver away. It has then minus 900 silver.

There were orders for 1 faction and 7 units read.
There were 2 errors and 4 warnings found.

If ECheck reports a region without a name (only coordinates) then you know that you had no unit in that region. Because ECheck reads the names of the regions from your orders template, it will not know the region names of any regions you are not in.

to top of page

Miscellaneous

If anyone finds an error in ECheck please send an E-Mail with version number and the orders template (at least the applicable part of the orders template from which the error is generated) and as exact of a description of the error as possible to me.

ECheck should be able to function on all systems. Example call with the gcc:

      gcc -s -O2 -o ECheck echeck.c

ECheck can be downloaded in various formats.

© 2005 Henning Peters