Hype and Ink: project structure for a visual novel?


I’m attempting to build a visual novel with Hype Pro and Ink story engine.

Ink is a branching story engine (Choose Your Own Adventure) written in javascript. They have an app Inky that outputs a functional webpage. I’ve poked around in the exported files and hacked the CSS, but I don’t understand fundamental javascript enough to ask a specific question. Any advice how to structure the overall visual novel project is appreciated.

My long-term goal is a webkit-type app. I’m not sure how it will ultimately look, so I will share some screengrabs from HypeReflect (ipad). The mockup is a Hype scene with parallax image layers, and a separate (overlaid) text area for the Ink story content:


My question is about the overall project structure, from a non-programmer who needs to learn some fundamental Hype/javascript concepts. Poking around, trying my own javascript links after watching random video tutorials isn’t getting me very far, I don’t know what I am doing. So let me just ask.

  1. My artwork is not typical japanese VN manga-style but I assume it is the same mechanic with each “story beat” (tap-/click) updating the Ink and cycling through visual elements. (The artwork is the one thing I am confidant about. )

But in Hype, are these image layers Symbols? Timelines? Or a folder of source pngs that I am swapping through code? The Ink story is branching, so I’m thinking not to create a Hype scene for every possible situation, but (generally) assemble the elements on a generic stage on the fly through calls from Ink.

Not all sprite groups will be seen (ie: the sprites of “evil Margaret” are not used in the “good Margaret” story line) and some backgrounds are never seen, so that makes me think I should load external images rather than create a massive comp with all options. Which of these approaches sound better? Would the difference in the two mock-ups (one art-heavy, the other text-heavy) change your project? How would this effect transitions?

  1. My javascript is almost zilch :sweat: so shortterm goal is to bridge Ink to Hype, and Hype to Ink, as easily as possible. A bare minimum would be that Ink can call a Hype scene, and Hype can call an Ink story thread, (or pass a variable)… The image on the right is the Ink export running in a Hype iFrame widget, but if Hype rebuilds the iFrame restarts Ink… I need Ink to “lead” Hype, and Hype to ping back, but not restart Ink when Hype scenes load or change.

Both Hype and Ink have APIs. I get the idea of calling a js function, but I don’t understand how to make the communication “connect”, or where the Ink runtime lives.

  1. I would like to include interactive Hype scenes (mini-games, inventory, journal, etc), that take over the fullscreen and hide the Ink layer. I know how to do this in Hype with scenes, it’s also easier for me (artist) to use Hype to arrange layouts to fit different screens.

Can a Hype text layer be updated by the Ink – and also form the choices as links back to Ink, while the Ink runs invisibly (and consistently) outside of Hype? This would look more like the image on the left. Is this a Hype text layer (or possibly a separate CSS layer in the HTML document)?

  1. Is this going to be a single Hype document, or multiple documents that load into the page? I think some of my confusion is not understanding the “scope” of a big Hype project, when things need to become external.

  2. In a text-heavy version, would it be possible to embed the Hype scene inline, like a scrolling webpage? The Inky export can do this now using an image:url tag. Rather than a Hype “window” locked in place, could a hype scene be embedded within the Ink’s text flow (maybe animate as it hits a certain screen height and silences itself once it has scrolled off the screen?) This would be the opposite of showing Ink within a Hype window, it would be many simple Hype documents dialed to the appropriate scene to punctuate the text as it scrolls (assembled from the various sprites as needed for the scene).

I apologize for the broad and vague newbie questions. I see many ways to approach it but I don’t understand enough to know where to begin.

(Jonathan Deutsch) #2

While I’ve heard of Ink and understand the basics, I’m not very familiar with the backend javascript runtime and what parts are exactly exposed.

There’s probably two general strategies to go for - either Hype code controlling Ink or Ink code controlling Hype that would have very different technical solutions to setting up integration. My instinct would be to go for a strategy where Ink controls Hype. To this end, I’d probably use scenes to setup “templates” that could be filled in by data that is placed in an Ink script. The Hype scene as a template could set classes on elements (via the Identity Inspector) that would end up being replaced. You’d probably need some sorts of shared or naming conventions. The Hype API and HTML DOM APIs can do the work of replacing images or inner HTML in the elements.

Ultimately I don’t think there probably could be great answers to a lot of this until someone’s tried an implementation and figured out best practices for getting data back and forth (and some may be dependent on the story!). Regardless, it will be a javascript-heavy endeavor.

There was some previous discussion about a similar environment called Twine:

And @MaxZieb even made an extension to work with that! See:

So perhaps that project can provide some direction/inspiration.

(In some alternate universe where there’s more time I’d love to work on this project, but that’s not in the cards for now…)

(Loves Hype) #3

Ink is focused on C# and the Unity Engine. It shines there and you can inspect variable from Unity (looking into the ink-Engine) to influence the graphics in Unity (and apperantly vice versa) https://github.com/inkle/ink/blob/master/Documentation/ArchitectureAndDevOverview.md and https://github.com/inkle/ink/blob/master/Documentation/RunningYourInk.md#settinggetting-ink-variables

As I see it from quickly inspecting Ink it is a self contained environment with it’s own story format and language much like in Twine. The difference at first glance is that is not made to be easily extended from within and rather relies on inspection/observation of the story state from the outside. I guess this is to keep the story engine very portable and independant of the implementation.

There is a JS port here:

Here is a template that implements Ink/Inkle in a browser context:

And here is the corresponding main.js

As you can see in the man.js code (if you can read JS): They are letting the ported engine do it’s stuff and then they manipulate the page with the returns. So in theory you could use this a wrapper and start feeding vars into Hype while the story progresses (vice verso should also work).

Same as @jonathan I would love to take a shot at this but am currently scheduled for holiday.
When I am back I might given I have time … also maybe consider Hype TwineStage as it’s ready to use.


Ahh! I think DOM is the higher “level” that I didn’t know about. I will explore DOM API.
Thank you for the javascript realitycheck.

I saw this! :star_struck: I prefer writing with Ink’s markup, but Twine is a larger community with several add-ons….

I’ve been hacking at the main.js from Inky, but it’s not the same as knowing what I am doing. :sweat_smile: I’ll stick with Unity for now … this does not seem like a fun “Let’s learn how to JS” project. Haha.