Entities method for a Component Instance

I am able to retrieve a collection of entities for a group and also for a component definition however I am not able to use the entities method on a component instance.

How do I collect the entities for a component instance?

A component instance defines not its own entities, but refers to a definition which has an entities method. All instances of the definition thus have the same entities.


Be aware that when you traverse two instances of the same definition, you will visit the same definition entities twice. Both instances have the same definition and same entities, but the instances have different instance paths (list of parent group/component instances in the nesting tree). The same face in the definition entities may occur in several places of the model with different instance paths.

When you want to traverse recursively, you first need to decide whether you are interested in visiting every occurence of an entity (visiting the same face multiple times, for polygon counting, area summing, exporting to a primitive mesh format) or only visiting it only once (for applying an operation to the definition’s entities, for exporting to a format that supports instances).

In the first case, see recursive tree traversal in SketchUp. In the second case it’s easier to traverse the definitions list (plus the direct entities of the model).

1 Like

A group is a “specially handled” component instance “under the hood.”

This means that a group’s #entities() method is just a transparent wrapper (or shortcut method) that actually calls group.definition.entities(). A few versions back, the Group class did not have the #definition() method yet exposed so the “shortcut” was necessary.


In a script place_component can use a group definition. Nice, I want to be able to place groups.
I wish adding a group definition to the model could be as easy as a component one. One does not have to add a component in order to create a definition.
compo = Sketchup.active_model.definitions.add "name"
Did I miss something or one has to add the group to the model entities and only then can give it’s definition a name?
group = Sketchup.active_model.entities.add_group group.name = "name" groupdef = group.definition
The drawback of this is that a group will appear in the model before you use place_component.

The difference is that the SketchUp engine automatically purges a Group’s definition if there are no instances in the model or if the definition contains no entities. So yes, you have to add a group into the model’s entities to get an instance (and then act quickly to put something in the definition’s entities before it evaporates - many coders use a cpoint).

1 Like

Thanks Steve,
Worked around with a parent component, erasing it’s definition afterwards.