Back to page · View history on Codeberg

đź“„ posts/
#lang pollen

â—Š(define-meta title "RPG relationship mapping with Graphviz")
â—Š(define-meta published "2022-01-07")
â—Š(define-meta topics "RPGs,Burning Wheel, Burning Locusts, Hacks, Graphviz")

â—Šepigraph{Interrupting my train of thought

          Lines of longitude and latitude

          Define and refine my altitude

          Wire, Map Ref. 41°N 93°W}


I recently started running a Burning Wheelâ—Šsidenote{â—Šlink[""]{Burning Wheel HQ}} game after about two decades away from GMing role-playing games.
We are calling our game â—Šemph{Burning Locusts}.

The Situation revolves around a spooky mercenary company who returns
every 17 years to wreak havoc (there is a joke in there if you look
for it). It is set in a city called Scintallante that is modelled
after Italian city states during the Renaissance period. The city
resembles Milan geographically, with an ancient dwarven stronghold in
the center called Hartheld. In reality it is two cities: the dwarven
city of Hartheld and the human city of Scintallante.

There are three player characters in the game:

  â—Šitem{Ansidora: A dwarven runecaster}
  â—Šitem{Antonius di Mari: A human former mercenary captain turned thinker}
  â—Šitem{Frederico Pascolini: An ambitious human soldier, spy, thief}

For more background, one of the players has written excellent session
notes. They can be found hereâ—Šsidenote{â—Šlink[""]{Burning Locusts: Character Creation}}, hereâ—Šsidenote{â—Šlink[""]{Burning Locusts: Session 1}}, and hereâ—Šsidenote{â—Šlink[""]{Burning Locusts: Session 2}}.

As detailed in the â—Šemph{Character creation} post, the players created
characters with a number of interesting relationships and Beliefs
right off the bat. To make the most out of this, I wanted to find
some way to visualize the connections and observe how they change
over time.

â—Šsection{Mapping the relationships}

I am not a visual thinker so I find that I benefit from forcing
myself into that mindset. I also wanted to adopt better organizational
habits as a GM. My previous organizational habits from 20 years ago
involved writing things down on napkins, so there is certainly room
for improvement. So I created a relationship mapâ—Šsidenote{â—Šlink[""]{AFAIK, Sorcerer by Ron Edwards was the first game to introduce 
relationship maps as a tool for role-playing games in the â—Šemph{The Sorcerer's Soul}
supplement}} to better understand all of the interesting things
happening in our game.

To create the map, I evaluated a few options but I didn't want to use
a graphical or a web-based application to do it. I also wanted
something relatively easy to use. I settled on
Graphvizâ—Šsidenote{â—Šlink[""]{Graphviz, open-source
graph visualization software}}. Graphviz includes a programming
language called â—Šemph{DOT} that can be used to describe a graph
in plaintext using any text editor and turn it into an image.

â—Šsection{The graph}

â—Šfigure-popout["burning-locusts-1.svg" #:fullwidth #t]{}


A minimal amount of background knowledge is needed to start using the
basic features of Graphviz. The lines on the graph are called â—Šemph{edges}.
The lines connect â—Šemph{nodes} or â—Šemph{vertices}. That's all we need
to know to begin.

The Graphviz â—Šemph{DOT} language provides a simple shorthand for expressing

graph G {
    ansidora -- charles [label = "family"]

I have chosen to use an undirected graph for our relationship map
because it is easier, ie: the edges do not point in any direction, they
are just connections between nodes. In the code example above, this
choice is denoted by the keyword â—Šcode{graph}. A directed graph would
use the keyword â—Šcode{digraph} instead.

If this were directed graph, we would use â—Šcode{"->"} instead of
â—Šcode{"--"} to express these connections. The â—Šemph{label} tag should
be obvious but to further elaborate -- we are labelling this
connection as a â—Šemph{family} connection. â—Šemph{Family} is not a special
concept in Graphviz, it is just an arbitrary label for our
relationship map.

Please refer to the documentationâ—Šsidenote{â—Šlink[""]{DOT Language documentation}} for information on how to use the language.


When I made the graph, I decided to put each player character in a
subgraph to represented who is inside or outside of that character's
circle. This also had the benefit of showing that the marriage between
Lord Jade and Lady Jade crossed different character subgraphs via the
affair between Lady Jade and Frederico.


I wanted colors to represented the following:

  â—Šitem{Human player characters: â—Šbgcolor-rounded["#B2ABD2"]{color=8,#B2ABD2}}
  â—Šitem{Dwarven player characters: â—Šbgcolor-rounded["#8073AC"]{color=9, #8073AC}}
  â—Šitem{Human non-player characters: â—Šbgcolor-rounded["#FBD863"]{color=4, #FBD863}}
  â—Šitem{Dwarven non-player characters: â—Šbgcolor-rounded["#E08214"]{color=3, #E08214}}
  â—Šitem{Factions: â—Šbgcolor-rounded["#B35806"]{color=2, #B35806}}

I chose a set of Brewer colorsâ—Šsidenote{â—Šlink[""]{Graphviz Brewer colorschemes}} to have a range of colors that will stand
out from each other. The particular set I chose is â—Šemph{puor11}.

The following is a minimal example to demonstrate coloring and styling
nodes in a graph:

graph G {
   node [colorscheme=puor11 color=4 margin=0.2 fontsize=12 width=0.5 shape=box style=filled];
   lord_jade -- lady_jade [label = "married"]

There are the attributes from the code example:

  â—Šitem{colorscheme: A pre-determined set of colors}
  â—Šitem{color: A color from this set}
  â—Šitem{margin: The margin around the node name}
  â—Šitem{fontsize: The size of the node name}
  â—Šitem{width: The width of the node}
  â—Šitem{shape: The shape of the node (ex: box, circle, etc.)}
  â—Šitem{style: The style of the node (ex: filled, rounded, etc.)}
â—Šsection{Generating the graph}

Graphviz can be installed on Windows, Mac OS X, and Linux.
Instructions can be found on the website that is linked above.

Any text editor can be used to create a graph file in â—Šemph{DOT} and
some code editors provide extensions to automatically preview the
source code.

There are also a few online Graphviz editors such as this

This is the complete â—Šemph{dot} source code for the Burning Locusts
relationship map (â—Šcode{}):

graph G {
  size = 10.5;
  node [colorscheme=puor11 color=4 margin=0.2 fontsize=12 width=0.5 shape=box style=filled];

  subgraph cluster_1 {
    antonius [color=8]
    antonius -- maccio [label = "family"]
    antonius -- biagio [label = "friend"]
    antonius -- fiego [label = "teaching"]
    antonius -- hinterland_players [label = "member"]

  hinterland_players [color=2]
  biagio -- hinterland_players [label = "member"]
  lord_jade -- hinterland_players [label = "member"]
  lord_jade -- lady_jade [label = "married"]
  fiego [color=3]
  fiego -- lord_jade [label = "work"]
  thieves_guild [color=2]

  subgraph cluster_2 {
    frederico [color=8]
    frederico -- antonius [label = "teaching"]
    frederico -- lady_jade [label = "affair"]
    frederico -- thieves_guild [label = "member"]

  subgraph cluster_3 {
    ansidora [color=9]
    ansidora -- charles [label = "family"]
    ansidora -- tumoll [label = "family"]
    ansidora -- vadam [label = "divorced"]
    ansidora -- frederico [label = "work"]
    ansidora -- antonius [label = "work"]
    ansidora -- silas [label = "oath"]
    ansidora -- silas [label = "enmity"]

  vadam [color=3]
  silas [color=3]
  tumoll [color=3]
  charles [color=3]
  vadam -- tumoll [label = "family"]
  charles -- tumoll [label = "family"]
  tumoll -- ginna [label = "dating"]
  ginna -- silas [label = "ex"]

To generate the relationship map, run the following command:
â—Šcode{$ dot -Tsvg -o burning-locust-1.svg}

â—Šsection{Other work}

PlantUMLâ—Šsidenote{â—Šlink[""]{PlantUML}} can also
be used to the same effect. Jeremy at the Take on Rules blogâ—Šsidenote{â—Šlink[""]{Take on Rules blog}}
has an example for another Burning Wheel game that I am
playing in hereâ—Šsidenote{â—Šlink[""]{Using PlantUML to Model RPG Relationship Maps}}.