renpy-graphviz

Draws a flowchart graph of any Visual Novel from Renpy .rpy files !

Observability

labels

graphviz

graph

renpy

Ren'Py graph visualizer - branches flowchart generator

This is a tool written in Go that allows you to visualize the routes of your Ren'Py story

Routes of the Question Extract Routes of the Question, the classic Ren'Py example

Ren'Py graph visualizer - branches flowchart generator

Examples

Doki Doki Litterature Club Extract Doki Doki Litterature Club will no longer have secrets for you!

Coalescence Extract An extract from my personal VN, Coalescence. You can't imagine handling a heavy VN like this one without graphic tools... The labels are blurred due to the preview image

🔎 HOW TO USE?

Online version - try online

You can test this tool in the browser. If you want to get .png files, please download the software version. Note that this website will not be maintained and it is not guaranteed to represent the library fully.

https://ewenquim.github.io/renpy-graphviz

Software version -install it on your computer

The command line version is more powerful as you can add flags and a path, see the documentation by typing renpy-graphviz -h.

Download the latest version
Move the program to your game folder
Run it from the command line ./renpy-graphviz or by clicking on the icon in your file manager
- You might need to provide permissions, this program is not a virus. On Unix, run chmod +x renpy-graphviz*.
renpy-graphviz.png should appear, enjoy!

Use the boolean flags only in -flag=value format, not in -flag value format, e.g. use ./renpy-graphviz -open=false.

Go library

go install pkg.amethysts.studio/renpy-graphviz@latest

If you are a Go user and want to integrate this in a Go lib/program, it is possible. The /parser module is very powerful.

🏷 Tags

Since Ren'Py scripting isn't strict, therefore the script can't know what is going on in the .rpy file in some cases. So, this program uses a tag system to enforce some behaviors. For example;

label chapter_1: #renpy-graphviz: TITLE

Before tags, you must write renpy-graphviz in a comment to ensure there are no collisions with existing words in your VN. Here are the tags available:

BEHAVIOUR TAGS
- BREAK breaks the current flow for linear labels, creating a new parallel
- IGNORE ignores the current label. Jumps to this label will be drawn
- SKIPLINK avoids long arrows by creating shortcuts marked with an asterisk. These shortcuts can't have child nodes
- FAKE_LABELS simulates labels and jumps, creating a new parallel
- INGAME_LABELS interacts with real labels and jumps, similar to fake labels
STYLE TAGS
- TITLE is a style for chapters
- GAMEOVER is a style for endings
- SHAPE sets a shape
- COLOR sets a color

BREAK

Cancels any "guessed link".

Expected with BREAK script.rpy

Expected	with BREAK	script.rpy
		`label one: "blah blah" label two: "bla bla" # renpy-graphviz: BREAK label three: "the end"`

Example image of Break, Before

label one:
  "blah blah"

label two:
"bla bla"

# renpy-graphviz: BREAK

label three:
"the end"

IGNORE

Ignores the current line. If this is a jump to a label that isn't ignored, the label will still appear on the graph but not the arrow that should go towards it. Similarly, if this is a jump from a label that isn't ignored but the jump destination is, the arrow will not appear on the graph.

Expected IGNORE script.rpy

Expected	IGNORE	script.rpy
		`label one: label two: # renpy-graphviz: IGNORE label three:`

Example image of Ignore, Before

label one:
label two: # renpy-graphviz: IGNORE
label three:

SKIPLINK

Avoids long arrows by creating another label with the same name. Beware, the label can't have any children and is marked by an asterisk to show it is a copy. Jumps will not be directed to this label if there is an original label displayed, if not, the jump is ignored.

Expected SKIPLINK script.rpy

Expected	SKIPLINK	script.rpy
		`label one: if condition: jump six # renpy-graphviz: SKIPLINK else: pass label two: label three: label four: label five: label six:`

Example image of Skiplink, Before

label one:
    if condition:
        jump six # renpy-graphviz: SKIPLINK
    else:
        pass

label two:
label three:
label four:
label five:
label six:

FAKE_LABEL(a) & FAKE_JUMP(a, b)

Creates a node or an arrow in the graph without having to create a label in your Ren'Py script. It is disconnected from the normal flow, label and jump in your script.

FAKES script.rpy

FAKES	script.rpy
	# You can mix different tags on the same line # renpy-graphviz: FAKE_LABEL(a) TITLE # If b/c does not exists, it creates it # renpy-graphviz: FAKE_JUMP(b, c) label real_1: # There will be no 'indirect link' from `real_1` to `d` # renpy-graphviz: FAKE_LABEL(d) # Implicit jump from `real_one` to `real_two` # (normal behaviour as `d` is ignored by the normal flow) label real_2: # No jump from `real_two` to `a` or `d` # renpy-graphviz: FAKE_JUMP(a, d)

Example image of Fakes

# You can mix different tags on the same line
# renpy-graphviz: FAKE_LABEL(a) TITLE
# If b/c does not exists, it creates it
# renpy-graphviz: FAKE_JUMP(b, c)

label real_1:
# There will be no 'indirect link' from `real_1` to `d`
# renpy-graphviz: FAKE_LABEL(d)

# Implicit jump from `real_one` to `real_two`
# (normal behaviour as `d` is ignored by the normal flow)
label real_2:

# No jump from `real_two` to `a` or `d`
# renpy-graphviz: FAKE_JUMP(a, d)

INGAME_LABEL(i, a) & INGAME_JUMP(i, b)

Same as above but interacts with label, call and jump in your normal flow in the Ren'Py script. You need to specify an indentation level.

# renpy-graphviz: INGAME_JUMP(8, destination)

is the equivalent of:

        jump destination

INGAMES script.rpy

INGAMES	script.rpy
	# renpy-graphviz: INGAME_LABEL(0, start) # renpy-graphviz: INGAME_JUMP(4, option_one) # Creates a link from `start` to `option_two` even # if there was a jump before -like normal jumps # renpy-graphviz: INGAME_JUMP(4, option_two) label option_one: "dialogue" # should follow the previous label (implicit jump) # renpy-graphviz: INGAME_LABEL(0, indirect_label) # jumps from `indirect_label` to `option_two` jump option_two

Example image of Label & Jump

# renpy-graphviz: INGAME_LABEL(0, start)
# renpy-graphviz: INGAME_JUMP(4, option_one)

# Creates a link from `start` to `option_two` even
# if there was a jump before -like normal jumps
# renpy-graphviz: INGAME_JUMP(4, option_two)

label option_one:
    "dialogue"

# should follow the previous label (implicit jump)
# renpy-graphviz: INGAME_LABEL(0, indirect_label)

# jumps from `indirect_label` to `option_two`
    jump option_two

TITLE & GAMEOVER

Sets styles.

TITLE / GAMEOVER script.rpy

TITLE / GAMEOVER	script.rpy
	`label routeone : # renpy-graphviz: TITlE d "Hello World!" if condition: jump bad_ending label routeAlternative: d "Normal bubble" jump good_ending label bad_ending: # renpy-graphviz: GAMEOVER d "Bad ending" return`

Example image of Title

label routeone :  # renpy-graphviz: TITlE
    d "Hello World!"
    if condition:
        jump bad_ending

label routeAlternative:
    d "Normal bubble"
    jump good_ending


label bad_ending: # renpy-graphviz: GAMEOVER
    d "Bad ending"
    return

SHAPE & COLOR

You can set yourself a custom color or shape for a label.

SHAPE and/or COLOR script.rpy

SHAPE and/or COLOR	script.rpy
	`label first: # renpy-graphviz: SHAPE(rect) COLOR(red) jump second # renpy-graphviz: SHAPE(septagon) COLOR(#ffdd67)`

Example image of Shape Color

label first: # renpy-graphviz: SHAPE(rect) COLOR(red)
    jump second # renpy-graphviz: SHAPE(septagon) COLOR(#ffdd67)

Some examples of shapes and colors can be found here.

Shapes	Colors
Rectangle	Red
Septagon	Blue
Egg	Purple
Diamond	White

graph.go file also supports line styling, font size and line thickness. Default values can also be changed inside the graph.go file.

Limitations

This requires your VN to be structured in a certain way, so this may not be perfect for you. Feel free to raise an issue here, or to change your VN structure, by adding tags manually.

Your contribution to the project is appreciated!

CONTRIBUTING

See the CONTRIBUTING.md file

LICENSE

This program is free and under the AGPLv3 license.

Beware, if you use this program, you must credit it somewhere on your game.

Used Renpy Graph Vizualiser from EwenQuim

Enjoy! ❤️