Scripting notes

Eiyeron • 2018-12-31*2018-12-31 10:10* •

BBS>

Voxatron>Workshop

Hey there. I'll be writing down a few things I'm discovering while taking a bite off the brand new Voxatron update. Scripting API was a long-awaited feature and I'm definitely excited to give a new spin to Vox.

Disclaimer

I'm writing this post while playing with the alpha 0.3.5b. Stuff I'll be writing can and may change over versions.

Script organization

As a script is a component like others, you can perfectly use them in an actor as well as an animation or an emitter. update and draw are called when an actor is updated or drawn.

A script has a basic encapsulation system. Local "top"[^1] variables are indeed locals to the script and globals are shared over scripts. Yeah, you read that perfectly. You can perfectly have "library" script pieces that are just there to hold your functions akin to a Pico8 code tab as long as the desired functions or variables are global.

Note that if the script has _draw and _update, they take precedence over Voxatron's routines, even if they're not placed in a room. I'm linking a cart that stores two script pieces, a few circle drawing routines and a script having _update and _draw. Feel free to download it to see how it goes. As you can see, the room is totally blank and isn't actually rendered at all.

"Library" script test

by Eiyeron

Cart #doyumogeka-0 | 2018-12-31 | Embed ▽ | License: CC4-BY-NC-SA

I don't know if there are "rules" for loading or executing or ordering the scripts pieces yet, but it looks quite promising. You can have behavior code for an actor, an advanced particle emitter to add tidbits to a creature or even take over voxatron's rules temporarily to implement some logic over it (for instance a battle engine to intrrupt your RPG players with some slimes? :D )

Colors

Colors are actually spaced over the [0-255] range sparsely. I'm linking a demo so you see them. Press up or down to change the bottom layer to see which colors are transparent. The 0-15 colors are the good old Pico-8 palette where the 16 and 32 color row looks like complementary colors. There are two nice gray gradients at 80-85 and 86-91.

The (interesting) transparent colors are at 160-168, 192-200 and 224-255.

Color palette demo

by Eiyeron

Cart #sinihojoni-0 | 2018-12-31 | Embed ▽ | License: CC4-BY-NC-SA

Properly making global/local functions

In 0.3.5 there is a scoping issue as seen there that raises when trying to use a local function through a function set to a variable.

For instance trying to make a globally accessible class named B where one of the class (or object)' members in a script like this:

B = {}
local function new()
        return {draw = B.draw}
end
function B.new()
        return new()
end
function B.draw()
        print("Called",0,0,7)
end

will not properly find the local function new for unknown yet reasons. I suggest to create the global variable as-is and wrap the rest of the code in a do ... end block. It'll properly set the upvalues scoping and will fix the issue.

Making libraries

As there are a few quirks around how Voxatron loads code, there might be the need to make a few conventions to make easily shareable code.

As mentioned in the previous point, there is a current scoping issue, so the best route would be wrapping as much code in a do/end scope, if not the whole script object.
Currently, when exporting objects or folders, the resulting cart uses as label the BBS label of the currently loaded cartridge (the object seen in the Metadata tab). That could be a fancy way to give an identity to your library
An idea for organization is having a README script only to contain your licence. You can do comment blocks by wrapping your comment in --[[ <your code> ]].
You can directly export folders. That can be quite useful to export multiples scripts easily.

Random API bits

set_draw_slice also takes an additional boolean argument to determine if you want to draw the Pico8's slice on a XY plane (flat) or XZ plane (vertically in front of the player). If it's true, it'll use XZ and will draw the top 64 rows of Pico8's buffer, else (false or nil) it'll draw on a layer like before.
From what I tested, stat seems to work here and there. Looks like the CPU and memory usage functions seem to work. I have yet to test the rest

Footnotes

[^1]: I can't find a better way or word to explain, but any kind of variable that's not already in a scope like a do/end, a function, a condition, a while loop or a repeat.