A newer version of Max is available. Click here to access the latest version of this document.
Tutorial 1: Hello
Max patcher basics
Open the tutorial.
In this tutorial, we will examine the building blocks of a Max patcher: the object box, the message box and the comment box. We will also delve into some of the basic editing functions provide by the Max environment.
This brief tour of a simple patcher will show the basic typology of simple programs written in Max: object boxes that perform command actions within a patch; message boxes that allow us to create messages that can be sent to the objects; comment boxes that allow us to document our patchers to make them easier to understand.
Looking around
Take a look at the patcher 01mHello. At the top right-hand side of the patch window, we can see three types of boxes.
The first element is the box labeled print. This is an object box, and can be recognized by it's rounded outline and (in this case) a small "port" at the top left that we call an inlet. Object boxes are the basic logic element of Max – they contain functions that perform some sort of task, and operate like miniature programs within the larger environment.
Just below the object box is a message box (labelled with the word "message"). These are visually different from the object box – they have a gray background, and do not have an outline. Message boxes contain some information (called a message) that can be sent to objects, and can operate as either commands or control data.
The third box doesn’t look like a box at all – it appears to be text on the background of patcher window. There is actually a box around this text, but it is not visible until we decide to edit our patch. This comment box is used to add text for labeling controls (e.g. "click me"), or for adding comments to your patch to make its operation more apparent to you or anyone you might share your patch with.
Max programs function by passing messages between objects. Object boxes can be connected to one another, and message boxes can be used to originate or, in some cases, process messages that are used to control other objects.
Unlocking the patcher
When you first opened this patcher, we found it in a "locked" state – meaning that we cannot edit any of the objects or text in the window. When a patcher is locked, the intention is that it be used as a program. Since the power of Max is that we can to edit and manipulate these programs to do whatever we like, let's "unlock" this patch and do some editing.
Choose Edit from the View menu. You will see several changes in the patcher. First, the boxes surrounding the comment boxes are revealed (we told you they were there). Secondly, the message and comment boxes show inlets that were hidden in the locked state. In addition, ports on the bottom of these boxes are revealed; these are outlets. Finally, many more of the icons at the bottom of the patcher window are now available for our use.
In addition to the visible changes, we are now free to edit the contents of the window. Double-click inside the object box in the upper-right that says print; the text is selected, and you can type the name of another object name into that box. Type "metro" (without the quotes), and click outside the object box to complete the edit. We have now changed the function of that object (it is now a metro object). You will see the object box change size, and the number of inlets and outlets will change as the function of the object has changed. We learn Max by building up a vocabulary of objects and how they connect to other objects (i.e. what messages they understand and transmit).
Double-click inside the message box right below that. Change the message text to anything (for example, type in the word "anything"), then click outside the box to accept the change. Note that changing the message text does not change the inlets or outlets, since only the contents (but not the function) of the message box has changed.
Finally, double-click inside the comment box and change its text. Since the comment box has no function other than adding text to the patch, you are free to put in any text that pleases you.
Interacting with a locked patcher
Lock the patch by unchecking Edit in the View menu. Let’s see what happens when we click on each of the box types. In the upper right-hand corner of the patch, click on the object box (which we changed from print to metro) – nothing happens. Clicking on the message box directly below it, however, changes the background color – obviously, something is happening when we click on that box.
On the left side of our patcher, there are three message boxes connected to a print object with lines (called patchcords). Click on each of these message boxes in turn, then look at the Max window; you will see that the contents of the message boxes we clicked are displayed there. This was a result of clicking on the message boxes: they generated a message (the content of the message box) and sent it down the patchcord to the print object. The print object takes any message it receives in its inlet and "prints" it out in the Max window.
Commas change everything
You probably noticed that two of the message boxes have almost identical text, but the display in the Max window is different. The message box with the text "Good morning, everybody!", when sent to the print object, caused the text to be displayed on two lines. The message box right below it (with the text "Good morning\, everybody!") was displayed by the print object on a single line in the Max window. The difference is in the use of the comma, which has a special meaning in message boxes within Max.
In a message box, the comma is used as a message separator; in essence, it turns a single line of text into two discrete messages. Thus, the message "Good morning, everybody!" is really treated like two messages: "Good morning" is sent out the outlet of the message box, followed immediately by "everybody!".
In order to treat the comma as text (rather than as a message separator), you need to let the message box know that you are overriding the comma’s special behavior. You do this by preceding the comma with the backslash ("\") character, which tells the message box to ignore the comma’s special use, and treat it as a literal text character. Those of you familiar with textual programming languages will find the use of a backslash character to "escape" a character that has special meaning familiar.
Unlock the patcher, click inside the lower message box (the one with the backslash) and remove the slash. Lock the patch and click on the edited message box – you will see that it, too, now creates two lines of text in the Max window. Edit the first message box, adding a backslash before its comma, and lock the patch; it now exhibits the expected behavior of printing the entire message on a single line.
Getting help
The print object is obviously doing something to send text to the Max window; in fact, every object box performs some sort of task. To determine what function an object box performs, you can view several types of document to get help.
Unlock the patcher and select the print object box by either clicking into it or clicking and dragging the mouse over it to highlight it. Select Open print Help from the Help menu. A new patcher window (called a Help patcher) opens with an example that shows the print object in action. Note that this is an actual Max patch, and can be unlocked, edited, or copied elsewhere, retaining any of the displayed functionality.
Close the print object's Help patcher and reselect the print object. Select Open print Reference from the Help menu. A browser window (much like this one) is displayed with the Reference Manual page for the print object. This gives detailed information about the object, all of its inlets and outlets, and even provides an example patch for your reference. This is perhaps the most detailed information available for any object. In both the Help patcher and the Reference page, objects and topics relevant or similar to the object you're viewing can be viewed by clicking on links in the See Also section at the bottom.
Create some new messages
Let’s add some objects to our patch, and create our own message passing logic. First, with the patcher unlocked, click on the palette icon (the "+" symbol at the bottom of the window) and select the first object – it is the object box. This will place an empty object box on your patcher window, ready for you to enter its name. Enter "print", then click outside the box to accept this change. Move the object somewhere in the patcher with some clear space above it by clicking and dragging it around.
Next, click on the palette icon and select the second object, a message box. When it appears in your patcher window, type in the message "Goodbye!". Place this message box above the print object. Finally, connect the two boxes by clicking on the outlet of the message box, dragging the mouse to the inlet of the print object, then releasing the mouse button. This will create a patchcord between the two objects, allowing messages to pass from the message box to the print object.
Lock the patch and click on the new "Goodbye!" message. You will see the text "Goodbye!" appear on the Max Window. Congratulations – you’ve just done your first Max patching!
The three main elements of a Max patch (object boxes, message boxes and comment boxes), along with patchcords, are the core of all Max programs. Each type of element responds to a variety of messages and editing functions; these can be explored by viewing the help files and Reference Manual documents. Each of these aspects will be expanded upon in later tutorials.

See Also

Name Description
print Print any message in the max window
message Send any message
comment Explanatory note or label