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:
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.
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:
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:
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:
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.
Extra credit:
Draw some risers that are shaped like circles. (Hint: replace the line with add_face to use entities.add_circle)
Add a handrail. You can do it!
After running your script, select Edit > Undo in SketchUp. Note how each little operation is an undo step. Let's group those operations together!
Change your menu handler to something like this...
UI.menu("PlugIns").add_item("Draw stairs") { Sketchup.active_model.start_operation "Draw Stairs"
draw_stairs Sketchup.active_model.commit_operation }