aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/README.md8
-rw-r--r--docs/general-program-architecture.md52
-rw-r--r--docs/simulation/goods.md48
-rw-r--r--docs/simulation/ideologies.md11
-rw-r--r--docs/simulation/provinces.md104
-rw-r--r--docs/simulation/sim-doc-format.md (renamed from docs/simulation/sim_doc_format.md)0
6 files changed, 193 insertions, 30 deletions
diff --git a/docs/README.md b/docs/README.md
index b6edf3a..5a4d160 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,5 +1,11 @@
# Documentation
- [Contribution Quickstart Guide](contribution-quickstart-guide.md)
+- [General Program Architecture](general-program-architecture.md)
- [Project File Structure](project-file-structure.md)
-- [C++ Style Guidlines](styleguide-cpp.md) \ No newline at end of file
+- [C++ Style Guidelines](styleguide-cpp.md)
+
+## Simulation
+- [Goods](simulation/goods.md)
+- [Ideologies](simulation/ideologies.md)
+- [Provinces](simulation/provinces.md)
diff --git a/docs/general-program-architecture.md b/docs/general-program-architecture.md
new file mode 100644
index 0000000..533a8fa
--- /dev/null
+++ b/docs/general-program-architecture.md
@@ -0,0 +1,52 @@
+# Player-Game Interaction
+```mermaid
+sequenceDiagram
+actor Player
+participant UI as Godot
+participant Bridge as Godot-CPP Bridge
+participant Simulation
+participant Dataloader
+autonumber
+
+Player ->> UI: Program starts
+UI ->> Bridge: Godot autoloaders fire
+Bridge ->> Dataloader: Signal to load Simulation
+Dataloader ->> Simulation: Read in data from file(s)
+Simulation ->> Bridge: Simulation finished loading data
+Bridge ->> UI: Autoloaders finish
+UI ->> Player: Display Main Menu
+Player ->> UI: Press "New Game" or<br>"Load Game" button
+UI ->> Bridge: Begin new Game Session
+Bridge ->> Simulation: Start new Game Session
+Simulation -->> Dataloader: Load previous savegame<br>(If necessary)
+Dataloader -->> Simulation:
+Simulation ->> Bridge: Provide information necessary<br>for UI and visual elements
+Bridge ->> UI: Signal that Game Session<br> is ready for interaction
+UI ->> Player: Present to Player
+
+loop Core Game Loop
+Player ->> UI: Interact with game controls
+UI ->> Bridge: Convey player intent<br>according to UI<br>handler functions
+Bridge ->> Simulation: Relay changes to entities<br>controlled by the Player
+Note over Simulation: When unpaused:
+Simulation ->> Simulation: Advance to next in-game day<br>according to game speed<br>and update Simulation state
+Simulation ->> Bridge: Inform of relevant<br>changes to game state
+Bridge ->> UI: Update UI and map
+UI ->> Player: Display new data
+end
+
+opt Save Game
+Player ->> UI: Press "Save Game" button<br>in the Game Session Menu
+UI ->> Bridge: Demand that the current<br>game state is saved
+Bridge ->> Simulation: Begin save routines
+Simulation ->> Dataloader: Write current state to disk
+Simulation ->> Bridge: Save routines completed
+Bridge ->> UI: Trigger "successful save"<br>message
+UI ->> Player: Give visual confirmation<br>of successful save
+end
+
+Player ->> UI: Press "Exit Game" button
+UI ->> Player: Give a "Confirm quit (Y/N)"<br>dialog window
+Player ->> UI: Confirm intent to quit program
+UI ->> Player: Program closes
+``` \ No newline at end of file
diff --git a/docs/simulation/goods.md b/docs/simulation/goods.md
index 241362b..15b4864 100644
--- a/docs/simulation/goods.md
+++ b/docs/simulation/goods.md
@@ -52,18 +52,18 @@ classDiagram
|timber|Raw|0.90|146 72 17|True|True|False|False|
|tropical_wood|Raw|5.40|213 177 118|True|True|False|False|
|wool|Raw|0.70|234 195 158|True|True|False|False|
-|steel|Industry|4.70|95 128 147|False|True|False|False|
-|cement|Industry|16.00|185 187 164|True|True|False|False|
-|machine_parts|Industry|36.50|177 198 196|False|True|False|False|
-|glass|Industry|2.90|201 200 199|True|True|False|False|
-|fuel|Industry|25.00|145 110 89|False|True|False|False|
-|fertilizer|Industry|10.00|133 101 35|True|True|False|False|
-|explosives|Industry|20.00|192 68 20|False|True|False|False|
-|clipper_convoy|Industry|42.00|21 65 30|False|True|False|True|
-|steamer_convoy|Industry|65.00|76 18 0|False|True|False|True|
-|electric_gear|Industry|16.00|255 255 0|False|True|False|False|
-|fabric|Industry|1.80|186 50 40|True|True|False|False|
-|lumber|Industry|1.00|180 94 26|True|True|False|False|
+|steel|Industrial|4.70|95 128 147|False|True|False|False|
+|cement|Industrial|16.00|185 187 164|True|True|False|False|
+|machine_parts|Industrial|36.50|177 198 196|False|True|False|False|
+|glass|Industrial|2.90|201 200 199|True|True|False|False|
+|fuel|Industrial|25.00|145 110 89|False|True|False|False|
+|fertilizer|Industrial|10.00|133 101 35|True|True|False|False|
+|explosives|Industrial|20.00|192 68 20|False|True|False|False|
+|clipper_convoy|Industrial|42.00|21 65 30|False|True|False|True|
+|steamer_convoy|Industrial|65.00|76 18 0|False|True|False|True|
+|electric_gear|Industrial|16.00|255 255 0|False|True|False|False|
+|fabric|Industrial|1.80|186 50 40|True|True|False|False|
+|lumber|Industrial|1.00|180 94 26|True|True|False|False|
|paper|Consumer|3.40|216 185 77|True|True|False|False|
|cattle|Consumer|2.00|84 227 40|True|True|False|False|
|fish|Consumer|1.50|128 98 73|True|True|False|False|
@@ -106,18 +106,18 @@ classDiagram
|timber|Raw|0.90|146 72 17|True|True|False|False|
|tropical_wood|Raw|5.40|213 177 118|True|True|False|False|
|wool|Raw|0.70|234 195 158|True|True|False|False|
-|steel|Industry|4.70|95 128 147|False|True|False|False|
-|cement|Industry|16.00|185 187 164|True|True|False|False|
-|machine_parts|Industry|36.50|177 198 196|False|True|False|False|
-|glass|Industry|2.90|201 200 199|True|True|False|False|
-|fuel|Industry|25.00|145 110 89|False|True|False|False|
-|fertilizer|Industry|10.00|133 101 35|True|True|False|False|
-|explosives|Industry|20.00|192 68 20|False|True|False|False|
-|clipper_convoy|Industry|42.00|21 65 30|False|True|False|True|
-|steamer_convoy|Industry|65.00|76 18 0|False|True|False|True|
-|electric_gear|Industry|16.00|255 255 0|False|True|False|False|
-|fabric|Industry|1.80|186 50 40|True|True|False|False|
-|lumber|Industry|1.00|180 94 26|True|True|False|False|
+|steel|Industrial|4.70|95 128 147|False|True|False|False|
+|cement|Industrial|16.00|185 187 164|True|True|False|False|
+|machine_parts|Industrial|36.50|177 198 196|False|True|False|False|
+|glass|Industrial|2.90|201 200 199|True|True|False|False|
+|fuel|Industrial|25.00|145 110 89|False|True|False|False|
+|fertilizer|Industrial|10.00|133 101 35|True|True|False|False|
+|explosives|Industrial|20.00|192 68 20|False|True|False|False|
+|clipper_convoy|Industrial|42.00|21 65 30|False|True|False|True|
+|steamer_convoy|Industrial|65.00|76 18 0|False|True|False|True|
+|electric_gear|Industrial|16.00|255 255 0|False|True|False|False|
+|fabric|Industrial|1.80|186 50 40|True|True|False|False|
+|lumber|Industrial|1.00|180 94 26|True|True|False|False|
|paper|Consumer|3.40|216 185 77|True|True|False|False|
|cattle|Consumer|2.00|84 227 40|True|True|False|False|
|fish|Consumer|1.50|128 98 73|True|True|False|False|
diff --git a/docs/simulation/ideologies.md b/docs/simulation/ideologies.md
index 4d91056..f56cda7 100644
--- a/docs/simulation/ideologies.md
+++ b/docs/simulation/ideologies.md
@@ -9,16 +9,17 @@ classDiagram
class IdeologicalGroup {
<<enumeration>>
- Facist
+ Fascist
Conservative
Socialist
Liberal
}
class Ideology {
+ + String id
+ IdeologicalGroup group
- + Date earliest_date
- + boolean uncivilized_nations
+ + Date earliestDate
+ + boolean uncivilizedNations
+ Colour colour
}
@@ -38,7 +39,7 @@ classDiagram
|anarcho_liberal|liberal|1845/01/01|True|#96960A|
|socialist|socialist|1860/01/01|False|#FF0000|
|communist|socialist|1865/01/01|False|#960A0A|
-|facist|facist|1905/01/01|False|#3C3C3C|
+|fascist|fascist|1905/01/01|False|#3C3C3C|
### John Cena
@@ -50,7 +51,7 @@ classDiagram
|anarcho_liberal|liberal|1845/01/01|True|#96960A|
|socialist|socialist|1860/01/01|False|#FF0000|
|communist|socialist|1865/01/01|False|#960A0A|
-|facist|facist|1905/01/01|False|#3C3C3C|
+|fascist|fascist|1905/01/01|False|#3C3C3C|
## References
diff --git a/docs/simulation/provinces.md b/docs/simulation/provinces.md
new file mode 100644
index 0000000..88eea50
--- /dev/null
+++ b/docs/simulation/provinces.md
@@ -0,0 +1,104 @@
+# OpenVic2 Provinces
+
+## OpenVic2 Structure
+
+```mermaid
+classDiagram
+ class Province {
+ Int64 id
+ string provinceName
+ string tradeGood
+ Int64 lifeRating
+ bool hasLegalSlavery
+
+ Int64 fortLevel
+ Int64 navalBaseLevel
+ Int64 railroadLevel
+
+ string regionId
+ string continentId
+ }
+```
+<!-- The following attributes will need to be added when Nations are added
+ NationId owningNation
+ NationId controllingNation
+ NationId[] coreNations
+-->
+
+# Dataloading
+To populate the Province structures, the following data files will be loaded in the following order:
+1. `provinces.json`
+2. `regions.json`
+3. `continents.json`
+
+## 1. Provinces.json
+The `provinces.json` file shall look like:
+```json
+{
+ "provinces": [
+ {"id": 123, "provinceName": "abc", ...},
+ ...
+ ]
+}
+```
+Where the `"provinces"` array contains valid province JSON objects which conform to the following key-value pairs:
+| Key | type | Required? | Default Value |
+|--|--|--|--|
+| id | int | required | N/A |
+| provinceName | string | required | N/A |
+| tradeGood | string | optional | "no_good" |
+| lifeRating | int | optional | 0 |
+| hasLegalSlavery | bool | optional | false |
+| fortLevel | int | optional | 0 |
+| navalBaseLevel | int | optional | 0 |
+| railroadLevel | int | optional | 0 |
+### Notes on values:
+- The values of `fortLevel`, `navalBaseLevel`, and `railroadLevel` may not be negative
+- The value of `tradeGood` may only be a Good Identifier string as defined in [goods.md](goods.md) or `"no_good"`
+
+
+## 2. Regions.json
+The `regions.json` file shall look like:
+```json
+{
+ "regions": [
+ {"id": "abc", "provinceIds": [123, 456, ...]},
+ ...
+ ]
+}
+```
+Where the `"regions"` array contains valid region JSON objects which conform to the following key-value pairs:
+| Key | type | Required? | Default Value |
+|--|--|--|--|
+| id | string | required | N/A |
+| provinceIds | Array[int] | required | N/A |
+### Notes on values:
+- The value of `id` may not be an empty string
+- The value of `id` must be unique among all continents
+- `provinceIds` may be an empty array; an empty array should be logged as a warning
+- The content of `provinceIds` may only be Province Identifier integers as defined above
+- A province may only belong to a single region, any attempts to re-assign a province's region during dataloading should be ignored and logged as an error
+
+
+
+## 3. Continents.json
+The `continents.json` file shall look like:
+```json
+{
+ "continents": [
+ {"id": "abc", "provinceIds": [123, 456, ...]},
+ ...
+ ]
+}
+```
+Where the `"continents"` array contains valid continent JSON objects which conform to the following key-value pairs:
+| Key | type | Required? | Default Value |
+|--|--|--|--|
+| id | string | required | N/A |
+| provinceIds | Array[int] | required | N/A |
+### Notes on values:
+- The value of `id` may not be an empty string
+- The value of `id` must be unique among all continents
+- `provinceIds` may be an empty array; an empty array should be logged as a warning
+- The content of `provinceIds` may only be Province Identifier integers as defined in [provinces.md](provinces.md)
+- A province may only belong to a single continent, any attempts to re-assign a province's continent during dataloading should be ignored and logged as an error
diff --git a/docs/simulation/sim_doc_format.md b/docs/simulation/sim-doc-format.md
index 68bd905..68bd905 100644
--- a/docs/simulation/sim_doc_format.md
+++ b/docs/simulation/sim-doc-format.md