Patching Guide: Development with VVVV.js

This guide will give an introduction to the key principles of working with VVVV.js, and will make you comfortable with the patch editor. After reading this guide, you will understand how the VVVV.js runtime parts and the patch editor work together, and basically know your way around the patch editor. You don't need anything but a Chrome web browser to work this guide.

Key principles

The basic thing to understand about VVVV.js is how developing and running VVVV.js plays together. There are these 3 compononents:

• the VVVV.js Patch, a .v4p file in XML format, defining all the nodes and connections which build the logic
• the Website, which acts as host for a patch, loads it and runs it
• the Patch Editor, which you can launch from the website, to modify the running VVVV.js patch

Key to understanding VVVV.js: it starts with a VVVV.js patch (here: example11.v4p) running in a website. The patch editor can be launched on top of it.

What differs VVVV.js from similar projects is the fact that it does not start with launching an empty editor, which subsequently creates patches. Instead, it starts with a website running an (initially empty) patch, where you can plug the patch editor in. So, to emphasize this:

A VVVV.js patch can not run without a containing website. Also, the patch editor can not exist without a patch, it can only be launched on top of an already running patch

This is essential, because this way, there is no difference between development mode and runtime mode. Your changes to the patch will be reflected immediatly in the final environment — no exporting, no compiling, no refreshing.

Warm-up

Let's forget about how to include and load VVVV.js for a moment, and just get some idea of how patching itself works. The best place to start is the VVVV.js Lab, where we can launch the editor on any of the posted patches, and play around with them. So let's head to http://lab.vvvvjs.com/show.php?id=a15e18297f17a8dcb8ff94c2199e68c4 and click the Edit Patch button. This should open the patch editor in a new window. If not, check your browser's popup blocker.

Now you can make changes to the patch, and see the results on the website immediatly. Have a look at the VVVV.js Cheat Sheet for the basic patching operations. The figure below gives some inspiration about what you can do with the patch.

1

Right-Click the IOBox and change
the number of arcs
You can enter a value or hover over the input field and use the mouse wheel to modulate

2

Right-Click the Width pin to change
the stroke width
You can enter a value or hover over the input field and use the mouse wheel to modulate

3

Right-Click the Color pin to change
the fill color
Hover over the color field, and use
Mouse Wheel to modulate the hue
Shift+Mouse Wheel to modulate the lightness
Alt+Mouse Wheel to modulate saturation
Alt+Shift+Mouse Wheel to modulate alpha

4

Right-Click the Input 2 pin to change
length of the arcs
You can enter a value or hover over the input field and use the mouse wheel to modulate

Try to modify some values in this patch from the VVVV.js Lab.

Using the #edit command

Of course, in a real-life scenario you usually don't want any "Edit Patch" and "Save Patch" buttons on your website. But that's ok, since we actually don't need them. Instead we are providing a special command to the URL in the address bar, so we can launch the editor without the need of any controls on the website. Open http://www.vvvvjs.com/vvvv_js/template/ and once it is loaded, view the page's source code (e.g. Right-Click -> View Source). You will find the line

This line tells you that the file template_patch.v4p has been loaded and is running. We are going to attach a patch editor to it by adding #edit/template_patch.v4p to the URL in the address bar, like so:

Adding #edit/[patch file name] to the URL in the address bar will launch the editor.

The patch editor should open in a new window. Again, check your popup settings for the page if it does not work. Make this simple rotating quad more interesting by adjusting the patch like this:

1

Double-Click anywhere in the patch to
create an IOBox (Value Advanced)
Right-Click the IOBox to set its value to e.g. 31

2

Create a CircularSpread node and a Translate (Transform) node.
This CircularSpread node will create a spread (~array) of 31 X and Y values, which form a circle. Going through the Translate node, this will result in 31 quads, arranged in a circle.

3

Draw connetions by left-clicking the Output Pins and Input Pins you want to connect
Only pins of matching type can be connected. VVVV.js will highlight the pins that match.

4

Create the rest of the nodes (HSV (Color Join) and LinearSpread) and connect them.
This HSV (Color Join) creates a series of 31 color shades, which will be applied to the 31 quads.

Double-Click anywhere in the patch to create new nodes. Left-Click pins to draw connetions.

Adding subpatch nodes

Subpatch nodes will not show up in the list of nodes, as VVVV.js initially has no idea about any available subpatches. You have to enter the complete relative filename of the subpatch and hit enter. Let's say the patch you are working on is /patches/main.v4p, you can load the subpatch /patches/sub/subpatch.v4p like this:

1. Double-Click anywhere in the patch
2. enter "sub/subpatch.v4p", including the .v4p extension
3. hit Enter

To add the subpatch /patches/other_subpatch.v4p (which is in the same directory as main.v4p), you have to enter "./other_subpatch.v4p"

Conclusion

That's it, you learned how to launch the editor and made your first steps in patching VVVV.js. Now it's time to find out how to use VVVV.js in your own project, rather than just edit already deployed patches. Read all about it in the next guide, Embedding VVVV.js.