Monkey Script Compiler

SummaryHow to use the Script Compiler

What is the Script Compiler?

The Monkey Script Compiler is a standalone executable which does not rely in any way on the Monkey Script Editor Plugin. You do need to have Rhino4 installed on your machine in order for the Compiler to work. The Compiler is a little application which enables you to convert RhinoScript files (*.rvb extension) into Rhino plugins (*.rhp extension). The benefits of this are:

Script code is encapsulated (made unreadable)
Scripts become linked to custom commands which autocomplete in Rhino and which can be scripted in turn
You can add menus which run your scripts or other macros
Distribution is easier
Plugins can be license protected
You can package script library files

The disadvantages of compiling your scripts into plugins are:

Scripts become unreadable and can thus no longer be changed in situ. They have to be recompiled.
The plugin might not load on other versions of Rhino, even though the scripts might have worked.

The Compiler follows the standard Windows Wizard UI. You can start it from within Rhino (using the Monkey menu) or you can launch the Compiler by double clicking on the application. Also, if you have an *.mcp file (Monkey Compiler Project) on your system, you can double click that file, and the compiler will start and load the project automatically. Alternatively, you can drag and drop a number of *.rvb files from Windows Explorer onto the Compiler icon and it will create a new project for those script files.

Note that the *.mcp format does not store the contents of the referenced script files, merely their location on the disk. If you rename/delete/move script files that are linked to a project, they will fail to load.

Contact the author

Join or start a discussion

What is the Script Compiler not?

Plugins for Rhino are written either in C++ or a DotNET compliant language such as VB.NET or C#. Instead of the RhinoScript methods, plugins use the much more powerful Rhino SDK and since plugin code is compiled into binaries, they run a lot faster than scripts. This is not the case for Monkey Compiled plugins. Although the actual plugin is a precompiled binary which talks to Rhino via the SDK, your scripts are merely encapsulated and they will be extracted at runtime and run as though they are normal scripts. You will not see any difference in execution speed.

The 3 Steps to Victory

The Monkey Script Compiler is an easy to use piece of software that doesn't require an understanding of C++, DotNET or the Rhino SDK. Since chances are good that you are a programmer though (you may not be compiling your own scripts of course, it's just statictically more likely that you are), I will use programming jargon to explain how the Compiler works. Most of the following doesn't require more than a basic understanding of logic and software though.

The Monkey Script Compiler is a Wizard like application that guides you through the three requird steps (and two optional ones) needed to make a compiler project. If you start the application, you will see the welcome page of the Script Compiler:

which provides some basic information about how to use the app. If you click on the [Next] button, you will be starting with a blank plugin project. This is what we're going to do, but if you already have a plugin project file (*.mcp) you can load it by dragging it into the Load icon in the lower left corner of the welcome page.

Step 1: Plugin attributes

However, since this is the first time we're using the compiler, we do not have an existing *.mcp file and we need to start with a blank project. Thus we press the [Next] button, which takes us to the Plugin Attributes page. If you open the plugin manager in Rhino, you can access the properties of all loaded plugins (use the menu of the plugin listbox). These properties include:

Name
Version
Type
Load time
All defined commands
All defined filetypes
Manufacturer details
Technical information

Some of these can be set to custom values:

In this picture, I have already filled out all the fields. There are two things you need to know here. First, the plugin name must be a valid VB variable name. Thus, you are not allowed to use any weird characters, you are not allowed to use spaces (but you can use underscores), and you cannot start the name with a number. If you enter an invalid name the field will become red and the [Next] button will be disabled. Note that whenever the [Next] button is disabled, there is something wrong with your settings. Whenever this happens there will be a link to the left of the [Next] button which lists all problems.

The Organization and Website attributes are important if you plan to enable License protection. See the licensing section for further details.

Step 2: Plugin commands

Once we have specified a vald name for our plugin, the [Next] button on the Attributes page will be enabled and we can move on the Commands page:

Since we started a blank project, there are no referenced script files yet. We can add script references either by dragging them from Explorer into the list, or by using the [Add Script] button. Since we are still in the process of adding scripts, the [Next] button is disabled. You need to reference at least one script before you can move on.

If you drag files, they will be given default attributes, if you use the [Add Script] button the command attribute dialog will be shown immediately. The image above shows that I dragged six files into the command list:

FirstScript.rvb
SecondScript.rvb
ThirdScript.rvb
FourthScript.rvb
FirstLibrary.rvb
SecondLibrary.rvb

All these files have been given default attributes, as we can see below; they all have the same icon:

By default a referenced script will become a command named the same as the file. However, I want something more specific. I have two library scripts, which contain code that is used by the other scripts, and they should not be exposed as commands. Also, FourthScript.rvb contains some secret functionality and I don't want the command to be generally known. I need to change the script attributes in order to achieve this (double click the script in the list, which will display the script attribute dialog):

Here you see the properties of the FirstLibrary.rvb script, after I checked the Library option (it is off by default). Library scripts are no longer treated as commands and all the other options are therefore disabled. Library scripts will be loaded into the script engine prior to any command calls in their plugin. It is therefore important that you do not put any executing code into library files.

We also have to tag SecondLibrary.rvb as a library component, and we have to set the flag "Hide command" for the FourthScript.rvb. If you hide a command, it will not autocomplete in the command line and it will not be visible in the Plugin Properties dialog in the Rhino Plugin Manager.

After we have set all specific flags, the Command page looks as follows:

You can see that the library and hidden scripts have gotten a different icon and we are ready to move on to Step 3. Do note that command named (like the plugin name) must adhere to Visual Basic variable naming conventions.

Step 3: Compilation settings

The last required step (which is valid by default) is to specify certain compilation settings. The Monkey Script Compiler has quite a few compilation settings, some of which are rather advanced and have a section of their own. The Compile page looks like this:

The compilation settings have been grouped under three categories: "Destination", "Compiler options" and "Load options". The Destination is simple, here you specify where the plugin *.rhp file is supposed to end up. The folder has to exist, or you will not be allowed to compile. By default, plugins will be put on the desktop. Upon compilation you are free to move the plugin file wherever you like, it will run from any location.

There are two Compiler options available; encryption and license protection . The Script Compiler will encapsulate the referenced script files, but it is still possible for a hacker to reverse-engineer the original scripts. This is not easy to do, but if you are worried about this, you can enable encryption, which will encrypt the scripts with a 'private-key stream-cipher algorithm' making it much harder (but not impossible) to extract original script text. Encryption comes with a cost though, the scripts have to be decrypted before they can be run which results in a delay which becomes noticeable on large scripts.

See the licensing section on more information on plugin licensing.

It is possible to save the project from the Compile page. Click on the Project icon button to save your *.mcp file to the disk. Note that this file contains all data required for a project (apart from the script contents, which are freshly loaded every time) including sensitive licensing info. Do not give this file to anyone if you have licensing enabled.

The Load options determine how your plugin behaves when it is loaded. You can create a plugin menu which will be added to Rhino when the plugin loads. See the section on menu specification for further details. You can also specify whether your plugin loads at Rhino startup or when it is needed (i.e. the first time when a command in your plugin is called). Generally, plugins are loaded when needed, but if you have defined a menu, you may want to load the plugin right away or else the menu will not be visible. Also, you can specify a message to print when the plugin loads. The following screenshot shows custom compilation settings for our example project:

We are now ready to compile the plugin. In theory, since the [Compile] button is enabled we should encounter no problems. However, this is beta software and it is possible we have missed some rare case which causes problems. If everything goes well, you will see the following, final page of the Wizard:

If the compilation failed, the central textfield will contain the compiler report, with all errors and warnings that were encountered. If you experience a failed compile, please send the content of this texfield to the developer

Plugin menu

The Script Compiler comes with a menu editor which allows you to create a fully customized menu. This menu will be inserted at the end of the Rhino main menu (but before the "Help" menu) when the plugin is loaded. By default, a plugin does not define a menu so you have to specifically enable this on the Compile options page. If you check the [Create plugin menu] option, the [Menu editor...] button will be unlocked. There is a default menu setup, which will be created whenever you first enable the plugin menu. It consists of a root item which has a similar name as the plugin, and a simple list of all non-hidden commands in the plugin:

Let's say that we want some more commands in there that are useful macros for people who are using our scripts. We want to make them slightly less important that the actual commands, so we'll separate the two groups and even nest some of them. First however, we add the items using the buttons on the toolbar. Menu items come in three flavours; active items, parent items and separators. Parents and separators do not have macros assoiated with them, and separators have no names either. Only active items do something. You can specify both the name and the macro of an item. When you select an item in the tree, its properties will be loaded. You can also change the name of an item directly in the tree:

Whenever you add an item (be it a menu item or a separator) it will be appended to the currently selected item. Since the root item is selected by default, we ended up with a straight list of new items. We can reorder items by dragging them around. Since you need to be able to both reposition and nest items, the dragging in the editor works slightly different from what you're used to:

If you drag an item in between two existing ones, you will reposition it
If you drag an item onto the end of an existing one, you will nest it

Feedback is drawn in the tree so you always know what happens when you drop a an item in a particular spot. The image below shows a drag operation which will result in a nesting:

When we're done reordering our menu structure, we can click [OK] to return to the Compile page. When we compile this plugin, the menu in Rhino looks like this:

WHAT THIS PAGE SHOULD NOT BE VISIBLE ERROR MEANS IN COMPILING WHICH PAGE CAN ANYONE EXPLAIN