Customizing the action menu (manually)
See here for a video explaining this topic: YouTube
To add your own entries to the action menu you can add a subfolder
to the config/actionMenu folder, and define the menu layout in a file named 'layout.json'.
(Although you can edit the existing layout.json in the 'default' folder that is already there,
this is not recommended because the default menu may be changed in future releases of R.U.B.E, and
it also makes it inconvenient to share your scripts with others.)
Let's look at an example of adding a simple custom menu by manually editing the layout.json file.
We'll create a script that selects all bodies with names that match a string entered by the user.
The script can be edited and tested in the script panel, and then
saved to a file with an '.rs' extension. The file should be placed in a subfolder of the config/actionMenu folder, with
layout.json in the same place.
Menu entries will be added
to the action menu in alphabetical order of the subfolder names. To ignore a subfolder, you can
add a hyphen to the end of the folder name.
layout.json format
The contents of layout.json to display a menu entry for this script would be as follows.
The root object of the JSON file should have an array property called 'children' which contains
a list of menu entries to add to the root level of the action menu. The menu entries are objects
with the properties explained below.
name
The name property defines the label to display in the menu. You can specify shortcut keys by
placing an ampersand in front of one letter in the name. The menu resulting from the layout.json
above will look like this (here, the menu could be accessed via the keyboard by hitting
Space, C, B).
type
The type property can be 'menu' or 'action'.
'menu' will cause a sub-menu to be added to the
action menu, in which case you should also add a 'children' array property as for the root object.
'action' becomes a reference to a script file, in which case you should also add 'file' and
'desc' properties as well.
type
For entries of type 'action', the 'file' property specifies the script file to use for the action.
The '.rs' extension should be omitted, and no path needs to be given.
desc
The 'desc' property allows you to set a description for what the script does, which will be shown
in undo/redo displays.
Optional properties
For entries of type 'action', you can specify that the menu should be grayed out if the necessary
items are not selected in the scene. For example to create a joint, two bodies must be selected.
It's more user-friendly to show a grayed out menu indicating that an action is not
available, rather than letting them select it and then have nothing happen, or show a message after the fact.
You can use the following optional properties to check for a minimum or maximum number of currently
selected items. If any of the required conditions are not met the menu entry will be grayed out.
- minBodies - at least N bodies must be selected
- maxBodies - no more than N bodies should be selected
- minFixtures - at least N fixtures must be selected
- maxFixtures - no more than N fixtures should be selected
- minVertices - at least N vertices must be selected
- maxVertices - no more than N vertices should be selected
- minJoints - at least N joints must be selected
- maxJoints - no more than N joints should be selected
- minImages - at least N images must be selected
- maxImages - no more than N images should be selected
As an example, here is the 'Weld vertices' action menu entry from the default menu, which requires
that at least two vertices be selected.
