Featured

Javascript native wrappers in V8 — Part I

While embedding v8, exposing native objects in Javascript is mostly unavoidable. As easy as it might sound the process involves a very specific set of steps as well as certain design decisions. From Javascript standpoint, there will no difference between a pure Javascript object and a wrapped one. For example, you must be able to extend a native object prototype with a plain Javascript object or vice versa.

The link between Javascript and native world is bidirectional. A native wrappable object, should refer to a single Javascript object (not necessarily, but it will save a lot of headaches at a later stage with garbage collection). This is done by keeping a reciprocal reference between a v8::Persisten<v8::Object> and a native object, or bridging between the two.

It is important to note that now, two inter-related objects exist, a Javascript wrapper and a native wrappable. Both have different lifecycles, and we must bind them in the right way.

Design decisions

Native wrappable objects will extends a base class object: Wrappable. Its purpose is to keep track of the Javascript object wrapping a native object (hence its name) and also does the heavy lifting to associate a native object with a Javascript object, like invoking the constructor, setting Javascript object’s native pointers, etc.

Wrappable will rely on a WrapperTypeInfo to configure itself. Each potentially wrappable exposed in Javascript will define one such struct. For example, for an actual Event object I define:

const WrapperTypeInfo V8Event::wrapperTypeInfo = {
        V8Event::InterfaceTemplate,        // configuration function
        "Event",                           // js object context
        nullptr                            // inherit from
};

For code simplicity, I will define two cpp files for each object I’d like wrapped and exposed in Javascript. For the Event object sample, a file Event.cpp will keep the delegated methods invoked from javascript. Don’t forgetEvent class extends Wrappable so inherits the possibility to generate the Javascript wrapper on demand. The other file, V8Event.cpp contains all javascript related stuff, like the constructor function, the list of accessorsfunctions, etc.

Another design decision I make is about object extension. Any Javascript object extending another object, will reflect in its native wrappable extending the another wrappable. Basically, makes sense an object extending another in Javascript, necessarily means c++ class extending another one.

Configuring wrapper objects

Depending on whether we expect this to be part of the global context object, we will create either a v8::FunctionTemplate or a regular v8::Function object.

In this article, I will be creating an Event object in Javascript, which is actually delegating all its functionality to a Native c++ wrappable instance.

FunctionTemplate structure

As we know, a javascript function, is a first class object. It can be called, can be called as a constructor (instanced), which will create a prototype chain if needed, and the function object itself can hold functions and variables. All this translates directly into native code, where a v8::FunctionTemplate object (which we will name interface_template from now on), exposes two methods returning a Local:

// prototype function template
Local<ObjectTemplate> prototype_t= interface_t->PrototypeTemplate();
// instance function template
Local<ObjectTemplate> instance_t = interface_t->InstanceTemplate();

So, for each wrappable object, we will manage 3 different places to add native bindings code to:

  • Prototype template will be used, of course, to define accessors and function on the prototype.
  • Instance template will be used to add accessors or functions to an instance resulting from calling the constructor function.
  • Interface template will be used to add accessors or functions to the constructor function itself. These won’t be accessible from any instance or object prototype though.

Exposing a Constructor function in Javascript

The constructor function is the entry point to instantiate Javascript objects and bind them with native wrappable objects.

The first thing would be to make our instantiation function available in Javascript. This is done by exposing our interface_template in the global context object (or any other object). Something like:

global_template_object->Set(
        v8::String::NewFromUtf8(isolate_, "Event"),
        interface_template->GetFunction());

When in Javascript the Event object is created by calling new Event(), the wrapper will invoke our supplied construction callback. This constructor callback is defined as:

// c++ function invoked when new Event() is called in js.
// see "Javascript-native object relationship" 
interface_template->SetCallHandler(V8Event::constructorCallback);
// constructor length, e.g. number of parameters
interface_template->SetLength(1);

This CallHandler function, is an special native constructor delegate. It is responsible for associating a Javascript with its native wrappable when invoked from javascript as new Event(), but it also must handle the situation when an existing native object, just needs be wrapped and be available in javascript. We’ll see how to do this later in the article.

The CallHandler, has a signature of a regular native function callback:

void constructorCallback(const FunctionCallbackInfo<Value> &ci);

Adding accessors

Accessors will act as properties’ getter and setter function callbacks. Normally I will add accessors in the prototype or instance templates. Or both. But they can be added as well to the interface template. Once in Javascript, there will be no difference with a regular object variable, except for the fact that behind the scenes, a native object is accessed, and a native value is wrapped as a Javascript type.

For accessors in prototypes or instances, we need to add a regular v8::FunctionTemplate representing the getter or setter to the corresponding v8::ObjectTemplate.

Adding accessor to the interface template is a bit different, since its type is v8::FunctionTemplate, and not v8::ObjectTemplate.

Doing this is mostly trivial:

void native_getter(const FunctionCallbackInfo<Value> &info) {
    ...
}

void native_setter(const FunctionCallbackInfo<Value> &info) {
    ...
}

// getters don't need parameters, we pass 0.
Local<FunctionTemplate> getter = v8::FunctionTemplate::New(
        isolate, native_getter, Local<Value>(), Local<Value>(), 0 );

// setter need a parameter, so we pass 1.
Local<FunctionTemplate> setter = v8::FunctionTemplate::New(
        isolate, native_getter, Local<Value>(), Local<Value>(), 1);

// these getter/setter function callbacks don't need a prototype.
getter->RemovePrototype();
setter->RemovePrototype();

// create an accessor name
local<String> name = String::NewFromUtf8( isolate, "prop" );

// binding:
instance_or_template->SetAccessorProperty(
        name, 
        getter, setter,
        attribute         // see v8::PropertyAttribute
);

Now, whenever we call from Javascript ev.prop, the native_getter function is invoked. Our wrappable code starts to make sense now.

We must monotonically perform the same process for each accessor we’d like to have in our Javascript wrapper objects.

Adding functions

Another functionality wrapper objects need is functions. As in the case of accessors, Javascript function callbacks must be defined. Simply enough:

void callback(const FunctionCallbackInfo<Value> &info) {
    ...
}

v8::Local<v8::FunctionTemplate> function_template =
        v8::FunctionTemplate::New(
               isolate, 
               callback, 
               v8::Local<v8::Value>(),
               v8::Local<v8::Value>(), 
               numberOfParameters );

// again, prototype not needed for this callback function
function_template->RemovePrototype();

instance_or_template->Set(
    method.MethodName(isolate), 
    function_template,
    attribute           // see v8::PropertyAttribute    
);

Again, repeat this process for each function we want to be available in our Javascript wrapper.

Javascript-native object relationship — Javascript Instantiation

When code like this is executed in Javascript

 new Event();

the registered constructor callback is invoked. It will also add all defined accessor and function bindings, create the prototype chain, etc. As a native function callback, the signature is:

void constructorCallback(const FunctionCallbackInfo<Value> &ci)

It has three main responsibilities:

  1. abort object creation if this is not a valid constructor. For example, TouchList is not instance-able by constructor, so it is safe to throw an exception here. A call of the form will do the trick.
isolate_->ThrowException( v8::Exception::Error( v8::String ... 

// don't forget to return from constructorCallback after throwing...
return;

2. Generate native wrappable instance and associate it with the Javascript object:

// create a wrappable
Event* event = new Event();

// we associate a native Event object, with constructorCallback's
// holder. Holder() points to the object being constructed in 
// javascript.
v8::Local<v8::Object> wrapper = ci.Holder();

// Event instance holds a v8::Persistent<v8::Object> reference
event->wrapper_.Reset(isolate, wrapper);

// Manage gc.
//
// e.g:
//    event->wrapper_.SetWrapperClassId( ...
//    event->wrapper_.SetWeak( ...
// or
//    event->wrapper_.ClearWeak();

3. Bridge the Javascript object with the native wrappable

wrapper->SetAlignedPointerInInternalFields(0, event);

After this code, a Javascript object has a pointer to the wrappable c++ object. And the wrapple c++, has set a v8::Persistent handle to the same Javascript object.

Accessor and Function callbacks

For the three of accessor getter, setter and function callbacks, we must specify a function of type v8::FunctionCallback, that is

void fnName(const FunctionCallbackInfo<Value> &info);

How the Javascript object accesses its native wrappable object is as follows:

void fnName(const FunctionCallbackInfo<Value> &info) {
    Local<Object> holder = info.Holder();
    Event* event = reinterpret_cast<Event*>(
        object->GetAlignedPointerFromInternalField(0));
    info->GetReturnValue().Set( event->name );
}

The key here is where to obtain the native pointer to the wrappable object. And that will always be the Holder object on every FunctionCallback.

Javascript-native object relationship — Native Instantiation

Sometimes, we want to expose in Javascript a native wrappable object w/o it being created from Javascript. For example, a pointer data generated in native needs to make its way through to Javascript.

Event* ev = new Event("load"); 
// set wrappable properties
ev->target = this;
ev->currentTarget = this;
// create a Javascript object to reference to this ev
// native instance.

For this to happen, we need to manually create a Javascript object of the needed type. We have the interface template so seems like a trivial operation, just (deprecated: call it as constructornew instance the interface template function.

We would be mostly done, except for the fact that this code will invoke the constructorCallback previously defined. Which will create a new Event instance. Our constructorCallback must therefore be aware of the fact that an existing native object is being wrapped instead. Other than that, the code will be the same for the constructorCallback.

// Signal constructorCallback to wrap an existing object, 
// instead of creating a new one. RAII on isolate's private data.
Config::ConstructorMode p = Config::Status::CurrentConstructorMode;    Config::SetCurrentConstructorMode(Config::kWrapExistingObject);
v8::Local<v8::Object> wrapper = interface_template->
        GetFunction()->
        NewInstance( 
           creation_context->CreationContext() 
        ).ToLocalChecked();

// do wrapper association just as in the javascript instantiation
// example.
// restore constructor mode to previous one.
Config::SetCurrentConstructorMode(p);

Needless to say , I also trivially check for an already existing Javascript wrapper for the native object.

Prototype Inheritance

Inheriting a prototype for a wrappable object can only happen from a native prototype. Don’t worry though, you will be able to extend a wrapper object from Javascript.

The inheritance process boils down just to one native call, and must happen at constructor function definition time. This code will extend the prototype chain of our wrapper object:

// function_template->Inherit( v8::Local<v8::FunctionTemplate> );
//
// this function template is the previously defined 
// interface_template
//
interface_template->Inherit(parent_interface_template);

Object naming

By default, wrappable objects will identify themselves in chrome devtools console as the infamous: {} that is, no name. To properly have our wrappables named in dev-tools, we’d need to do a couple things:

  1. set the constructor function class name.
interface_template->SetClassName( v8::Local<v8::String> );

This will properly name our wrapper exposed constructor function. Unfortunately, this won’t be sufficient, since our wrapper’s prototype object still won’t show the expected naming. To fix this, a trickier approach must be taken:

2. name our prototype object:

prototype_template->Set(
        v8::Symbol::GetToStringTag(isolate),
        v8::Local<v8::String>,  // desired string representation
        v8::PropertyAttribute); // e.g.: v8::ReadOnly | v8::DontEnum

Putting it all together

I have created this repository where all things covered in this article have been placed. It is a compilable and runnable version of this post.

Conclusion

There is still some other stuff that native wrappable objects can do. Indexed properties, which would accept indexed access on them like an array or for the DOM TouchList object. Interceptors, making an object callablereceiverssignaturesinheritance… v8’s bestiary is fairly interesting and each of the creatures deserve one or more posts to describe them.

At first glance it is not easy to create a Javascript wrapper. Too many steps, for something conceptually simple, specially if we compare it with defining a plain Javascript object. That’s Javascript’s magic. It abstracts away all the dirty details from the developer, like GC, instantiation, wiring, etc. This article might be also useful to realise how complex a browser can just be. We just scratched the surface and shaw how to wire the simplest native object possible.

I’d like to make an explicit disclaimer here. All credit of this article must go to the V8 and Chromium project developers. Being able to scavenge through the whole browser source code has been an invaluable resource to figure out stuff, and to learn very solid foundations on v8 development. On my side I just made the effort of collecting low hanging fruit.

Featured

V8 inspector from an embedder standpoint

It’s been recently that the old V8 debugger API has been removed from V8’s source code in favor of the more modern Inspector API.

This Inspector API is great, and allows me to debug my embedded Android V8 code using Chrome dev tools directly from the browser, or by using an standalone version of them. Profiling, memory dumps, source maps, breakpoints, all works like a charm (except minor bugs here and there mainly related to chrome version though). Unfortunately, there’s not much documentation on this Inspector integration from the embedder point of view.

Inspector integration process

The first to note about the Inspector is that inspection is per Isolate. One single Inspector object instance will be enough to debug all your javascript Context s. The Isolate is thread dependent, and as such you must keep your isolate in scope Isolate::Scope when necessary. That said, the elements that will conform your inspection code are very simple:

InspectorClient

This object will be used to select what Context we are currently debugging, but more importantly, it will handle runMessageLoopOnPause and quitMessageLoopOnPause methods. These two methods are called by V8 debugging internals when you are breaking into js code from Dev Tools. While runMessageLoopOnPause is being called, you must synchronously consume all front end (Dev Tools) debugging messages. If not, you will not get all context information of the code you are debugging. Once V8 knows it has no more inspector messages pending, it will call quitMessageLoopOnPause automatically.

The InspectorClient could do the debugging initialisation process like this:

// create a v8 inspector client: 
// InspectorClientImpl : public v8_inspector::V8InspectorClient
v8_inspector::InspectorClient = new InspectorClientImpl();

// create a v8 inspector instance.
v8_inspector::V8Inspector inspector_ = 
    v8_inspector::V8Inspector.create( isolate, inspectorClient );

// create a v8 channel. 
// ChannelImpl : public v8_inspector::V8Inspector::Channel
v8_inspector::V8Inspector::Channel channel_ = new ChannelImpl();
v8_inspector::StringView view( ... )

// Create a debugging session by connecting the V8Inspector
// instance to the channel
v8_inspector::V8InspectorSession session_ = 
    inspector_.connect( 
        1, 
        channel, 
        view);
v8_inspector::StringView ctx_name( /*ctx_name*/ )

// make sure you register Context objects in the V8Inspector.
// ctx_name will be shown in CDT/console. Call this for each context 
// your app creates. Normally just one btw.
inspector_->contextCreated(
    v8_inspector::V8ContextInfo(
        context, 
        1, 
        ctx_name);

That’s pretty much it. After this, you’ll have a valid debugging session. How do you, as a dev, interact with each of these elements: V8InspectorClientV8InspectorV8Inspector::ChannelV8InspectorSession ? Well, to answer this question, first we call all this code happening in our V8-enabled app the debugging backend, which implicitly means we should have a debugging front-end.

V8InspectorSession

Ideally, the debugging front-end would be Chrome Dev Tools. CDT opens a WebSocket to communicate with the debugging back-end. You can make this happen in Chrome with something like this:

chrome-devtools://devtools/bundled/inspector.html?experiments=true&v8only=true&ws=127.0.0.1:20000/backend

This causes chrome to open a dev tools only tab, w/o most DOM specific stuff. In my case, the 20000 is a forwarded port from my android app to a local port(adb forward tcp:20000 tcp:20000) and /backend in the url is a mount point on the backend WebSocket listener. All front end inspector messages will be received on the backend websocket listening code, and must be forwarded to the debug session:

// msg is a std::string with whatever front sent to back.
// normally a json object with sequence and payload.
v8::internal::Vector<const char> v(msg.c_str(), msg.length());
// inspector session requires a v8_inspector::StringView
v8_inspector::StringView message_view(
    reinterpret_cast<const uint8_t *>(v.start()), v.length());
// let the magic happen:
session_->dispatchProtocolMessage( message_view );

The V8InspectorSession object is full of inspection love. I recommend you having a look at v8-inspector.h header file. While all interaction happens from CDT front end, you’ll recognise a lot of functionality there like breakProgram, pause or resume methods.

V8Inspector::Channel

All inspector protocol handling happens automagically. You don’t have to worry about front end message id sequences, or their responses. The only missing part is forward inspector session message results from backend to front end. Responses happen in the custom v8_inspector::V8Inspector::Channel object implementation. Both methods:

sendProtocolResponse(
    int callId, 
    const v8_inspector::StringView& msg);

void sendProtocolNotification(
    const v8_inspector::StringView& msg);

will handle inspector protocol responses from commands received from inspection front end. Just convert msg from StringView to std::string (or whatever your code requires) and send to front end

Diagram

This is a small diagram of how things work:

Result

At the end of the process, you’ll get a full browser-enabled remote v8 debugging session. Here’s an screenshot of a sample app. All objects but console are custom bound native objects. In this sample screenshot, the host application OS is Android.

Also note, this inspector-over-devtools integration also works on the Android emulator. In my Mac, I have an android emulator, running my app with embedded v8 and connected to dev tools on chrome to debug javascript… what a time to be alive !

Myriahedral projections

It’s recently been the 10th anniversary of this paper. It is such a fantastic example of data visualisation that have always feel the need of making an implementation of it. Finally I gave it a try with more or less successful results.

Unfolding a Myriahedron. Tetrahedron, 4096 faces.

How I reached this point, was a bit of a rollercoaster of failure and success, but intuition always works. Unfolding the myriahedron is composed of three different yet related steps, each one a problem in itself:

  • Create the myriahedron.
  • Calculate a maximum spanning tree (MST).
  • Unfold the geometry based on the spanning tree.

Myriahedron

Myriahedron, refers to a ten-thousand-face polyhedron. To start with, I selected a regular tetrahedron and then recursively subdivide its edges. During subdivision, process I chose to generate new edges for 4 new triangles, though 9 could be generated as well.

Recursion level 6 leads a 4096 faces polyhedron. We just need the edges for this subdivision process. At the same time we recursively subdivide the edges, we generate a numerical parameter for each of them, which gets modified on edge split, or edge generation, during the recursion process. This allows us to label edges as folds or cuts. After subdivission process, we get a Myriahedron with indexed geometry: 2050 vertices, 4096 faces, 6144 edges.

This process does not offer any remarkably interesting visualisation result, just the edges of a recursively subdivided tetrahedron. If for instance during this process we decided not no include the edges for the central triangle (remember we subdivided each triangle in four new ones), we’d get a Sierpinsky tetrahedron:

Sierpinsky tetrahedron
Normalized sierpinsky tetrahedron

Maximum Spanning Tree (MST)

This step is a bit tricky, but the results pay off by themselves.

During the recursive subdivision, we ended up with a graph composed of vertices, and undirected links between a pair of points (Edges). We need to generate another graph, which instead of connecting vertices, it connects myriahedron faces. I basically use a dual structure here which keeps track of the original Edge (connecting vertices) with its new information (what faces this edge is shared by).

I apply Prim/Kurskal algorithm to this faces-connecting graph to obtain a maximum spanning tree. These nodes have the same weights as the Vertices set. In my case I did the most naive Prim’s implementation, with a full search per iteration instead of using a priority queue (more on my laziness on future posts). This subgraph will be the set of folds, over the final geometry. One side note: during our recursive subdivision process, we set edge weights to increment when new edges are created. We expect higher values to be a fold in geometry, and lower values to be a cut, so I needed to negate the weight to obtain a Maximum instead of a minimum spanning tree.

Another MST needs to be calculated, for the geometry cuts. It turns out, we don’t need to calculate another MST. Since we know, for each face-connecting edge, what the original vertex-connecting edge it was created from, we can just substract from the set of all vertex-connecting edges all the faces-connecting edges.

The MST offers outstanding visuals by itself.

Recursively subdivided tetrahedron. Folds (magenta), Cuts (cyan)
Cuts/Folds over normalized recursive subdivided tetrahedron (4096 faces)

In these pictures we can observe a few things:

  • Each triangle in the geometry, has at least one cut and one fold.
  • Folds (magenta) are edges connecting faces. Folds have a direct relationship with cuts (cyan). The unfolding edge will be an edge on the triangle which is not a cut.

Unfolding the geometry

Despite being quite intuitive, unfolding the geometry took me the most time to figure out. First, I needed to re-triangulate the geometry. From list of edges to polygons. Each polygon has its own vertices (non indexed geometry).

Though not necessary. I decided to generate a connecting graph for every fold, just to get strips of connecting faces.

The only needed structure for unfolding, is the folds MST. This is a recursive process starting by the terminal nodes MST nodes. Each node connects two faces. We calculate the angle between these two faces (cross product over their normals). Then rotate accordingly all adjacent faces’ geometry. I tested rotations using Rodrigues and Quaternions to obviously obtain the same results. I ended up using quaternions since the maths involved where a bit less allocative.

After repeating this process for every MST node (connecting faces), we’d get the following results:

Fully unfolded geometry
Tetrahedron MST on sphere. Folds (magenta) cuts (cyan)
slightly unfolded geometry

See how cuts (cyan on the left image) will be followed by the unfolding geometry process (result on the right). See how Europe and Africa are unfolded following exactly the cuts path.

Tetrahedron MST on sphere. Geometry + folds view.

This is a capture of the un/folding process. Beautiful imo.

This exercise just covers recursive subdivision of Platonic solids and graticules. Unfortunately, no maps of earth’s coastline, or land/water like in the original paper.

Unfolded Platonic solid results

Unfolded Tetrahedron

Tetrahedron 1024 faces

Unfolded Cube

Cube 3072 faces
Octahedron 2048 faces
Icosahedron 5120 faces

Graticules

Gore’s Map (Cylindrical projection)

Conical projection

Azimutal projection

Azimutal two hemispheres

Polyconical

Bonus track

While trying to make sense of the paper, it was interesting to actually visualise some intermediate steps and structures.

Making sense of the MST nodes hierarchy

MST nodes hierarchy diagram.
MST nodes hierarchy diagram. 2. Close up

Visualising whether unfolding normals where correct

Some blatant errors, yet beautiful visualisations

Failed MST hierarchy view
Coronavirus ?? #facepalm

Failed unfolding process (wrong faces orientations)
Failed unfolding process (wrong faces orientations)

I am still fixing minor lots of stuff on the code. I pushed it as-is here.

New v8 compiled version

Just compiled and added to the repo of v8 versions 8.4.371.7.

This version consistently crashed for arm, arm64 and x86 when the Isolate initialization process tried to set the logger up. I have disabled Isolate log capabilities, which is fine on my side, but could not be your case.

As usual, I have added library files and compilation header files for easy embedding.

Go get them out while fresh: https://github.com/hyperandroid/CompiledV8

Building a Javascript game Day 9

A lot of time has passed since 8th day of work in the game. That subtle need of providing is probably the culprit…

I have added a in-game feature: rainbow bubble. This bubble matches against any other bubble type. Can’t be selected on its own or popped using the ray. It is created by popping a large array of bubbles. 12 at the moment, but will surely adjust it. The generation of this bubble is renderer in a custom shader which, based on time, draws more and thicker small particles in a rectangle. This is the effect of adding up to 60 particles in a second:

I have also modified the game model. Bubble Locks are just one of the condition types by which you can beat a game. Still need to add timed games, explode-N-bubbles-of-a-type and leave-as-much-as-N-bubble-in-game logic types. But after the model refactor, this should be affordable to do.

The most complicated type-of-game to code was the previously existing Locks mode. Each lock is attached to a bubble position, and to the bubbles model, etc. which needed of some wiring into the Condition interface.

I will leave game features as they already are, whitout adding any more. I plan to release the game on day 12, which overall would mean 2 working weeks of semi dedicated time. After that, buy some artwork and sounds before making it an open release.

Building a Javascript game Day 5,6,7,8

These days have been invested on finishing the game model. It’s been an scattered working routine. Instead of taking this side-project too seriously, I just developed when I really felt I could be productive which has turned to be best idea ever since lots of stuff has been accomplished.

Score, bonus notification, one power up, bubble locks, level cycle, level stats, end game menu… all these have been implemented. I still need to work on sound, visuals and tuning levels difficulty up. I was supposed to finish the game by day 9, and surprisingly, I will have a functional game by then. I think I have added a lot of detail to the game with everything subject to have a little animation.

Locks animation
Power up
Big pop + power up feed

I feel trapped inside the Pareto rule. The little pending details the game need are taking like forever to finish, but the game mechanics are just there.

Building a Javascript game Day 4

4 days in a row working on this little game. Everything starts to pay off, and at the same time, I am already feeling that recurrent thinking of giving up. After all, I doubt I will be able to finish the game in time (my own imposed schedule), and even worse, I doubt I could make any profit from it as well. Lets be honest. My hard-disk is populated by dozens of zombie corpses of unfinished projects. Even some finished ones are left to rot there on their own so this one would not be an exception either.

During day 4 I worked on the game’s logic. Hooking model with the renderer turned to be a pain, not because the game is complicated, but because I tend to be goofy when doing things. For example this code:

for (let j = c; j < this.columns - 1; j++) {
	this.elements[row][c] = this.elements[row][c + 1];
	this.elements[row][c].column = j;
}

if supposed to fold the bubble matrix when removing a whole column. I banged my head for like an hour trying the find a fix for a bug everywhere else but here. Where every c in the for body, must actually be j instead. And I did two like this one so could have finished way before than I did.

Other than that, the model is in place. Bubble visual nodes react to input and game model’s events. I also polished a few details on the rendering pipeline.

The result so far, is this one:

Day 5 will be to finish the model, and add some power ups. Or maybe will be an spare day for playing The Division 2. 50-50 chance either side.

Building a Javascript game Day 3

Day 3, has been for general refactor. Adding a game model which drives all in-game interactions/actions and on-demand enabling of post-effects (explosion).

I am quite happy with the result, but still a couple days away from being able to play the game. I have squandered almost an hour figuring out a problem where the explosion post effect flipped the rendered image vertically. I spent a lot of time looking on the shaders projection matrices, just to realise the problem was in the shader itself, sampling bottom-up #facepalm.

The actions subsystem has shown to be not as robust as I expected. E.g. the use case for actions pre-creating, and reusing them over time was not thought ahead of time. Also the use case where a Node is removed from a container w/o disposing it was missing.

I still need to check on a couple shaders blending mode. I think I could improve them.

What went right:

  • Adding a model substantially improves code readability and usability.
  • Shaders model is pretty robust. It can seamlessly interact with the existing WebGL rendering context.
  • Easy hook of bubble interactions. Explosion (triggered with more than 8 popped bubbles).
  • Bubble souls, have been easily added. One every 4 popped bubbles. Its color matches the bubble selection, and its intensity, the amount of bubbles.

Day 4 plans: work towards actually playing a game.

Building a Javascript game Day 2

Sundays are for rest, so this day of work has been an easy one. Some code refactors, like changing the default blending mode, but most importantly I added an important feature I wanted to have in the game.

It is expected, that when a group of bubbles pop, depending on their number, some “soul lines” would be added. These are the white lines in the gif.

These lines will fed up a power-up. Pop bubbles are the energy necessary to power one special effect that would randomly pop a predefined amount of bubbles. These lines are governed by an specific shader. They can have different color, size and intensity, and travel by a random cubic bezier curve. The curve describes the whole traverse path, and the segment is calculated by making use of a fancy easing scheme.

...
this.easingStart = EasingEaseIn({exponent: 1.5});
this.easingEnd = EasingEaseOut({exponent: 1.5});
...

// nt stands for normalized time.
// If the soul animation takes 2000 ms, nt=.5 means we 
// are at half the animation time.
// Since I use a bezier curve, this does not correlate 
// to be the half point in the curve.

// t0 and t1 will be two solved values over the bezier curve
let t0 = this.easingStart(nt); 
const t1 = this.easingEnd(nt);

...

// calculate a cubic segment ranging from t0..t1 on 
// the bezier curve
for(let i = 0; i<Segments; i++) {

	bezier.getValueAt(t0, p0);
	bezier.getValueAt(t0+.001, p1);

	// normal vector as point p0 in the curve
	let nx = p1.y - p0.y;
	let ny = p1.x - p0.x;

        // normalized vector
	const l = Math.sqrt(nx*nx + ny*ny);
	nx/=l;
	ny/=l;

	...

        // generate shader points:
        //   p0 + nx * lineWidth
        //   p0 - nx * lineWidth

	let yy0 = p0.y + p0y;
        let yy1 = p0.y - p0y;

        // avoid twisted lines
	if (yy0>yy1) {
	        [yy0, yy1] = [yy1, yy0];
	}

	this.lineData[ptr++] = p0.x + p0x;
	this.lineData[ptr++] = yy0;
	this.lineData[ptr++] = tint;
	this.lineData[ptr++] = 1;
	this.lineData[ptr++] = p0.x - p0x;
	this.lineData[ptr++] = yy1;
	this.lineData[ptr++] = tint;
	this.lineData[ptr++] = -1;
        
        ...
}

The shader fragment is as simple as

vec4 f = vec4(uIntensity*smoothstep( .9, .0, abs(vY)));  // vY -1 or 1
gl_FragColor = f*uColor*tint;

This line shader does not use tessellation. It does not benefit from any charming line join/cap process either, but i just want it to be a simple flowing line. It is current state, it does not batch lines. I should duplicate some shader data for that, which I will definitely do if I have the time or should I need to start optimising code.

In day 3 I will start coding in-game model + logic. Instead of an animation, I’d start to resemble more a whole game.

If you think you could contribute some graphics, just lemme know 😀

Comments are also welcome.

Building a Javascript game Day 1

Today has been mostly a setting up day. It is surprising how code written several years ago is still on shape. The game engine allowed me smoothly add a few shaders for the game. Underwater god rays, an explosion that will be triggered when several bubbles are pop at the same time and some rays that will throw from a power-up (think of some well known match-3 game’s chocolate ball).

I had some trouble enabling background rendering surfaces backed by a framebuffer where the rendering appeared to just fill 1/4th of the screen. I forgot my sprites by default have translation anchor at (.5, .5), so that was an easy fix.

It took me around an hour to enable post-render effects on top of the background surface. Not by the renderer capabilities, but because I had to plug a new pre/post Scene render hook to properly draw a Node2D into the offscreen instead of the main screen.

This is the result so far. Forgive my art capabilities that are close to 0 (from the negative size).

Plans for day 2 include some fancy lines-over-a-cuve. These will be the indication of a popping group of bubbles. Popping bubbles will also leave a trail of smaller bubbles moving up. I will probably won’t address playability until day 3.

All this renders beautifully in my android tablet, running inside my v8 wrapper:

Stay tuned.

Building a Javascript game from scratch.

For the next 7 to 10 days I will be building a game from scratch. It will be a one-finger time-waster simple-puzzle type of game. Proudly written in Javascript, deployed on android and FB messenger, and running on my own wrapper+renderer tech. Will document each day of work, with a little list of TO-DOs, expected work time, and conclusions at the of the day. Excited to start on this. Stay tuned.

Generic Javascript to Java bridge

When embedding v8, one of the pain points is how to call Java/Kotlin code from Javascript. It is not just a matter of setting a FunctionCallbackInfo<Value>, but also of dealing with JNI. While there are really impressive exercises for automating JNI code calls, these are only valid suitable when you know your JNI needs upfront, e.g. method signatures, calling objects/classes, etc. More concretely, when you can compile your own v8 code. In my case, all my v8 is primarily embedded in Android, and I share around an AAR file with all needed v8 dependencies. How each project depending on this AAR exposes its own Javascript bindings, is as simple as annotating Java code with @Bridge.

This post depicts how I built a dynamic bridge between Java and v8, and how methods annotated as @Bridge are automatically exposed in javascript.

For example:

// Java
class Test {
  @Bridge(returnsJSON = true)
  String method2() {
    return "{\"result\":0}";
  }

  String method1(int a, int[] i32, double[] f64) {
    return "";
  }
}

// Javascript
> Test.method2();
> { result: 0 }
> Test.method1(1, [1,2,3], new Float64Array([.1, .2, .3]));
> ""

// Javascript call with wrong Java parameter signature:
> Test.method2(1,2);
> null
> Test.method1(32);
> null

As nice as it might sound, it comes with a myriad of limitations:

  • Method disambiguation. In Java we can have method overloading, which does not exist in Javascript.
  • Javascript to Java and vice versa type conversion. Only number, string, boolean, null, typed arrays and array, or object of these types can be safely converted between environments. Arrays and Objects are defined recursively.
  • Java method signatures. In Javascript, you can call a function with an arbitrary number of parameters and types. Exposed Java functions are no exception. Only Javascript calls that match Java method signature (based on previous point types’ conversion) will be executed. By now, this is a reflection based method invocation. Slow, but convenient.
  • Java method return types. While a Java method can virtually return anything, I constrained return types to String. Optionally, this string can be JSON parsed before setting the Javascript call return type. If any error has been caught, null will be returned instead.
  • Every Javascript call will pass through a unique JNI entry point.
  • Asynchronous calls. These can not be directly modelled with this approach. But they work under other @Bridge annotation options.
  • It tends to be slow: reflection in Java + JNI bridge. Read on my APT articles on how to remove reflection calls.

Are all these limitations worth it ? it totally is for non critical code paths. In my case I use it for things like calling the speech synthesiser, open share dialogs, create gl textures… But definitely not for calling into every OpenGL function per frame for example.

Implementation details in an upcoming article version 2.