Diagrams used for writing without coding

Thank you for sharing this! And do you go through the whole game in this draft overview stage, before you start coding?

1 Like

Not so far, though that would be perfectly feasible. Especially for a writer collaborating with a coder. But I’m doing the coding myself as well as the writing, so until now I’ve been using this system to swap to and fro between the two. So I’ll do the creative writing side as I feel the urge, especially for things I haven’t started coding yet. Then I can start coding them later.

I do find it helpful to write each mini section quite comprehensively before coding though. The game this particular example from is episodic, so I can do an episode at a time. So I would aim to write up an episode in this way pretty fully before I start coding. That seems quite an efficient approach for me.

4 Likes

I don’t have any useful answer for you, but your question is an excellent one :grinning:

I earn my living writing software. For a long time, I thought the best diagramming system for engineers/designers/architects/artists was UML. It’s a family of about 12 different visual patterns which achieved concensus in the 1990s, at the peak of the drive towards higher standards in software design practice.

It was a humbling experience for me that when I tried to apply these patterns to my IF project, they really didn’t cut the mustard. The best I’ve been able to arrive at as a visualisation of an interactive drama is a variant of the UML Activity diagram, which allows transitions to consist of message passing to game world objects.

I have been meaning to document this somewhere. But it turns out, the intersection between formally schooled Software Engineers and IF authors is a very small set. That’s not necessarily a bad thing.

1 Like

I made this thing that was originally intended for writing gamebooks in ebook form using a variety of markup languages, but an additional feature is that it automatically creates a dot file from the passages and their links that you can pass to graphviz to generate an image map of your story. It’s pretty handy for sketching things out quickly.

You can also add notes to passages and track obtaining and removing of items. It also tracks loose passages and links to missing passages.

5 Likes

Yes. Look into UML (Unified Modeling Language), which has been around for programmers for decades. It is a diagram language for describing program actions, things, and relationships. It resembles your picture above a little. See Unified Modeling Language - Wikipedia.
Each entity contains a name, data needed (conditions?), and a set of actions, neatly encapsulated in a bub-tangle (rectangle with rounded edges). It also supports how other items can share properties with related items (inheritance). I have used UML for years, and think of it when designing my IF stories.

3 Likes

There’s a great article on how diagrams were used to track puzzle dependencies in the Monkey Island games. There’s a related thread on this site here.

On the topic of using UML for puzzle/story design, here’s a work in progress of mine which might interest you as an example. I drew it with Inkscape, hence the SVG.

It wasn’t easy to arrive at. But it’s the best I’ve been able to achieve so far. This particular thing is not an IF-style puzzle, more a non-linear narrative. The reader is able to travel between locations and witness the story unfold, in a Christmas Carol kind of way.

Just quickly to explain the basics:

  • Boxes with rounded corners are UML Activities. In my world, that means a scene of dramatic dialogue, triggered by a combination of world object state.
  • The square-cornered boxes are game objects. Their state is modified by one activity, and used as conditional input by another, hence they are effectively messages which signify transitions from one activity to another.
  • Text in square brackets are UML guards. They are the conditions by which the gameplay may exit an activity.
  • The diamonds are branching points, where there are alternative paths out of an activity.
  • The thick line is a split to allow parallel activity flows.

Thank you, I didn’t know this app, either!

[EDIT: Doesn’t Vizon look very much like Puzzlon? I’ve no idea how to start working with either of them, though.]

Yes, making sure you don’t make unsolvable situations is always a must, but in this thread I am mainly asking how (if at all) writers go through writing responses for all game actions before they (or another programmer) get to code. My idea is either some sort of diagram like the one at the beginning of this thread, or a Room > Item > Action description in a text file.

Room 1

    item 1:

        EXAMINE: "This is the description of item 1."

        TAKE (instead): "You don't want to steal [character 1]'s [item 1]."

    character 1: 

        ASK ABOUT ITEM 1: ...

etc.

Thank you for this. Wow, there are so many apps and tools! I didn’t know graphviz either…

1 Like

When I open Vizon in my browser, the window is split into two panes. There’s the “puzzle chart” in the right-hand pane, and the code which generates it in the left-hand pane. I simply started messing around with the code to see how it changed the puzzle chart. I added a new action with no preconditions, and then cut and pasted in new actions dependent on that, experimenting with OR gates etc. as I went. My pc is a bit slow, so I turned off the auto-redraw.

The thing I like about it is that order of the bits of code in the left-hand window doesn’t matter: it’s the dependencies which Vizon uses to draw the chart. So I can focus on designing one bit of the game, while the app keeps an eye on the whole game so that if I accidentally short-circuit another puzzle, it lets me know.

If you save the page, it saves the puzzle chart too, somewhere in the bowels of Firefox, but I’m cautious about that sort of thing, so I copied and pasted the left-hand pane into a plain text file and saved that in my project folder. I tested pasting the text into the left-hand pane, and it worked fine.

Vizon doesn’t export to any IF system, so it’s really only useful for generating a chart of what you intend your code to do. So for me the process resolved into:

  1. Use Vizon to plan the intent of my game
  2. Code up part of the game
  3. Use one of the game analysing apps to discover that my code didn’t actually do what I intended!

I find that for planning scenes, a plain text editor is best. I sit down and write a fake transcript (with prompts etc.) that represents an ideal “minimal path” route through the scene. If the scene is a “branching scene” – i.e. one where the player can get a good or a bad ending, or it sets the channel for the next part of the story then I write separate fake transcripts for each route.

I find that anything which requires more logic (such as an app that would require me to click in different boxes) defeats the object of writing the transcript because it interrupts the writing flow, and any creative writing (e.g. descriptions and dialogue) turns to cardboard. I think coding and “writing” use different and incompatible parts of our brains. Certainly if I try to do both simultaneously I find I do neither well.

Of course, the downside of doing it this way is that often an expression or process that produces natural prose, or an action that should produce a particular effect, turns out to be an absolute PITA to code. But I think this is the right way to proceed. We should be forcing the machine to do what we want, rather than shaping our stories to fit its cramped capabilities.

Mind you, I’ve yet to out-stubborn the compiler!

It’s only once I have a working skeleton of a scene up that I start thinking about the additional commands and responses needed (a.k.a. a thousand reasons for telling the player “no”!)

That’s part of the reason I’ve become very interested in Dialog recently. I like the way that I can put myself in the player’s shoes and use the interactive debugger to expand the play options in an organic way. Most of the computer theory about why Dialog does what it does the way it does goes right over my head, but I do like the way that it seems to keep the “book keeping” aspect of maintaining the world model separate from the generation of output. This seems to me natural as well as convenient. I’m finding the Dialog engine much less of a buttinsky than Inform 7.

1 Like

This is actually a great idea! I will try that with my current story, alongside with the Room > Item > Action lists. Moreover, I sense it would pay off more if not kept as a “minimal path.” I’ll know more when I try it, but I have the impression that it offers the opportunity to improvise, being the writer and the player at the same time. Just like a player, you can just type whatever command comes to mind. Then, as a writer, you come up with replies.

I agree. :blush:

My experience was that if I got fancy then I just ended up with a lot of wooly text with no clear intention.

I found it more useful to flesh out the scene interactively, playing through the game (ideally after it having been coded for a while and then laid aside) so that I was adding responses prompted by the text. I guess that I’d still have a bunch of work to do incorporating feedback from beta-testers, but no project of mine ever got that far, alas.

1 Like

I made a video a while ago on how to use Vizon/Puzzlon, maybe it’s useful?

2 Likes

Dizzydonut,
Thanks for all this. You might want to turn this into a podcast tutorial.
I didn’t know about Vizon or Dialog but now I want to try them. I also agree with your minimal path approach being expanded to flesh out the story. I learned that lesson from compiler design. I also agree with you about the different parts of the brain that codes a story vs. creates the story.

1 Like

I want to add the introduction of beta players. They are essential. They ALWAYS think of things, or read the output, in ways I never thought of. When I handle their comments, my story always grows, and becomes more stable.

2 Likes

I think you may be crediting me with a little too much! The video was made by @adventuron. Only the half-ass philosophizing is mine. :slight_smile:

The Dialog manual is really well written and should give you a good insight into whether the language will be a good fit for you or not. It’s still in beta, so you have a chance to be involved in shaping it. @lft (Linus Akesson) is very good at responding to user suggestions. There’s a whole other section on this site devoted to Dialog.

3 Likes

Thanks

1 Like

I just stumbled onto this tool today and it looks really cool. It’s kind of like Twine but focused on flowcharting. I’ve seen similar things done before but they usually cost at least $60 and are windows only. This one is free and is precompiled for windows and linux and compilable for Mac.

I haven’t had a chance to play with this myself, but it seems really intuitive from the video.

4 Likes

Wow, first time I see this one!

I actually did my diagrams on Arcweave. I’m very positively predisposed towards it, because it’s a friend and colleague who develops it. It’s freemium, so you can make small projects for free.

This is a sample project, which you can also run, when pressing the PLAY button up right.

1 Like

Arcweave is pretty awesome.

When I get around to developing for grade school level students the graphics tracking would be very nice.