SketchUp Components: A Guide to ComponentInstance and Definition

SketchUp Ruby API documentation explains how component instances in a model are represented and how their associated definitions can be managed. ComponentInstance represents a placed component instance in the model, while ComponentDefinition represents the definition that instance is based on. The instance’s position in the model is also determined by transformation data. Understanding this distinction helps separate changes that affect reused objects from edits that apply to just one instance.

This guide is based on methods documented for ComponentInstance, DefinitionList, and Model in the SketchUp Ruby API. The methods’ version notes vary; where documentation specifies a version, the relevant limit is noted separately.

1. Understand the relationship between an instance and its definition

1. Treat a component instance in the model as separate from its definition. A ComponentInstance references a ComponentDefinition object and carries its position through transformation data. This structure allows multiple placed instances to use the same definition. So, before editing an instance, it’s important to check which definition it uses.

2. In the Ruby API, Sketchup.active_model returns the active model. The Model object’s definitions method provides access to the DefinitionList collection, which contains the model’s ComponentDefinition objects. An instance’s definition method returns the definition associated with that particular instance. This means inspecting definitions across the model and finding the definition for a specific instance are separate tasks.

3. If you don’t want changes to affect other instances that use the same definition, consider calling make_unique before editing an individual instance. According to the documentation, this method creates a new definition for that instance that is not used by other instances. This distinction can be useful when you want to change just one of several copies of a piece of furniture, a door, or a fixture.

2. Inspect and isolate an instance with the Ruby API

The example below searches the active editing context for the first ComponentInstance object. If it finds one, it prints the name of the associated definition, then calls make_unique to create an independent definition for that instance. The code does not scan the model’s entire definition list; it gets the definition name through the selected instance’s definition method.

model = Sketchup.active_model
instance = model.active_entities.grep(Sketchup::ComponentInstance).first

if instance
  puts instance.definition.name
  instance.make_unique
end

1. Before running this example in your own model, verify which component is selected or present in the active editing context. The code retrieves the first ComponentInstance object; it does not select a component by name. So, if there are multiple components, check the output and target instance. Calling make_unique also creates an independent definition in the model; it does not just display information.

2. Changing the associated definition and changing the instance’s position are separate operations. The definition= method on ComponentInstance assigns a different definition, and the documentation says it preserves the instance’s existing transformation. Use transformation and transformation= to read or set the transformation. transform! applies a Geom::Transformation; move! sets the transformation in a similar way but does not record the operation on the undo stack. Keep this distinction in mind when designing the editing and undo flow in a plugin.

3. Work carefully with geometry and definition collections

1. The explode method converts a component instance into separate drawing elements. It may return an array of elements on success or false on failure. If preserving the component structure matters, consider the effect this operation will have on the model before using it. The documentation also lists geometric operations such as intersect, outer_shell, split, subtract, trim, and union; some are defined to work on manifold solid volumes. So, don’t assume they’ll produce the same result for every component.

2. trim calculates the difference between two manifold solid volumes non-destructively; subtract is another method listed for difference operations. The API documentation also notes that intersect is not available in SketchUp Make. The manifold? method on ComponentInstance is marked as deprecated; according to the documentation, use ComponentDefinition#manifold? to check whether the definition is manifold. These notes show why it’s important to check the method description and object type before running geometric operations.

3. DefinitionList includes methods for finding definitions by index, name, or GUID; adding a new definition; loading a component from a file; and purging unused definitions. purge_unused removes unused definitions. Avoid deleting items from the collection while iterating over it with each: the documentation warns that some definitions may be skipped because the item count and indexes can change. If you need to delete items, the documented approach is to copy the collection to an array first, then work with that copy.

4. Check version compatibility and file safety

1. The load method in DefinitionList is used to load a SketchUp component file. According to the documentation, starting with SketchUp 2021.0, the allow_newer option makes it possible to load models saved in a newer version. However, some information may be skipped during loading; the API documentation warns against saving over the file loaded from a newer model. Preserving the source model should therefore be part of the workflow.

2. There’s also a version note about reloading a component from the same file path. Before SketchUp 2023.0, if the model already contained a different component associated with the same path, the load call could return the existing component instead of loading the new content. If the file doesn’t appear to have updated, check the SketchUp version and file path; reflect the version limits noted in the source documentation in your plugin’s compatibility requirements.

Impact on architecture, interior design, and visualization workflows

For architecture and interior design teams using repeated furniture, doors, and fixtures, the distinction between an instance and its definition makes it easier to understand the scope of changes in a model. The component relationship is useful when a shared definition needs to be changed; if only one instance needs to be different, make_unique is the API method provided for that purpose. This distinction can help teams working on a model track which elements change together.

For visualization teams and plugin developers, the key is to verify that the correct instance and definition are selected. The sources do not specify any particular hardware requirements, performance measurements, or licensing conditions. The concrete points to track are whether the SketchUp version in use supports the relevant method and whether the source file is preserved when loading files from newer versions.

Common mistakes

• Editing an instance’s shared definition without accounting for the possibility that other instances may change too.

• Forgetting that the code finds the first ComponentInstance object and assuming it selects a particular object.

• Treating assigning a definition and changing the position transformation as the same operation.

• Using geometric methods with manifold requirements as if they would work on every component.

• Deleting items from a DefinitionList while iterating over it.

• Ignoring the warning not to save over the source file after loading a newer model.