Designing Map Sub-Projects

[DanVanAtta]

I'm planning to start carving off maps related sub-projects. In terms of important sub-projects, this is a pretty big one. Remaining on the radar is AI, but we'll leave it for another day. I'm opening this issue to communicate these plans, answer any questions and to gather any feedback and thoughts that people might have.

For a project dependency graph, we'd have something that looks about like this:

Sub-project interactions, create a clean data interface between sub-projects

In short, the interaction between sub-projects will largely be based on map-data domain objects. The idea is largely to create domain objects that will represent an interface between map-reader and map-writer and game-core. In other words, the map reader can create a map data object that consists of a composition of domain objects that game-core can then use. On the other direction, the map writer could convert those objects back to a persistence format (XML and property files).

To give more detail, a map reader would read the XML DOM and convert what it reads into a java representation of those elements. The "DOM model objects" would then be converted to map domain objects that would be the familiar 'attachment' and 'unit' objects we see in 'game-core' today.

To illustrate the data transformation, it'd look something like this:

Immutable map data and future potential relation to save-games

This is in part building to a place where we'd have an immutable core of map state objects that are derived from a map and we'd remove those objects from the GameData. Perhaps going forward we can then create a relationship where the map data represents an initial game data state which can then save a series of game data change objects whereby if you "replay" all of the changes then you get to the latest game data state. In this way if we have save games be nothing other than a record of which map created the initial state and a series of persisted change objects, we'll potentially solve the save game compatibility problem.

Flexibility for different XML specs & testing

Another benefit to this structure is we gain more flexibility in how we read maps, so long as the same object model can be created the details of the exact XML (or even YAML) are abstracted away. This can in turn also help the integration testing problem we have where we require many full-blown XMLs to test. Instead the test responsibility can be broken up such that we can verify a given XML creates the right "DOM Model objects", next that "DOM model objects" can be translated to "map data domain objects". Last in this test configuration we can create the model objects in test and then verify that game data does the right thing with them.

[DanVanAtta]

Moved to this documentation: #7633

Going forward we probably should do PRs into the 'design' folder of documentation so that these documents can be longer lived.