Atlantis Little Helper

Notes about the 2019 changes
Introduction
Installation and configuration

Compiling the sources
Installation
Installation on Windows
Configuration

Map Legend
Use bitmaps to display terrains
Alliance support
Pseudocomments (special abilities)
Python enhancements

Downloads and contacts

You can check for new versions at https://alh.lightspear.net/

Notes about the 2019 changes to ALH

I have made changes to ALH which diverge from the original design of ALH. I added features which rely for a large part on details about how Atlantis works. One such component is the routeplanner, which can calculate how long it takes for a unit to travel from its current location to its destination. This takes properties of the terrain, roads and weather into account. It does not support the atlantis v5 'queued up' movement points yet. It can also create a move order with the fastest path to the destination for you, see the $move Pseudocommand.

As ALH is now aware where units are going, as a convenience the destination hex will show the arriving units in the unit list at the bottom, with a yellow background color. You can issue orders to them, regardless of whether you have the departure or the arrival hex selected. Units which are leaving a hex have a blue color, and guards have a brown color. Note - a unit may need more than one turn to arrive at its destination. It will not show in hexes along the route.

If ALH knows how shafts are connected it can predict movements to the underworld. ALH learns this when one of your units travels through a shaft. If you know how shafts are connected and want to tell ALH this, you can use the connect shafts option from the menu.

Another major change is that new units, such as NEW 1, are no longer transient. They keep exisiting even after you select another hex to look at. Instead of typing the FORM X command in the orders for another unit, ALH does this for you. Right click on the unit which should create the new unit and select "Split". In the Split Unit dialog you can directly give items from the original unit to the new one and issue orders for the new unit. After splitting, you can select the new unit and modify its orders. Repeated @FORM no longer works.

Another feature is the economy prediction. ALH is quite good at predicting how much silver a unit will have during the various phases when the turn runs. It will calculate how much silver a unit will tax for, its study costs, which units will share silver if you use the SHARE 1 flag, and whether a unit will have enough maintenance silver to survive the maintenance phase. You can activate these options in the Economy Menu; when you start ALH they are always off.

Feedback is welcome, you can leave me a message on discord @Zorky#3892 or erwin@bridgebar.nl.

Introduction

Atlantis Little Helper (ALH) is a client application for Atlantis PBEM game. It is simple and it is intended to be as much compatible with different varieties of Atlantis 4 as possible.
There were two design goals for ALH - simplicity and compatibility. ALH is not overloaded with controls, it parses reports as little as possible and it is not pretending to know everything about Atlantis ruleset. So new items, skills and such would not cause it to crash.
ALH is an Open Source project. It is cross-platform (Windows/Unix/Mac), at least it was tested on Linux and Windows.
ALH is available as source code and as compiled Windows and Linux binaries.

Installation and configuration

Compiling the sources

Install wxWidgets GUI Library. If it is not in you distribution, download from www.wxwidgets.org. Versions 2.4.x, 2.6.x work fine. You will need both base system and development files.
If you want Python support, install Python (available from www.python.org). Again, both base system and development files are needed.
For win32 platform, set WX2 evironment variable to the path you have installed wxWidgets into and PY24 to the Python's installation path. Then use ah.dsp file for VC++ compiler.
On *nux run
```
./configure
make
```
Installation
ALH uses current directory for storing configuration and history files. So, you will need a separate directory for every game you are playing. And that directory must be a current directory when you are starting ALH.
Just copy ALH executable to some directory on the path and run it from the game directory.

Installation on Windows
ALH uses current directory for storing configuration and history files. So, you will need a separate directory for every game you are playing. And that directory must be a current directory when you are starting ALH. The simplest way to do it is just to copy ah.exe in every game directory. Or desktop shortcut may be created for each game, starting directory set to point to your game directory. And so on.
Windows file extension association may be created, so you will just have to click on a report file to run ALH. If you placed ALH into, say, d:\bin, then use the next line for "Application used to perform action" when creating an association: d:\bin\ah.exe "%1" This is yet another way to handle the current directory requirement.

Configuration
ALH stores configuration data in two files:
ah.cfg contains client configuration, such as windows positions and sizes.
ah.st.cfg contains game specific data, such as item descriptions or report file names.
There are user interfaces for the most common configuration tasks. For example, fonts and colors can be changed from Menu/View/Options. Column sets in the unit lists can be modified from Menu/Windows/List Columns/...
Config files can be modified manually as well.

Config file sections of interest are:

    [ALIASES]        - In this section aliases must be in underscored
			form, like Horse_Training. In orders both forms
			are valid, so it ok to write "Horse Training"
			as well.
format:
    alias  = name


    [COMMON]         - common settings
values:
    HEX_SIZE_LIST    - comma separated list of hex sizes
    MEN_THRESHOLD    - if number of your men in a hex is bigger then
                       this number, thick bullet will be displayed on
                       the map.
    REPORT_CACHE_MAX - how many reports to keep in memory.
    BRIGHTNESS_DELTA - difference in brightnes between normal and
                       read-only edit panes.
    DECORATE_ORDERS  - add some comments to the generated order file.
    LEAD_SKILL_BONUS - Leaders and heroes skill bonus for Arcadia games.
    TAX_PER_TAXER    - how much silv each taxer collects per turn.
    CHECK_FACTION_X_NEW_Y - 1 to check, 0 to not check if actual FACTION X NEW Y unit exists.
                       Of course, you need faction's X report and orders for the check.
    BATTLE_STATISTICS- 0 to disable battle statistics. Checked during report load                   
    UPKEEP_LEADER    - The maintenance fee for leaders
    UPKEEP_PEASANT   - The maintenance fee for normal characters

    [LIST_COL_UNIT_<set name>] - set of columns to be diplayed in the unit list
format:
    sequence  = width, flags, property, column_name

    sequence    - order in which columns will appear in the unit list
    width       - column width, easily changed with a mouse :)
    flags       - 0 for left alignment, 1 for right alignment
    property    - property name, alias or group name
    column_name - display name for the column


    [UNIT_PROPERTY_GROUPS] - unit property groups which can be displayed
                            in the unit list as columns
format:
    group_name  = comma_separated_list_of_property_names
values:
    junk_items  - items you do not need, used for popup menu action
                discarding junk items.
    trade_items - used to calc trade points for buying them.
    men         - used to find out if a particular item in unit's posession is a men
    mag_skills  - used to find out if a skill is a magic skill, needed for Arcadia


    [PANE_MAP]   - settings for the map panel
values:
    DASH_BAD_ROADS - show bad roads by dashes or by color
    WALL_WIDTH     - line thickness for drawing walls.
    FLAG_WIDTH     - line thickness for drawing flags.
    ROAD_WIDTH     - line thickness for drawing roads.

    [MAX_SKILL_LEVELS] - maximum skill levels for races
    race = speciallevel, defaultlevel, comma separated list of special skills

    [MAX_SKILL_LEVELS_MAGIC] - maximum magic skill levels for race heroes (Arcadia)
    race = speciallevel, defaultlevel, comma separated list of special skills

    [RESOURCE_LAND]
    LandType = comma separated list of advanced resources, example:
    Forest   = IRWD, YEW

    [RESOURCE_SKILL]
    skill = comma separated list of resources and required skills, example:
    LUMB = IRWD 3, YEW 5

    [STRUCTURES] - structures and comma-separated list of their attributes.
                   The following attributes are possible:
    MOBILE        - it is ship
    MIN_POWER NN  - value of minimum required number of sailors
    MAX_LOAD  NN  - ships capacity
    HIDDEN        - special skills required to see the structure
    ROAD_N        - Road N
    ROAD_NE       - Road NE
    ROAD_NW       - Road NW
    ROAD_S        - Road S
    ROAD_SE       - Road SE
    ROAD_SW       - Road SW
    SHAFT         - It is shaft
    For example:
        Balloon = MOBILE, MIN_POWER 10, MAX_LOAD 800

    [PLANE_SIZE] - ah.st.cfg. When you know the dimensions of your world, enter
                   them and ALH can use them to wrap the map before you explore
                   the edge. Syntax: plane_name = x-min,y-min,x-max,y-max. 
                   For example:
        [PLANE_SIZE]
        Overworld  = 0,0,29,29
        underworld = 0,0,9,9

Unit properties

Units have properties. Every item unit posess or skill it has is a property. Short form of an item/skill name is a property name. Undescore is appended to a skill name to distinguish it from an item name. For example, HORS property specifies how many horses unit has and HORS_ specifies unit's skill level in horse training.
Unit properties are used to display units in the lists and process orders.
Underscores are only used for unit's skill properties, in orders skill names are used as usual!

Built-in unit properties are:

    id                - unit id
    name              - unit name
    description       - full unit description
    factionid         - faction id
    faction           - faction name
    landid            - id of region the unit is in
    structid          - id of a structure the unit is inside
    structowner       - is unit an owner of a structure?
    structname        - name of a structure the unit is inside
    comments          - the first comment line of default orders/comments
                        pane (the first character of a comment line is ';')
    orders            - orders
    teaching          - shows how many students per teacher this unit is
                        teaching (rounded up), or how many days of
                        teaching the unit receives (rounded down).
    weight            - unit's weight.
    movement          - movement mode.
    sequence          - report's order of units.
    flags_standard    - standard unit flags, condensed into string.
    flags_custom      - custom unit flags, comma-separated.
    flags_custom_abbr - custom unit flags, numbers condensed into string.

It is possible to assign an alias to a property name. Default aliases are defined based on 4.0.4 source code. Aliases are not deducted from the report, they are read from the config file!
Properties can be combined into groups in the [UNIT_PROPERTY_GROUPS] section.
When defining a group, only property names can be used. Aliases and groups are disabled here since they slow down display significantly.
Features and Playing
ALH accepts report file name as a command line parameter.
ALH processes GIVE, BUY, SELL, FORM, STUDY, TEACH, CLAIM, LEAVE, ENTER, PROMOTE, MOVE, SAIL, ADVANCE, TURN/ENDTURN, ATTACK, ASSASSINATE, STEAL, GUARD, AVOID, BEHIND, REVEAL, HOLD, NOAID, CONSUME, NOCROSS, TAX, AUTOTAX orders.
Try right-clicking and double-clicking everywhere! There are many actions performed this way. For example, double-clicking in the Errors and Messages window will select a corresponding unit and/or hex.
There are hotkeys to make writing orders easier while in the same hex:
Ctrl-U goto Unit list
Ctrl-O goto Orders pane
Ctrl-N select next unit (while focus stays the same pane)
Ctrl-P select previous unit (while focus stays the same pane)
If the split-unit dialog has focus, Ctrl-Enter/Return activates the submit button.
ALH may become confused when a new plane appears in a report. In this case just click a couple of times on plane switching/centering buttons and everything will be back to normal.
In the reports regions' X and Y coordinates must be in the range [-2048 .. 2047], maximum number of planes is 256. Faction and unit ids must not exceed 65535.
Map Legend
There is a number of icons which could be displayed in the map:
'$' specifies taxed regions.
'P' specifies regions with production activities.
Pyramid represents a generic object.
Inverted Pyramid is a ship.
Ladder is a shaft.
A square with hole in it is a gate.
Line is a road. A bad road is dashed line or thin line. Dashing does not work on Windows.
Use bitmaps to display terrains
Get a set of windows bitmap files you want to use for the terrain. File names must correspond to terrains, for example bitmap for forest must be called 'forest.bmp'.
Place bitmaps into your game folder.
Alliance support
Allies' reports can be joined to the player's report. It will combine visibility of units, hexes and such.
Allies' units can be given orders just like player's units.
Joining can be done through Menu/File/Join or all the reports can be given in the command line.
Map fragments can be joined as well. Of course, map fragments must be in the natural format, the one used in the reports!
Map fragments can be exported as well. It is possible to drag mouse on the map selecting an area, and then export that area.
Pseudocomments (special abilities)
Pseudocomments are special comments which allow to modify the way how a command in the orders is executed.
The following pseudocommands are supported:
$ne - ignore warnings and errors. If error happens, it will affect the command as usual, however, no indication of the error will be given.
For example,

@give 123 all iron ;$ne

will not keep annoying you if unit 123 does not have any iron.
$get N itemname - will get N items. N can be negative. Useful when ALH does not know about side effects of some commands, such as price of casting a spell. Example:

cast Magic_Shoe_Making ;$get -100 silv
;$move <location>
If the unit does not have a move order, ALH will create a move order for the unit to go to the specified location. Location can be specified by coordinates or by settlement name.
;$checkzero <item>
Creates warning if unit has 'item'. Using a category such as 'stuff' works. Useful for checking that a caravan unit fully offloads all of its cargo. It is easy to forget that your iron mine suddenly gives mithril to your transport and forget to offload.
;$upkeep <X>
deducts X turns of upkeep.
;$travel < walk | ride | fly >
ALH by default will issue a warning if a unit tries to move further than it can travel in one turn.
You can suppress any warnings by adding ';ne' to the move order, but the next turn it probably comes back when on a lenghty journey. The travel command will suppress warnings about multi-turn movement, and creates a warning if the unit cannot move at the specified speed.

	examples: 

	;$move 10,14
	;$move mountain (10,14)
	;$move Peghtmont
		MOVE NE NE NE NE NE NE NE N N ; 9 turns
		MOVE SW NW NW 1 IN NE ; 5 turns
	;$move 10,14,2 <underworld>
	;$move cavern (10,14,2 <underworld>)
		MOVE SE SW SW S ; 4 turns
	;$upkeep 2 ; will reduce silver count by 20 for a peasant.
	@;$travel ride ; do not warn about multi-turn move order
	@;$travel walk ; quite useful for livestock transports, or perhaps for horse-pulled wagons.

	One caravan:
	@TURN
	  give 123 all iron ;$checkzero stuff
	  give 123 all silv ;$move 4,4
	ENDTURN
	@TURN
	  take from 456 2000 silv ;$move 5,7
	ENDTURN

Python enhancements

Python unit filters

Both Python and conventional filters are supported.
When making conventional filter, corresponding Python filter is constructed in parallel to give some help.
Unit filter is a Python expression returning true or false, for example
```
   SILV < 0 
```
Filter is executed in the context of a unit. In other words, unit properties are global Python variables.
Python filters are more flexible, allowing to compare unit properties, for example. Consider the following filter
```
   LEAD == 0 and SILV > MEN*10*12 and (SWOR >= MEN or XBOW >= MEN) 
```
which returns all armed non-leader units having enough silv for a year.
It is possible to use functionality in Python modules for processing filters. All required imports should be included in ah.common.py file. By default it imports only string module, which allows advanced string filtering. For example, the following filter will return all avoiding units:
```
   string.find(flags_standard, "a") >= 0
```

Downloads and contacts

The latest sourcecode of Atlantis Little Helper can be found at https://github.com/erwin47/alh.
ALH was originally designed and developed by Max Shariy.
- Some valuable contributions received from Sh'Arcashmo.
- The new ALH website design by Giovanni Baldini .
- The new map window appearance designed and developed by Jan Rietema .
- Loriaki made sure it works on OS X and provided build for it.