Paul Toone avatar image
Paul Toone posted

Custom Libraries Concepts   



FlexSim lets you create and configure special libraries in addition to the standard library set. These are referred to as user libraries. You can create custom defined functionality on objects, and then add those objects to a library for use in other parts of your model or in other models. You can save these libraries and then load them into other projects later on. You can also define a set of objects in the library to be automatically installed to your model when a new model is created or when you load the library.

You can create new User Libraries and Open User Libraries from the File Menu.

The custom library, or user library, mechanism provides you with flexibility in many areas. The most widely used functionality of the user libraries is to reuse customized objects in a model, but you are not confined to only that functionality. User libraries allow you to automatically install custom objects and data into models, install objects and data into the main project and view tree, and execute code when an object in the icon grid is dropped into the model. All of this functionality stems from two mechanisms within the user library functionality. First is the droppath and dropscript mechanism, which allow you to customize what happens when an object is dropped into that model. Second is the automatic install mechanism, which allows you to install objects or data when the user does operations like creating a new model or opening a model. This topic will discuss these two mechanisms in detail.

Adding objects to a custom library

There are several types of objects that you can add to a user library. You will most commonly add a standard object like a Processor or Queue whose properties you have modified to fit a custom modeling situation. You could also start from scratch with a BasicFR or BasicTE object, implement your custom behavior, and then add it to a library. Another possibility is to use a VisualTool as a container of a sub-model, and add the whole sub-model to the library. To add these types of objects to a user library, right click on the object in the 3D model view and select Edit > Add to User Library.

If you already have User Libraries loaded, a list of those libraries will appear in the right click menu.

You can also add GUIs, Global Tables, Flowitems, and User Commands to a custom library. You can access this capability from the windows in which you edit these respective objects. The figure below shows a menu option in the GUI editor to add the GUI to a library.

Editing Library Objects

When an object is added to a library, a copy of the object is created and put in the library. This means that once it is added in the library it has no more linkage to the original object. It is a copy and can be changed on its own, separate from the original object.

The User Library is stored in the Main Tree in the userlibrary node.

You can also access the properties of your library object through the right click menu on the Library Icon Grid.

Saving / Removing Libraries

To Save or Remove a User Library, click the arrow next to the User Library in the Library Icon Grid.

Dropscript and Droppath

The droppath and dropscript mechanism allows you to customize what happens when an object is dropped into the model. This is done by creating a custom object in the user library, and then adding either a "dropscript" or a "droppath" attribute to the object and specifying the data for the dropscript or droppath.


If a dropscript attribute is added, then the dropscript node will be executed as flexscript, and values will be passed into the flexscript function that give it information about the drop.

Note: In order for an object to display in the Library Icon Grid, it needs to have a picture attribute as shown above in our Custom object.

There are 5 access variables you can get within the dropscript function. They are:

parnode(1) - the object that was dropped onto. If the user dragged onto a blank area in the model, then this variable will be 0, or NULL. In such a case, you can usually assume that the user intends to drop it into the model. However, this is not always the case. For example, the user may drop the object into a 3D view that is viewing a subspace of the model, like a VisualTool. To ensure a safe drop in this case, you should use the viewfocus of the view as the drop point: node(">viewfocus+", parnode(5)).

parval(2), parval(3), parval(4) - the x, y and z location of the drop, respectively. If the parnode(1) is NULL, then this is the location within the model space (or the view's viewfocus' space). If parnode(1) is not NULL, then this is the location within parnode(1).

parnode(5) - the view window onto which the object was dropped. Use node(">viewfocus+", parnode(5)) to get access to the viewfocus of the view.

If within the dropscript function you would like to do a standard object drop, as if it were a regular user library object being dropped, then you can use dropuserlibraryobject command. This command executes the same functionality as when a regular object is dropped from a user library object. The first parameter is the object to drop, and the next five parameters are the onto object, x, y, z, and onto view, just like the dropscript function itself. The command returns a reference to the object that was created.

Return Value - Your dropscript function should also return a reference to the object you created. This allows FlexSim to do some extra work like checking to see if there were any c++ nodes created, and if so, set a flag to notify you that you need to compile the next time you run the model.

The dropscript mechanism allows you ultimate flexibility with user libraries. You can use it in the standard way, for example to do a regular object drop but also execute some extra code to initialize the dropped object. You can also use it in more non-standard ways. Some ideas may be to use a dropscript to add a curved or straight section to a conveyor belt, or to add levels or bays to a rack object. You could also use a dropscript to add code to triggers of an object, or to set certain parameters of the object. You could add collision spheres to an object, or add a set of functionality to the model's tools folder. There are any number of possibilities.

Refer to the Example page for examples on using the dropscript node.


The droppath mechanism is a method of indirection. It is a way that you can refer to another object that you want to be dropped when the icon is dropped into the model. This is usually used with automatic install functionality, but it can also be used with an icon in the icon grid. The method of creating a droppath object is the same as for creating a dropscript. You add an object to the library, and give it object data, but this time you give it an attribute named "droppath". You should not toggle the node as flexscript, but should give text data to the droppath attribute and specify in the text a path to another object that should be dropped.

For example, you may give the droppath attribute the text: MAIN:/project/library/NetworkNode. This will effectively cause a network node to be created when you drag your object's icon into the model. You might ask why not just add a network node to the user library, or why not just make them go to the regular library and drop a network node from there. To the former question, if you plan on using this user library for a long time, you may want the network node to be compatible with future versions of FlexSim. You may want to drop whatever is the latest version of the network node, without having to update the user library with each new version. Also, why have redundant data in your user library if all of it is already there in the regular library? To the latter question, it may be useful to have the network node as a droppable icon in your library if the user uses the object often. It reduces the number of mouse clicks needed.

The droppath can either be an absolute path MAIN:/project/library/fixedresources/Processor or relative ..>Processor.

Automatic Install

The automatic install mechanism allows the user library to install objects and functionality to the model when the user performs certain actions like creating a new model, or opening a model. Automatic install is available through FlexSim's user interface for GUIs, Global Tables, Flowitems, and User Commands.

To create a custom automatic install, you can add special nodes to the user library object. The specific set of valid node names are listed as follows:

newmodelinstall - This node is installed when the user creates a new model. It is also installed when the library is loaded.

startupinstall - This node is installed when the library is loaded if the user has designated this library as a library to load during startup.

loadinstall - This node is installed when the library is loaded explicitly by the user.

openmodelinstall - This node is installed when the user opens an existing model. You may use this node to check if the model contains the library's components, and if not, installs them. You could also use it to update components in the model if those components are from an earlier version of the user library.

Customizing the Library Icon Grid

There are a few attributes that can be added to objects in your custom library that will affect they way they are displayed by the Library Icon Grid.

Note: Some visual attributes will not be update in the library icon grid without closing and reopening the view.


The picture attribute specifies the path to an image to display in the icon grid. Leaving the path blank will display the object name only. To give your object a Processor image, your picture attribute would contain the path:


You can also specify the left alignment by changing the picturealignleft node value.

Icon Grid Width and Height

You can designate the size of icons in the library icon grid. Just give the library attributes named "cellwidth" and "cellheight". Each attribute should contain a number that is the width and height of one icon in the icon grid in pixels.

flexsim users manual
5 |100000

Up to 12 attachments (including images) can be used with a maximum of 23.8 MiB each and 47.7 MiB total.



paul.t contributed to this article


FlexSim 2016.1