Skip to main content

Creating commercial libraries

Overview​

info

This information is for companies wishing to create a distribute asset libraries that are integrated into Forest Pack. It isn't necessary to learn these steps if you are only creating libraries for internal use.

Users expect that libraries sold through our store should be integrated with the Forest Pack library. This will allow them to quickly preview and load assets directly inside Forest Pack with materials automatically applied to match their current renderer.

In the case of ground cover assets like grass, rather than provide individual models we prefer to create presets with key Forest Pack settings already applied. You can find out more about this in our Creating Presets tutorial .

General rules​

  • Each item should use just one material. It could be a "consolidated" Multi/Sub-Object material containing materials for the current renderer. Then by using a macro, user can choose from several material libraries upon renderer used in the scene.

  • Materials should be stripped from the objects in the Max file, or replaced with Standard materials. This is to avoid problems with users getting messages about missing maps and shaders.

  • Each item must have a unique name - in case of variations numbering should be used.

  • Do not use Proxy objects with the Forest Pack library. It increases file sizes by requiring a separate file for each renderer and there is very little performance advantage in using Proxies with Forest Pack.

  • Each asset in the library needs its own thumbnail, rendered in a square 1:1 aspect ratio no smaller than 800 x 800 and ideally 1024 x 1024. This should be on a simple light background similar to the one shown below. If you like we have a template file for this that we can provide.

  • Where possible use standardised specular and glossiness PBR workflows this will allow us and our users to easily create additional materials to support new renderers with relatively predictable results.

  • Plant information and descriptions are need for each asset.

    Naming is important. We believe we should try to be as specific as possible about the species of plant or tree.

    A short description of each plant can also be included in the library XML. For multiple versions of the same plant, this can simply be duplicated. The asset names, descriptions and thumbnails are also used to automatically populate an online catalogue.

  • Where possible add Forest Colour maps to add texture and/or tint variety to your objects. Users expect that libraries provided for use with Forest Pack make full use of its features.

  • Where possible it is better to use leaf geometry than opacity maps which can have a negative impact on render times. For some very large trees or for leaves that have complex leaf shapes we understand it may not always be necessary.

  • Keep polygon counts reasonable. It's impossible to give an exact figure because it depends on the size and complexity of the tree/plant, but for a large tree up to 2 million should be OK. Less if possible and only go higher than this if absolutely necessary.

Creating the Library​

Forest Pack's Library Browser needs to have a folder structure with an index.xml file (storing all library information needed) and a set of thumbnail images, that are be stored in thumbnails folder (containing thumbnail images) or in the same path as object files. Additionally, it's recommended to have a [library name].ms maxscript file handling any function needed by the library, like getRenderer() for detecting the current renderer, custom actions etc...

File Names and directory structure​

Items can share maps and materials, all necessary maps and material libraries should be stored in separate directories, as follows:

- \objects\<plant_name>.max (one mesh object per file, same name as filename)
- \thumbnails\<plant_name>.jpg
- \maps\<mapname>.jpg
- \matlibs\scanline.mat
- \matlibs\mentalray.mat
- \matlibs\vray.mat

If possible, please add a fp_ to the start of all files and names of objects. It makes it easier for users to identify the origins of the files. For maps use the following formula:

fp_assetname_[maptype].jpg

For example an asset named daffodil1 might have these assets:

- fp_daffodil1_diffuse.jpg
- fp_daffodil1_glossiness.jpg
- fp_daffodil1_normal.jpg
- fp_daffodil1_translucence.jpg
- fp_daffodil1_opacity.jpg

This also makes it simpler for us to recreate materials for other renderers and opens the option to automate the process further down the line, similar to the approach used by Quixel.

Index.xml structure​

Header

<?xml version="1.0"?>
<library version="100" order="1">
    <select class="material" setmacro="\product name>RENDERER">
        <option value="@forestlib.ms:getRenderer()" default="1">Automatic Selector</option>
        <option value="standard">Standard</option>
        <option value="mental">MentalRay</option>
        <option value="vray">VRay</option>
    </select>

The Header part is used to assign correct materials to selected item by calling the getRenderer() function defined in the forestlib.ms maxscript file (or in the [product name]catalog.ms) to evaluate the currently used renderer in the scene. In any case (using the default forestlib.ms or custom [product name]catalog.ms), the macro name needs to be set up properly by setmacro="[product name]RENDERER"> and needs to be different from default setmacro="RENDERER" to avoid any error possible error messages.

Item

<item class="maxobject">
    <name lang="english">Latin plant name</name>
    <name lang="latin">Common plant name</name>
    <family>Botanical family of plant</family>
    <description>Textual description about the plant</description>
    <bitmap>\thumbnails\[plant_name].jpg</bitmap>
    <maxfile>\objects\[plant_name].max</maxfile>
    <object>[plant_name]</object>
    <matlib>\matlibs\$([product name]RENDERER).mat</matlib>
    <material>[plant_material]</material>
</item>

The path to any models / textures could be also handled in two ways:

Relative to the location of XML file:

<maxfile>objects\_fp_[plant_name].max</maxfile>

Reference by macros:

<maxfile>$([product name]_PATH)\objects\_fp_[plant_name].max</maxfile>

The use of macros for mapping files is not mandatory, however this mechanism is useful for point to models stored in another location, or add variations to the library (by renderer, season or other criterias).

Library Installation​

Note:

If you are producing libraries to be branded as iToo products, you can ignore this section.

The Library Paths section of Forest Pack's Library Browser holds the location of the different libraries. The user can add their manually their own libraries under File>Preferences>Library Paths section and by Add... the path where the .xml files are stored. These values are stored in the user's registry:

[HKEY_CURRENT_USER\Software\Itoo Software\Forest Pack Pro\LibraryDir]

Also, it could be defined globally in following system registry key by any third-party installer:

[HKEY_LOCAL_MACHINE\Software\Itoo Software\Forest Pack Pro\LibraryDir]

Each library vendor is responsible to install, manage and reference all their objects and files. Although custom automation is possible via the .ms, the library doesn't copy or move any file from their original locations.

Library Macros​

The Library Macros are the mechanism to store and automate elements in the library. The library macros are stored in the registry in the following locations:

Macros modifiable by maxscript and stored in the user's profile:

[HKEY_CURRENT_USER\Software\Itoo Software\Forest Pack Pro\LibraryMacros]

Macros defined globally by any third-party installer:

[HKEY_LOCAL_MACHINE\SOFTWARE\Itoo Software\RailClone Pro\LibraryMacros]

The content of the macro can be any free text, when applied to any of the maxfile, object, matlib or material fields, the text is substituted and applied to the item. Additionally, it's possible to get the macro value from maxscript, using the following format:

@<library name>.ms:<maxscript call>

For example

@hqcatalog.ms:getHDFlowerRenderer()

Where the function asks 3dsmax for the current renderer and returns the appropriate prefix to modify the file or object paths. The .ms file must be located in the same path as .xml file.

Macros selectors​

For values that can be selected dynamically by user, is possible to show a combo box handled by the library code. This option allows to change macros values without the need of programming additional code:

<select class="material" setmacro="<product name>RENDERER">
    <option value="@forestlib.ms:getRenderer()" default="1">Automatic Selector</option>
    <option value="standard">Standard</option>
    <option value="mental">MentalRay</option>
    <option value="vray">VRay</option>
</select>

Currently only combo for material selection is allowed, however could be possible to add more combo boxes in the future.

Library examples​

Simple library without macros​

Index.xml:

<?xml version="1.0"?>
<library version="100" order="1">
    <item class="maxobject">
        <name lang="english">English Oak</name>
        <name lang="latin">Querqus robur</name>
        <family>Fagaceae</family>
        <description>Quercus robur is commonly known as the English oak or pedunculate oak or French oak.
        It is native to most of Europe, and to Anatolia to the Caucasus, and also to parts of North Africa.</description>
        <bitmap>_fp_English Oak01.jpg</bitmap>
        <maxfile>objects\_fp_English Oak01.max</maxfile>
        <object>_fp_English Oak01</object>
    </item>
    <item class="maxobject">
        <name lang="english">Holm Oak</name>
        <name lang="latin">Quercus Ilex</name>
        <family>Fagaceae</family>
        <description>Quercus ilex, the evergreen oak, holm oak, or holly oak is a large evergreen oak native to the Mediterranean region.
        It takes its name from holm, an ancient name for holly. It is a member of the white oak section of the genus,
        with acorns that mature in a single summer.</description>
        <bitmap>_fp_Holm Oak01.jpg</bitmap>
        <maxfile>objects\_fp_Holm Oak01.max</maxfile>
        <object>_fp_Holm Oak01</object>
    </item>
    <item class="maxobject">
        <name lang="english">Silver Maple</name>
        <name lang="latin">Acer saccharinum</name>
        <family>Sapindaceae</family>
        <description>Acer saccharinum, commonly known as silver maple, creek maple, silverleaf maple,
        soft maple, water maple, swamp maple, or white maple — is a species of maple native to eastern
        North America in the eastern United States and Canada. It is one of the most common trees in the United States.</description>
        <bitmap>_fp_Silver Maple01.jpg</bitmap>
        <maxfile>objects\_fp_Silver Maple01.max</maxfile>
        <object>_fp_Silver Maple01</object>
    </item>
</library>

Library with auto-shader selections​

Index.xml:

<?xml version="1.0"?>
<library version="100" order="1">
    <select class="material" setmacro="RENDERER">
        <option value="@forestlib.ms:getRenderer()" default="1">Automatic Selector</option>
        <option value="scanline">Standard</option>
        <option value="mentalray">MentalRay</option>
        <option value="vray">VRay</option>
    </select>
    <item class="maxobject">
        <name lang="english">English Oak</name>
        <name lang="latin">Querqus robur</name>
        <family>Fagaceae</family>
        <description>Quercus robur is commonly known as the English oak or pedunculate oak or French oak.
        It is native to most of Europe, and to Anatolia to the Caucasus, and also to parts of North Africa.</description>
        <bitmap>_fp_English Oak01.jpg</bitmap>
        <maxfile>objects\_fp_English Oak01.max</maxfile>
        <object>_fp_English Oak01</object>
        <matlib>matlibs\$(RENDERER).mat</matlib>
        <material>_fp_English Oak</material>
    </item>
    <item class="maxobject">
        <name lang="english">Holm Oak</name>
        <name lang="latin">Quercus Ilex</name>
        <family>Fagaceae</family>
        <description>Quercus ilex, the evergreen oak, holm oak, or holly oak is a large evergreen oak native to the Mediterranean region.
        It takes its name from holm, an ancient name for holly. It is a member of the white oak section of the genus,
        with acorns that mature in a single summer.</description>
        <bitmap>_fp_Holm Oak01.jpg</bitmap>
        <maxfile>objects\_fp_Holm Oak01.max</maxfile>
        <object>_fp_Holm Oak01</object>
        <matlib>matlibs\$(RENDERER).mat</matlib>
        <material>_fp_Holm Oak01</material>
    </item>
    <item class="maxobject">
        <name lang="english">Silver Maple</name>
        <name lang="latin">Acer saccharinum</name>
        <family>Sapindaceae</family>
        <description>Acer saccharinum, commonly known as silver maple, creek maple,
        silverleaf maple, soft maple, water maple, swamp maple, or white maple — is a species of maple native to eastern
        North America in the eastern United States and Canada.
        It is one of the most common trees in the United States.</description>
        <bitmap>_fp_Silver Maple01.jpg</bitmap>
        <maxfile>objects\_fp_Silver Maple01.max</maxfile>
        <object>_fp_Silver Maple01</object>
        <matlib>matlibs\$(RENDERER).mat</matlib>
        <material>_fp_Silver Maple01</material>
    </item>
</library>

Custom actions (open website)​

Index.xml:

<?xml version="1.0"?>
<library version="100" order="1">
	<maxscript file="CustomActionsLibrary.ms" script='onLibOpen "CustomAction1";' execute_on="lib_open"/>
	<maxscript file="CustomActionsLibrary.ms" script='onItemSelect "CustomAction2";' execute_on="item_select"/>
	<select class="material" setmacro="CustomActionsLibraryRENDERER">
    	<option value="@CustomActionsLibrary.ms:getRenderer()" default="1">Automatic Selector</option>
    	<option value="scanline">Standard</option>
    	<option value="mentalray">MentalRay</option>
    	<option value="vray">VRay</option>
   	</select>
   <item class="maxobject">
    	<name lang="english">English Oak</name>
    	<name lang="latin">Querqus robur</name>
    	<family>Fagaceae</family>
    	<description>Quercus robur is commonly known as the English oak or pedunculate oak or French oak.
		It is native to most of Europe, and to Anatolia to the Caucasus, and also to parts of North Africa.</description>
    	<bitmap>_fp_English Oak01.jpg</bitmap>
    	<maxfile>objects\_fp_English Oak01.max</maxfile>
    	<object>_fp_English Oak01</object>
    	<matlib>matlibs\$(RENDERER).mat</matlib>
    	<material>_fp_English Oak</material>
   </item>
   <item class="maxobject">
    	<name lang="english">Holm Oak</name>
    	<name lang="latin">Quercus Ilex</name>
    	<family>Fagaceae</family>
    	<description>Quercus ilex, the evergreen oak, holm oak, or holly oak is a large evergreen oak native to the Mediterranean region.
		It takes its name from holm, an ancient name for holly. It is a member of the white oak section of the
		genus, with acorns that mature in a single summer.</description>
   	 	<bitmap>_fp_Holm Oak01.jpg</bitmap>
    	<maxfile>objects\_fp_Holm Oak01.max</maxfile>
    	<object>_fp_Holm Oak01</object>
    	<matlib>matlibs\$(RENDERER).mat</matlib>
    	<material>_fp_Holm Oak01</material>
   </item>
   <item class="maxobject">
    	<name lang="english">Silver Maple</name>
    	<name lang="latin">Acer saccharinum</name>
    	<family>Sapindaceae</family>
    	<description>Acer saccharinum, commonly known as silver maple, creek maple, silverleaf maple, soft maple, water maple, swamp maple,
		or white maple — is a species of maple native to eastern North America in the eastern United States and Canada.
		It is one of the most common trees in the United States.</description>
    	<bitmap>_fp_Silver Maple01.jpg</bitmap>
    	<maxfile>objects\_fp_Silver Maple01.max</maxfile>
    	<object>_fp_Silver Maple01</object>
    	<matlib>matlibs\$(RENDERER).mat</matlib>
    	<material>_fp_Silver Maple01</material>
   </item>
</library>