SDK Compatibility Issue: SURefType Enum Change Between 2024 and 2026 SDKs

Developers SketchUp SDK
1

Hi team,

I’m observing unexpected behavior in my C extension (Rayscaper) regarding SDK version compatibility.

I built the extension against the SketchUp 2026 SDK (2026-0-429) but ran it in SketchUp 2024. It appears that the SURefType enum changed in a non-backward-compatible way between these versions.

For example, in the 2026 SDK:

enum SURefType {
  SURefType_Unknown = 0,
  SURefType_AttributeDictionary,
  SURefType_Camera,
  SURefType_ComponentDefinition,
  SURefType_ComponentInstance,
  SURefType_Curve,
  SURefType_Edge,
  SURefType_EdgeUse,
  SURefType_Environment, <<< NEW VALUE
  SURefType_Environments, <<< NEW VALUE
  SURefType_Entities,
  SURefType_Face,
  ...
};

In the 2024 SDK, however:

enum SURefType {
  SURefType_Unknown = 0,
  SURefType_AttributeDictionary,
  SURefType_Camera,
  SURefType_ComponentDefinition,
  SURefType_ComponentInstance,
  SURefType_Curve,
  SURefType_Edge,
  SURefType_EdgeUse,
  SURefType_Entities,
  SURefType_Face,
  ...
};

As you can see, the SURefType_Environment and SURefType_Environments values were inserted before SURefType_Face, which shifted the enum values and broke backward compatibility.

When running on older SketchUp versions, this results in incorrect type interpretation. For example, during an EntitiesOnElementAdded callback, a SURefType_Face in 2026 is reported as SURefType_Environments when running under 2024. Here’s what happens when adding a basic plane (4 edges + 1 face):

[debug] EntitiesOnElementAdded() type=SURefType_Edge id=4456
[debug] EntitiesOnElementAdded() type=SURefType_Edge id=4457
[debug] EntitiesOnElementAdded() type=SURefType_Edge id=4458
[debug] EntitiesOnElementAdded() type=SURefType_Edge id=4459
[debug] EntitiesOnElementAdded() type=SURefType_Environments id=4465  << In SketchUp 2026 this is a Face, in 2024 this is an environment, leading to bogus results.

Question:
What is the recommended approach for building C extensions with the latest SDK while maintaining compatibility with older SketchUp versions?

Thanks,
Thomas Loockx

1 Like
2

Dang! That is a bad booboo.

If they were added to the end of the enumeration like what was done in the past when new types were introduced, they’d likely be backward compatible (as long as not used older versions.)

@CraigTrickett @bugra

1 Like
3

Ugh.. very sorry about this @pixelcruncher . We rely on code reviews to catch ABI compatibility issues and things slip through sometimes. Now this is a bit of a dilemma; if we moved the new enumerations to the end, we might further cause issues for code that already built it this way (though the likelihood of that is much smaller since it hasn’t been that long)

I guess the only (somewhat ugly) workaround that comes to mind is to check for the API version (SUGetAPIVersion) and make a correction on your side. Is this possible? (It’s late at night and I am not entirely sure what this EntitiesOnElementAdded callback is. So I might be misunderstanding the extent of your predicament)

4

@bugra Thanks for the quick response!

Ugh.. very sorry about this @pixelcruncher . We rely on code reviews to catch ABI compatibility issues and things slip through sometimes. Now this is a bit of a dilemma; if we moved the new enumerations to the end, we might further cause issues for code that already built it this way (though the likelihood of that is much smaller since it hasn’t been that long)

I would also think that most people adopting the latest SDK would code using the SURefType enumeration rather than the numerical values. So for them, it doesn’t matter if the actual enum values change, unless of course those values are already stored somewhere.

I can also imagine that anyone who uses the 2026 SDK with an older version would run into this if they use any of those ref types. So I’m surprised that I’m the first one to notice this.

I guess the only (somewhat ugly) workaround that comes to mind is to check for the API version (SUGetAPIVersion) and make a correction on your side. Is this possible? (It’s late at night and I am not entirely sure what this EntitiesOnElementAdded callback is. So I might be misunderstanding the extent of your predicament)

I think it’s possible to make this correction; I have to try it out. But this means that in the future, you’ll be forcing every SDK user who wants to remain backwards compatible with 2024 or earlier to go through this enumeration conversion process, which doesn’t seem like a great developer experience to me.

Wouldn’t it be better to make a potentially breaking change to the SDK to fix this, rather than moving forward and forcing it on every SDK developer?

To provide some more detail on what I’m doing. I maintain a render engine for SketchUp, so I need to be aware of every change in the model, every entities list, … . In this case I am observing the entities list via the onElementAdded method (Class: Sketchup::EntitiesObserver — SketchUp Ruby API Documentation) and I pass that directly to the C code of my plugin:

void SuModelManager::EntitiesOnElementAdded(RUBY_VALUE entity) {
  ZoneScoped;
  auto entity_ref = RubyValueToEntity(entity);
  if (!entity_ref) {
    Log::Debug("EntitiesOnElementAdded() invalid-ref");
    return;
  }

  SURefType entity_type = SUEntityGetType(*entity_ref);
  Log::Debug("EntitiesOnElementAdded() type={} id={} ptr={}",
             SURefTypeToString(entity_type),
             GetEntityID(*entity_ref),
             static_cast<void*>(entity_ref->ptr));

  switch (entity_type) {
      case SURefType_Face: {
        // DO something
        break;
      }
      case SURefType_ComponentInstance: {
        // DO something else
        break;
      }
      case SURefType_Group: {
        // DO ANOTHER THING
        break;
      }
      // More things to do.
      default: {
        // Not handled here.
      }
    }
  }
}

But because of this change, the SUEntityGetType can’t be trusted anymore and requires a conversion everywhere. This API is very frequently used in my code. On top of that, any API that deals with SURefType is broken now. You can’t really program against the SketchUp API anymore without creating your own conversions everywhere. That does not seem like a great way to program for SketchUp plugin developers.

And there might be other impacts I have not yet assessed. My users don’t get very far because most API calls are broken for them now, and they can’t really do anything anymore with my plugin. So I can’t assess further impact at this time.

Thanks for your help!

Regards,
Thomas Loockx

1 Like
5

Thank you for the detailed context Thomas. I agree that we need to do something about this. The problem is SketchUp C API can also be used in what we call the “live” context, which is by calling the APIs exported from the executable rather than the DLL, which is necessary in order to be able to act on the currently active model. (In fact, it seems your extension should be doing it that way also).

This means we can’t just patch the SDK package, this will require a desktop client release as well, which will take some time. And the 2026.0 release will also be there for you to deal with as well as the newer “patched” release.

I will speak to the team and decide on how we can remedy this soon.
Thank you for bringing this up!

Bugra

1 Like
6

This is further complicated by the fact that this change was made in 2025 actually (not 2026)
I don’t know if you never supported 2025 (?)
I suppose no other developer is relying on the integer values of these enumerations since we never heard of this. But this was certainly a mistake that we try not to make.

1 Like
7

Should have clarified that, but my plugin is using the live API, and not doing any modifications to the model, just ingesting model updates.

You are right. The problem must have existed already in 2025 as well. User reported issues with the 2024 version before as well, but I only connected the dots a couple of days ago.

Regards,
Thomas

1 Like
8

If we fix this now, I’m afraid we will rock the boat even more. Unless you are willing to drop support for 2025 and 2026.0, you’d also have to deal with 2 breaking changes. So our current conclusion as a team is to:

  • Add tests internally to prevent this from happening again.
  • Document what happened in release notes.

But do not change the current definition of the enumeration.
Sincere apologies and thanks again for bringing this to our attention.

1 Like
9

@bugra Fair enough, I understand that fixing this will cause even more collateral damage. I will work around this in my own extensions. Thanks!

1 Like
10

So basically there is a “breaking change” support line between 2024 and 2025.
Live C API Extensions would need to sniff the version on the Ruby side and branch to load the proper DLL or SO file that was built with the matching SDK version.

Either this or publish separate extension editions pre-2025 & post 2025. The latter would likely be smaller download and consume less storage space on user machines. Separate editions would need to still do a version check so as not to load into unsupported SketchUp environments.
ADD: Thinking more … this paradigm would be better maintainable. A bug in one edition could be fixed and deployed without forcing the other to download and install a new version without benefit.

1 Like
11

This is how I plan to work around this issue. Pack 3 Rayscaper DLLs into a single RBZ file, then load the correct DLL based on the SketchUp version. I’m not keen on sniffing out differences on the C side or manually translating enum values.

Either this or publish separate extension editions pre-2025 & post 2025. The latter would likely be smaller download and consume less storage space on user machines. Separate editions would need to still do a version check so as not to load into unsupported SketchUp environments.

Ideally, but this becomes a lot of hassle for plugin developers, especially if they have to distribute via multiple channels. So I’m just packing it up in one big RBZ.

edit: Not to mention the customer support overhead. Because there are multiple ways now to combine the wrong SketchUp version with the wrong RBZ file.

1 Like
12

In the end, ya’ gotta do what works for your system.

1 Like
13

This topic was automatically closed 7 days after the last reply. New replies are no longer allowed.