In this tutorial we share tips and tricks for creating your own libraries and presets for Forest Pack. If you regularly use the same objects in your renders, it makes sense to add them to the library browser for easy access, and If you work in a studio you can easily save library configuration files in a networked location so that artists can share and collaborate on a central repository. In the first half of this tutorial we focus on the the essentials of using the library browser to create and edit libraries.
In the second half we'll demonstrate advanced tips that show how to support multiple renderers and trigger maxscript events to extend the functionality of the library. This section is aimed at users that would like to share their libraries either in the same studio or even for distribution online. We'll explain how to package assets and make them more accessible for users with different configurations.
Throughout this tutorial we will demonstrate the creation of a library called "unkempt lawns" that consist of over 30 individual items plus a few presets to get you going. The final library, including all the plant assets is available to download below in Max 2011 format with material libraries for V-Ray, Mental Ray and Corona.
Though this tutorial focuses on Forest Pack, most of the techniques are equally applicable to creating libraries for RailClone.
By completing this tutorial you will be able to:
The scene files for this tutorial include the pre-built "unkempt lawns" library . This library contains over 30 plants plus presets and sample maxscript functions. It is designed to illustrates how a library might be packaged for distribution.
If you're new to Forest Pack, before creating your own libraries it's worth taking some time to recap the library interface. To open the library click on in the Geometry rollout.
On the left of the interface is the navigator, use this to select, edit and open your libraries. You'll notice that there are two types of folder. System folders, which are represented in blue, denote the libraries that come packaged with Forest Pack or RailClone. These are read-only and can't be modified from the library browser. Below these are the editable user folders represented by a green folder. This is where your custom libraries can be found.
After a fresh install of Forest Pack or RailClone you'll have one location already added called User's librarys. The default location for this is C:\Users\<username>\Documents\Forest Pack\libs but you can save libraries on any local or network drive in any folder. We'll look at how to edit and add locations a little later in this tutorial.
On the right is the Items grid. This view previews the contents of the selected library and allows you to selects individual objects, multiple objects by holding down shift or control, and presets. Along the top is the toolbar, with several command buttons to navigate, save and refresh the library as well as changing the size of the thumbnail images.
There may be times when you'd like to make a copy of an exisiting library. To do this select a library and then dragging it to any user folder while holding down CTRL. All the neccesary files are copied to the new location and you can now edit this version. You can also move files between folders just by clicking and dragging in the navigator view, theres no need to open Explorer for basic file operations!
So that's the basics, let's add a new library!
The first thing you need is a root folder. This is the path that Forest Pack or RailClone's library browser will search in for library configuration files. As mentioned above, there's already a User folder set up, but for the purposes of this tutorial we'll add a new directory. In this example the path is created locally, but there's no reason why this can't be shared network location so that assets can be easily accessed by multiple artists in a studio environment. To add a new library location:
Now that we have a new folder created, we can add a library, but it's worth mentioning that it's also possible to add additional sub-directories to this folder directly within the Library Browser. To do this
Finally let's add the library itself.
When you create a library, a new folder is added that includes an XML file and a sub-folder for thumbnails. This and any other folders found in the same location as an index.xml file are not displayed in the Library navigator. This allows you to organise your assets by adding additional directories to separate models, maps and materials.
Although you can easily create libraries entirely from the library browser interface, if you plan to share library files with colleagues, other users, or offer them for sale, it is helpful to understand how library files are stored behind the scenes. Fortunately it's not complicated, and the Library browser does most of the work for you. Let's look at how a library is organised:
The XML file itself contains the configuration for the current library, including the location and name of the max files and objects referenced, the materials to use, which thumbnail to display and much more. As we'll see later, it's also possible to trigger maxscript events from the XML file to add additional functionality to the library such as detecting the current renderer, adding new user paths and much more.
Never save your own libraries in the same location as Forest or RailClone's built in presets. This directory will be wiped whenever you update the software and you'll lose anything saved there.
To create the "Unkempt Lawns" library we need to add the files to the folders we just created. To do this:
Now that the source files have been moved to correct locations we're ready to add some objects. To start with let's look at how to add a single item:
Once you've added an object to the library you can open the XML to see how Forest pack saves this information. Even if you're not familiar with XML syntax, this mark-up is fairly self-explanatory:
<?xml version="1.0" encoding="utf-8"?>
<library version="100" order="1" masterScale="3.93700787402e-002" xref="1" bitmap="">
<description>The petals are often highly lustrous, especially in yellow species. Buttercups usually flower in the spring, but flowers may be found throughout the summer, especially where the plants are growing as opportunistic colonizers, as in the case of garden weeds.</description>
The details for each item are stored between <item></item> tags with the class "Max Object". Inside this there are tags for the fields that we just entered in the library browser. If you look at the <maxfile> tag you can see that paths are relative to the index.xml file.
If you prefer to create libraries purely by editing the XML, it's a simple case of duplicating the <item></item> tags plus their contents, and changing the values.
Adding items one at a time like this can be time-consuming, fortunately the Library browser allows you to automate the addition of multiple objects that are contained in a single .max file. To do this:
As you can see, using the import objects tool you can very quickly populate an entire library in a couple of clicks.
Presets allow you to import a whole Forest Pack style, including all the necessary geometry, the distribution and transform settings and more. Once a user has loaded a preset it should only be necessary to assign the scatter areas and they're ready to go. We provide our presets in two size, a detail preset that uses individual plants and is suitable for small areas, and a large preset that uses pre-combined "patches" of plants and is designed to cover much larger areas of a scene. The only real difference between the two is the geometry used.
There are a 4 detail presets already included in the download but we'll create a 5th that combines the grass, chickweed and buttercup models to illustrate how it's done.
Adding this preset to the library uses the same procedure as adding a regular item.
Next let's create a large area version of this preset. Because the geometry used for large area presets can have high polygon counts, it is good practice to create each preset in a new file .max file:
Unless you specify otherwise, the materials applied to the original source objects will be imported along with the geometry, so if your only supporting a single renderer or you don't plan to distribute the library there's probably no need to go through the following steps and your library is done!
If however you would like to add the ability to select materials to support multiple renderers, here how this works.
You may have noticed our built in libraries have the option to select a different material library for each supported renderer using a drop down list. This is achieved using a macro that inserts a different name into a material library's path depending on the option selected in the material selector dropdown. For this to work you need 3 ingredients:
<select class="material" setmacro="UNKEMPT_LAWNS_RENDERER">
Using these 3 ingredients, we'll demonstrate how to add the ability to select materials to our unkempt lawns library for Mental Ray, Corona and V-Ray:
|vray||V-Ray and V-Ray RT|
|mental||Mental Ray and IRay|
Using these we create material libraries with identical names except for a prefix or suffix that contains the renderer value. For example in this tutorial the matlibs are named _fp_unkempt_lawn_corona.mat, _fp_unkempt_lawn_mental.mat, and _fp_unkempt_lawn_vray.mat. You'll find these in the the Matlibs folder in the downloads for this tutorial.
In each case the text between the opening and closing tags displays in the drop down list and the value is the text that the macro returns when called.
Finally, add a closing </select> tag.
Save the file and open the library browser. You should now see the 3 options in the Material drop down menu.
Now that the options are working we must override the materials currently applied to the object with those from the material library, To do this:
In this example we are replacing the material on the object with another of the same name from a material library. It is also possible to assign a completely different material from a material library. To do this in the Item Settings click on and pick a new material from the library. This will add a new line to the XML, for example:
For a more advanced setup it is also possible to extend the library using maxscript functions. For example, you may want to add the ability to automatically detect the active renderer instead of selecting it manually. To set this up:
fn getRenderer = (
local renderClass = (classof renderers.current);
if ((renderClass == VRay) or (renderClass == VRayRT)) then
else if ((renderClass == mental_ray_renderer) or (renderClass == iray_Renderer)) then
else if (renderClass == Octane3dsmax) then
else if (renderClass == Thea_Render) then
else if (renderClass == CoronaRenderer) then
When a maxscript file is called by the library browser it will search through all valid folders within the library path. We recommend saving Maxscript files either in the same location as index.xml or if you plan to re-use the same functions for multiple libraries in the root directory. (these are the directories shown in the File > Preferences > Library Paths list.
The remapping of bitmap paths is not handled automatically by the Library Browser. To ensure that maps are located correctly you will need to add the maps directory to the users paths manually. To do this:
If you have a large number of libraries it may be simpler to simply copy all of the maps to single central folder and add this to the user paths instead of adding a maps folder for each library.
In the next section we'll look at how this process can be automated using maxscript.
To add additional functionality to the library browser we have included the ability to run a maxscript function when either the library is opened or an object is imported. To do this you need two things. Firstly an .ms file containing the functions, as before this should be saved in the same location as index.xml or the root directory if you'd like multiple libraries to access the file. Secondly you should add a line to the XML to tell it which .ms file to load plus the function's name. The basic format for this is
<maxscript file="filename.ms" script='functionName();' execute_on="item_select"/> -- (Execute_on can also = "lib_open")
Where filename.ms is the name of the maxscript file, functionName() is the name of the function saved in the maxscript file, and lib_open or item_select is when the script should be executed.
To demonstrate this, we will add a code snippet that adds the maps folder path for the current library to the User Paths automatically. This is useful if you are distributing libraries as it will prevent users from having to add these paths manually. This function can be found in the tutorialLibraryFunctions.ms file we used earlier and is included in this download. The function is called addMapDirectory and is as follows:
fn addMapDirectory LibraryMapPath =
local pathExists = false
for i = 1 to mapPaths.count() do
if mapPaths.get(i) == LibraryMapPath then pathExists = true
if (pathExists == false) then
if queryBox "This library's maps folder should be added to Customize->Configure User Paths->External Files.\n\nClick YES to add it automatically\nClick NO if you prefer to configure the map path manually." title:"Add Maps Path?" beep:true then (
Without going into detail, this checks to see if the directory contained in the variable LibraryMapPath is already present in the User Paths. If it is missing a dialog will appear asking the user if they'd like to add it automatically. Let's add this to the library:
This is just one example, any maxscript can be triggered by the library including multiple functions.
That completes this library. If you want to distribute it, just .zip the folder and it's ready to go.
Now that this library is complete here's how to install it on another machine. This is very straightforward as it is only necessary for the user to add the library's path to their browser preferences. In fact it is the same technique as we used at the beginning of this tutorial to add a new folder location. If you're sharing your library, these are the kind of instructions you could distribute with your library files:
The final library created during this tutorial follows the good practice guidelines we recommend for well formed libraries that can be easily redistributed. In addition the thumbnails folder and index.xml file, the final structure includes a maxscript file for any additional functions and separate folders for objects, maps, and material libraries:
We've also looked at adding support for multiple renderers and how to add the libraries maps folder automatically to the Users Paths. Though we've only focused on a single library in this instance, multiple libraries can be included in the same location to make it easy to organise your content into logical catergories.
Finally, If you are a Evermotion, XFrog or HQPlants customer then there's no need to go through this process. For each of these vendors we have a catalogue installer that can be downloaded from our site that will automatically add all the correct files for you. To find out how this works please see the Installing HQ Plants catalogue tutorial and the additional install notes for XFrog Plants.