JSON based IF language

I was using choicescript for my project since it has surprisingly high coding complexity, but then I got to the point where I needed custom formatting beyond what it could provide. I tried doing a straight-up html/javascript solution, but it’s not easy to refactor since I would need to edit the javascript itself everywhere it appears. I settled on possibly writing the whole thing as a JSON string that stores all the storypoints with commands that dictate how it’s fed to the user.

What do you guys think of this approach. Has it been tried before?

Not sure exactly what you mean here. Are you suggesting converting a json description into CS or some existing format, or are you suggesting a new IF language stored as json?

The latter. I have something like…

    "start": {
        "story_content": [
                "action": "log_text",
                "text": "Starting Project..."
                "action": "clear"
                "action": "goto",
                "label": "/orphanage/orphanage_home_base/start"
    (More stuff)

And I’m going to interpret it and turn it into a web page. One upside is that this is a standardized format and I wouldn’t have to deal with straight-up string parsing. It doesn’t seem like it should be too hard, right? :sweat_smile:

If i’m not mistaken, ink actually started as a json format, then evolved in a full-fledged language (that is still “compiled” to json)


Nice! I was trying to look into its particulars, but the compiler to js seems to be binary even on the github. I thought they called it open-source, maybe I’m just being dense? Or is it just that that part of the project is actually closed-source?

I just realized there’s a topic just for this stuff! (Technical development - Interpreters).

Is there a way to change topics? Would it be appropriate to make a new one?

1 Like

Either would be acceptable. Consider cross-linking it if appropriate.

Everything is open source and on their github. This is C#

A port to js also exists.

You might find Dendry interesting.


Ah, I was checking inky’s github (emphasis on the extra y!), where the C# aspect seems to have been compiled. Confusing that they’re named so similarly! Thanks.

1 Like

It’s funny, cos a couple years ago I made my own attempt to write an IF language that used JSON and JavaScript, running in C#.

JSON to describe the world model and commands, JS to implement the commands.

	printedName: "Transport Chamber",
	description: "This is a smallish room dominated by a transporter roughly a meter or so in diameter. The only way out is through the transporter (not an option) and through an automatic sliding door in the southwest corner.",
	southwest: "middeckfore",
	scenery: [
		/* Inline object definition */
			printedName: "transporter pad",
			description: "The transporter glows a functional blue.",
			patterns: [ "transporter pad", "transporter", "pad" ]
	things: [
		/* External file reference */
		"stem bolt"

	printedName: "self-sealing stem bolt",
	description: "What is this even for?",
	patterns: [ "(stem )bolt" ]

	name: "Taking",
	patterns: [ "^take (?<thing>.+)", "^get (?<thing>.+)", "^pick up (?<thing>.+)" ],
	script: "take.js"
var thing = player.Parent.FindThing(parms[1]);
if (thing == undefined) {
	print ("You can see no such thing here.");
	return false;
if (thing.Kind != "Thing") {
	print ("That's not something you can pick up.");
	return false;
if (!thing.Portable) {
	print ("That's fixed in place.");
	return false;
print ("Taken.");
return true;

Worked quite well tbh.


I don’t actually see any real advantage in representing your IF language in json. There are several problems of json [1] for this that means you’ll probably have to write your own json reader/writer to relax them. And if you’re going to parse a syntax, it might as well be domain specific in the first place.


  • i think (need to check), json does not like newlines in strings.
  • quotes within json strings is another escape annoyance. This will come up a lot in authoring.
  • having the value keys quoted as standard is another annoyance.

I came here to say something similar. JSON is human-readable, but handwriting it has more headaches than you might think.

If not json, what do you recommend? I really need more flexibility than current languages like Twine and ChoiceScript, and would rather code my own language than using one of these as a boilerplate. So keeping this in mind, it seems like I could just write things in a txt, which would make parsing harder but maybe it’d be easier to write. I could also write directly in another programming language, but that only seems to make both write-ability and read-ability worse. Let me know if there’s other approaches you think of.

And yeah, I agree json has some annoyances, but the ones you list at the very least are very minor. Typing “\n” or “<br>” or whatever escape sequence I choose to go with instead of an enter press every now and then isn’t a big deal, neither is typing " instead of " (and if it really bothers you for large passages of text, it’s super easy to do a find and replace), and quoted value keys aren’t really very different from unquoted ones.

Still, though, the number of curly braces really does seem to add up, and I’m scared of bloat for the future. I don’t know the best way to keep everything small. Let me know if you have ideas!

JSON is ok. Tracery is pretty popular and gets away with it just fine for everyone from programmers to very-much-not programmers. It can maybe be a hard sell if you were trying to get other people to start using your tool, but once people get into it it’s ok.

And if I understand correctly you’re making this for yourself, so… I’d just go with JSON unless you have a strong, specific reason to do otherwise.

Off the top of my head, there’s YAML, which is friendlier than JSON in terms of hand-editing.

Another possibility is Markdown, which is easy to pick up and read.

YAML is easy to write by hand and it’d be trivial to translate into JSON.

Or, what Jim said, since he ninja’d me.

1 Like

Is Tracery more for making writing the strings easier or is it supposed to provide the whole framework?

YAML seems intriguing. Have heard of it but didn’t look into it too much. I don’t understand how I’d represent the data of my story in markdown. What were you imagining it would look like?

EDIT: Also, how would you translate to JSON? Seems like it has some features (like array keys) that would be difficult to translate.

Any recommendations from your experiences?