I've been focused a lot on performance at work recently, and have been toying around with different tools to quickly put together diagrams where we show a timeline of events.
One tool that intrigues me and I hope to use regularly is PlantUML.
Getting Started
To use, simply download the JAR file, and then you can use the command line to either produce diagrams from text descriptions, or bring up a GUI that will let you quickly iterate on that.
To generate diagrams as PNG files, run it as java -jar plantuml.jar file1 file2 file3
To bring up the GUI and select a directory to monitor for changes to render, run java -jar plantuml.jar -gui
Timing Diagrams
There are a lot of diagram types you can use with PlantUML, but the one that we'll use is timing diagrams.
Here is a simple diagram that has a simplified model of the Unity loop.
@startuml
concise "Simplified Unity Loop" as SUL
@0
SUL is Physics
@4
SUL is "Input Events"
@5
SUL is "Game Logic"
@7
SUL is "Scene Render"
@12
SUL is End
@13
SUL is "Frame+1"
@enduml
Let's look at how to address some common scenarios.
How do I model interactions?
To show how two processes interact on the timeline, use an arrow syntax as in this example.
@startuml
robust "Web Browser" as WB
concise "Web User" as WU
@0
WU is Idle
WB is Idle
@100
WU -> WB : URL
WU is Waiting
WB is Processing
@300
WB is Waiting
@enduml
What if I don't know the specific timings?
You can hide the time axis and then just adjust to give some sense of proportion.
@startuml
hide time-axis
concise "Web User" as WU
WU is Absent
@WU
0 is Waiting
+500 is ok
@enduml
How do I adjust text to fit?
You can change the scale to give yourself more room.
@startuml
concise "Simplified Unity Loop" as SUL
scale 1 as 100 pixels
@0
SUL is Physics
@4
SUL is "Input Events"
@5
SUL is "Game Logic"
@7
SUL is "Scene Render"
@12
SUL is End
@13
SUL is "Frame+1"
@enduml
Alternatively, you can shorten the text and then add a small note above.
@startuml
concise "Simplified Unity Loop" as SUL
@0
SUL is Physics
@4
SUL is "input": input events
@5
SUL is "Game Logic"
@7
SUL is "Scene Render"
@12
SUL is End
@13
SUL is "Frame+1"
@enduml
You can add a UML note style and declare to be on top or bottom as well.
@startuml
concise "Simplified Unity Loop" as SUL
@0
SUL is Physics
@4
SUL is "input"
note top of SUL: input events
note bottom of SUL: handle with care
@5
SUL is "Game Logic"
@7
SUL is "Scene Render"
@12
SUL is End
@13
SUL is "Frame+1"
@enduml
If you're going to use lots of abbreviations, a legend is handy. You can also have titles, and footers for more context.
@startuml
concise "Simplified Unity Loop" as SUL
legend
P: physics
I: input
GL: game logic
SR: scene render
end legend
@0
SUL is P
@4
SUL is I
@5
SUL is GL
@7
SUL is SR
@12
SUL is End
@13
SUL is "Frame+1"
@enduml
How do I zoom into something?
Everyone shares a timeline, so if you really want to zoom into some specific slice, you're better off with a second timeline diagram.
How do I call out specific points?
Using notes is one of the better ways of doing it, which you can place at the transition points.
How do I call out specific ranges?
Use an arrow with two ends syntax as in this example.
@startuml
robust "Web Browser" as WB
concise "Web User" as WU
WB is Initializing
WU is Absent
@WB
0 is idle
+200 is Processing
+100 is Waiting
WB@0 <-> @50 : {50 ms lag}
@WU
0 is Waiting
+500 is ok
@200 <-> @+150 : {150 ms}
@enduml
Alternatively, use a highlight.
@startuml
concise "Simplified Unity Loop" as SUL
@0
SUL is Physics
@4
SUL is "Input Events"
@5
SUL is "Game Logic"
@7
SUL is "Scene Render"
@12
SUL is End
@13
SUL is "Frame+1"
highlight 4 to 7 #LightGreen: C# code
@enduml
Happy diagramming!