From ac89d0b6f01f5a168fd9911b6280eec12b3888fc Mon Sep 17 00:00:00 2001 From: heinezen Date: Sat, 5 Aug 2023 17:24:25 +0200 Subject: [PATCH] doc: Engine architecture rewrite. --- doc/code/architecture.md | 59 +- doc/code/images/engine_architecture.svg | 269 ++++ doc/code/images/engine_architecture.uxf | 1092 +++++++++++++++++ .../images/engine_target_architecture.svg | 344 ++++++ 4 files changed, 1745 insertions(+), 19 deletions(-) create mode 100644 doc/code/images/engine_architecture.svg create mode 100644 doc/code/images/engine_architecture.uxf create mode 100644 doc/code/images/engine_target_architecture.svg diff --git a/doc/code/architecture.md b/doc/code/architecture.md index 4e7bbec9d1..e0eda0701d 100644 --- a/doc/code/architecture.md +++ b/doc/code/architecture.md @@ -51,32 +51,53 @@ All of them need to be revisited to implement the goal architecture. The current data flow of openage is just to display the raw simulation data. +![Engine architecture workflow](images/engine_architecture.svg) + +The presenter, simulation, and time subsystems each run in a loop in their own threads. +They are largely decoupled from each other and only communicate via defined interfaces. + +Communication between all subsystems forms a larger *main* loop that encompasses everything +happening in an engine run. It's workflow is roughly like this: + ``` -input -> simulation -> renderer -> output +renderer (window system) -> input -> event system -> simulation -> renderer -> output ``` +openage does not have simulation steps or *ticks* since everything in the simulation is +event-based and scheduled by time. Therefore, updates between threads should work +asynchronously in general. + +Decoupling allows us to treat some subsystems as optional such as the renderer and input +system (basically everything from the presenter). + ### Goal architecture -``` -0 input -> -1 network -> -2 simulation -> -3 network -> -4 prediction/interpolation -> -5 renderer -> -6 output -``` +The goal architecture extends the current workflow by subsystems for networking and +scripting: + +![Goal architecture workflow](images/engine_target_architecture.svg) + +Both of these are supposed to be decoupled and optional. The current architecture can be extended +by adding the missing components in between. -For *singleplayer* we could bypass `1 network` and `3 network` by using direct function calls or talk to a local socket. -For *multiplayer* this means that we will have a single authoritative server that is just running -the simulation. Each client then receives the data visible for it. +Networking forwards the relevant events and simulation parameters during multiplayer. +We will have a single authoritative server that is also running the simulation asynchronously. +Each client then receives the data visible for it. -The current architecture can be extended by adding the missing components in -between. +Scripting extends the event system with external sources targets for events. Most +scripting should be integrated using event logic. -The `prediction/interpolation` reuses the `simulation` code, but is -non-authoritative: The data provided from `2` has higher priority. +The new workflow would then look something like this: -There exists a link of `0 input -> 4 prediction` so that input -is immediately accounted in the prediction, thus displayed. +``` + ---------> scripting + | ^ + | | + v v +renderer (window system) -> input -> event system -> simulation -> renderer -> output + ^ ^ + | | + | v + ---------> network +``` diff --git a/doc/code/images/engine_architecture.svg b/doc/code/images/engine_architecture.svg new file mode 100644 index 0000000000..c24199612c --- /dev/null +++ b/doc/code/images/engine_architecture.svg @@ -0,0 +1,269 @@ + + +Current timeAnimation requestsCurrent timeScheduled eventsCurrent timeEntity updatesInput eventsMouse eventsKey/Mouse eventsClockTimePresenterSimulationEventLoopGUIRendererInput diff --git a/doc/code/images/engine_architecture.uxf b/doc/code/images/engine_architecture.uxf new file mode 100644 index 0000000000..35b2297706 --- /dev/null +++ b/doc/code/images/engine_architecture.uxf @@ -0,0 +1,1092 @@ + + + // Uncomment the following line to change the fontsize and font: +fontsize=14 +// fontfamily=SansSerif //possible: SansSerif,Serif,Monospaced + + +////////////////////////////////////////////////////////////////////////////////////////////// +// Welcome to UMLet! +// +// Double-click on elements to add them to the diagram, or to copy them +// Edit elements by modifying the text in this panel +// Hold Ctrl to select multiple elements +// Use Ctrl+mouse to select via lasso +// +// Use +/- or Ctrl+mouse wheel to zoom +// Drag a whole relation at its central square icon +// +// Press Ctrl+C to copy the whole diagram to the system clipboard (then just paste it to, eg, Word) +// Edit the files in the "palettes" directory to create your own element palettes +// +// Select "Custom Elements > New..." to create new element types +////////////////////////////////////////////////////////////////////////////////////////////// + + +// This text will be stored with each diagram; use it for notes. + 15 + + UMLClass + + 690 + 345 + 195 + 90 + + +**Input** + + + + UMLClass + + 1020 + 180 + 195 + 90 + + +**Renderer** + + + + UMLClass + + 690 + 90 + 195 + 90 + + +**GUI** + + + + UMLClass + + 1035 + 600 + 195 + 90 + + +**EventLoop** + + + + UMLClass + + 1275 + 405 + 195 + 90 + + +**Simulation** + + + + Text + + 525 + 15 + 195 + 60 + + **Presenter** +fontsize=20 + +style=wordwrap + + + + Relation + + 510 + 0 + 780 + 45 + + lt=. + 10.0;10.0;500.0;10.0 + + + Relation + + 510 + 0 + 45 + 600 + + lt=. + 10.0;380.0;10.0;10.0 + + + Relation + + 510 + 555 + 450 + 45 + + lt=. + 280.0;10.0;10.0;10.0 + + + Relation + + 1245 + 0 + 45 + 360 + + lt=. + 10.0;220.0;10.0;10.0 + + + Relation + + 915 + 315 + 375 + 285 + + lt=. + 10.0;170.0;230.0;10.0 + + + Text + + 1620 + 90 + 105 + 60 + + **Time** +fontsize=20 + +style=wordwrap + + + + UMLClass + + 1500 + 180 + 135 + 90 + + +**Clock** + + + + Relation + + 1245 + 75 + 495 + 45 + + lt=. + 10.0;10.0;310.0;10.0 + + + Relation + + 1695 + 75 + 45 + 285 + + lt=. + 10.0;170.0;10.0;10.0 + + + Relation + + 1440 + 315 + 300 + 45 + + lt=. + 180.0;10.0;10.0;10.0 + + + Relation + + 1695 + 315 + 45 + 510 + + lt=. + 10.0;320.0;10.0;10.0 + + + Relation + + 1245 + 315 + 495 + 45 + + lt=. + 10.0;10.0;310.0;10.0 + + + Relation + + 915 + 780 + 825 + 45 + + lt=. + 530.0;10.0;10.0;10.0 + + + Relation + + 915 + 555 + 45 + 270 + + lt=. + 10.0;10.0;10.0;160.0 + + + Relation + + 840 + 225 + 210 + 150 + + lt=<- + 10.0;80.0;10.0;10.0;120.0;10.0 + + + Relation + + 765 + 165 + 45 + 210 + + lt=<- + 10.0;10.0;10.0;120.0 + + + Relation + + 870 + 375 + 255 + 255 + + lt=<- + 150.0;150.0;150.0;10.0;10.0;10.0 + + + Relation + + 1185 + 465 + 120 + 165 + + lt=<- + 60.0;10.0;10.0;10.0;10.0;90.0 + + + Relation + + 1155 + 255 + 150 + 195 + + lt=<- + 10.0;10.0;10.0;110.0;80.0;110.0 + + + Relation + + 1455 + 255 + 150 + 225 + + lt=<- + 10.0;130.0;80.0;130.0;80.0;10.0 + + + Relation + + 1200 + 210 + 330 + 45 + + lt=<- + 10.0;10.0;200.0;10.0 + + + Text + + 840 + 210 + 225 + 45 + + Key/Mouse events +fontsize=12 +style=wordwrap + + + + Text + + 630 + 225 + 150 + 45 + + Mouse events +fontsize=12 +style=wordwrap + + + + Text + + 915 + 390 + 150 + 45 + + Input events +fontsize=12 +style=wordwrap + + + + Text + + 1200 + 510 + 180 + 45 + + Entity updates +fontsize=12 +style=wordwrap + + + + Relation + + 1155 + 450 + 150 + 180 + + lt=<- + 10.0;100.0;10.0;10.0;80.0;10.0 + + + Text + + 1500 + 450 + 180 + 45 + + Current time +fontsize=12 +style=wordwrap + + + + Text + + 1110 + 435 + 180 + 45 + + Scheduled events +fontsize=12 +style=wordwrap + + + + Relation + + 1215 + 435 + 390 + 240 + + lt=<- + 10.0;140.0;240.0;140.0;240.0;10.0 + + + Text + + 1440 + 645 + 180 + 45 + + Current time +fontsize=12 +style=wordwrap + + + + Text + + 990 + 285 + 195 + 45 + + Animation requests +fontsize=12 +style=wordwrap + + + + Text + + 1380 + 195 + 180 + 45 + + Current time +fontsize=12 +style=wordwrap + + + + UMLClass + + 690 + 1215 + 195 + 90 + + +**Input** + + + + UMLClass + + 1020 + 1050 + 195 + 90 + + +**Renderer** + + + + UMLClass + + 690 + 960 + 195 + 90 + + +**GUI** + + + + UMLClass + + 1035 + 1470 + 195 + 90 + + +**EventLoop** + + + + UMLClass + + 1275 + 1275 + 195 + 90 + + +**Simulation** + + + + Text + + 525 + 885 + 195 + 60 + + **Presenter** +fontsize=20 + +style=wordwrap + + + + Relation + + 510 + 870 + 780 + 45 + + lt=. + 10.0;10.0;500.0;10.0 + + + Relation + + 510 + 870 + 45 + 600 + + lt=. + 10.0;380.0;10.0;10.0 + + + Relation + + 510 + 1425 + 450 + 45 + + lt=. + 280.0;10.0;10.0;10.0 + + + Relation + + 1245 + 870 + 45 + 360 + + lt=. + 10.0;220.0;10.0;10.0 + + + Relation + + 915 + 1185 + 375 + 285 + + lt=. + 10.0;170.0;230.0;10.0 + + + Text + + 1620 + 960 + 105 + 60 + + **Time** +fontsize=20 + +style=wordwrap + + + + UMLClass + + 1500 + 1050 + 135 + 90 + + +**Clock** + + + + Relation + + 1245 + 945 + 495 + 45 + + lt=. + 10.0;10.0;310.0;10.0 + + + Relation + + 1695 + 945 + 45 + 285 + + lt=. + 10.0;170.0;10.0;10.0 + + + Relation + + 1440 + 1185 + 300 + 45 + + lt=. + 180.0;10.0;10.0;10.0 + + + Relation + + 1695 + 1185 + 45 + 510 + + lt=. + 10.0;320.0;10.0;10.0 + + + Relation + + 1245 + 1185 + 495 + 45 + + lt=. + 10.0;10.0;310.0;10.0 + + + Relation + + 915 + 1650 + 825 + 45 + + lt=. + 530.0;10.0;10.0;10.0 + + + Relation + + 915 + 1425 + 45 + 270 + + lt=. + 10.0;10.0;10.0;160.0 + + + Relation + + 840 + 1095 + 210 + 150 + + lt=<- + 10.0;80.0;10.0;10.0;120.0;10.0 + + + Relation + + 765 + 1035 + 45 + 210 + + lt=<- + 10.0;10.0;10.0;120.0 + + + Relation + + 870 + 1245 + 255 + 255 + + lt=<- + 150.0;150.0;150.0;10.0;10.0;10.0 + + + Relation + + 1185 + 1335 + 120 + 165 + + lt=<- + 60.0;10.0;10.0;10.0;10.0;90.0 + + + Relation + + 1155 + 1125 + 150 + 195 + + lt=<- + 10.0;10.0;10.0;110.0;80.0;110.0 + + + Relation + + 1455 + 1125 + 150 + 225 + + lt=<- + 10.0;130.0;80.0;130.0;80.0;10.0 + + + Relation + + 1200 + 1080 + 330 + 45 + + lt=<- + 10.0;10.0;200.0;10.0 + + + Text + + 840 + 1080 + 225 + 45 + + Key/Mouse events +fontsize=12 +style=wordwrap + + + + Text + + 630 + 1095 + 150 + 45 + + Mouse events +fontsize=12 +style=wordwrap + + + + Text + + 915 + 1260 + 150 + 45 + + Input events +fontsize=12 +style=wordwrap + + + + Text + + 1200 + 1380 + 180 + 45 + + Entity updates +fontsize=12 +style=wordwrap + + + + Relation + + 1155 + 1320 + 150 + 180 + + lt=<- + 10.0;100.0;10.0;10.0;80.0;10.0 + + + Text + + 1500 + 1320 + 180 + 45 + + Current time +fontsize=12 +style=wordwrap + + + + Text + + 1110 + 1305 + 180 + 45 + + Scheduled events +fontsize=12 +style=wordwrap + + + + Relation + + 1215 + 1305 + 390 + 240 + + lt=<- + 10.0;140.0;240.0;140.0;240.0;10.0 + + + Text + + 1440 + 1515 + 180 + 45 + + Current time +fontsize=12 +style=wordwrap + + + + Text + + 990 + 1155 + 195 + 45 + + Animation requests +fontsize=12 +style=wordwrap + + + + Text + + 1380 + 1065 + 180 + 45 + + Current time +fontsize=12 +style=wordwrap + + + + UMLClass + + 1035 + 1770 + 195 + 90 + + +**Networking** + + + + UMLClass + + 660 + 1470 + 195 + 90 + + +**Scripting** + + + + Relation + + 840 + 1485 + 225 + 45 + + lt=<- + 130.0;10.0;10.0;10.0 + + + Relation + + 840 + 1515 + 225 + 45 + + lt=<- + 10.0;10.0;130.0;10.0 + + + Relation + + 1065 + 1545 + 45 + 255 + + lt=<- + 10.0;150.0;10.0;10.0 + + + Relation + + 1110 + 1545 + 45 + 255 + + lt=<- + 10.0;10.0;10.0;150.0 + + + Relation + + 1215 + 1350 + 225 + 510 + + lt=<- + 130.0;10.0;130.0;320.0;10.0;320.0 + + + Relation + + 1215 + 1350 + 195 + 480 + + lt=<- + 10.0;300.0;110.0;300.0;110.0;10.0 + + + Text + + 1335 + 1830 + 180 + 45 + + Server updates +fontsize=12 +style=wordwrap + + + + Text + + 1275 + 1755 + 180 + 45 + + Client data +fontsize=12 +style=wordwrap + + + + Text + + 1125 + 1665 + 180 + 45 + + Server events +fontsize=12 +style=wordwrap + + + + Text + + 960 + 1665 + 180 + 45 + + Client events +fontsize=12 +style=wordwrap + + + + Text + + 870 + 1530 + 180 + 45 + + Event notifiers +fontsize=12 +style=wordwrap + + + + Text + + 870 + 1470 + 180 + 45 + + Script events +fontsize=12 +style=wordwrap + + + diff --git a/doc/code/images/engine_target_architecture.svg b/doc/code/images/engine_target_architecture.svg new file mode 100644 index 0000000000..fbc026c06a --- /dev/null +++ b/doc/code/images/engine_target_architecture.svg @@ -0,0 +1,344 @@ + + +Script eventsEvent notifiersClient eventsServer eventsClient dataServer updatesScriptingNetworkingCurrent timeAnimation requestsCurrent timeScheduled eventsCurrent timeEntity updatesInput eventsMouse eventsKey/Mouse eventsClockTimePresenterSimulationEventLoopGUIRendererInput