SketchUp ships with a number of simple examples to help you get started programming with Ruby. The examples illustrate some of the techniques that you can use in a script.

Note - These example scripts are not the same as the example scripts that demonstrate how to use each individual method.

Location of Example Scripts

When SketchUp starts up, it will automatically load any scripts that it finds in the Plugins folder. Ruby scripts have the extension .rb. Additional example scripts are located in a sub-folder of the Plugins folder called Examples. 

The location of the Pluginsfolder varies depending on whether you are running on OS X or Windows.

MacOS X

On OS X,the plugins are installed in the Pluginsdirectory within the application bundle. The scripts that ship with SketchUp are installed in:

/Contents/Resources/Plugins

The examples are in:

/Contents/Resources/Plugins/Examples

Microsoft Windows

On Windows, the plugins are installed into the same folder where you install SketchUp. This location may vary depending on where you installed SketchUp. The default location is:

C:\Program Files\Google\Google SketchUp 6\Plugins

The examples are in:

C:\Program Files\Google\Google SketchUp 6\Plugins\Examples 
 

Loading Scripts

You must load Ruby scripts before you can test them. Scripts can be loaded manually through the Ruby console, automatically using the Plugins folder, automatically using the requireRuby command, and automatically using the require_all Ruby command.

Manually Loading a Ruby Script

The Ruby console can be used to load and test your Ruby scripts. To load and test a Ruby script using the Ruby console:

1. Display the Ruby console by select View > Ruby Console from the main SketchUp menu (The Ruby Console is actually added to the View menu when the Ruby script sketchup.rb is loaded upon execution of SketchUp)

2. Type load 'examples/box.rb' in the Ruby Console's text entry box to load the box.rb Ruby script from the Plugins/Examples directory. The load command is used to load any ruby commands from within the Ruby Console and SketchUp adds the Plugins folder to the path to look for Ruby scripts. The Ruby Console will display "true" if there are no syntax errors in the file. Otherwise the Ruby Console displays error messages and the associated line numbers where the errors were found. Use these error messages to test and debug your script.

This method of loading Ruby scripts is the best method to test and debug Ruby scripts. Use one of the following methods  to load your script automatically when SketchUp starts once you have tested and debugged your script.

Automatically Loading A Ruby Script from the Plugins Folder

You can automatically load your Ruby scripts from the Plugins folder once they have been tested and debugged. To automatically load a Ruby script from the Plugins folder:

1. Ensure that your script has the .rbextension. Any files with the extension .rbthat are in the Pluginsfolder are automatically loaded when you start SketchUp.

2. Copy the Ruby script into the SketchUp Pluginsfolder.   

While this method easy automatically loading scripts, consider one of the following loading methods to load multiple scripts at the same time and avoid possible name conflicts.

Automatically Loading a Ruby Script Using the "require" Ruby Function

The SketchUp installation might overwrite any script in the Plugins and Plugins/Examples directory with identically named scripts in future releases of SketchUp. However, you can create a script that auto-loads your Ruby scripts from locations that SketchUp will not touch. For example:

require'c:\myrubyscriptsdirectory\cylinder.rb'

Create a script file that is named uniquely, such as MyRubyScripts.rb. This file will contain a require command for each of the scripts you do not want overwritten by the SketchUp installation program. For example, to ensure the c:\myrubyscriptsdirectory\cylinder.rbfile doesn't get overwritten by a newer copy, place the following command in the MyRubyScripts.rb file:

Note - You may also want to reference scripts in the Example directory as a mechanism to auto load these scripts when SketchUp loads. New versions of the examples that are overwritten by a future SketchUp install will be auto loaded by the MyRubyScripts.rb file.

Load SketchUp. SketchUp will read the MyRubyScripts.rb file in the Plugins directory and load any scripts that the file references, such as box.rb.

Automatically Loading a Ruby Script Using the "require_all" Function

The sketchup.rbfile defines a require_allfunction which requires all files with the extension .rb in a given folder. Another good option for automatically loading Ruby scripts is to create your own folder of Ruby scripts (outside of the Pluginsdirectory) and add that directory to the sketchup.rbfile. For example, to load all scripts in the myrubyscriptsdirectory:

1. Create a directory in a directory, such as C:\ (windows) or your home directory (OS X), called myrubyscriptsdirectory.

2. Create file called myRubyScripts.rbcontaining the following line of code on Windows:

require_all("C:\myrubyscriptsdirectory")

Or for the OS X:

home = File.expand_path "~"
myrubyscripts = File.join home, "MyRubyScripts"
require_all( myrubyscriptsdirectory )

The Example Scripts (in the Plugins directory)

 The following Ruby scripts are located in the Plugins directory and are loaded by default.

examples.rb

This example contains three methods: setLayer, totalArea, and perimeter. The setLayer method sets the layer of all selected entities to a layer with a given name (you must provide the layer name). The totalArea method computes the total area for all faces in a model. The perimeter method computes the perimeter of the selected faces. Methods in this file can be loaded by typing the function name in the Ruby console. For example:

setLayer layername

extensions.rb

This file contains the base class for extensions.

utilities.rb

This example creates three new tools in the Utilities sub-menu in the Tools menu: Create Face, Query Tool, and Fix non-planar faces. The Create Face tool is used to recreate a face for three intersecting, co-planar lines in the event that the face has been deleted. You must select the three or more lines prior to selecting this menu item.

The Query Tool displays mouse coordinates in the VCB as you move the mouse around the screen.

The Fix non-planar faces tool is used to find and fix non-planar faces in your model.

The Example Scripts (in the Examples directory)

The following Ruby scripts are located in the Examples directory within the Plugins directory. Go to Preferences > Extensions within SketchUp and check the Ruby Script Examples checkbox to see how these scripts work. SketchUp will automatically load these scripts when you check this checkbox. Checking this checkbox also adds the following items to the menus: Draw > Box, Plugins > Cost, and Camera > Animations. Note: Do not change or move these scripts as you will break the functionality of the previously mentioned menu items.

animation.rb 

This example shows how you can create animations in Ruby. The animation.rb example creates a simple animation that spins the camera around.



This example adds a menu item called Animations at the end of the Camera menu. The Animations menu contains two options: spin view and stop spinning. Select spin view to rotate the camera continuously around your model. Select stop spinning to stop the spin view.

attributes.rb 

This example shows how to attach arbitrary application specific attribute data to SketchUp entities. The attributes.rb example also illustrates the use of input boxes to get data from the user and how to query data on the model using cost data information to compute a simple materials cost estimate.



This example adds a Cost menu item to the Plugins menu. The Cost menu contains three items: Assign Estimate to Material, Assign Estimate to Faces, and Computer Estimate. Select Assign Estimate to Material to assign a per/foot cost to all items with a specific material. Select Assign Estimate to Faces to assign a per/foot cost to all selected faces. Select Compute Estimate to get a dollar amount for the currently calculated estimate.

box.rb 

This example shows how to create simple geometry using Ruby. Additionally, the box.rb example shows how to create a dialog box to prompt for user input and how to add an item to a menu.

This example will add a menu item called Box at the end of the Draw menu when loaded. This menu item displays a dialog where you input the size of the box you want to create and then, after clicking OK, creates the box.

contextmenu.rb  

This example shows how you can add new choices to context menus. The contextmenu.rbexample adds a Point at Centeritem to the context menu for arcs and circles to create a point at the center of the arc or circle. To use this feature, create an arc or circle and context click on the arc or circle to use Point at Center (bottom-most option).  

exampleScripts.rb  

Loading exampleScripts.rb loads all of the examples in this section.

linetool.rb 

This example shows how you can create tools that respond to mouse events in Ruby. The linetool.rb example defines a simple tool that behaves similar to the pencil tool in SketchUp except that it creates finite length construction lines instead of regular SketchUp edges.

The following command will load the linetool.rb example:

Sketchup.active_model.select_tool LineTool.new

selection.rb 

This example contains a number of examples of how to traverse a model and select geometry. Methods in this file can be loaded by typing the function name in the Ruby console. For example:

select_by_material