Mailbag: IF Infrastructure From Scratch

I reached out to you a while ago to ask about your consultation services / fees and you told me that you weren’t taking on any new clients.  I respect that.  I was hoping you might “mailbag” my question or maybe have a little advice off the top of your head.  Any help would be greatly appreciated!  I posted this on the IntFiction forums as well and just hoping to get a little bit of your expertise / feedback.

I am working on a CYOA sandbox visual novel project. My buddy wrote a framework in C# / Unity and I’m currently writing the story in OneNote / Scrivener with articy:draft doing a lot of the node-work / structural organization. I used SimpleMind to do some high-level mapping for the sandbox but it’s been very clunky. I reverted to using Excel so I could bring direct mathematical tests into my work for planning and it’s been really tough to combine the cell-based organizational structure with blocks of text.

Creatively – I don’t write well in little bubbles…at all. I prefer writing in a Word / WordPerfect / Scrivener / Notepad setting. It’s easiest for me to see all the text, re-read what I need to, edit, etc. I’m at a point where the story is getting difficult to test / debug / and translate into Unity. At the end of the day – whatever tools I use – I have to be able to hand my work over to the developer and make sure he understands everything in as neat / concise a manner a possible.

Here’s an example of some of my code:

\INSTRUCTION((ONCLICK.CELLPHONE)(=)(0)) // sets the variable that counts the number of clicks to zero – variable declaration

\EVENT((CELLPHONE)(ONCLICK))

     \INSTRUCTION((ONCLICK.CELLPHONE)(+)(1)) // adds 1 to the counter variable

     \CONDITIONTEST((ONCLICK.CELLPHONE)(=)(1)) // tests the counter variable – boolean (true / false)

          \TRUE

               \ITEMDESCRIPTION((CELLPHONE)(ONCLICK)(This is your cell phone)) // cell phone description on the first click

          /TRUE

          \FALSE

               \CONDITIONTEST((ONCLICK.CELLPHONE)(=)(2)) // cell phone description on the second click

                    \TRUE

                         \ITEMDESCRIPTION((CELLPHONE)(ONCLICK)(This is STILL your cell phone))

                    /TRUE

                /CONDITIONTEST((ONCLICK.CELLPHONE)(=)(2))

                \CONDITIONTEST((ONCLICK.CELLPHONE)(>)(2)) // cell phone description on every click after second

                      \TRUE

                           \ITEMDESCRIPTION((CELLPHONE)(ONCLICK)(Why do you keep checking your cell phone?))

                      /TRUE

                 /CONDITIONTEST((ONCLICK.CELLPHONE)(>)(2))

          /FALSE

     /CONDITIONTEST((ONCLICK.CELLPHONE)(=)(1))

/EVENT((CELLPHONE)(ONCLICK))

The bottom line: Some of what I do is creative writing – storytelling, dialogue, and narration / item / entity descriptions, etc. And the other part of what I do is basically writing the instructions to the developer so he knows when to call which functions and how the visual novel is basically supposed to operate. Does that make sense? It’s super time-consuming because I have to partition portions of my mind to work on the tasks separately. My biggest hurdle to overcome is finding a medium in which to do this. I can’t write everything in Unity because I don’t know the C# code and that’s really what my buddy is there for. I’d write everything in Scrivener but I need the math functionality.

Here’s an issue I just came to that I’m still unsure how to properly detail:

Because of decisions the PC has made in the past dialogue options change for NPC reactions and PC responses. I need to be able to test those conditions / variables within the dialogue event to determine how the NPC will respond OR what new options open up for the PC. For example he / she can now intimidate the NPC or charm / impress – or maybe the NPC knows that the PC slept with her girlfriend and refuses to even respond, etc. So using the syntax that I posted above the conditional dialogue gets BOGGED DOWN.

My biggest concern right now is PLAYTESTING / AUDITING / DEBUGGING the game. I’m trying to follow my map and getting very confused with seeing variable counters. Hey – at this point in the game what are the values of these 5 variables? With the decisions that were made in the sandbox – how are we tracking affection across different NPCs – okay I want a numerical value that I can condition test at each potential branch / etc. Right now it’s almost impossible to track all the variables and know where they are at whichever point in the story you’re testing. My biggest issue with articy:draft is that the play-through / play-back doesn’t really work the way I expect it to and it’s NOT Excel – so I am having a difficult time using it to AUDIT though it’s decent for setting up the dialogue branches – even the conditional branches.

Lastly – I humbly apologize. I realize my thoughts must be all over the place. Could definitely use a little direction if you’ve done this sort of thing before – any advice is appreciated.

“This sort of thing” — working out how to combine code and writing features comfortably, how to visualize story flow, how to test what you’ve designed, how to make the experience low-friction for non-coding authors and allow for relatively painless revision — this is the substance of IF tool design. It pulls together considerations about the runtime engine, the authoring user interface, and the player experience with the resulting story. In a different domain, this is a significant part of my day job.

So while I have indeed done this sort of thing before, it’s a big job solving the design challenges for a new project. Doing a complete job on this is definitely “hire a consultant” territory rather than “hope someone can write a quick blog post solving your problems” territory. However, I can make a few suggestions.

The easy way. Usually I tell people not to roll their own tools if they can possibly avoid it. This advice may be too late for you, but if you’re using Unity and you want a tested, relatively-friendly way to write interactive text for it, check out ink from inkle studios. It is designed for this purpose and has been used on multiple pro-quality games; and because of how it works with Unity, there’s nothing there to stop your programmer adding whatever other game features you consider necessary at the C# side.

But suppose that’s not workable for you, for some reason. What could you do instead?

Custom-define a syntax that meets your needs. Your sample code above is bulky and repetitive; there would be much briefer ways to communicate the same information with at least equal precision.

Then you could have your coder make you a script that takes a simpler, more compact human-readable text or CSV file, recognizes simple markup in it, and re-exports that as (say) XML that the Unity project can use as an asset. Depending on your comfort with Unity, you might be able to load the resulting project up yourself and playtest the game right away on your own machine, even if you don’t speak C#. Getting to a point where the author can directly load and test their own content is very important, because if the work flow is always going through a second human implementer, the creative process slows to a crawl. So if that’s not already possible for you (and it sounds like it isn’t), you really want to get there as fast as you can.

(An intermediate step would be to do this directly in valid XML, but you’d have to do more typing as an author, in that case, and the Unity engine would still need to be able to read and deploy the XML, so your coder would have to be involved somehow.)

That still leaves a big question, though, which is how your hypothetical authoring file should specify all the features that you need to describe. Here what you’re doing is coming up with a template that captures consistently repeated design elements, and probably streamlining any unusual, unrepeated design elements or generalizing them into something repeatable.

This is still far shy of really writing your own IF language or tool because you’re creating a structure that is designed only and specifically for your one game, meaning you don’t have to work out all the abstractions that would be required for a reusable, multi-game system — but it gives you some of the leverage of having such a system, and it’s the prototyping point from which a lot of more mature IF languages begin.

For instance: the example you’ve given above suggests that you might have a whole category of inventory items that track how many times they’ve been clicked, with associated messages (1, 2, …, default). Here is one of many ways you could express that idea more compactly and readably than you did above:

Inventory: “cellphone”

description:

— 1: “This is your cell phone.”

— 2: “This is still your cell phone.”

— default: “Why do you keep checking your cell phone?”

This syntax should be robust enough to work if you add more enumerated answers (3, 4…) or if you have nothing here but the default.

Doubtless that’s not all you need to specify, though — you might also have dialogue or scene-setting narration, location descriptions, inventory items with state that affects how they’re described, or whatever else.

However, if you have done enough work at this point to understand your design well, you may already know what kinds of variables you’re tracking for each of those items. For instance, your conditional dialogue might (always or merely sometimes) offer a “charm” and an “intimidate” set of options, which unlock only if the protagonist has the right stats. (If you are doing this currently in a completely ad hoc way, with each choice node having arbitrary tests, limits, and variables, then you can also make your life easier, and your game more legible to your players, if you work towards a systematic mechanic that offers a consistent framework for determining whether a player should succeed or fail.)

Testing once the template exists. Having a well-defined template also lets you automate verification: if, e.g., you know that every inventory item must have a custom response of a particular type, your coder can make checks that validate the completeness of the data, or provide a default response in case you haven’t specified one.

There’s quite a lot more one could say here, about designing supportive tools and automated testing and visualization, about types of state that are useful to track in IF development, and about syntax specification, which I’ve described here in a deliberately simplistic way. But perhaps that is enough to think about as a starting point.

*

For those (probably not the original poster, admittedly) who want to go further in that direction, I’ve written some more elsewhere about IF tool development.