Design Question - Working w / Unity / articy:draft

Hey guys! Merry Christmas!

I am working on a CYOA 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.

I’m in a bit of a predicament. 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

     \INSTRUCTION((ONCLICK.CELLPHONE)(+)(1)) // adds 1 to the counter variable
     \CONDITIONTEST((ONCLICK.CELLPHONE)(=)(1)) // tests the counter variable - boolean (true / false)
               \ITEMDESCRIPTION((CELLPHONE)(ONCLICK)(This is your cell phone)) // cell phone description on the first click

               \CONDITIONTEST((ONCLICK.CELLPHONE)(=)(2)) // cell phone description on the second click
                         \ITEMDESCRIPTION((CELLPHONE)(ONCLICK)(This is STILL your cell phone))
               \CONDITIONTEST((ONCLICK.CELLPHONE)(>)(2)) // cell phone description on every click after second         
                         \ITEMDESCRIPTION((CELLPHONE)(ONCLICK)(Why do you keep checking your cell phone?))

So I hope folks are still following along. This was just a brief example. 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.

Does anyone have any experience with this? Does anyone have any recommendations or suggestions?

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 is this variable? 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 folks out there have done this sort of thing before - any advice is appreciated.


TL;DR: Difficulty being creative and writing dialog / story inside articy with the fragments - very disjointed / interrupted continuity. Writing in MS Word / Scrivener much easier. Need variable tracking over the course of play-through / play-testing for internal auditing. Need condition testing for conditional dialog / conditional location availability in sandbox. Need formula / functions to change variables


Wow! It removed all my formatting / indentation. Ugh! I hope it’s not too difficult to read. Sorry guys!

(Quick note, you can preserve formatting and indentation by wrapping your code in code-tags. I did that to your original post.)

Thank you!

Have you considered using Choicescript, Squiffy or Ink?

Ink (by Inkle Studios) seems the most elegant of these, but also the most complex to get a handle on (at least when I look at it). On the plus side, it’s designed to be able to integrate with Unity. Perhaps a good fit for a later project that you’re not already in the midst of.

Choicescript has a community-built IDE that seems like its very robust.

Squiffy has an IDE with a pane at the bottom that shows which variables exist and with what values, at any particular point in the game. Unfortunately whenever you make a change to the game and you want to test it, you have to restart the game and work your way back to what you’re testing from the beginning. I believe this last may be a limitation of all of these systems–someone please correct me if I’m wrong.

Choicescript and Squiffy are both pretty simple to understand to just start writing.

All of these would have you writing in a text editor environment and have mechanisms for setting and changing variables and sending the player to different points in the game based on variable values. I think they would be a step up from tracking your variables manually.

These also should all be able to print variable values in-game. So for the ones that don’t have a pane in the IDE displaying variable values, you could include lines in your game source text asking for the variables to be printed out as you play.

Their syntaxes are all pretty straightforward (Choicescript and Squiffy particularly) so that I think you could probably present your source text to your collaborator and have them be able to make sense of it.

I don’t understand what you mean by “I reverted to using Excel so I could bring direct mathematical tests into my work for planning”…can you elaborate, if its relevant?

I am coming from the perspective of pretty much a non-programmer. I’ve been writing a CYOA in Scrivener that will functional as either a simple ebook or a printed book, so the player is required to manually keep track of variables.

I’ve been using Scrivener for all of the node/structural organization (e.g. subfolders). You don’t use subfolders in Scrivener?

I hope this may be of some use, and hopefully some other people chime in.

Hey Loopernow! Thank you for the response!

What I was trying to say is that Excel has been invaluable for embedding a “CONDITIONTEST” (as I call them) in a cell and having it return a value - whether that value is numerical, boolean (true/false), or etc. For example, when I get to a dialogue and there’s two options and a hidden 3rd and 4th option - the first two always display, the third displays if the player is returning to the NPC a 2nd time and the 4th only displays if a previous trigger / variable is set to true. Based on which option is chosen I’m changing the conversation menu variable to track that decision.

There’s “passage of time” in the game - so i’m constantly tracking the time-periods. In the sandbox the player is allowed (4) different actions per day - morning, afternoon, evening, and night. If the player goes to his “job” for the morning and afternoon time slots he can go to the gym and the bar afterward. So I’ve created a few encounters that are only available in certain locations at certain times of day. And I’ve created certain static encounters that happen over the course of the game at set intervals - call them quarterly events - but whose conditiontests determine the nature of the event, the options, and the potential outcomes. There are also “random” encounters that can occur potentially anywhere - but that need to be called upon knowing the value of my randomizer’s variable. Excel does the random function well-enough for my purposes.

The math I’m doing changes based on the situation and it’s all very simple. The player’s “wallet” is another function in the game so I’m adding arbitrary amounts of funds to the wallet variable at different times. If the player gets a promotion and subsequent raise then the weekly paycheck goes from $2000 to $2500. If he gets demoted maybe it goes down to $1500. If he loses his job altogether then it goes to zero until he can find another job. If he pays for dinner and drinks out on a date his wallet might go down $200. Maybe at a movie it only goes down $20 (yeah right - it’s 2018).

Another example of the math is the affection system I’ve created. It tracks your affection with certain people - best friends or love interests and I need to add and subtract from those variables regularly based upon the player agency / choices. Then new story arcs / dialog options become available based on certain levels of affection (high or low) with the NPC whom you’re interacting.

To directly address your question - I’ve never used ChoiceScript, Squiffy, or Inkle. I think it’s safe to say that it might be too late to scrap our Unity framework since it’s basically ready for artwork and story. My buddy wants to incorporate all the regular features of a game into this so it can be sold on Steam - achievements, CG gallery, save / load / options, user / account specific saves / achievements, and a whole host of other things that Unity does really well. Oh! We started using Ren’Py but it was a little lacking in a few categories so my buddy scrapped it in favor of Unity.

Thanks so much for your response! I really appreciate the feedback!!!


Hey there Brent,

I’m not sure if I’m correctly understanding your question so let me rephrase it so you can tell me if I’ve got it right. :slight_smile:

You are writing the game, in the sense that: a) you are writing the script, including all of the conversation and action choices, and b) you are writing the skeleton of the game; that is, you are deciding how time works, and money, random encounters, etc. – all of the variables.

You are producing “quasi-code” that your partner will use to turn what you’ve written into an actual, in-the-flesh game in Unity. Assets (graphics and such) are coming from somewhere, your partner or somewhere else, but is beside the point for the purpose of your question.

artily:draft is supposed to be able to track all of your variables for you, and show branches conditionally, etc etc, so that you can “PLAYTEST… / AUDIT… / DEBUG…” efficiently, but doesn’t work the way you want it to. Also, it sucks for writing in because of the bubbles. So you are writing in Scrivener/OneNote instead, which is much easier, except that now you manually have to keep track of the variables yourself, in Excel, “flipping the switches” there, so to speak, and cognitively tracing the choice and gameplay path of the player by reading through your Scrivener/OneNote document, tracking variables in Excel as you go, and it’s getting really confusing. So you want to know if there’s some other, faster method that you can use to produce your quasi-code for your partner. Also, I’m assuming you’re having to write your game twice: once in Scrivener/Word and then you have to copy and paste stuff into artily:draft.

Am I close, I hope, to what you meant?

Re: Excel, so you’ve got a formula in one cell and you plug a value into another cell based on your playtesting, so that you can see what value the formula returns so that you can continue playtesting?

The code that you included in your first post, is that produced by artily:draft? Or you’re just straight-up writing that way?

I didn’t mean you should scrap Unity as the platform for your end product. My thought was, if you’re not married to the exact syntax of the quasicode you pasted in your first post, you could use the ChoiceScript or Squiffy syntax instead, that way you could use one of those systems to playtest your game, the way artily:draft is supposed to but doesn’t (since you said it doesn’t playthrough/playback the way you expect it to). Then, once you’re satisfied with how everything plays, you could either give the ChoiceScript document to your partner to turn into the Unity-based game, or if you need to you could convert it into the code syntax that you are using currently.

The syntax of ChoiceScript or Squiffy is pretty straight-forward; it’s almost like Markdown–but with the ability to set variables, modify them with math operations, and use if-then-else logic. And if you know Javascript, you can insert that into Squiffy. And you would be able to write in a text editor environment rather than a “bubble” environment.

ChoiceScript supports simple subroutines. I’m thinking something like that could be used to track time of day? Other people would know a lot better than me how to make something like that work.

Hey Loopernow! Responses in-line below:

That’s correct.

You totally got it!

Right on the nose!

I just made that up because it seemed to make sense to me at the time and my buddy gets it - kind of a mash-up between HTML / JS / and BrentHomebrew - LOL!

Ahhhh!!! That makes sense now! I apologize for misconstruing the intent behind your words. I think that might be a great idea - especially since, upon further inspection, ChoiceScript does a lot of what I need to do and it makes the auditing process pretty simple.

I just read about that and I think it would be extremely helpful for us!

Right now the beginning of the game is static - hand-holding, training wheels, get-your-feet wet - the middle of the game is all sandbox (locations, time of day, almost complete freedom) - and the end of the game is dynamic but at a FIXED-POINT in time but contingent upon the conditions the player explores / sets in the middle. I’m writing all the locations as modular so the instant you arrive at a location I’m testing for a ton of condition variables ranging from - what time of day it currently is to how close you are to getting a promotion at work to how much money you have in your wallet to random number generator to the barista’s affection for you, etc. At the end of the module you jump back into the sandbox but “time” has advanced one “period.”

Thanks so much for helping me talk this one out! This is our first project and we’re both doing it in our spare-time. It’s a labour of love! I feel like it totally would have made sense to start with fewer systems, less content, and a much simpler premise. But…c’est la vie!!!


Awesome! Glad to possibly be of some help. :stuck_out_tongue:

If you have the chance, post a post-mortem here. Would love to hear how things went. Good luck!

Hey! I posed this question of Emily Short and I believe she’s going to “mailbag” it in the next week or two. Right now I’ve been doing a bunch of the back-end in Excel and it’s working out well. The meat and potatoes are going into Scrivener but Excel is doing the framework very well - if a little disjointed.

When I get some time to play around with ChoiceScript I’d love to incorporate that - or do the entire project in that. I’m hesitant to switch gears right in the middle though.

I’ll keep you posted when I read Emily’s next newsletter.


I just ran across this via Emily Short’s blog…

I’d disagree with this: I haven’t tried Squiffy, but AFAICS Choicescript and Ink cover almost exactly the same ground, only Choicescript’s syntax is generally much more verbose. So…I guess you could say that Choicescript is more self-documenting and might be a little quicker to get started with, but Ink is simple enough that it doesn’t take long. It seems to be heavily inspired by Markdown, so it all makes pretty good sense. An asterisk marks the beginning of a choice, so choices clearly look like a list, an arrow (-> name) means to go to a named section, a left double arrow (<= name) means to insert some named text and choices into the current section, and so on.

And Ink is designed to work with Unity so it should be really easy to drop into your existing code.

Like the other two, Ink has an IDE/editor called Inky in which you write your story in one pane and it runs it in the other. If you play through part of the story and then change your code, it will recompile and (attempt to) make the same series of choices and update the transcript. So you don’t have to manually go through from the beginning.

The code side in Unity is also about as simple as possible. You create a story object from your story data, then you ask it for story text (line by line or all at once), and then get the current list of choices. When the user makes a choice, you tell it which one they made (e.g. choice #3) and then you can go back and ask for the next bit of story text. You can easily get and set story variables by name.

It also allows you to attach tags to any line (you might tag a line with the name of an image or sound or whatever that goes with it). Or if you have existing code to extract that kind of info from the story text, you can just leave it there and Ink will pass it through.

Ink’s page is at, the documentation is at Writing with Ink, and info about hooking it up to unity Unity is at Running Your Ink. Well worth checking out. Since you’re using Unity I’d bet this is the easiest solution on the code side, and Inky makes it pretty pleasant to write, rewrite, edit, and move stuff around on the authoring side. The devs are helpful and responsive. I’d highly recommend you take it for a spin. I don’t think it would be a big time investment. Probably a half-hour should suffice to get the flavor of it and see if you think it will work for you?

Hey! Thanks so much for your response. I’m out of town until late January but I’ll check this out and respond with an update as soon as possible. Cheers!