# MaPZone User Interface Guide (WIP)

If you've never used a node-based application, MaPZone's user interface can be a little daunting at first. Although the work flow takes a little getting used to, I'll think you'll find that adding and rearranging nodes can be quite fun and intuitive. The advanced options, like creating custom Fx-Maps and adjusting the FX shaders present a more significant challenge, but with time and patience these can be understood and mastered as well. (Though, TBH, I haven't figured out the entire thing myself!)

## The Library Dialog

When you start MaPZone, the first window you see after the loading screen is the Library, a dialog that allows you to navigate through your MaPZone file folders and preview files (or texture set in MaPZone parlance). MaPZone has a somewhat unusual user interface when it comes to loading and saving files and it can be a little disorienting the first time you use it.

### Opening Texture Sets

You select a folder or texture set by left-clicking on it, which will highlight your selection in orange. If you double-click a folder, it will open, allowing you to browse its contents. If you double-click a file (texture set), it will load the set into the main editing window and close the Library dialog. Every time you start MaPZone, it will automatically select the last texture set you edited, which makes it easy to continue working on a current project.

Two Different Interfaces: The Library dialog and the main editing window are never open at the same time. If you open a new texture set from the main editing window, MaPZone will prompt you to save your work, then close the current window and open the Library.
QuickScan: To create a new texture set, double-click the New folder to open it, then double-click the New icon.

### Using the Context Menu

You can cut, copy, paste, delete, and perform other actions on folders and texture sets using the context menu by right-clicking on an object in the Library view. Most of the standard operations can be accessed in this way, like creating new folders, renaming folders and texture sets, and exporting texture sets as image files.

### Menu Bar

The Library has a number of menu options. Clicking on Help... (shortcut F1) will open the MaPZone documentation page on Allegorithmic's website. (You'll need to have internet access to retrieve it.) I recommend you spend some time studying the documentation. There isn't a lot of it, and most of it is in picture form, so it is fairly easy to digest. Like any other application, though, you really have to use MaPZone before the documentation will start to make sense.

You can also get quick help by holding your mouse cursor over the buttons and some of the window labels to summon a tooltip that will provide a brief description of the object. Studying the tooltips is really the easiest way to learn about MaPZone, which does an excellent job documenting itself. You can also use the ? button (shortcut Ctrl+F1) to get an alternate set of tooltips. Just select the ? button and then select a button or area on the Library dialog and a tooltip describing the selected object will appear. The tooltips retrieved using the ? button are different than the regular tooltips so you can sometimes glean additional insight using this method. The ? button also provides information about areas of the editor that don't have normal tooltips (like the Library and Preview windows), so if you're stuck on something, don't forget to check this. The ? button is a one-shot affair, so you have to reselect it for each item you want identified.

The third button, Quit, is straightforward and quits the application (shortcut Ctrl+Q). MaPZone makes you save or discard your work before leaving the main editing window to return to the Library, so it is always safe to click this to exit the application without losing any work.

The next option, Export as bitmaps... (Ctrl+E) allows you to export your texture sets as image files. It actually allows you to export in a number of different file formats, not just bitmaps, which I'll discuss below.

The last option, Edit, simply opens the selected texture set in the main editing window. This option is greyed out unless you have a texture set selected.

### Managing Files and Folders

The Library directory has a couple of useful options which are accessed by clicking the small icons beside the Library heading.

The icon allows you to open the current Library directory using Windows Explorer. This can be more convenient for people who prefer to use a familiar interface. MaPZone has a curious oddity in that folders created within the Library directory within MaPZone are not stored as sub-folders in Windows: all of your texture sets will appear lumped together in the Library directory.

The icon allows you to change the Library directory. This uses the standard Windows browser dialog which should be familiar to you. The default Library directory is located under Allegorithmic/MaPZone 2.6/Library/, but if you want to create an alternate Library located somewhere else, you can use this function to create it, and then access it. Just navigate to the location where you would like the new Library and create a new folder. MaPZone can only access one Library at a time, so to access the new Library, you have to quit MaPZone and restart it to load the new Library assets.

If you create a new Library, you will only have access to the files contained in that Library during your session, so before you can begin using the new Library you have to copy and past the New_New.map and New_New.png files into your new directory along with any of the presets that you want to use. MaPZone uses the New_New.map as a template for your custom maps; you won't be able to create new ones without it.

### Searching for Files and Folders

The Search box requires a bit of explanation as it operates a little strangely. When you type a word or part of a word (techie people call that a character string or search term) into the Search box and press Enter, MaPZone will find the first occurrence of that string in the current Library directory and select it. (Make sure you delete or type over the ellipses first.) If you press Enter again, MaPZone will tab down to the next occurrence of that string. If the current selection is a folder, however, it will tab to the first sub-folder within that folder or the next instance if there are no more sub-folders. This quirk is a little odd at first, but as long as you're aware of it, you should be fine.

You can continue to tab through sub-folders and instances of a string by pressing Enter until you reach the last instance or sub-folder in the Library directory at which point MaPZone will return to the top of the directory and start cycling through them again. If you type a string and MaPZone can't find any matches, it will pop up an alert box informing you of this fact. You will get the same alert if your search term only returned one result and MaPZone has already found it. (Which can be confusing if you try to search for the same thing twice in a row!)

### Previewing Texture Sets

If your texture set has attached Output nodes, the Library will show you a preview in the Preview column on the right. You can change what is displayed in the preview by clicking on the Display button in the top right corner. You can selectively turn on and off display for Shaders and Outputs, Shared FX-Maps, and Shared FX-Filters. This might save you a bit of time if you're looking for a specific map or filter.

### Adding Descriptions to Texture Sets

You can add a decription to a texture set in the Desc. field beneath the folder tree. MaPZone won't save your description unless you hit Enter so don't forget to do that when you're done typing. This can be useful if you want to make a short note about a texture set; for example, 'Not finished', or 'Metal template', or something to that effect. You can change the description at any time.

### Cut, Copy, and Paste Texture Sets

The Opt. button in the corner allows you to copy, cut, paste, delete, and perform other actions on your selected texture set or folder. This is identical to the right-click menu.

### Opening Recent Texture Sets

You can reopen a recent texture set by using the Recently Opened drop down box at the bottom of the Library dialog. MaPZone stores your last 10 recently opened files. (Very Minor Bug: The tooltips and ? information for the Recently Opened widget point to the help files for the Desc. field, not for the Recently Opened field. No biggie.)

## The Map Editor

The Map Editor is the main MaPZone interface, and it's where you'll spend 99% of your time. Although it looks fairly simple, there is a lot of complexity tucked away in sliding panels. This first illustration shows you the main editing windows and a sample map that I created.

### The Graph Editor

The first thing you probably notice is the collection of rectangles connected by lines in the top right window. This is the Graph Editor where you assemble the components that go into your map. Each of these boxes is a node that defines either a map preset, or a modifier to a preset. If you have any experience using Photoshop or Gimp, you may be familiar with the concept of layers. MaPZone's nodes are very similar to layers, but more flexible.

Terminology: MaPZone terminology can be a little confusing, so I'm going to cover a few of the main terms here. A preset is a bitmap image defined by a series of algorithms using the FX-Map editor. It is equivalent to an FX-Map, but presets dragged to the graph from the Preset panel are called FX-Map Links, not FX-Maps, because they are duplicates or instances of an FX-Map but not the original FX-Map. FX-Map Links can be 'flattened' and edited without affecting the original FX-Map they are based on. (In other words: by using Links instead of the original maps, presets can be edited non-destructively.) Filters are modifiers applied to FX-Maps. They do things like add color, blur, emboss, warp, etc., but have no existence in and of themselves without an FX-Map to work on. (The one exception to this is the Uniform Color filter, which can stand on it's own.) Some filters do not modify an FX-Map, but perform an operation on one, like exporting a node sequence as a bitmap, or importing an SVG file. All presets and filters are collectively known as nodes. A complete node sequence is known as a map. If a map has output nodes it is known as a texture set. Whew! That's a lot of terms for a relatively simple concept. You might want to read that a couple of times.

### The Presets Panel

You create a map by dragging a preset from the Presets panel to the Graph Editor and then modify it by adding nodes, or filters. Presets are patterns of procedural noise that can be very simple or quite complex. MaPZone comes with a large, built-in selection of presets which you can use as is or modify in the FX-Map editor. You can even build presets from scratch.

You can add multiple presets to a map and combine them to create more complex and interesting effects. The final result depends on the order in which the nodes are connected, and the blending modes you use to combine the filters. Much of the learning curve associated with mastering MaPZone comes from learning how to select and combine presets effectively.

### Using the Graph Editor

The Graph Editor is very straightforward to use. To add a preset to the Graph, left-click on a preset in the preset column, hold down the left mouse button button and drag it onto the Graph.

To add a filter, you can either right-click in a blank area of the Graph to open the context menu and select New Filter, or you can double-click on the graph with the left mouse button to open the Node Panel and select a node (filter). It doesn't matter which method you use; the context menu has more options, but the node panel is faster if all you're doing is adding a node.

Once you've added presets or filters to the node graph, you can drag them around by selecting them with the left-mouse button and holding the button down while you drag. If you try to drag a node off the graph it will automatically pan to make more room: there really isn't any limit to how large your graph gets. If you find your node graph is getting too big to fit on a single screen, you can pan around the graph by pressing and holding the middle mouse button.

If your graph gets really large, a mini-map will appear in the upper left corner of the graph showing your current location. The current screen will be rendered as an orange rectangle overlapping a grey rectangle representing the total area of your graph.

### Connecting and Disconnecting Nodes

To connect two nodes, you need to connect the output pin on the first node to the input pin on the second node. To do this, place your mouse cursor over the first node's output pin (the little left-pointing triangle, or arrow). It should highlight with an orange border and pop up a tooltip like in the image below:

You can connect nodes in one of two ways: by selecting an output pin with a left mouse click and then selecting an input pin with a second left mouse click, or by selecting an output pin with a left mouse click, holding down the button, and then dragging the mouse to an input pin and releasing the mouse. A line, or wire, will follow the mouse and will remain red until it finds an input pin it can connect to.

When your mouse cursor is over an input pin that it can connect to, the line should turn orange to indicate that a connection is available.

When you release the left mouse button, or click for a second time, the line should turn yellow to indicate that you have established the connection.

To disconnect a node, either hold down the Shift key, press and hold the right mouse button, and then drag across the wire connecting the nodes to 'cut' it, or right-click the input pin and select 'Disconnect'.

For a more detailed explanation about adding and editing nodes, refer to the MaPZone tutorial.

### The 2D Texture Viewer

More to come!

Last updated October 23, 2011

© 2009-2011 Dave Finch

SUPPORT TRUANCYFACTORY