communic8

This is still alpha software and could have bugs or missing features, please use at your own risk

(that said, trying it out and reporting bugs and problems is much appreciated!)

#Communic8

Communic8 is a library to make it easy to send messages between JavaScript
running on a page and the PICO-8 webplayer.

The PICO-8 webplayer exposes a shared array to allow communication with the browser.
This library manages that shared array for you to make that communication simple.

If you're just coming at this from PICO-8 land, keep in mind you'll probably
want some familiarity with JS to make use of this.

##What can you do with it?

Lots of things! Anything you need PICO-8 to talk to an external program for,
this will help you with.

I originally made it so I could make a tool for making Tool Assisted Speedruns,
specifically for CELESTE, I wanted to be able to step through the game
frame-by-frame, forwards and backwards in order to get perfect play.

However, it's much more versatile than that.
Here are some ideas:

* Sending extra data into PICO-8 (example)
* High score boards
* Bigger effects (change the background of the webpage in response to events in the game!)
* Tools for orchestrating the play of a game (such as my TAS tool)
* Online play (someone please make a pokemon ripoff with online trading)

and probably much more I haven't even thought of!

##Quick usage example

The general idea is that PICO-8 exposes messages that it can receive
(RPC/Remote Procedure Calls), which JavaScript can call into.

For this example, we'll just set up a little function inside PICO-8 that
returns the sum of two numbers.
We can make these functions do anything we want, but this is an easy example to
see stuff actually happening.

We define an RPC and start communic8 as follows:
``lua
functions = {}
-- define a function with id 0 that JavaScript can call into
functions[0] = {
-- define what datatypes this function can take
input={
arg_types.byte,
arg_types.byte
},
-- define what datatypes this function returns
output={
arg_types.byte
},
-- how the function is actually executed
execute=function(args)
return {args[1] + args[2]}
end
}

update_communic8 = init_communic8(functions)
function _update()
update_communic8()
end
`

In JavaScript, we need to define the same RPC so it knows how to talk to PICO-8.
We then start communic8 and send the message over, wait for the response, and then print it out.

`javascript
var add = RPC({
id: 0, // a unique byte to identify the RPC
input: [
ArgTypes.Byte,
ArgTypes.Byte
],
output: [
ArgTypes.Byte
]
});

var bridge = connect();
bridge.send(add(2, 3)).then((function(result) {
console.log("2 + 3 =", result[0]); // => "2 + 3 = 5"
});
`

If you just want to jump into some working examples, look in the examples/
folder for some functional examples.

##Getting it

If you're npm-inclined, you know the drill:

`
npm install --save communic8
`

but if you'd rather just have a file you can include in a