Jaculabilis/5dplomacy
1
1
Fork 0
Code Pull Requests Activity

Update and refactor documentation

Browse Source 
The README will become an entry point for using the project. Notes on design decisions and explanations of the rules are split off into their own documents.
This commit is contained in:
Tim Van Baak 2024-08-09 13:18:49 -07:00
parent 3db01c0ffd
commit 9fd63f4317
3 changed files with 99 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
README.md
View File

@ -2,28 +2,10 @@
_5D Diplomacy with Multiversal Time Travel_ is a _Diplomacy_ variant that adds multiversal time travel in the style of its namesake, _5D Chess with Multiversal Time Travel_.
## Acknowledgements
This project was inspired by [Oliver Lugg's proof-of-concept version](https://github.com/Oliveriver/5d-diplomacy-with-multiverse-time-travel) and based on the adjudication algorithms of Lucas B. Kruijswijk. For more information on the design, see [docs/design.md](./docs/design.md). For more information on the rules of multiversal Diplomacy, see [docs/rules.md](./docs/rules.md).
This project was inspired by [Oliver Lugg's proof-of-concept version](https://github.com/Oliveriver/5d-diplomacy-with-multiverse-time-travel). The implementation is based on the algorithms described by Lucas B. Kruijswijk in the chapter "The Process of Adjudication" found in the [Diplomacy Adjudicator Test Cases](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). Some of the data model is inspired by that of Martin Bruse's [godip](https://github.com/zond/godip).
## Usage
## Variant rules
This project is not ready for end users yet!
### Multiversal time travel and timeline forks
_Diplomacy_ is played on a single board, on which are placed armies and fleets. Sequential sets of orders modify the positions of these units, changing the board as time progresses. This may be described as something like an "inner" view of a single timeline. Consider instead the view from "above" the timeline, from which each successive state of the game board is comprehended in sequence. From "above", each turn from the beginning of the game to the present can be considered separately. In _5D Diplomacy with Multiversal Time Travel_, units moving to another province may also move to another turn, potentially changing the past.
If the outcome of a battle in the past of a timeline is changed by time travel, then the subsequent future will be different. Since the future of the original outcome is already determined, history forks, and the alternate future proceeds in an alternate timeline.
Just as units in _Diplomacy_ may only move to adjacent spaces, units in _5D Diplomacy with Multiversal Time Travel_ may only move to adjacent times. For the purposes of attacking, supporting, or convoying, turns within one season of each other adjacent. Branching timelines and the timelines they branched off of are adjacent, as well as timelines that branched off of the same turn in the same timeline. A unit cannot move to the province it is currently in, but it can move to the same province in another turn or another timeline.
When a unit changes the outcome of a battle in the past, only the timeline of the battle forks. If an army from one timeline dislodges an army in the past of a second timeline that was supporting a move in a third timeline, an alternate future is created where the army in the second timeline is dislodged. The third timeline does not fork, since the support was given in the original timeline. Similarly, if a unit moves into another timeline and causes a previously-successful move from a third timeline to become a bounce, the destination timeline forks because the outcome of the move changed, but the newly-bounced unit's origin timeline does not fork because the move succeeded in the original timeline.
### Sustaining timelines and time centers
Since there are many ways to create new timelines, the game would rapidly expand beyond all comprehension if this were not counterbalanced in some way. This happens during the _sustain phase_, which occurs after the fall movement and retreat phases and before the winter buid/disband phase.
(TODO)
### Victory conditions
The Great Powers of Europe can only wage multiversal wars because they are lead by extradimensional beings masquerading as human politicians. When a country is eliminated in one timeline, its extradimensional leader is executed, killing them in all timelines.
I am working in VS Code on NixOS so currently the developer setup is optimized for that. Code is launch from inside a `nix develop` shell so it gets the environment.

40
docs/design.md Normal file
View File

@ -0,0 +1,40 @@
# 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.

55
docs/rules.md Normal file
View File

@ -0,0 +1,55 @@
# Multiversal Diplomacy rules
_Diplomacy_ is played with armies and fleets on a single board. Each set of orders results in the state of the board changing. Suppose that, instead of moving the pieces on the board, a second board were set up according to the resolution of the orders given to the first board. If this continued, the whole evolution of the game board could be observed from start to finish. One could even go back to a board state in the middle of the game and give a different set of orders, creating a new version of history and playing out a different game.
Now suppose that, in addition to moving to another province on the board, units could move to _another board_, changing the outcome of the turn and creating a new sequence of boards as the new history plays itself out. This is _5D Diplomacy with Multiversal Time Travel_. Units may move or support into the past, changing history and creating alternate timelines, or move or support into those alternate timelines.
## DATC compliance
When the adjudicator is in a more complete state, this section will declare the extent of the adjudicator's DATC compliance. If no unit attempts multiversal time travel, the game plays out exactly as _Diplomacy_ does normally.
The MDATC (Multiversal Diplomacy Adjudicator Test Cases) document defines test cases that involve multiversal time travel.
## Variant rules
### Multiversal time travel and timeline forks
Just as units in _Diplomacy_ may only move to adjacent spaces, units in _5D Diplomacy with Multiversal Time Travel_ may only move to adjacent times. For the purposes of attacking, supporting, or convoying, turns within one season of each other adjacent. Branching timelines and the timelines they branched off of are adjacent, as well as timelines that branched off of the same turn in the same timeline. A unit cannot move to the province it is currently in, but it can move to the same province in another turn or another timeline.
When a unit changes the outcome of a battle in the past, only the timeline of the battle forks. If an army from one timeline dislodges an army in the past of a second timeline that was supporting a move in a third timeline, an alternate future is created where the army in the second timeline is dislodged. The third timeline does not fork, since the support was given in the original timeline. Similarly, if a unit moves into another timeline and causes a previously-successful move from a third timeline to become a bounce, the destination timeline forks because the outcome of the move changed, but the newly-bounced unit's origin timeline does not fork because the move succeeded in the original timeline.
### Sustaining timelines and time centers
Since there are many ways to create new timelines, the game would rapidly expand beyond all comprehension if this were not counterbalanced in some way. This happens during the _sustain phase_, which occurs after the fall movement and retreat phases and before the winter build/disband phase.
The seven capital supply centers are also considered _time centers_. During the sustain phase, each time center chooses a timeline to sustain. Each timeline with at least one time center sustaining it remains in play. All other timelines dissolve into the ether and cease to be playable. A time center's "vote" is split equally among all timelines and each fraction is owned by the owner of that time center in that timeline.
> [!WARNING]
> The sustain phase is a speculative feature and has not been implemented yet.
### Victory conditions
The Great Powers of Europe can only wage multiversal wars because they are lead by extradimensional beings masquerading as human politicians. When a country is eliminated in one timeline, its extradimensional leader is executed, killing them in all timelines.
> [!WARNING]
> Victory conditions have not been implemented yet.
### Open convoys
The standard _Diplomacy_ rules require that a convoy order include the convoyed unit's origin and destination. This is hard to coordinate once there are multiple turns and timelines involved. _5D Diplomacy with Multiversal Time Travel_ thus introduces the concept of an _open convoy_, a nonspecific convoy order that can become part of a convoy later. An open convoy order does not require specifying the origin or destination of the convoyed unit; the unit is simply told to expect guests. Consequently, it is possible for a unit doing an open convoy to be used by a hostile power to convoy in the opposite direction.
> [!WARNING]
> Open convoys are a speculative feature and have not been implemented yet.
### Jump assist
Outside of convoys, a unit may only move one province at a time. Multiversal time travel also allows units to move back or forward by one turn and/or across by one timeline. Since time moves forward by one turn per turn, this makes it difficult to go further back into the past. The _jump assist_ order provides a way for units to intervene deeper into the past. A unit may be ordered to give a jump assist to another unit's move. For each successful jump assist given, a unit may move one more turn or timeline. Jump assists do not grant units the ability to move further geographically than they could otherwise.
> [!WARNING]
> Jump assists are a speculative feature and have not been implemented yet.
## Unit designations
In _Diplomacy_, orders refer to provinces, such as "A Mun-Tyr". In _5D Diplomacy with Multiversal Time Travel_, this is insufficient to unambiguously identify a province, since the province exists in multiple timelines across multiple turns. The convention for identifying a multiversal location is `timeline-province@turn`, where `timeline` is the timeline's identifier and `turn` is the turn's identifier, e.g. "b-Mun@3".
(Why this order? Short representations for timelines and turns can be confused for each other, especially for timelines designated with `f` or `s` that might be confused for fall or spring turns. _5D Diplomacy with Multiversal Time Travel_ is already complicated enough, so the timeline and turn are put on either side of the province and delimited with different symbols.)