Experimenting with a format and editor for interactive fiction (iepub)

Technical Development Development Systems
1

Hello everyone,

A few months ago I started trying to write an interactive fiction novel. Or at least I tried. As the story started growing, the structural side of things became harder and harder to manage.

Branches multiplied, narrative state started spreading everywhere, and I found myself constantly trying to remember where certain conditions or variations lived in the story.

After fighting with that for a while, I realised the main problem (at least for me) was that the prose and the interactive logic were completely mixed together. The text of the story, the conditions, the variables, the branching… everything lived in the same place. The more the story grew, the harder it became to keep it readable and maintainable.

That got me thinking about whether those two things could be separated.

So I started experimenting with a different approach: keeping the prose as prose, and moving the interactive logic into a separate layer that controls how the text is presented.

That experiment eventually turned into a small project called iepub.

iepub is a structured format for interactive books inspired by EPUB. The idea is to keep the narrative text clean and readable, while the branching logic, conditions and state live in a separate system that decides which parts of the story appear to the reader.

With that structure, a story can include things like:

  • traditional branching choices

  • conditional variations of scenes

  • narrative fragments that appear depending on earlier decisions

  • variations triggered by variables or reader behaviour

While working on the format, I also started building an editor called ieWriter, because editing this kind of structure directly in files quickly becomes painful.

The idea behind the editor is fairly simple: it should feel like writing in a normal text editor (something closer to Google Docs than to a programming tool), but designed specifically for interactive fiction.

So the writing interface focuses first on the prose itself, but allows you to layer interactive elements on top of it without breaking the flow of writing.

Inside the editor you can:

  • define conditions that control when parts of the text appear

  • attach variables or narrative state to sections of the story

  • configure dice rolls or probabilistic events if the story needs them

  • add narrative variants that replace or extend the base text

  • visualize the structure of the story as a graph to better understand how branches connect

The goal is to make it possible to build fairly complex narrative structures while still keeping the project understandable for the author.

The whole system runs on a small reader runtime that interprets the format so the story can actually be read as an interactive book across devices.

To test everything together I started writing a demo novel using the system, so the full workflow (writing → structuring → reading) can be explored.

If anyone is curious, the project and the demo are here:

https://iepub.io

I’d genuinely be interested in hearing thoughts from people here, especially anyone who has spent time wrestling with the structural side of IF tools.

6 Likes
2

ok, i’ve been clicking on things for 20 minutes and i still can’t figure out how to “add a choice block” ?

3

ok, i found it, but they don’t do anything…

4

still trying to connect choices to scenes…

5

Hey! Thanks for your feedback. There are docs, and loadable examples in the writer so that first interaction is less painful. I can assist too.

6

ok, i managed to name the choices in order to validate. but it took ages to find “preview”. I made a cover but it doesn’t appear, except on the “open” menu.

7

Quick review;

This looks exciting and a bit different. For example, it doesn’t use a visual node based editor which is proving controversial. As a plus point, it looks quite sophisticated and capable. However;

The “docs” are not. They say things like “create a choice block” without telling you how to do this. Whether that’s because it’s hard to find these in the editor, or the docs are lacking are different sides of the same coin.

I guess, once you know how to drive the basics, it’s a bit easier. But it’s a hurdle. There’s a “tutorial” yes, but it doesn’t teach anything.

Amazingly, whilst clicking on other things which changed the page, it didn’t lose my work in progress. Big plus there. On the other hand, how exactly do i return to my project if i close the browser?

Best of luck, looks interesting.

3 Likes
8

thanks a lot for taking the time to try it and write this up — this is really useful feedback.

You’re absolutely right about the documentation. Right now it’s still very rough and in many places it assumes you already know where things are in the editor, which obviously isn’t ideal. Improving the docs and the onboarding is definitely one of the next things I need to work on.

The same probably applies to the tutorial. It was more of a quick walkthrough to get something in place, but it clearly needs to explain the concepts and steps much better.

Regarding your project: at the moment the editor stores projects locally in the browser, so if you return using the same browser it should still be there. That said, the project management part is still pretty early and will definitely need a clearer way to load/export projects.

And I’m glad the autosave worked — that’s one thing I really didn’t want to break :slightly_smiling_face:

If you feel like experimenting with it a bit more, I’d be very happy to help if you get stuck — either here on the forum or by email.

1 Like
9

I played with this a bit as well. My tool of choice these days is Twine, but your editor caught my attention because I’ve definitely struggled with this:

My solution in my own Twine project was to offload a lot of the actual nuts and bolts to various macros I wrote in Javascript, and keep the prose pretty much as pure as I can. It works… well enough.

In all honesty I can’t say I feel any particular motivation to leave Twine behind, but it’s an interesting project.

One suggestion, if I may: unless I missed some other means of doing this, it might be a good idea to allow a single-choice “choice block” to advance the text, in case the author wants to break a wall of text into more manageable chunks.

2 Likes
10

thanks for reading! and for the feedback!
That’s actually exactly the problem that pushed me down this rabbit hole.

In my first attempt the manuscript slowly became this mix of prose, branching logic, state variables and conditions — and at some point it stopped feeling like a document and started behaving more like a system.

The idea behind iepub was basically to separate those layers so the prose can stay readable while the logic lives somewhere else.

Totally understand the point about Twine though — it’s a mature ecosystem and it’s hard to move away from something that already works.

And thanks a lot for the suggestion about the single-choice block to advance the text. That actually makes a lot of sense for pacing and breaking long sections. I hadn’t implemented it that way yet, but I’m noting it down and I’ll work on adding it.

Out of curiosity: in your Twine setup, do you mostly handle that kind of thing with macros as well?

On the other hand, I’d be curious to hear how the experience of using the writer felt from your side. Did it feel intuitive to navigate, or was it a bit confusing / complicated to get started?

thanks again

11

Something that i have not talk about yet, is that I am currently working on a import/transform way for both ink and twine projects, so that users can test their own creations

12

Seconded. I had this problem already in my three scene experiment!

1 Like
13

Already working on it! Thank you so much

1 Like
14

I have published this improvement and it is fully available ! thanks again for your feedback

1 Like
15

I have deployed today what you suggested regarding single choices blocks. Thank!

16

Yes, I have a macro that creates a link that inserts some text below it in a newly created div. It ends up feeling very similar to how you’ve implemented it, although I hadn’t seen your work at the time.

There was a little bit of confusion to get started, but there always is when trying out a new application, so I don’t hold it against you. It ended up feeling pretty easy to figure out what I was doing.

Personally, I am more of a programmer than a writer, so my own usage preferences would tend towards the ability to write code rather than set things up visually like your editor. That said, I also understand how “I want to write code” and “I don’t want a bunch of code in my document” might seem a somewhat contradictory set of constraints. Something like Twine’s macros: an easy, high-level alias for lower level code that I can write myself, is what ended up working well for me. But please don’t feel any pressure or take anything I’ve said as a feature request, because I know my use case might be atypical.

1 Like
17

Thank you so much again! Your feedback is super helpful!
I am currently working on improving onboarding so that friction with new users is reduced.
The idea here is simplify the writing experience, and see if eeryone, with or without programming notions can write interactive fiction. This way the interactive fiction community can grow!!
If you want I will let you know once it is available!