Golden Rules of SketchUp Plugin Development

The Ruby language is very easy to extend to suit your needs. Some very pretty looking code can be written.

However, when you write plugins for SketchUp’s Ruby API you should be careful. The environment is shared between all plugins, so there is a good risk of clashes if you do not “play nice”. Here’s an overview of important points to remember when you develop plugins for Google SketchUp.

Never modify existing base methods that ships with SketchUp

This is one golden rule one should adhere to at all times! You might have an improved version of one of the base classes that makes the code cleaner and more efficient. The problem is that other plugins will be relying on the original behaviour and will therefore break. Causing frustration among users and developers. It is something that will quickly send a plugin to the blacklist – where the SketchUp community will discourage the use of the offending plugin.

What to do instead? Just accept that the code needs some extra syntax and keep your improved method within your own namespace.

Avoid adding methods to the global namespace

If you write a plugin without wrapping the code in a module or class you are actually adding the methods to the Kernel class. Since every class inherit Object, and Object inherit Kernel, these methods becomes available to all other classes. Causing potential for conflict everywhere.

Avoid global variables

For the same reasons you should avoid methods in the global space, avoid global variables and constants. Keep it contained to your own namespace. (That’s the general jest of playing nice and safe in the SketchUp Ruby API world.)

Avoid extending base classes and modules

It can be tempting to extend base classes with extra methods with the intention of writing pretty code. It is in effect the same as adding method to the “global namespace”. You cannot be sure that no one else attempts to add a method with the same name. Nor can you be sure that name might be used by the official API in the future.

Staying on the safe side

Due to the shared nature of SketchUp’s Ruby API environment, the safest way to avoid clashes is to wrap all your code in a carefully picked namespace which you hope will be unique. Over at SketchUcation the common convention is for developers to use their initials as prefixes for the root namespaces they use for their plugins.

I would for example use module names like TT_MyNewCoolPlugin. (Though my recent ones are located under TT::Plugins – ie. TT::Plugins::HelloWorld.)

If you extend a base class for any reason you are much more likely to run into clashes with other plugins. And that doesn’t just cause problems for you, but also your users, the developer of the other plugin and his users. And a whole lot of time end up being consumed trying to track down the source of unexpected behaviour.

In order to play nice and make your plugin as robust as possible, keep everything neatly wrapped in modules with carefully crafted names to reduce possible clashes.

An Hello World example that “plays nice”

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

require 'sketchup.rb'
 
module NN_MyOwnUniqueNamespace
  
  unless file_loaded?( __FILE__ )
    menu = UI.menu( 'Plugins' )
    menu.add_item( 'Hello World' ) { self.hello_world }
  end
  
  # Use instance variables inside modules instead of global variables.
  @my_variable = 'Hi there! :)'
 
  def self.hello_world
    puts @my_variable
  end
 
  file_loaded( __FILE__ )
 
end # module

require 'sketchup.rb'
 
module NN_MyOwnUniqueNamespace
  
  unless file_loaded?( __FILE__ )
    menu = UI.menu( 'Plugins' )
    menu.add_item( 'Hello World' ) { self.hello_world }
  end
  
  # Use instance variables inside modules instead of global variables.
  @my_variable = 'Hi there! :)'
 
  def self.hello_world
    puts @my_variable
  end
 
  file_loaded( __FILE__ )
 
end # module