5dplomacy/docs/design.md

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. 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 occupation by a unit and being a supply center are properties of the Province as a whole. This makes it easy to represent the different paths available to armies or fleets: the land and sea graphs are unconnected and only interact at the Province level. This 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 fundamental difference between army movement and fleet movement, since the inability of armies to move into the ocean is ensured by the lack of edges between land and sea locations. Unit type still remains significant with respect to convoys, since only fleets can convoy and only armies can be convoyed. Unit type is also relevant to the interpretation of orders that do not fully specify location. And, of course, unit type matters to how clients represent the units.

Internally, land locations are named "land" or "l" and water locations are called "water" or "w". For example, SPA has three locations: SPA/nc, SPA/sc, and SPA/l. This provides a uniform way to handle unit location, because locations in orders without coast specifications can easily be inferred from the map and the unit type. For example, "A Mun - Tyr" can easily be inferred to mean "A Mun/l - Tyr/l" because A Mun is located in the "land" location in Mun and the "land" location in Tyr is the only connected one.

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.

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" as well as "The Math of Adjudication". The approach taken follows the partial information algorithm later described in DATC v3.0 §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, leaving the inputs unchanged. 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.

Game options

In order to support different decisions about how adjudication or the rules of multiversal Diplomacy are implemented, the Options object is a grab-bag of settings that can be used to tune the adjudicator. The following options are supported:

• implicitMainTimeline: Whether orders to units with no timeline designation should be interpreted as orders for the first timeline. (This may be the default behavior to support adjudication of classical Diplomacy games.)
• enableOpenConvoys: Whether the open convoy order can be used.
• enableJumpAssists: Whether the jump assist order can be used.
• victoryCondition: The victory condition to use for the game. "elimination" means a player is eliminated if they are eliminated in a single timeline and the last player standing wins. "majority" means a player wins if they control the majority of supply centers across all timelines. "unique" means a player wins if they control 18 unique supply centers by name across all timelines.
• adjacency: The rule to use for determining province adjacency. "strict" means provinces are adjacent if they are within one timeline of each other, within one turn of each other, and geographically adjacent. "anyTimeline" follows "strict" but all timelines are considered adjacent to each other.

[!WARNING] Options are not implemented yet.