41 lines
4.1 KiB
Markdown
41 lines
4.1 KiB
Markdown
|
# Architecture
|
||
|
|
|
||
|
|
In lieu of a systematic overview of the architecture, here are a few scattered notes on design decisions.
|
||
|
|
|
||
|
|
## Provinces and Locations
|
||
|
|
|
||
|
|
The data model here is based on the data model of [godip](https://github.com/zond/godip). In particular, godip handles the distinction between army and fleet movement by distinguishing between Provicnces and SubProvinces, which 5dplomacy calls Locations. The graph edges that define valid paths are drawn between Locations, but a Province's supply center or occupation by a unit are at the Province level. This makes it easy to represent the different paths available to armies or fleets, since each is essentially moving through a distinct graph from the other, while still interacting at the Province level. It also provides a way to distinguish the connectivity of multiple coasts within a province.
|
||
|
|
|
||
|
|
As a consequence of the unconnected land and sea graphs, there is no special significance to unit type in movement, since the inability of fleets to move to land locations is ensured by the lack of edges from land locations to sea locations. Unit type is still relevant to convoy orders and how clients represent the units.
|
||
|
|
|
||
|
|
## Timeline notation
|
||
|
|
|
||
|
|
In Diplomacy, there is only one board, whose state changes atomically as a function of the previous state and the orders. Thus, there is only ever need to refer to units by the province they instantaneously occupy, e.g. "A MUN -> TYR" to order the army in Munich to move to Tyrolia. 5dplomacy needs to be able to refer to past states of the board as well as alternative timeline states of the board. The timeline of a province is specified by prefixing the timeline designation, e.g. "a-MUN" to refer to Munish in timeline a or "b-TYR" to refer to Tyrolia in timeline b. The turn of a province is specified by a suffix, e.g. "LON@3" to refer to London in turn 3.
|
||
|
|
|
||
|
|
> [!WARNING]
|
||
|
|
> The timeline notation is in flux and archaeological layers of previous decisions are scattered around the code.
|
||
|
|
|
||
|
|
## Adjudication algorithm
|
||
|
|
|
||
|
|
The adjuciation algorithm is based on the algorithms described by Lucas B. Kruijswijk in the [Diplomacy Adjudicator Test Cases v2.5 §5 "The Process of Adjudication"](https://web.archive.org/web/20230608074055/http://web.inter.nl.net/users/L.B.Kruijswijk/#5) as well as ["The Math of Adjudication"](http://uk.diplom.org/pouch/Zine/S2009M/Kruijswijk/DipMath_Chp1.htm). The approach taken follows the partial information algorithm later described in [DATC v3.0 §5.E](https://webdiplomacy.net/doc/DATC_v3_0.html#5.E). These algorithms are based on the recursive evaluation of binary (move succeeds, unit is dislodged, etc.) and numeric (attack strength, hold strength, etc.) decisions.
|
||
|
|
|
||
|
|
In order to support multiversal time travel, 5dplomacy adds an additional binary decision for each relevant timeline: whether the timeline advances. The timeline advance decision is resolved for each timeline-turn as follows:
|
||
|
|
|
||
|
|
- The head of a timeline always advances.
|
||
|
|
- The target of a new (i.e. not previously adjudicated) and successful move always advances.
|
||
|
|
- A timeline-turn adcanfes if the outcomne of a battle is changed, as follows:
|
||
|
|
- The outcome of a dislodge decision is changed.
|
||
|
|
- The outcome of an intra-timeline move decision is changed.
|
||
|
|
- The outcome of an inter-timeline move into that timeline-turn is changed.
|
||
|
|
|
||
|
|
A timeline head advances into a new turn of the same timeline. A turn behind the head advances into a forked timeline.
|
||
|
|
|
||
|
|
Note that the timeline advance decision depends on the result of previously-adjudicated decisions, which informs the data model.
|
||
|
|
|
||
|
|
## Pure adjudication
|
||
|
|
|
||
|
|
The core adjudication algorithm is intended to be a pure function. That is, adjudication begins with all relevant information about the game state and orders, and it computes the result of adjudicating those orders. Data persistence is handled by a higher layer that is responsible for saving the information the adjudicator needs and constructing the input data structure. This is intended to encapsulate the adjudicator logic and decouple it from other concerns that depend on implementation details of the application.
|
||
|
|
|
||
|
|
> [!WARNING]
|
||
|
|
> This is not complete and the adjudicator is still stateful.
|