ink2nom — A CLI tool to visualize your Ink stories as flow diagrams

[kilken (Martin)]

Hi everyone,

I built a small command-line tool that converts compiled Ink story JSON into flow diagrams. It uses the nomnoml renderer to generate SVG, PNG, or .noml files right from your terminal. I created this to help visualizing my project and I thought I would make it open source and I didn’t really research much on the topic, so maybe there are better tools out there.

It supports both named-knot and pure-weave structures while allowing for automatic node styling based on naming patterns, such as rendering hubs as rounded boxes or choices as diamonds. While the tool functions well within these boundaries, the layout engine may struggle with dense diagrams, occasionally causing connection lines to route out of bounds, and it currently collapses stitches into parent knots while displaying all possible paths for conditional choices.

Repo here

I would love to hear if this helps anyone’s workflow or if the current limitations are dealbreakers for your setup. It is MIT licensed.

M

[Draconis (Daniel Stelzer)]

Welcome to the site! How large of projects does this support?

[kilken (Martin)]

Thank you!
No idea, my story is 67 nodes and has 138 edges (connections). It would be great to be able to test on a large story. Is there any way to access an “open source” game made with ink?
M

[Draconis (Daniel Stelzer)]

There are definitely some out there! I need to check if we ever released the source for Loose Ends; that one I suspect is big enough to end up an unmanageable tangle.

[averyhiebert]

I assume you’ve tried it on The Intercept?

[kilken (Martin)]

Yes, these are the generated images:

1- Only knots

2- Knots + stitches as frames

3- All knots including utility/function knots

[averyhiebert]

Tried it for a couple of my more random-event-driven games, which I guess is not really the intended use case but might be interesting to observe:

My point & click game, on the other hand, is probably much closer to the intended use case but does get a bit unwieldy:

EDIT: Trying to make an actually “nice” diagram for the point & click game, my main thought is that the styling & utility filtering would be more usable if they checked for knot-level tags like #HUB or #UTIL, rather than relying on naming conventions.

For this particular game, all of my “hub” nodes were already indicated with a tag #WORLD for engine reasons, and the main utility functions that I need to filter out are named “back_button”, “menu”, and “use_item,” none of which match the existing UTIL_PATTERNS. I think conveying this sort of metadata is basically an intended use for knot-level tags in Ink.

[n-n]

Tried it on my Ink game and the output is very nice, thanks!

Market Day diagram

[kilken (Martin)]

Thanks for the feedback. These are all valid points. I will be creating a branch soon(ish) to use a (configurable) tag-based classification.

[kilken (Martin)]

I just pushed an update : “Knots and stitches are automatically styled using explicit inline Ink tags or fallback name patterns. Tags take absolute precedence over naming conventions, allowing you to flag nodes for game engine reasons (like #WORLD or #UTIL) and have them accurately visualized without changing your code architecture.”
this is from the tags.ink in the resources’ folder.

The tag map is at the top of the code. I guess the next step would be to have a config.json (or other format) to pass tags to the script.