The Anatomy of a N4M Patch
The Basic Parts of a Node for Max Patch
You can think of Node/node.script as a kind of sidecar for your Max motorcycle. It’s a separate application process which lives and runs alongside your Max patch.
There are three components that make up a N4M patch:
- The Max patch itself contains all your patching and your node.script object
- A JavaScript program which is run by Node for Max
- Messages that are used to communicate with a node.script object, including inlet and outlet messages
JavaScript Programs
The program loaded into each node.script object is defined by a single entry point Javascript (.js or .mjs) file which is stored somewhere in your Max Search path (and referenced by the first argument for the node.script object itself).
Note: Unlike the standard Max js object which holds the contents of a Javascript file in Max/s program memory, the node.script object must execute from a separate text file on disk.
Each node.script object in your Max patch represents a single instance of a Node program. It’s possible to have multiple instances pointing to the same JS File, but that also implies multiple instances of the program!
Each node.script object in your Max patch contains a valid Node JS program written in Javascript. The version of the JavaScript language supported by node.script includes recent additions and features to the EcmaScript standard. For a quick overview on recent language features see this cheat sheet: https://mbeaudru.github.io/modern-js-cheatsheet/ For a full list of supported features based on the current Node version please refer to http://node.green.
A node.script JavaScript program usually has the following parts:
- A JavaScript program which is saved as a text file using the .js or .mjs extension to your hard drive and available to the Max Search Path.
- The program can import and use libraries from the Node JS API. This lets you make HTTP requests, access the file system and more. For more information on the Node JS API, see: https://nodejs.org/docs/latest-v20.x/api
- To communicate bi-directionally with your Max Patch, import the max-api module ( https://docs.cycling74.com/nodeformax/api/index.html ). This contains functions for sending messages to, and receiving messages from Max. You can also open the API documentation by sending the api message to a node.script object
Control Messages
Control messages sent to a node.script object can be easily identified: they always begin with a script prefix. These messages communicate with the node.script process manager, rather than the Node script which is run by Node for Max.
Input Messages
Input Messages are sent into the Node JS Program via the node.script object’s inlet. They are messages that you would like to send into the JavaScript context of the node.script object. These messages can include lists, numbers and dictionaries.
The node.script object can also react to incoming input using the max-api module ( https://docs.cycling74.com/nodeformax/api/index.html ).
Output Message Handling
Output Message Handling is composed of the Max patching you create to handle the messages sent out the left outlet of the node.script object. You’ll usually use a Max route or routepass object to handle that message output in your patching.
It is possible to output messages from within the JavaScript context of node.script directly to your Max patcher using the max-api module.
Monitoring / node.debug Messages
Monitoring and node.debug messages provide status and error messages that keep you informed about what’s going on in the Node Program itself. The node.script object sends lifecycle messages, information and events out of the rightmost outlet in the form of Max dictionaries.
Note: The form of the lifecycle dictionaries is somewhat complex (as documented here ). To make monitoring easier, you can use node.debug , which covers all the received messages and shows all status information, stdout/stderr logs and other data in an easier to use UI.
See Also
| Name | Description |
|---|---|
| Node for Max Documentation - Table of Contents | Node for Max Documentation - Table of Contents |
| Node for Max - Debugging | Node for Max - Debugging |
| Node for Max - Programming Interfaces | Node for Max - Programming Interfaces |
| Node for Max - Script Lifecycle | Node for Max - Script Lifecycle |
| node.script |