JavaScript and Max: An Introduction
Max includes a built-in JavaScript interpreter, accessible by creating a js
object. This object should have one argument: the name of the JavaScript file
you'd like to create.
You'll find there are few important differences between the JavaScript you're
used to and JavaScript as implemented in Max. First, Max uses a pre-ES2015
version of JavaScript, meaning that newer features like the let and const
keywords, arrow functions, and array destructuring will be interpreted as
syntax errors. Another difference is that Max doesn't use the DOM API, meaning
that global variables like document and window no longer carry any special
meaning. On the flip side, Max introduces its own brand-new API, loading
special meanings onto variable names like inlets, bang, post, and many
more.
Let's build a simple JavaScript program inside Max. First, exit edit mode, and
then double-click on your newly-made js object to open up the code editor.
Then, open the Max console by typing ctrl- or cmd-M. This step is important
because the Max console will tell you if your code has any syntax errors.
Next, use the code editor to declare how many inlets and outlets your js
object will have. Do this with the global inlets and outlets variables.
When you save your code, you'll see that the number of inlets and outlets of
the js object will change accordingly.
The next thing we'll do is create a function called bang(). bang() is a
special function that executes whenever the js object receives a bang in
its leftmost inlet. Let's add the code, post("hello world");. As you can
probably guess, the post() function is the Max equivalent of a
console.log(), printing a debug message to the Max console.
Let's test our code by creating a button, and then connecting it to our
js object. You'll see that the "hello world" keeps repeating on the same
line; to change this behavior, we need to manually provide a \n.
In our next example, let's have our js object spit out a random number when
you send it a bang. JavaScript has a built-in math library, including a
function called Math.random(). Let's assign our random number to a local
variable called random. Then, we need to send our random number to an
outlet. To do so, use the built-in outlet function. The first argument is
the index of the outlet to send the data to—and be careful, it starts at 0!—and
the second argument is the data to send.
Before moving on, let's briefly talk about how to organize your ".js" files in
relation to your ".maxpat" files. The simplest method is to throw everything
in the same folder, ".js" and ".maxpat" alike; crude as this is, it will ensure
that Max won't run into any file path issues when trying to find your
JavaScript code. A fancier solution is to create something called a "Max
project", by going to File->New Project in Max. A Max project automatically
organizes your Max patches in a "patches" subfolder, and your JavaScript code
in a "code" subfolder; it will also do the same for your externals and JSON
files. As you begin to develop larger and larger projects, you'll probably
find that Max projects provide a cleaner and safer way to organize your code
than the one-folder way of doing things.