esms - the main engineupdtr - the updating toollgtable - table updating tooltsc - teamsheet creatorroster_creator - creator of ESMS rostersfixtures - generators of league fixtures/schedule
This document is the official Administrator's manual for the ESMS program. It explains how to use the ESMS family of programs to run a fantasy soccer league. Familiarity with the ESMS User's Manual is assumed.
You are reading this document, which means that you have dowloaded ESMS and unzipped the package. If, for some reason you haven't, please do this now. Put everything in a single directory - I will call it the ``working directory'', or shortly the work dir. The work dir contains ESMS programs, configuration files and a ``doc/'' directory with the documentation.
Some notation: administrator - the person who is in charge of a ESMS league. manager - a person participating in a league and managing a team.
I think that the best way to learn something is by going through an example. This section guides you through running a very simple (though a complete !) league. It's trivial and will take only a few minutes, but it will get you started quickly with ESMS.
This section swiftly goes through the steps - for an in-depth explanation of the programs and options involved, see the next section.
Make sure that you have the latest ESMS package unzipped to your work directory. ESMS programs are console based - that is, they don't have a GUI but provide a command line interface. You can work with ESMS from Windows like with any other program, but for some people it is more convenient to open a command prompt (Start->Run->cmd). Unix/Linux users almost always use a command prompt.
Also, make sure you have a text editor at hand. Notepad should do, but it's better to have something more powerful (for example Scite, Textpad, Ultraedit, GWD, etc). Do not use Word or Wordpad unless you know very well what you're doing, since ESMS understands only plain text files, and those editors usually add special formatting characters that don't work with ESMS.
ESMS includes a program that creates rosters, which makes it simpler to initially setup leagues.
The program is called roster_creator and it has a configuration file - roster_creator_cfg.txt
Now run roster_creator - with its default options (which you can modify in roster_creator_cfg.txt).
It should have created 4 new roster files: ss1.txt, ss2.txt, ss3.txt and ss4.txt
Let us now decide on our team names. These are the abbreviations and full team names we will use:
mac - Machos FC bla - Blade Runners esu - ESMS United cra - Crazy Insomniacs
First of all, rename the rosters to these abbreviations - the rosters should now be
mac.txt, bla.txt, esu.txt and cra.txt. You can take a look at the rosters, by the way.
The player names have been randomly generated by roster_creator - they're far from
perfect, but usually you will either let your managers pick their players' names on
their own, or will use real players names for your league. The rosters generated
by roster_creator are good as templates and for testing.
Next, we will set up the full names translation for ESMS. This is done in the main configuration file - league.dat; you should have this file now in the work dir, open it with a text editor.
In the bottom of that file there's an Abbreviations section. Insert the abbreviations there as follows:
Abbreviations: mac = Machos_FC bla = Blade_Runners esu = ESMS_United cra = Crazy_Insomniacs
Now ESMS will know the link between abbreviations and full team names. There is a lot of other interesting settings in league.dat, but that's for the next section. Note the underscores in the full teams' names. These replace spaces, just like in players' names.
Now we will generate the schedule for our small league. A schedule sets which team plays
which and when. You don't have to do it manually, the fixtures program will help. First,
create a text file named teams.txt - it lists the teams fixtures will use. Edit the
file so it looks like this:
Machos_FC Blade_Runners ESMS_United Crazy_Insomniacs
Now, run fixtures. It should have generated a schedule
file named fixtures.txt - this file can be sent to the managers to know what games their
team will play during the league and when. Our fixtures.txt starts like this:
1.
Machos_FC - Blade_Runners ESMS_United - Crazy_Insomniacs
2. ESMS_United - Machos_FC Blade_Runners - Crazy_Insomniacs ... and so on ...
So, in the first ``week'' of the league, Machos_FC plays against Blade_Runners and ESMS_United hosts Crazy_Insomniacs.
Now we'd like to run the first week of our league. But we need the teams' managers to send in
teamsheets, and there are no managers yet. So what can you do ? The tsc program is just
for that - it takes a roster and generates a basic teamsheet for it. The teamsheet isn't too
sophisticated - it has no orders, for example, but it generates correct teamsheets (it won't
name injured and suspended players).
Run tsc - it asks for a roster name, give it mac.txt, give it also a formation+tactic, for
example 442N. It should now create a teamsheet for mac.txt and name it macsht.txt. Take
a look at the teamsheet. Now repeat the same operation for the other 3 teams. At the end you
should have 4 teamsheets, one for each team: macsht.txt, crasht.txt, esusht.txt and blasht.txt
Now we are finally ready to run the games of the first round in our league. Run esms (the
main engine). When it asks for a home teamsheet name give it macsht.txt, and for away teamsheet
give it blasht.txt (recall from the schedule that these two teams clash in the first round).
If everything is OK, ESMS will tell you that the game ended successfully.
Take a look at the commentary file that was created: mac_bla.txt - it lists the game events (note that ESMS inserted the full team names where appropriate).
Repeat the same to run a game between ESMS_United and Crazy_Insomniacs (run esms with
esusht.txt and crasht.txt as the home and away teamsheets, respectively). You should get another
new file - esu_cra.txt
If you were running a real league now, you'd send each commentary file to the managers of the teams who played in that match.
If you look at the bottom of the commentary files, you will see that players accumulated statistics
(such as goals and key tackles), got cards, lost fitness, etc. All this should be now reflected in
the rosters. Besides, you have to create a summary of the round, and create/update the league
table. The updating tool updtr does all that. It's as simple as a couple of clicks.
But first you should create a teams listing for the tool to know which teams it should update. Create a new file - teams.dir (you do this only once for your league !), and put the following into it:
mac.txt bla.txt esu.txt cra.txt
Now run updtr and select option 6 (full update). When you press Enter, updtr runs and
gives you a full report of what it did. updtr did many interesting things - it updated
the rosters (you can take a look at them now), and created several new files. table.txt is
the league table, for example. updtr_summary.txt is a summary of the round that is ready to be sent
to the managers, together with reports.txt that lists all the results. Read in the next section
about what goes into these files.
Wasn't it simple ? Running the next rounds is even simpler, because you don't have to do all the initializations like changing league.dat and creating the fixtures and teams.dir
What you should remember to do is delete the stats.dir file before the next round, so that
updtr won't do unnecessary updates. When you run the main engine for the next round, it
will create a fresh and relevant stats.dir file. The next section explains everything in
much more detail.
This section explains in detail each configuration file ESMS uses.
ESMS is highly customizable, which allows every league to tailor it to its specific needs. The
main configuration file in ESMS is league.dat. This file is built from
key = value
pairs. The keys are not case sensitive, so HOME_BONUS and home_bonus mean the same. The following
are the keys of league.dat ESMS understands:
short = full style. The ESMS tools use the short names (usually a 3 letter
abbreviation) for some things, and full names for some things, and this section is
read to establish the connections.
ESMS is designed to allow easy translation to languages other than English. The language.dat
file is a single point of reference for language-dependent strings. By translating this file,
people can decide how ESMS prints out game commentaries.
Translation is not the only use of language.dat, however. It also allows to extend the
commentaries ESMS prints, and some leagues inded took advantage of this feature.
Take a look at language.dat - its structure is self-explanatory. Lines starting with |
are comments which explain how to translate each commentary group.
When ESMS runs a game, it computes three major skill totals for each team, and uses those to run the simulation. The totals are:
To compute these three totals, the contribution of each active player is summed. Each player
(except the GK) contributes to all three totals, depending on his major skills (Tk, Ps, Sh),
team tactic, and other factors (side, fitness, etc). The tactic acts as a multiplier on the
player's major skills. For each position the player plays, the contributions are different.
All these multipliers are set in the tactics.dat configuration file.
The defaults that come with ESMS withstood the testing of time, so it's adviced not to change them, although that is possible if your league wants to modify tactics or even create new ones.
A sample from tactics.dat will explain its structure:
# P - Passing MULT P DF TK 1.0 MULT P DF PS 0.75 MULT P DF SH 0.3 MULT P DM TK 0.87 MULT P DM PS 0.87 MULT P DM SH 0.28 MULT P MF TK 0.25 MULT P MF PS 1.0 MULT P MF SH 0.25 MULT P AM TK 0.25 MULT P AM PS 0.87 MULT P AM SH 0.68 MULT P FW TK 0.25 MULT P FW PS 0.75 MULT P FW SH 1.0 BONUS P L MF SH 0.5 BONUS P L MF TK 0.5 BONUS P L FW SH 0.25
There are two types of lines here. MULT lines set the tactic multiplier - for each of the positions (DF, DM, MF, AM, FW) - each of the contributions (TK, PS, SH). Thus, for example a DF in a team playing P has his PS contribution multiplied by 0.75. BONUS lines add bonuses to certain tactics against other tactics.
ESMS consists of several programs and some files these programs read and write. For each program, I list the input files it expects and the output files it generates
Note: Each of the ESMS programs can accept a command line argument --no_wait_on_exit that makes
it exit immediately after finishing, without waiting for you to press Enter. While the waiting is
convenient when running from Windows, people who use ESMS from the command line usually prefer to
supply this argument. For running automatic games, it is essential.
esms - the main engineesms is the main game engine of ESMS. It runs a simulation of a soccer game between two teams,
given their teamsheets and rosters (you can learn in detail about teamsheets and rosters in the
User's manual).
Input: Configuration files (league.dat, language.dat, tactics.dat), a pair of rosters and a pair of teamsheets for these rosters.
Output: A commentary file for the game, and adds a line to the reports.txt file, and a line to the stats.dir file.
A commentary file is generated by esms and contains the listing of all major events in the game.
It is intended to be read by humans, and is usually sent to the two managers of the playing teams.
The commentary file also contains a summary of game statistics and changes in players' attributes
which is used by updtr to update the rosters.
reports.txt contains a summary of games' results. It is generated by esms and can be sent to
the whole league announcing all the scores in some round. This file is also used when updating
the league table.
stats.dir contains a list of commentary files which updtr should use to update the rosters.
esms creates it and adds a line to it for each game it runs. In the end of the round, after
updtr did its updating, this file
should be deleted - it will be regenerated by esms in the next round.
teams.dir is simply a list of the rosters that make your league. It should be created only once
in the beginning of your league season. This file is essential for updtr to know which rosters
it should update.
updtr - the updating toolupdtr is the second of the two most important tools an ESMS league administrator uses to run
a league. After esms runs all the games, updtr is used to handle all the rest - update the
rosters with player statistics, update the league table with the latest results, and take care
of injuries, suspensions and fitness. updtr can do it all just in a few clicks, and usually
runs smoothly if your league files are set up correctly.
When you run updtr you get the following menu:
What would you like to do ? 1) Update rosters 2) Decrease injuries 3) Decrease suspensions 4) Update league table 5) Decrease suspensions + update rosters 6) Decrease suspensions, injuries + update rosters, league table Enter your choice ->
This lists the various functions updtr performs, and their combinations to make matters simpler. The
functions are:
Update rosters: updtr looks at all game commentaries listed in stats.dir, and updates
the players' attributes from the played games in the team's rosters. For example, it adds
1 to the ``Games played'' statistic of all players who played, computes the injury periods of
newly injured players, etc.
Decrease injuries / suspensions: Players in ESMS are injured for a certain amount of weeks and
suspended for a certain amount of games. updtr takes care to reduce the period of injury/suspension
of each injured/suspended player. These options are separated because in some occasions suspensions
and injuries are not parallel. For instance, in cup games that happen in the middle of the week, injuries
are usually not decreased, but suspensions are.
Update league table: updtr takes table.txt and the latest results from reports.txt and updates
the table. If the table doesn't exist (like in the first league round), updtr just creates it.
The other options are combinations to make working with updtr more efficient. For instance, (6) is
used to update after league rounds - it does everything one needs. Most often, this is the single option
admins use after running league rounds. (5) is often used to run updates after cup games. The multitude
of separate options and their combinations were designed to provide the league administrator with a
maximal level of flexibility.
Input: updtr's input depends on the function you ask it to perform, but generally it uses:
the configuration file league.dat, stats.dir, teams.dir, commentary files listed in stats.dir,
rosters, reports.txt and table.txt
Output: updtr updates the rosters, table.txt and creates a summary file to be sent to
the league managers - updtr_summary.txt
A summary file created by updtr after each round. This file contains interesting information about
the league round, together with some statistics. It is usually sent to the managers of the league
after each round.
This is a standard league table file. For example:
Pl Team P W D L GF GA GD Pts ----------------------------------------------------------------- 1 Blade Runners 4 2 2 0 3 1 2 8 2 Crazy Insomniacs 4 2 0 2 5 4 1 6 3 ESMS United 4 1 2 1 4 3 1 5 4 Machos FC 4 0 2 2 0 4 -4 2
The columns are: Pl - place, Team - team name, P - games played, W/D/L - games won/drawn/lost, GF - goals for (how many goals the team scored), GA - goals against (how many goals the team conceded), GD - goal difference, Pts - points.
lgtable - table updating toolThe league table updating ability is so useful that a separate tool exists to handle it. League
administrators don't really need it to run a league, but I include it in the package because some
people find it convenient. lgtable does what updtr does in its table update - it updates table.txt
with results from reports.txt.
Input: table.txt and reports.txt
Output: updates the table.txt
tsc - teamsheet creatortsc assists managers to create template teamsheets. It is given a roster name and a formation+tactic
and creates a teamsheet. Don't expect tsc's teamsheets to bring you the league title - they are
far from being sophisticated. tsc doens't care about fitness, sides and it doesn't create orders.
But the teamsheets it creates are correct (contain no injured/suspended players) - they will run with esms
so it is useful to just create template teamsheets for your team. Administrators also use tsc to create
teamsheets for managers that forgot to send a teamsheet for some game.
Input: a roster
Output: a teamsheet
roster_creator - creator of ESMS rostersroster_creator creates as many random rosters as you want, using a configuration file - roster_creator_cfg.txt
It is very useful for creating random players and teams.
Input: roster_creator_cfg.txt configuration file
Output: one or more rosters, depending on what's set in the configuration file.
This file sets the configuration options for roster_creator as key = value pairs.
roster_creator creates players that are suitable
for certain positions - for example players with high Ps for MF.
roster_creator tries to fit the average rating to the option
set in the configuration.
roster_creator creates rosters with the names ``xx1.txt'', ``xx2.txt''
and so on.
roster_creator to create randomized names for the players. If this
option is not set, blank spaces will be left in the rosters instead of the names.
fixtures - generators of league fixtures/scheduleThis program creates a schedule / fixtures list for a league. A league is played in two rounds, N-1 games in each round (where N is the amount of teams). During a league run, each team plays each other team twice, once home and once away.
Input: table.txt - list of team names to create the fixtures for. Full names should be listed here.
Output: a list of fixtures in fixtures.txt
The input and output of this program is so simple that there's no point to list the files it uses separately.
You probably noticed that the only tools a league administrator really needs are esms
and updtr. All the rest are just auxiliary programs some administrators use, and some
don't.
Most of the files created by the ESMS programs during a run of some round are either temporaries that are needed to communicate between the tools, or information files that are to be sent to the league managers. The files that really last between rounds are the configuration files, teams.dir, table.txt and the rosters. All the other files are usually deleted after performing their purpose, in order not to clutter the league directory. For example, after a round is run, the commentary files, reports.txt and stats.dir should be deleted.
That's about it for a guide on ESMS administration. Like with any unfamiliar program, it may look intimidating at first, but once you get to know it, it is really very simple. When your league is correctly set up, running the ESMS tools is very simple and only takes a few moments. Seasoned administrators report that each week the bulk of their time (which isn't more than a few minutes) goes into fixing mistakes in teamsheets sent in by managers. The rest of the process - running the games and updates takes almost no time.
So if you are new to ESMS, the best advice I can give is practice. Go through the tutorial again, make sure everything makes sense, run a few more rounds, set up a small test league for friends. Practice brings perfection.
If you need any help at setting up a league, or have any questions and requests regarding the ESMS programs, feel free to ask me.
This document, as is ESMS itself, was written and is maintained by Eli Bendersky. My email address is eliben@gmail.com. Feel free to send me comments, feedback and questions. I usually answer emails very regularly and will be glad to help.
ESMS also has a low-volume, but important mailing list at Yahoo Groups. In the list new features are
usually discussed, and
people often ask questions and request ideas for their ESMS leagues. To sign to the mailing list,
visit http://groups.yahoo.com and look for esms.
Eli Bendersky (eliben@gmail.com)