The js object allows you to write and run a JavaScript program inside Max.

JavaScript was developed as a language for writing programs, called scripts, that would run within Web pages. For that reason, most basic tutorials you might read about JavaScript give you a lot of information about how to write programs that do useful things in Web pages, but those tutorials aren’t especially relevant to Max. This post is intended to give you some background information that will get you started writing JavaScript programs within Max.

JavaScript effectively has two parts, a generic programming language, called core JavaScript, and a part that does Web-specific tasks, called client-side JavaScript. The Max js object runs the core programming language, but disregards all the client-side part, which is specific to Web pages, and therefore is irrelevant in Max. The Max version of JavaScript also includes some additional Max-specific features, having to do with inlets, outlets, and Max messages, which would be irrelevant in a Web page.

When you create a js object in a Max patcher window, you can Command-double-click on it (Control-double-click in Windows) to open up a text window for you to type your JavaScript program. By default, the js object will have one inlet and one outlet. If you want more than that—say, two outlets, for example—you can just type this line at the beginning of your text file:

outlets = 2;

The “=” sign means “is”. So in this case, the statement means, “The number of outlets is 2.” Every command in a JavaScript program should end with a semicolon “;”.

What do I want my js object to do? Let’s suppose I’d like it to send a greeting message out its outlet when it gets the message ‘greeting’ in its inlet. (Admittedly that’s a stupid task that you’d probably never want to do in Max, but bear with me for the sake of this example.) In order for your js object to understand the message ‘greeting’ you need to write what’s called a function that will respond to that message. You’d have to type something like this:

function greeting()
{
    outlet(0, "Hello there!");
}

The word ‘function’ creates a function, the word ‘greeting’ gives it a name that corresponds to the message that will trigger it, the empty parentheses (), which should follow the function name without any space, mean that the ‘greeting’ message won’t have any additional arguments, and the curly brackets {} enclose the commands that we want to happen when the message ‘greeting’ is received. The ‘greeting’ function has only one command, which says, “Out of the first outlet, send the message “Hello there!”. ‘outlet’ is a built-in function that already exists in js, which performs the task of sending a message out the designated outlet. It has two arguments: the outlet number, and the message to be sent out. Outlets, like most things in computer programs, are numbered starting at 0, so outlet 0 is the first outlet. As usual, the command ends with a semicolon.

That’s a complete (if not very sophisticated) JavaScript script. You would just save the text file with a .js filename extension somewhere in the Max file search path, then type your filename as an argument in the js object, and it will look for and load your script the next time the patch is loaded.

Now let’s try a script thats just a bit more practical. Let’s write a script that will output the square of whatever floating-point number you send in. There’s a built-in function name you should use for float messages, called ‘msg_float’.

function msg_float(f)
{
    outlet(0, f*f);
}

This script is not very different from the first example. In this case, though, the parentheses contain an argument, designated by the variable f, that will contain the whatever number you send in the inlet. So in our outlet function, we send the product of f times f out of the first outlet. You would just save this script in a file called squared.js (or whatever name you prefer), and load that file into a js object by typing it as an argument in the object box.

This mini-tutorial is just the tip of the iceberg of possibilities, of course. You can learn a few more basics by studying this additional set of three small JavaScript programs. Download and save the six files in that directory. The files are meant to be studied in progressive order: 1) bang2x.maxpat, 2) number1x.maxpat, 3) numbearray.maxpat. Within each patch, double-click on the js object to open the script it contains.

You can also look up anything you don’t know in the official JavaScript reference manual.