Release Notes

The SketchUp API has been around in some fashion since the early days of SketchUp, and with every release we have extended its capabilities. Read below for what's been changed.

Though our adoption rate to the latest version is quite high, it can take time after a release before everyone upgrades. If you are building scripts that rely on functionality from the most recent version, be sure to check the Sketchup.version to make sure your users are able to run your script:

# You do something like this in the initialization routine of your extension.
version_required = 16
if (Sketchup.version.to_f < version_required)
  UI.messagebox("You must have Sketchup 20#{version_required} to run this "\
                "extension. Visit sketchup.com to upgrade.")
else
  # Your stuff...
end

Build Numbers

Here are the build numbers for recent SketchUp releases. Note that build numbers in languages besides English are larger for each release, so it is best to check for builds that are greater than or equal to the numbers here.

  • SU2024.0 = 24.0.484 on Windows 64-bit, 24.0.483 on Mac 64-bit.

  • SU2023.1.3 = 23.1.340 on Windows 64-bit, 23.1.341 on Mac 64-bit.

  • SU2023.1.2 = 23.1.315 on Windows 64-bit, 23.1.314 on Mac 64-bit.

  • SU2023.1.1 = 23.1.313 on Windows 64-bit, 23.1.312 on Mac 64-bit.

  • SU2023.0.2 = 23.0.419 on Windows 64-bit, 23.0.418 on Mac 64-bit.

  • SU2023.0.1 = 23.0.397 on Windows 64-bit, 23.0.398 on Mac 64-bit.

  • SU2023.0 = 23.0.367 on Windows 64-bit, 23.0.366 on Mac 64-bit.

  • SU2022.0.1 = 22.0.354 on Windows 64-bit, 22.0.353 on Mac 64-bit.

  • SU2022.0 = 22.0.316 on Windows 64-bit, 22.0.315 on Mac 64-bit.

  • SU2021.1.2 = 21.1.332 on Windows 64-bit, 21.1.331 on Mac 64-bit. (Contained no Ruby API changes)

  • SU2021.1.1 = 21.1.299 on Windows 64-bit, 21.1.298 on Mac 64-bit.

  • SU2021.1 = 21.1.279 on Windows 64-bit, 21.1.278 on Mac 64-bit.

  • SU2021.0.1 = 21.0.391 on Windows 64-bit, 21.0.392 on Mac 64-bit. (Contained no Ruby API changes)

  • SU2021.0 = 21.0.339 on Windows 64-bit, 21.0.338 on Mac 64-bit.

  • SU2021.0 = 21.0.114 on Windows 64-bit, 21.0.113 on Mac 64-bit.

  • SU2020.2 = 20.2.172 on Windows 64-bit, 20.2.171 on Mac 64-bit.

  • SU2020.1.1 = 20.1.235 on Windows 64-bit. (Contained no Ruby API changes)

  • SU2020.1 = 20.1.229 on Windows 64-bit, 20.1.228 on Mac 64-bit.

  • SU2020.0 = 20.0.133 on Windows 64-bit, 20.0.134 on Mac 64-bit.

  • SU2019.3 = 19.3.253 on Windows 64-bit, 19.3.252 on Mac 64-bit.

  • SU2019.2 = 19.2.222 on Windows 64-bit, 19.2.221 on Mac 64-bit.

  • SU2019.1 = 19.1.174 on Windows 64-bit, 19.1.173 on Mac 64-bit.

  • SU2019 = 19.0.685 on Windows 64-bit, 19.0.684 on Mac 64-bit.

  • SU2018 M1 = 18.1.1180 on Mac 64-bit. (Contained no Ruby API changes)

  • SU2018 = 18.0.16975 on Windows 64-bit, 18.0.16976 on Mac 64-bit.

  • SU2017 = 17.0.18899 on Windows 64-bit, 17.0.18898 on Mac 64-bit.

  • SU2016 = 16.0.19912 on Windows 64-bit, 16.0.19911 on Windows 32-bit, 16.0.19913 on Mac 64-bit.

  • SU2015 M2 = 15.2.685 on Windows 64-bit, 15.2.687 on Windows 32-bit, 15.2.686 on Mac 64-bit.

  • SU2015 M1 = 15.1.106 on Windows 64-bit, 15.1.105 on Windows 32-bit, 15.1.104 on Mac 64-bit.

  • SU2015 = 15.0.9350 on Windows 64-bit, 15.0.9351 on Windows 32-bit, 15.0.9349 on Mac 64-bit.

  • SU2014 M1 = 14.1.1282 on Windows, 14.1.1283 on Mac.

  • SU2014 = 14.0.4900 on Windows, 14.0.4899 on Mac.

  • SU2013 M2 = 13.0.4812 on Windows, 13.0.4811 on Mac.

  • SU2013 M1 = 13.0.4124 on Windows, 13.0.4123 on Mac.

  • SU2013 = 13.0.3689 on Windows, 13.0.3688 on Mac.

  • SU8.0 M2 = 8.0.11752 on Windows, 8.0.11751 on Mac.

  • SU8.0 M1 = 8.0.4811 on Windows, 8.0.4810 on Mac.

  • SU8.0 = 8.0.3117 on Windows, 8.0.3161 on Mac.

  • SU7.1 M2 = 7.1.6860 on Windows, 7.1.6859 on Mac.

  • SU7.0 M1 = 7.0.10247 on Windows, 7.0.10246 on Mac.

  • SU7.0 = 7.0.8657 on Windows, 7.0.8656 on Mac.

  • SU6 M6 = 6.4.265 on Windows, 6.4.263 on Mac.

What's new in SketchUp 2024.0

Ruby API Additions and Improvements

Ruby API Bug Fixes

  • Fixed issue on Mac where UI.create_cursor would provide an incorrect hotspot

  • Fixed regression in Sketchup.resize_viewport introduced in SketchUp 2023.1 on Windows.

  • Fixed Layout::Entity#move_to_layer when moving an entity from a nonshared layer.

  • Changed Sketchup::Model#close to set focus to the next open model window on macOS.

  • Fixed regression from SketchUp 2023.1 with the Ruby Console on Windows where new-line character was incorrectly added to the end of print calls.

What's new in SketchUp 2023.1

Ruby API Additions and Improvements

What's new in SketchUp 2023.0.2

Ruby API Bug Fixes

What's new in SketchUp 2023.0.1

Ruby API Bug Fixes

  • Fixed issues with UI.inputbox and UI.messagebox not being modal.

  • Fixed issue where new Ruby toolbars might not show up by default.

What's new in SketchUp 2023.0

Overlays

Overlays are a new SketchUp API capability which allows developers to persist extension behaviors while you are using other tools. Effectively, extensions can now continue to analyze, visualize, and create information in the modeling window as you continue evolving a SketchUp model using other native tools and extensions. Previously, extension developers were limited to drawing information to the modeling window only when their extension had a tool active .

Update OpenSSL to 1.1.1o

The version of OpenSSL in Ruby was updated to 1.1.1o.

Ruby API Additions and Improvements

Ruby API Bug Fixes

What's new in SketchUp 2022.0.1

Ruby API Bug Fixes

  • In SketchUp 2022.0 a bug might lead to an available component definition name being incorrectly renamed. Or a name that should be unavailable would be duplicated. This was fixed in SketchUp 2022.0.1.

What's new in SketchUp 2022.0

EntitiesBuilder

We added a new interface, Sketchup::EntitiesBuilder, with the purpose of being able to generate bulk geometry with similar speed to Geom::PolygonMesh + Sketchup::Entities#fill_from_mesh but with the simplicity and per-entity control that Sketchup::Entities offer. This is particularly useful for importers where you can expect to see major performance improvements by switching from Sketchup::Entities#add_face to Sketchup::EntitiesBuilder#add_face.

Universal binary support on Mac

We now support universal binaries on macOS that run natively on both Apple silicon and Intel-based Mac computers.

Update OpenSSL to 1.1.1l

The version of OpenSSL in Ruby was updated to 1.1.1l.

Made Ruby Console output more consistent

Earlier versions of SketchUp printed the return values to Ruby Console commands different depending on platform. This has been made consistent following the pattern of Ruby's own IRB tool. A side effect of this is that the console now uses .inspect instead of .puts when printing the returned value which makes it less ambiguous in many cases. For example nil vs "" that would otherwise print a blank line in both cases.

Ruby API Additions and Improvements

Ruby API Bug Fixes

  • Fixed a bug in UI::HtmlDialog#initialize where max_height and max_width were swapped when use_content_size was set to true.

  • Fixed a bug where UI::HtmlDialog position was set incorrectly when use_content_size was set to true.

  • Fixed a bug in UI::HtmlDialog where use_content_size was not persisted (when preference_key is set). Due to this bug, in some instances, HtmlDialog changed size when it was re-created.

  • Fixed a bug on Mac where the size and the position of the UI::HtmlDialog were not persisted when SketchUp was closed without first closing the UI::HtmlDialog window.

  • Fixed a crash with UI.savepanel on Mac when using a filename with a * prefix; response = UI.savepanel('Save Image', nil, '*.png').

  • Fixed “EntityInfo” not being a supported parameter for UI.show_inspector

  • Fixed “EntityInfo” not being being listed in UI.inspector_names

  • Fixed Sketchup::Face#uv_tile_at could return incorrect values in some edge cases.

What's new in SketchUp 2021.1.1

Ruby API Bug Fixes

  • Fixed regression in UI::HtmlDialog from SketchUp 21.1.0 where the methods on JavaScript's sketchup object for registered action callbacks were missing after navigating away from the initial page.

What's new in SketchUp 2021.1

Upgrade Ruby to 2.7.2

For SketchUp 2021.1 we have upgraded the version of Ruby that we ship with SketchUp from 2.7.1 to 2.7.2.

Notable bug-fix in Ruby 2.7.2 is correcting a bug that prevented profiling tools such as ruby-prof from reporting correct results.

Update OpenSSL to 1.1.1k

The version of OpenSSL in Ruby was updated to 1.1.1k.

Ruby Console Improvements

  • The Ruby Console now remembers its visibility between sessions.

  • The Ruby Console was moved from the Windows menu to the new Developer menu.

Ruby API Additions and Improvements

Ruby API Bug Fixes

What's new in SketchUp 2021.0

Upgrade Ruby to 2.7.1

For SketchUp 2021.0 we have upgraded the version of Ruby that we ship with SketchUp from 2.5.5 to 2.7.1. Developers should verify that their extensions are working as expected in this new version of Ruby.

Ruby API Additions and Improvements

Ruby API Bug Fixes

  • Fixed Sketchup::Texture#filename such that it appends a file extension matching the data format it was loaded from when the internal texture filename is missing the extension.

What's new in SketchUp 2020.2

Ruby and C Exchange API

To allow better interoperability of the Ruby API and C API within the SketchUp application we introduced the ability to exchange entities and image reps between the APIs.

Entities because it's a key type and ImageRep because it can be an expensive object to copy.

  • SUEntityToRuby

  • SUEntityFromRuby

  • SUImageRepToRuby

  • SUImageRepFromRuby

For more details refer to the C API documentation.

Ruby API Additions and Improvements

Ruby API Bug Fixes

  • Fixed Unicode characters not displaying correctly in the Ruby Console.

  • Fixed crash in UI::HtmlDialog when closing the dialog right after opening it.

  • Fixed DWG import option, :preserve_origin is ignored.

What's new in SketchUp 2020.1

Ruby API Additions and Improvements

What's new in SketchUp 2020.0

Ruby API Additions and Improvements

Ruby API Bug Fixes

  • Fixed potential crash in UI::HtmlDialog's callbacks due to values not protected against Ruby's garbage collection.

  • Fixed model validation where it incorrectly flagged some valid UV mapping as invalid and reset it.

What's new in SketchUp 2019.3

Ruby API Bug Fixes

  • (Win) Updated libcrypto and libssl dlls to 1.1.1c.

  • Fixed UI.openURL to not perform URL encoding on Mac for cross platform consistency.

What's new in SketchUp 2019.2

Ruby API Additions and Improvements

  • Added Sketchup::Selection#invert

  • Added :scale_factor option to Sketchup::View#write_image allowing control over the scale of viewport dependant elements such as text heights, arrow heads, line widths, stipple patterns, etc

  • Documented :source => :framebuffer option in Sketchup::View#write_image that dumps the current frame as drawn in viewport. This has existed since SketchUp 7

  • Added the new area and volume unit settings to Sketchup::OptionsProvider

  • Added Sketchup.format_volume

  • Added constants to the Length class for area and volume units to be used with the OptionsProvider

  • Added checks to prevent Image materials from being assigned to normal drawing elements. Doing so will now throw an ArgumentError

  • Increased performance of PNG image export for colorized materials. Previously, it used to use max compression. Now we use a more balanced compression setting. This affects Sketchup::Texture#write as well as the texture writer. We also added some general optimizations for Sketchup::Texture#write. On a 4Kx4K texture we saw the processing time drop from ~50 seconds to ~6 seconds.

  • Added Sketchup::Tool#onMouseWheel event to the Sketchup::Tool interface

Ruby API Bug Fixes

  • Updated Ruby from 2.5.1 to 2.5.5 to address a logic bug in Ruby

  • Fixed possible crash in Sketchup::Entities#clear!

  • Fixed a bug in .skm serialisation where arrays in material attributes were not written out to file

What's new in SketchUp 2019.1

Ruby API Bug Fixes

What's new in SketchUp 2019

Upgrade to Ruby 2.5.1

We have upgraded from Ruby 2.2.4 to Ruby 2.5.1. These upgrades tend to introduce subtle changes to the Ruby language that sometimes are difficult for us to find in our internal testing. Our testing has not found any major compatibility issues between Ruby 2.2.4 and the new 2.5.1 and we expect the upgrade for most developers should be relatively straightforward. Please note that any compiled C extensions will need to be rebuilt. Ensure OpenSSL library calls are compatible.

Dashes

Stipples and dots and dotted stipples, oh my! SketchUp has added a Dashes feature that allows for unique line styles to be applied and controlled at the Layer level. We have exposed this new feature in the Ruby and C APIs. See the Improvements and Fixes sections of each API for a list of classes and methods we’ve added. See the documentation for each API for complete documentation on how to use these features.

InstancePath Support for Dimensions and Text

In SketchUp 2019 we have added Sketchup::InstancePath support to our existing Sketchup::DimensionLinear and Sketchup::Text classes. Now when creating a Linear Dimension, or an attached Text object, you can attach it to a nested entity by providing a valid InstancePath object, or an array version of an instance path. This will allow you to create a dimension in model space, but attach it to a valid nested entity. The linear dimension or text will then be attached to that entity, exactly how it is when linear dimensions and text are created via the UI.

Ruby API Breaking Changes

  • SketchUp changed how it presents units. Now it adds a space between the number and the unit indicator. If your extension uses a method of your own creation to interpret strings formatted by SketchUp you might find it doesn't work anymore if you don't account for the extra space. For example:

  • Before 2019: "2.5mm"

  • Now in 2019: "2.5 mm"

  • Ruby Version Upgrade - Ruby 2.5 removed the method: Dir::Tmpname.make_tmpname. If you were using that method, you will need to find an alternative

  • Sketchup::Entity#delete_attribute no longer returns true when attempting to delete a non-existing dictionary key

Ruby API Additions and Improvements

Ruby API Bug Fixes

  • Fixed a crash upon exit on Mac when a Sketchup::FrameChangeObserver is active

  • Fixed an issue where Sketchup::Model could become unusable after calling .singleton_class.

  • Fixed Ruby-created dimensions don't highlight when non-associated

  • Fixed Ruby-created dimensions don’t hide correctly when “Hide Foreshortened” is enabled

  • Fixed SketchUp crash when constructing Geom::PolygonMesh with negative values

  • Fixed Ruby DWG Importer units were not working correctly

  • Fixed Geom::PolygonMesh will not accept negative numbers as parameter

  • Fixed Extensions are loaded in a non-deterministic order on High Sierra

  • Fixed SketchUp crashes when attempting to load component made in newer version

  • Fixed typo concerning merge_coplanar_faces in the Importer Options documentation and code (old spelling remains for compatibility)

  • Fixed regression in SU2018 when renaming a material with the same name. This used to throw an error when it should have been a no-op

  • Fixed regression in SU2018 where model.materials["MaterialName"] might fail

  • Fixed a crash when loading a component made in a newer version of SketchUp

  • Fixed unicode characters in the Ruby Console on Windows

  • Fixed UI::HtmlDialog such that non-resizable dialog doesn't use width and height from preferences.

  • Sketchup::View#write_image should throw an error if there are more than 5 params passed in.

  • Fixed UI::HtmlDialog content flashing when resizing.

SketchUp C API Documentation

  • Updated SDK docs on VC++ runtime versions

LayOut Ruby API for SketchUp

What's new in SketchUp 2018 M0

LayOut Ruby API for SketchUp

This is a new Ruby based API for SketchUp that allows developers to read and write LayOut files using the regular SketchUp Ruby API. We’ve taken the existing LayOut C API and wrapped it with a Ruby layer and then included that inside SketchUp. This is proving to be a great working model for how to expose API functionality to our base C API and then expose that exact functionality to a Ruby layer without duplicating code.

Sketchup.send_to_layout

Along with the LayOut Ruby API for SketchUp we added the ability to open LayOut files with the LayOut application. This gives developers the ability to write a SketchUp extension purely in Ruby that parses the SketchUp model, writes a LayOut file and opens the LayOut file in LayOut in one smooth motion. This helps create a stronger connection between SketchUp and LayOut and can improve user workflows through the use of developer created extensions.

ImageRep

Hello Ruby API developers, meet Sketchup::ImageRep. This new class exposes a data structure internal to SketchUp called an ImageRep. ImageRep is an in-memory representation of an image (as opposed to a reference to an image inside the SketchUp model). This class exposes a number of image reading and manipulation tools to the Ruby API. Now you can get the color of a pixel at a specified uv coordinate from an ImageRep, get an array of all pixel data from an ImageRep, set pixel data in an ImageRep, save an ImageRep out to disk, and more. Of course we’ve also included utilities to convert an in-model texture to an ImageRep, and assign an ImageRep object directly to a material as the material’s texture. This new class opens up a lot of opportunities to read and manipulate images in the model. Check out the ImageRep class in Ruby API docs for more information.

Exposed Importer/Exporter Options to Ruby API

We have exposed all the options for our native importers and exporters to Ruby. See the Ruby API documentation on Sketchup::Model#import and Sketchup::Model#export.

New SketchUp Features in the API

A big round of applause for the SketchUp Core team for the improvements they have added to the SketchUp application. Well, we also wanted to make sure that these new features were accessible to our developer community. We have introduced new API features for Named Section Planes and Filled Section Cuts. Awesome!

Ruby Handling of Advanced Attributes

SketchUp core added a feature called Advanced Attributes. This adds some new attribute dictionaries and attributes to Component Instances and Definitions by default on every model. It should be noted that we have blocked the ability to delete the dictionaries via Ruby. This should not be possible, please let us know if you find a scenario where you are able to do so. You can however delete the key/value pairs. The UI will recreate those key value pairs if they do not exist.

Ruby Improvements and Fixes

Bug Fixes

  • Breaking Change - Fixed a bug in Sketchup::Material#name= which allowed the API to create materials with duplicate names. Now it will raise ArgumentError if it's not unique to the model.

  • Breaking Change - Changed Sketchup::Color class to be common between LayOut and SketchUp. The potentially breaking change is that Sketchup::Color changed to now compare RGBA values instead of the Ruby objects.

  • Breaking Change - Changed Geom::Transformation#identity? So that it now properly returns true in all cases where the transformation matrix match the values for the identity transformation.

  • Fixed Geom::Transformation.scaling(float) and Geom::Transformation#initialize(float) to not set the 15th component of the matrix, but instead adjust the other fields.

  • Fixed a crash when trying to call Sketchup::View#animation= from Sketchup::Animation#stop

  • Fixed a crash when calling UI.menu with empty string.

  • Sketchup::Pages#erase will now correctly delete the Scene tab, like the UI does.

  • Fixed a bug in Sketchup::ArcCurve#end_angle where it sometimes added 360 degrees to the returned value.

  • Fixed an issue where a Ruby Importer could cause the Import file dialog to render the drop-down items incorrectly under Windows due to pipe characters in the description.

  • Fixed a crash when using -RubyStartup command line argument with a file that raises errors while loading.

  • Fixed a crash in UI.create_cursor that would happen if the length was less than 4 characters.

  • Fixed a rare crash in Sketchup::MaterialsObserver.

What's new in SketchUp 2017 M0

Ruby 2.2

Yes, its that time again - time to update our Ruby Interpreter. We have upgraded to Ruby version 2.2.4. We're hopeful that extensions that use pure Ruby will be able to upgrade to Ruby 2.2 with little difficulty. Please note that any compiled C extensions will need to be rebuilt.

Embedded Web Framework

One of the developer features we are most excited about for SketchUp 2017 is a new Web Dialog framework. For SketchUp 2017 we are bundling the Chromium Web Browser with the SketchUp installer. What?! Yes, now SketchUp comes pre-packaged with a single web browser for both Mac and Windows clients. No more trauma from banging your head against the wall while trying to make your web pages compatible with Internet Explorer 8-11 and Safari.

In order to maintain backwards compatibility, we have implemented a new HtmlDialog class in the Ruby API and we have not altered the existing WebDialog class. Extensions that use WebDialogs should continue to work with no changes required.

New Ruby API Documentation

We have been working to improve our Ruby API documents and the publication process. We switched from an internally tweaked and maintained version of RDoc to YARD for our documentation generation. In the process we had to make many alterations to our documentation in the source code, we made a specialized YARD template to suit our needs. What we have now is a simple way to regenerate the documents in a matter of seconds, and we can push them to a git repo, where they are immediately available publicly. A process that used to take hours of manual html editing and special access to our Sketchup.com webserver, has been reduced to about a 10 minute process to generate and publish the documentation.

SketchUp C API Parity - continued

We have focused on adding features to the SketchUp C API in 2017 to provide greater benefit to our developers and as part of our continued effort to fully deprecate and remove the old C++ API in the future. We are continuing to add more until we gain enough coverage to consider the C API at feature parity with the deprecated C++ API.

Updated Compilers

We updated our compilers for Windows and macOS. On Windows we are now using Visual Studio 2015 SP1 (targeting Windows 7). On MacOs we are using XCode 7.2.1 (with deployment target 10.10).

New Ruby API Features

Bug Fixes/Small Improvements

Ruby API

  • Fixed Sketchup::Entities#transform_by_vectors so that it performs a bounds check on the second array. An ArgumentError is raised if the second array has less items than the first.

  • Added ability to UI::HtmlDialogs to receive JavaScript arrays and objects using callbacks.

  • Removed a limitation with UI::HtmlDialog where callbacks were required to have at least one argument. Now no arguments are required.

  • UI.show_model_info no longer opens a Model Info page for "Extensions" as that page is now replaced by the Extension Manager dialog.

What's new in SketchUp 2016 M0

A new LayOut API

We’re proud to announce our first step towards an extension ecosystem for LayOut. Using this new API developers can now open, create, modify, save, and export .layout files. Practically, this means that other applications can import or export the .layout file format using the C API. (This includes creating a .layout file from SketchUp). We have several sample scripts for developers to try out at release. Check out the API documentation in the Developer Center for more information.

Digitally Signing Extensions - Extensions Loading Policy

With SketchUp 2016 we introduced the ability for users to select which Extension Loading Policy they want to use. The options are “Identified Extensions Only”, “Approve Unidentified Extensions”, and “Unrestricted.

The developer side of this feature is known as a Digital Signature. All SketchUp extensions for 2016 or later will now require a Digital Signature to run in the highest security mode - “Identified Extensions Only”. If the user has chosen “Approve Unidentified Extensions” then all signed extensions will load automatically and any unsigned extension will have to be approved by the user. All extensions signed and unsigned, will load in “Unrestricted” mode.

SketchUp 2016 M0 installs in “Unrestricted” mode by default.

To digitally sign your extension, simply upload your .rbz package to our new Digital Signature and Encryption page and we will sign it and return it to you. Visit the new Extension Digital Signature page.

You will need to sign your extension each time you make code changes and want to re-release it. You will need to be a registered Developer on the Extension Warehouse to be able to sign or encrypt extensions. Apply here!

Ruby Encryption 2.0

Goodbye .rbs and Hello .rbe! We have added a new encryption that you can use to help protect your extension Intellectual Property (IP). SketchUp 2016 can read both .rbe and .rbs filetypes. This should help make sure that we maintain backwards compatibility for authors who need some time to re-encrypt their extensions. To use our new encryption, simply upload an unencrypted version of your .rbz package to our new Digital Signature and Encryption page and we will encrypt it and return it to you. Visit the new Extension Digital Signature page page here for more information.

You will need to be a registered Developer on the Extension Warehouse to be able to sign or encrypt extensions. Apply here!

Developer Center

Between the new Extension Digital Signature Page, the new LayOut C API and a whole lot of future ideas and potential, we have decided to create a new central location to organize our developer resources, API documentation, etc. Visit (and bookmark!): extensions.sketchup.com/en/developer_center

Observer Upgrades

We have been working on finding ways to make observers more stable and reliable for all developers. Most of these changes happen under the hood and are not entirely visible to developers. To help with that, we added a few Ruby Warnings that appear in the Ruby Console, and two debugging methods that will determine whether those warnings are shown: Sketchup.debug_mode= and Sketchup.debug_mode?.

  • Observer events are now queued up until the active operation is done.

  • Sketchup::ModelObserver doesn't notify about intermediate Ruby operations (“transactions”).

  • Observers should no longer return zombie Ruby objects for entities. See the Observers 2016 pdf for more information.

  • Removed dummy methods from all observer base classes in order to improve performance.See this pdf for a more in depth look at the changes we made to the Observers.

SketchUp C API Parity - continued

We have focused on adding features to the SketchUp C API in 2016 to provide greater benefit to our developers and as part of our continued effort to fully deprecate and remove the old C++ API in the future. Below is a complete list of functions that we have added for 2016. We are continuing to add more until we gain enough coverage to consider the C API at feature parity with the deprecated C++ API.

New Ruby API

Bug Fixes/Small Improvements

  • Fixed Sketchup::Pages#erase so that it doesn't incorrectly create an undo operation any more.

  • Removed instance of a zombie instance with Curves. See the Observers 2016 pdf for more information.

  • Fixed issue where Sketchup::ViewObserver does not fire when using the Zoom tool in parallel projection mode

  • Deprecated the Piranisi .epx import

  • IFC import failure resolved by library updates to Windows and Mac.

  • Fixed Collada export fails with :camera_lookout value with message “Pointer being freed was never allocated”

  • Fixed Collada export does not export cameras

  • Resolved multiple visual defects with Extension description box.

  • Sketchup.version_number now returns the correct value.

What's new in SketchUp 2015 M2

We fixed a crash on Mac that could occur when a timer was stopped via UI.stop_timer from within the timer procedure.

What's new in SketchUp 2015

Renaming the Plugins Menu

We renamed the “Plugins” menu to “Extensions” to be more inline with our current naming conventions. This should not break existing plugins. Adding a menu item to the “Plugins” menu will still work, it will be added to the “Extensions” menu.

New! - Extension Licensing API

One of the new features that we have added to API is the ability to create licensed extensions. The Extension Warehouse has been upgraded to manage and distribute these licenses.

New! - Classifier API

New API Features

64 Bit related changes to our Ruby API

  • Length no longer derives from Float. It should act the same in 2015 as it has in previous version of SketchUp This was required as part of our 64-bit upgrade changes

  • We have separated the GEM_PATH and GEM_HOME directories for 32-bit and 64-bit builds.

Webdialog JS error Dialogs for Developers

In previous versions of SketchUp on Windows, users would see javascript error popup boxes anytime there was malformed js code on a webpage. We muted those popups in a previous release. Due to popular demand, we have brought them back, this time for developers only! Developers can enable js error popups by creating this key in their Windows registry: HKEY_CURRENT_USER/Software/SketchUp/SketchUp 2015/WebDialogs/ShowErrorDialogs and adding a DWORD value set to 1.

Bug Fixes and Improvements

  • We are now setting the initial working directory to the user’s Documents directory.

  • Restored $0 to return "SketchUp" as it did prior to SketchUp 2014.

  • Fixed bug where point3d.vector_to(inputpoint) would return incorrect result.

  • Cleaned up inconsistent operation name and id used in the Sketchup::Edge class.

  • Fixed crashes caused by internal calls to Ruby from worker threads.

  • Prevented crash when there is an uncaught Ruby error happening in Sketchup::Importer#load_file

  • Geom::BoundingBox#corner now raises an IndexError when given an incorrect index.

  • Fixed a bug where Geom::BoundingBox#intersect could yield incorrect results.

  • Fixed a bug where Geom::BoundingBox#intersect would not accept an array of vertices or boundingboxes.

  • Fixed a bug where Geom::PolygonMesh#normal_at would not return correct vertex normal if the model was modified in the same processing loop as the script obtaining the PolygonMesh.

  • Fixed a bug where a frozen array might raise an error when a method acts on that array, even if the method does not modify the array.

  • Fixed a bug where InputPoint objects could cause a crash in certain circumstances.

  • Changed the classifications folder inside the Program Files folder from C:\Program Files (x86)\SketchUp\SketchUp 2015\Classifications to C:\Program Files (x86)\SketchUp\SketchUp 2015\ShippedClassifications. Now Sketchup.find_support_file("Classifications") will return the classifications folder in the user folder, instead of in the application folder.

  • Setting material during Sketchup::ModelObserver#onPreSaveModel did not work in SU2014. This should be fixed for 2015.

  • Sketchup::ViewObserver notification used to fail when in parallel projection. This has been fixed.

  • Custom context menus in custom tools have been improved. It is now possible to determine what type of entity was clicked on, before opening the context menu. Therefore custom context menus can be written to handle different types of entities differently.

  • Exploding an image entity now returns an array of entities. These include all associated edges, the face, edgeuse objects, etc. Previously it return an empty array.

  • Fixed a bug where view.draw(GL_LINES, ...) crashes when passed an odd number of points.

  • HTTPS connections should now work on Windows using 'net/https'.

What's new in SketchUp 2014 M1

  • Fixed a crash that occurred when exporting an animation while any Ruby tool was active.

  • Fixed an Sketchup::EntityObserver crash in Sketchup::EntityObserver#onEraseEntity that could occur if the observer removed itself.

  • Fixed a bug in Sketchup::ViewObserver which caused observer methods to not fire properly in certain rare cases. This occurred when an observer was being removed and a new one being added within the same notification loop of another event.

  • Fixed an issue where launching SketchUp by double-clicking a skp file on another drive would corrupt $LOAD_PATH and render the Standard Library inaccessible. This bug caused many people to run into plugin loading problems if they were opening files located on drives other than their “C:” drive.

  • Fixed a bug on Windows where plugins would not load if the user name contained single quotes.

  • Fixed a regression in Sketchup::Face#position_material. Under SketchUp 2014.0.4900 a (caught) exception generated by a failed Sketchup::Face#position_material call appears to cause SketchUp to unwind everything back to the last Sketchup::Model#start_operation.

  • Fixed a Ruby unicode issue where Ruby could not require .so files from unicode paths.

  • Added support to SketchUp Mac to load SURubyDebugger.dylib. Developers can now use our debugger on Mac.

  • Fixed an issue where the Sketchup::LayersObserver would cause SketchUp to crash when the user would do an undo then a redo.

What's new in SketchUp 2014

We have made many additions and improvements to the SketchUp Ruby API. These changes include some big and potentially code-breaking changes in this round of SketchUp. We strongly recommend all developers test their scripts for compatibility with 2014.

Upgrade to Ruby 2.0 and Stdlib is now included

  • We have upgraded to Ruby 2.0.0 p247 on both Windows and Mac platforms.

  • We are now shipping the Ruby Standard Library with SketchUp.

  • Ruby now supports proper unicode strings.

  • Plugins on Windows have now been moved outside the SU Installation folder. On Vista, Win 7, 8: C:\Users<username>\AppData\Roaming\SketchUp\SketchUp 2014\SketchUp\Plugins On Win XP: C:\Documents and Settings<username>\Application Data\Roaming\SketchUp\SketchUp 2014\SketchUp\Plugins

  • On Windows, we also load plugins from a user-independent support directory. On Win Vista, 7, 8: C:\ProgramData\SketchUp\SketchUp 2014\SketchUp\Plugins On Win XP: C:\Documents and Settings\All Users\Application Data\SketchUp\SketchUp 2014\SketchUp\Plugins This path is only loaded to the $LOAD_PATH array if the folder exists when on the user's machine when SU starts.

New! - Dimensions API

Please see the new API docs for how to implement these classes and methods:

New! - SectionPlane additions

Please see the new API docs for how to implement these classes and methods.

Added support for creating and activating Sketchup::SectionPlane entities:

Additional New API Methods and Features

Below is an outline of new API functionality. Please see the new API docs for how to implement these classes and methods.

Ruby Console Upgrades

  • Multi line code input and pasting into Ruby console on Win (Ctrl+Enter creates a new line)

  • Ruby Console writes data to itself much faster and does not slow down after many errors have been written

  • Typing cls now also clears the console

  • Mac Ruby Console reverted back to fixed width font

Observer Bug Fixes

Moved the Set class to Sketchup::Set

In order to avoid clashing with the Standard Ruby Library we moved the Set class to Sketchup::Set. All references to the SketchUp Set class should be refactored.

General Bug Fixes

  • Ensured that our classes that implement Enumerable don't override the improved Ruby 2.0 #count method. Also ensured all Enumerable classes implement #length and #size.

  • Updated Geom::PolygonMesh API docs to be accurate. Numerous other API documentation fixes and updates.

  • Fixed program hang when output is written to the console via puts from within a Ruby 2.0 Thread. These output will no longer hang the program but they also will not be printed. All access to the SU API (including writing to the console) must be made from within the main thread.

  • Added argument validation to Sketchup::Layer#page_behavior and updated API docs.

  • Fixed crash when hiding layers while iterating through selected entities. If your code modifies the collection you are iterating during the iteration process, SketchUp will stop iterating. Instead you should iterate over an array of the collection. Code similar to selection.each { |e| code_to_modify_the_selection_set } should be changed to: selection.to_a.each { |e| code_to_modify_the_selection_set } This is true of all collections such as: Sketchup::Entities, Sketchup::Layers, Sketchup::DefinitionList, Sketchup::Pages, Sketchup::Selection, etc.

  • Fixed a bug where groups that share the same definition would seem to continue to share entities after being made unique in some cases.

  • Fixed Sketchup::Group#description= which didn't make the group unique before setting its description.

  • Fixed the erroneous "RangeError: value cannot be negative" that was raised on valid input for Sketchup::ConstructionLine#stipple=

  • Fixed Sketchup::DefinitionList#load and load_from_url which did not start Ruby operations properly.

  • Fixed crashes and other oddities that would happen when applying a material that wasn't in the model already - either selected from Material Browser or a material from another open model. Now the material is recreated in the model it is applied to.

  • Fixed Sketchup::Entities methods erase_entities and add_3d_text which did not make the group unique when called for a group Entities.

  • Ruby references belonging to closed models should no longer remain alive and cause possible crashes on Mac.

  • Fixed the crash that occurred when Outliner is open and a group is created/erased within the same operation.

  • Fixed Sketchup.active_model.export('myFilename.dae') truncating first two characters when given relative paths.

  • Fixed Sketchup::Tools#pop_tool to ensure the last tool cannot be popped, which would leave SketchUp in a state without an active tool.

  • Fixed Sketchup::Tools#active_tool_name to return proper tool names on Mac.

  • Fixed Sketchup::Model#close_active so the operation appears on the undo stack as it should. Prevents undoing the operation from shifting the geometry.

  • Fixed Sketchup::Materials#remove so that it correctly removes the material from the entities in the model before removing it from the materials list.

  • Loader files registered to SketchupExtension can now be an encrypted file (.rbs).

  • Fixed the inputbox wrapper in sketchup.rb to not enter an infinite loop if no arguments are given.

  • Fixed loading errors to be more verbose and include file paths and code line numbers

  • Any Ruby errors occurring on rbs files are now reported with proper file name and line numbers.

  • Ruby keywords __FILE__ and __LINE__ now work properly within rbs files.

  • Ruby errors that occur during program startup are now reported with stack traces, which should make it easier to diagnose problems.

  • Fixed a bug on Windows where UI::WebDialog#show did not remember previous size/location of webdialog.

  • Sketchup.require did not push paths for loaded rbs files into $LOADED_FEATURES - this is now fixed.

  • RBZ extraction should now preserve file permissions.

  • Sketchup::Group#locked=/Sketchup::ComponentInstance#locked= now correctly adds itself to the undo stack.

  • Added negative value checks to methods that expect unsigned integer parameters (certain methods that use integers as arguments were allowing poorly formatted negative values).

  • Sketchup::ComponentInstance#explode/Sketchup::Group#explode while editing the component that you explode would crash SketchUp. This is now fixed.

  • Previously Sketchup::Tool#getInstructorContentDirectory method assumed everything was relative to the SketchUp Resource folder. This has been changed for 2014. Now it accepts absolute paths to either file or folder

  • New method: Sketchup.quit

  • Added UI::WebDialog#screen_scale_factor which can be useful on Mac retina screens.

  • Implemented Sketchup::EntitiesObserver#onActiveSectionPlaneChanged

  • Added Geom::PolygonMesh#set_uv

  • Fixed the Sketchup::EntitiesObserver bug where a wrong Entities reference would be sent to observer methods when observing a group's Entities collection.

What's new in SketchUp 2013 M1

Bug Fixes

Fixed a toolbar bug that caused some extensions to not display and become incorrectly docked behind other toolbars. Developers are now advised to call UI::Toolbar#restore after creating a toolbar, although those that do not will also work correctly on SU2013 M1.

Fixed a bug in UI::WebDialog#get_element_value which caused it to malfunction with some html elements on Mac.

What's new in SketchUp 2013

Expanded the SketchupExtension class

New methods:

Documented the LanguageHandler class

LanguageHandler} was an existing internal class which we are now exposing in the API. It has been updated such that it looks first for translated resources within the Resources folder in the extension directory structure (as explained in the Warehouse Developer Center). All translated resources should be located within the appropriate language folder.

Added special HTML link to launch an extension's page on Extension Warehouse

See detailed explanation of the "skp:launchEW" link in {UI::WebDialog class documentation.

Change in Sketchup.send_action

"addBuilding:" has been removed.

What's new in SketchUp 8 M2

The second maintenance release for SketchUp 8 was available December 1, 2011. It included a handful of Ruby API additions around managing extensions.

Improved the SketchupExtension class

Five new methods:

Added ExtensionsManager class

Lets you inspect which Extensions are registered.

Added new hooks in the Sketchup object

What's new in SketchUp 8 M1

The first maintenance release for SketchUp 8 was available January 12, 2011. It included several Ruby API fixes and additions.

Improved the UI::Toolbar class

Two new methods:

Fixed these failing method calls on Mac:

  • UI.set_toolbar_visible('GoogleToolPaletteController', false)

  • UI.set_toolbar_visible('ToolPaletteController', false)

  • UI.set_toolbar_visible("SolidModelToolPaletteController", true)

  • UI.set_toolbar_visible("SolidModelToolPaletteController", false)

Fixed this failing method calls on the PC:

  • UI.set_toolbar_visible("Walkthrough", true)

  • UI.set_toolbar_visible("Walkthrough", false)

  • UI.set_toolbar_visible("FullToolSet", true)

  • UI.set_toolbar_visible("FullToolSet", false)

Expanded the UI::Command Class

New methods:

Expanded the Material/Materials Classes

New methods:

Gave Ruby Access to the “Shadow Bug Fix”

If you find yourself in a situation where the 8.0 M1 shadow bug fix is getting unexpected results, you can turn it off.

Improved Alpha Transparency Control

Fixed Several Bugs

We accidentally introduced some bugs with recent SketchUp releases. So we fixed them in 8.0 M1:

Sketchup::View#pick_helper stopped respecting arguments passed to it. This was breaking the Bezier.rb and BZ Tools plugins. Now fixed.

Sketchup::ConstructionLine#stipple= method now works as documented.

Sketchup::Model#raytest method was occasionally returning incorrect values. We fixed that and added an optional boolean argument to specify whether or not to stop at hidden entities: model.raytest(ray) - ignores entities that are hidden model.raytest(ray, true) ignores entities that are hidden model.raytest(ray, false) stops at entities that are hidden (via hide or on hidden layers)

Sketchup::Color#to_a was returning a Bignum when a Fixnum was expected. A Fixnum is now returned.

What's new in SketchUp 8

Updated Ruby Version to 1.8.6 on PC

The version of the Ruby interpreter that ships with SketchUp has been upgraded to 1.8.6 on PC (still 1.8.5 on Mac). Please note that 1.8.6 includes thousands of bug fixes and stability improvements, but that it also is more strict about syntax. Scripts that work in SketchUp 7.x and earlier may have syntax failures in SketchUp 8.

WebDialog User Agent Updated

It used to be that WebDialogs would send a useragent string unique to SketchUp. We now send a useragent that is a concatenation with the embedded browser's original useragent and an extra string to identity SketchUp. This allows the Google Earth plugin (and similar plugins) to correctly detect the kind of browser so it works properly inside SketchUp.

Observer Bug Fixes

Sketchup::EntitiesObserver#onElementModified now accepts 2 parameters: entities and entity, making it much more useful.

Fixed common crash with Sketchup::EntitiesObserver#onContentsModified Also, Sketchup::EntitiesObserver#onContentsModified renamed to Sketchup::EntitiesObserver#onElementModified for consistency.

The callback Sketchup::MaterialsObserver#onMaterialRemoveAll now deprecated, we recommend using Sketchup::MaterialsObserver#onMaterialRemove instead.

Write Image Size Clamped

Sketchup::View#write_image is now clamped to export a maximum image size of 16000x16000 to prevent freezes.

Timers Work in Smaller Increments

UI.start_timer now accepts values less than 1 second.

New Boolean Methods

Sketchup::Group and Sketchup::ComponentInstance have several new methods for boolean operations:

  • manifold?

  • volume

  • intersect

  • union

  • subtract

  • trim

  • split

  • outer_shell

  • equals?

  • show_differences

Sketchup::Face#classify_point updated

Note that the return values for Sketchup::Face#classify_point have changed for SketchUp 8. See the documentation for the list of constants that you should check against. If you have scripts that rely on hard-coded numeric values, you should update them to use constants, instead.

Crashes fixed

Fixed crash in Sketchup::Pages#add and in Sketchup::Model#number_faces.

What's new in SketchUp 7.1

New methods

What's new in SketchUp 7.0 M1

New methods

What's new in SketchUp 7

Improved Script Performance

Ability to perform faster inside start_operation transactions.

go_faster = true
model.start_operation("My Processing", go_faster)
# Do processing here that was slow in SU6
# ...
model.commit_operation

Results from some real world tests, (comparing SU6 to SU7 on the same machine) once the go_faster boolean was added:

Intersect overlaps with 500 overlapping squares 28.4 seconds vs. 26.3 (~92% as long)

Make faces with 500 faceless cubes 21.7 seconds vs. 14.5 (~66% as long)

Windowizer 3.0 with Four 20'x20' windows, 12x12 16.1 seconds vs. 7.0 seconds (~43% as as long)

Windowizer 4.0 with Ten 5'x5' windows, 6x6 22.6 seconds vs 8.7 seconds (~38% as long)

Improved Web Dialogs

Addition of min/max widths.

webdialog.min_width=100
webdialog.max_width=300
webdialog.min_height=500
webdialog.max_height=600

Fixed Mac support for WebDialogs execute_script

webdialog.execute_script('alert("Bug is Fixed!")');

New full_security mode for webdialogs (disables plugins and remote links)

webdialog.set_full_security

Ability to hide home/next/back navigation icons on the Mac

webdialog.navigation_buttons_enabled=true

Cleaner, hash-based syntax for initializing

my_dialog = UI::WebDialog.new(my_settings_hash)

Control Scale Tool Handles

Your script can now control which scale tool handles appear when the user selects a given component.

# Disable the green and red-axes handles
# by setting bits 1 and 2 to 1.
behavior = my_component_definition.behavior
behavior.no_scale_mask = (1 << 1) + (1 << 2)

Load Definitions from the Web, or Save to Disk

Ability to download a definition from URL

model.definitions.load_from_url(url, download_handler)

Ability to Save components to disk from the API

my_definition.save_as(path)

Know More About User Interactions

New methods for detecting “Component Edit” mode

users_current_edit = model.active_path
edit_mode_transform = model.edit_transform

Easily determine if they're running in licensed Pro

is_licensed_pro = Sketchup.is_pro?

New “model level” callbacks in ModelObserver

def onActivePathChanged(model) { # Detect edit mode }

def onPlaceComponent(instance) { # Detect placements }
def onExplode(model) { # Detect group/component explode }
def onBeforeComponentSaveAs(instance) { # Add data on save as }
def onAfterComponentSaveAs(instance) { # Then clean up }

Detect if they've turned off your extension via the AppObserver

def onUnloadExtension(extension_name)

Assorted Improvements Requested by Developers

Delete your scenes via the API

my_page.erase

Keep SketchUp in Synch

UI.refresh_inspectors # force complete UI update
my_definition.refresh_thumbnail # force thumb update
my_definition.invalidate_bounds # force bb update

Measure your groups regardless of their transform

untransformed_bb = my_group.local_bounds

Use middle mouse button in your custom tools

def onMButtonDown(flags, x, y, view) # now works!
def onMButtonUp(flags, x, y, view) # now works!

Send Ruby console output to the standard out If you start up SketchUp from the command line, you can pipe to standard error and see Ruby puts statements appear for you.

Sketchup.exe > myRubyLog.txt

Finally, we fixed a number of crashing bugs, mostly related to iterating across entities in the model.

What's new in SketchUp 6

The most substantial addition to the SketchUp 6 Ruby API are the Ruby Observer Mechanism, the Tools class, the WebDialog class, the Styles class, and the Style class.

Ruby Observer Mechanism

The Ruby Observer Mechanism is designed to allow Ruby scripts to be notified when objects change in the SketchUp application or model. For example, you can create an observer class that “listens” to when SketchUp quits and then performs some action.

Create a Ruby class of a specific observer type, such as AppObserver, override the desired methods, such as onQuit, and add an instance of the observer to the applicable objects in your Ruby script (using the add_observer method for that object). Refer to individual observer interfaces for further information.

Tools Class

The Tools class contains methods to manipulate a collection of SketchUp tools. This class is primarily used to switch between tools through the use of key or mouse actions.

WebDialog Class

The Ruby WebDialog class to create and interact with, DHTML dialog boxes, called webdialogs in this documentation, from Ruby code. For example, you can create webdialogs that are invoked from your Ruby code to display a web site, or to accept user input and use the results in your Ruby code. Styles and Style Classes The Styles class contains methods for manipulating a collection of styles in a model. The Style class contains methods for modifying information about a specific style.

Before SketchUp 6

The core 62 classes of the API were established here. Very few users are on anything before SketchUp 6, so this documentation site focuses only on SketchUp 6 and up.