Improv.js [WIP]

a tool to make tools to make explorable explanations

Let's say you have a model of a complex system. And you want others to be able to play around with it, explore the system, change its rules, maybe even create their own models with it! Well, that's an incredibly specific goal to have, but hey, you're in luck.

Improv lets you write words normally like this...

A "boid" is like a bird, but worse.
Let's make a flock of {NUMBER count: min=0,max=100} boids,
and paint 'em all {CHOOSE color: black, red, blue, random colors}!

...which will get you something like this:

But wait, there's more! Besides sliding numbers and selecting from dropdowns, Improv also has the ability to let your readers "re-program" the system itself, without having to touch the messy code itself, without fear of breaking everything.

Here's how. Again, you start with regular writing:

Let's make a flock of {NUMBER count: min=0,max=100} boids,
and paint 'em all {CHOOSE color: black, red, blue, random colors}!

Also, every "tick", each boid does this:
{ACTIONS actions}

Notice the {ACTIONS actions} at the end. That's where your reader will get to live-edit the behavior of the system! Somewhere else, you have to define what "actions" an object in your system can do, and what parameters can be changed. Like so:

Improv.actions.move = {
    short: "Move forward...",
    editor: "Move forward by {NUMBER amount: min=0,max=50} pixels",
    act: function(boid,options){
        // code to make the boid move by [options.amount] pixels
    }
};

Here's another one:

Improv.actions.if_close = {
    short: "If close to...",
    editor: "If I'm within {NUMBER radius: min=0,max=500} pixels of "+
             "{CHOOSE target: the mouse, another boid}, then..."+
             "{ACTIONS actions}",
    act: function(boid,options){
        // code using options.radius, options.target & options.actions
    }
};

Notice {ACTIONS actions} is there again. This lets your reader make sub-actions for that action! Like my mama always said, recursion is its own reward. Finally, all that will give you something like this:

Now you can make all kinds of flocks! But while boids are cool, they aren't very useful. (actually, boids are often used in game AI, movie CGI, and swarm robotics. If I extended this demo a bit more, maybe I could create a pretty useful, designer-friendly boid "scripting" tool???)

Luckily, because Improv is independent of the kind of model you give it, both authors and readers can use Improv to live-edit all kinds of things! Such as:

Whatever it is, I'm excited to see what you can make with Improv. This tool, that makes tools, that make explorable explanations... that can make us into more active learners, more critical thinkers, better citizens of our shared world.

Download Improv.js

An Even Simpler Demo: 42 lines of code → The Stretchy Crayon Box

How To Use Improv.js: WIP Documentation

TO DO: