Creating Geometry

In this example we will write a script to draw a simple set of stairs. When we're done it will look something like this:

Step 1: Create a menu item

Using your favorite text editor, create a file called stairs.rb. Type the following lines of code into the file and save it into your Plugins directory.

# First we pull in the standard API hooks.
require 'sketchup.rb'

# Show the Ruby Console at startup so we can
# see any programming errors we may make.
Sketchup.send_action "showRubyPanel:"

# Add a menu item to launch our plugin.
UI.menu("PlugIns").add_item("Draw stairs") {
  UI.messagebox("I'm about to draw stairs!") 
}

Lines which start with a pound sign (#) are comments, meaning they do not execute. But everything else is an API command. The code that is contained between the curly braces { ... } will be run when you select our menu item. Right now all we're doing is showing a messagebox.

Let's check to see if it's working. Be sure the file is saved then restart SketchUp. If everything's gone well, you'll be able to launch our plugin by selecting Plugins > Draw stairs from the main menu.

If something doesn't work, check the Ruby Console for error messages that can help you track down the typo.

Step 2: Create a method to call

We could put all of the commands to draw our stairs directly between the curly braces { ... } mentioned above, but our code will be more reusable if we define a method instead. Add the following to the bottom of our script file:

def draw_stairs
  # Get "handles" to our model and the Entities collection it contains.
  model = Sketchup.active_model
  entities = model.entities

  # Create a series of "points", each a 3-item array containing x, y, and z.
  pt1 = [0, 0, 0]
  pt2 = [9, 0, 0]
  pt3 = [9, 9, 0]
  pt4 = [0, 9, 0]
  
  # Call methods on the Entities collection to draw stuff.
  new_face = entities.add_face pt1, pt2, pt3, pt4
end

The Sketchup module referenced above is a common entry point for getting handles to most everything inside SketchUp. In this case, we're not yet making stairs but taking the baby step of adding a face to our entities, which is just a fancy way of saying "drawing a square."

Note:In SketchUp, axes are highlighted with a color. The x axis is along the red line, the Y axis is along the green line, and the Z is along the blue.

To test this code, add these highlighted lines to our menu item block { ... }:

# Add a menu item to launch our plugin.
UI.menu("PlugIns").add_item("Draw stairs") {
  UI.messagebox("I'm about to draw stairs!")
  
  # Call our new method.
  draw_stairs
}

Restart SketchUp. If everything went well, then selecting our menu item will now create a 9"x9" square at the model origin:

Step 3: Use variables and loops to start climbing

Now let's expand our code to draw multiple stairs. We will build on how we drew the square, but instead of using hard coded points we will calculate new ones with some variables. Replace the old draw_stairs method with this one. Note the similiarities from before:

def draw_stairs

  # Create some variables.
  stairs = 10
  rise = 8
  run = 12
  width = 100

  # Get handles to our model and the Entities collection it contains.
  model = Sketchup.active_model
  entities = model.entities

  # Loop across the same code several times
  for step in 1..stairs
    
    # Calculate our stair corners.
    x1 = 0
    x2 = width
    y1 = run * step
    y2 = run * (step + 1)
    z = rise * step
    
    # Create a series of "points", each a 3-item array containing x, y, and z.
    pt1 = [x1, y1, z]
    pt2 = [x2, y1, z]
    pt3 = [x2, y2, z]
    pt4 = [x1, y2, z]

    # Call methods on the Entities collection to draw stuff.
    new_face = entities.add_face pt1, pt2, pt3, pt4
  end

end

Now we're getting someplace interesting! Restart SketchUp and give it a try. You should see a series of faces that form a staircase:

Step 4: Get thick with Push/Pull

Push/Pull is a powerful tool for manual modeling in SketchUp. It is also a powerful command inside the Ruby API. Specifically, pushpull is a method that can be called on any Face. Add the following highlighted lines to our draw_stairs method:

def draw_stairs

  # Create some variables.
  stairs = 10
  rise = 8
  run = 12
  width = 100
  thickness = 3

  # Get handles to our model and the Entities collection it contains.
  model = Sketchup.active_model
  entities = model.entities

  # Loop across the same code several times
  for step in 1..stairs
    
    # Calculate our stair corners.
    x1 = 0
    x2 = width
    y1 = run * step
    y2 = run * (step + 1)
    z = rise * step
    
    # Create a series of "points", each a 3-item array containing x, y, and z.
    pt1 = [x1, y1, z]
    pt2 = [x2, y1, z]
    pt3 = [x2, y2, z]
    pt4 = [x1, y2, z]

    # Call methods on the Entities collection to draw stuff.
    new_face = entities.add_face pt1, pt2, pt3, pt4
    new_face.pushpull thickness
  end

end

As you can see, you can create ever more complex geometry from the API using the same steps you might use manually in SketchUp, but do it in milliseconds:

Conclusion

Experiment with changing the variables to build stairs of all kinds. (Extra credit: You can make fences by setting the rise = 0, or walls with run = 0!)

Adding edges, construction lines, circles, etc. is all done in a similar fashion to the faces we made above. See the Entities documentation for the various ways to add geometry and you'll be well on your way to being a Ruby API master.