Tinderbox Forum

Using Tinderbox to write a Choicescript interactive narrative

I have been starting to frame up a Choice of Games style interactive narrative using their choicescript tools over on github here: https://github.com/dfabulich/choicescript

Well, sure drafting this up would probably be a good task for storyspace, but as the needs I have are pretty much text-focused I think this might be a good match for Tinderbox. (Also, I still have my license to Tinderbox 6, so I’m going to force myself to get started with this there, and if it works finally upgrade to the later version of Tinderbox.)

Here is the main thing I’m looking to get out of the opportunity to frame this up and write this in tinderbox. As with Python and similar, the indentation level is really critical for dividing up the blocks and knowing which option and stat metric is considered at what time, and where the narrative flows based on a choice.

but unlike a Python script where you can get a lot out of a screenful sometimes, so just a little code folding keeps you sane in plain text, with my choicescript project the blocks and bits of prose can be massive and have their own double-space gaps, indentations that mean things non actionable, and nexted choice options that don’t close under pages and pages and pages later.

So it seemed a lot more fun to set this up somewhere that would allow me to just write blocks at the base level and use links, nesting, and an output script to do all of the annoying indentation stuff upon output to plaintext files at the end!

And better than doing this in Scrivener, where I started with this, where the Scrivenings feature makes it crazy easy to read content nested even really deep within other notes that contain text, if I build this in Tinderbox I can potentially create visualizations of flow in the map view, and actually calculate various stats factors going up and down, to make sure I make an actually balanced experience.

But … I don’t actually know two things that are holding me back, and point to the fact that I seemed to have forgotten most of my tinderbox skills i haven’t used since Tinderbox 5 …

  1. how would one go about creating an export script that adds a tab for each level?
  • Is it better to use nesting to increment tab level for each line? seems totally possible?
  • Or is it better to assign a value to each block that already says what its level would be and then use some sort of link or outline series to select the order for output?
  1. is there a means of automatically and without a lot of visual tugging to include the title and all of the text in a note, and then the text linked or nexted into the note a deeper level? This is me being an idiot and not remembering anything not brute force about using Tinderbox, but a great answer to this might be to just link me to a project that does this well.

Anyhow, i’m hoping tinderbox will work for this, because then I get to force myself to aggressively use it again and potentially save up to do the update to make this a go-to tool like it was for me back in grad school!

  1. This is a very reasonable task. You might also enjoy “Getting Started With Hypertext Narrative” for some perspectives.

  2. For export, you’ll want HTML export.

  3. By “adding a tab”, do you mean literally adding a tab character, or do you mean indenting the left margin? Either is easy enough.

  4. To include the note’s name, use ^title^ or ^value($DisplayName).

  5. To include the note’s text, use ^text^ (for marked-up text) or ^text(plain) (for plain text.

  6. To include the note’s children, use ^children(…template name…)

See the HTML Export chapter of Tinderbox Help for more.

What will make this a LOT easier for other forum readers would be to include a very short sample of ChoiceScript, and perhaps a tiny Tinderbox document that corresponds to it. Then, we simply need to figure out how to export from that document to create something like that file.

Incredibly helpful, Mark. Thanks so much!

Here’s a sample from the choicescript intro pages - here:

I’m going to use // to mark as “comment” the page text around the code that is there to help make this page useful to readers.

// Your First Scene: *choice and *finish
// Here’s a simple scene written in ChoiceScript. You can find it in web/mygame/startup.txt.

  Your majesty, your people are starving in the streets, and threaten revolution.
  Our enemies to the west are weak, but they threaten soon to invade.  What will you do?

    #Make pre-emptive war on the western lands.
      If you can seize their territory, your kingdom will flourish.  But your army's
      morale is low and the kingdom's armory is empty.  How will you win the war?
        #Drive the peasants like slaves; if we work hard enough, we'll win.
          Unfortunately, morale doesn't work like that.  Your army soon turns against you
          and the kingdom falls to the western barbarians.
        #Appoint charismatic knights and give them land, peasants, and resources.
          Your majesty's people are eminently resourceful.  Your knights win the day,
          but take care: they may soon demand a convention of parliament.
        #Steal food and weapons from the enemy in the dead of night.
          A cunning plan.  Soon your army is a match for the westerners; they choose
          not to invade for now, but how long can your majesty postpone the inevitable?
    #Beat swords to plowshares and trade food to the westerners for protection.
      The westerners have you at the point of a sword.  They demand unfair terms
      from you.
        #Accept the terms for now.
          Eventually, the barbarian westerners conquer you anyway, destroying their
          bread basket, and the entire region starves.
        #Threaten to salt our fields if they don't offer better terms.
          They blink.  Your majesty gets a fair price for wheat.
    #Abdicate the throne. I have clearly mismanaged this kingdom!
      The kingdom descends into chaos, but you manage to escape with your own hide.
      Perhaps in time you can return to restore order to this fair land.

// As you can see, the *choice command presents the user with a list of #options; the result of choosing each option appears indented right below the option (in an “indented block”).

// If you go to play this scene, you’ll first be presented with three options:

// Make pre-emptive war on the western lands.
//Beat swords to plowshares and trade food to the westerners for protection.
//Abdicate the throne. I have clearly mismanaged this kingdom!
//If you choose option #1, you get to choose how to win the war. If you choose option #2, you may decide how to negotiate with the westerners. If you choose option #3, the scene ends with no additional choices.

// As you can see, there’s a lot you can do with just the *choice command and the *finish command. Indeed, using only these two commands and a lot of time, you could develop an entire “choose a path” style book!

whelp, my submission into this place of course killed the formatting – used the codeblock tool and fixed it, but you might still want to visit the link listed above to see the formatting clearly visible (spaces or tabs, you get to choose which, you just have to use the same choice for ALL of the scene).

Also, I have "Getting Started With Hypertext Narrative” – so would love to read whatever sections you recommend. Maybe I can read it all again, read the first edition years ago but … alas i can’t remember much.


This article might be useful regarding


for indenting your levels in the exported document.

1 Like

If each element (scene, choice, choice item elements, etc.) prototypes could be used to help abstract and automate things. The example above could be written in outline form thus:


For the interrelation of the plot to show on a single map via links, an outline as above won’t work as map links are drawn between sibling items.

Why not simply put the tab in the source text. This circles back to the last point above. There are several approaches I can see. A nested outline - as I’ve posited above is possibly the easier way to do this structurally but it might not give the narrative overflow you are after (i.e. a map with link lines).

Absolutely, via export code. This means the title ($Name) of a note does not need to be repeated in the note’s text ($Text) - at least not for export purposes.

But first, to avoid building on sand, I’d look at the following in parallel first as they have an impact on each other and the final layout choice:

  • decide on the granularity of your notes. Whole scenes? Each Choice? etc. Decomposing to notes representing function blocks allows for leveraging prototypes as suggested above.
  • decide whether you are going to use an outline or flat structure. For very large numbers of notes (100s) a single flat structure may get cumbersome but for smaller numbers of notes either is a possible choice. The granularity of your decomposition.
  • extract into a single doc the layout/indentation for all the ChoiceScript operators, not just those in the basic, as it is necessary to review each operator for potential difference/conflict in export markup.
  • find an example doc employing all the operators you will (may need to) use as this should be the skeleton for your initial test Tinderbox doc. (The downloadable files seem to lack such an example, so you may need to write it).

TL;DR this looks very do-able but needs a bit of preparatory mapping of structure. However, if that task it done well it should only need doing once.

1 Like

Wow, this is very helpful. and well worth experimenting with. If anything, because doing testing as I go before committing to lots of writing into notes in various structures might delay composition a bit, but then allow me to really start writing quickly later with full confidence I can get the output needed without insane levels of bruteforce fixing.

I’m going to document my efforts and share them back here in case anyone else could benefit from it – or at least in case people see more elegant ways to accomplish these tasks that I miss out on.

Surely, Getting Started With Hypertext Narrative can’t be “years ago?” I think it was only last year…

1 Like

Whelp, I was foolishly conflating your hypertext book with tinderbox way. Now I’ve ordered getting started with hypertext narrative and am re-reading tinderbox way 3d ed as well!! And am working hard to use tinderbox for my choicescript experiment! I vanished for a bit but finally have a writing project for the choicescript platform that excites me enough to go through all of process of building and testing in tbx!

Thanks, Mark!