StaticCompoundShapeSettings::Create can return a sub-shape directly, leading to "userdata" conflicts.

[Alan-FGR]

When StaticCompoundShapeSettings::Create is called with a single sub-shape and identity transform, it returns the sub-shape directly. This is a nice optimization, but I've had a few head-scratching moments because of it when setting/getting the userdata of what I thought was the compound silently swapped as the sub-shape (which is the kind of thing the pattern in Architecture.md relies on).

I would like to start a conversation about this, maybe addressing it somehow?

Some options off the top of my head:

• A JPH_TRACE (or similar) in debug when the optimization triggers.
• A doc note on Create() itself, perhaps in some (doxygen) warning banner or something very visible.

Also, maybe an opt-in flag on StaticCompoundShapeSettings in a future major version, so callers explicitly acknowledge that Create() may return a sub-shape?

[jrouwe]

A doc note on Create() itself, perhaps in some (doxygen) warning banner or something very visible.

Done in 153fd6f

Also, maybe an opt-in flag on StaticCompoundShapeSettings in a future major version, so callers explicitly acknowledge that Create() may return a sub-shape?

If you want to have a StaticCompoundShape with a single shape, you can also use this code:

StaticCompoundShapeSettings settings;
settings.AddShape(...);
ShapeSettings::ShapeResult result;
TempAllocatorMalloc allocator;
Ref<StaticCompoundShape> shape = new StaticCompoundShape(settings, allocator, result);
if (!result.IsValid()) ...

[Alan-FGR]

@jrouwe, doesn't this seem a footgun enough to be disabled by default to you, though? Since this makes the userdata land at the wrong place (the subshape), and that being such a fundamental part of the API, I would expect this optimization to be opt-in.
Consider the following:

• Create shape with userdata pointing to the gameobject data
• Create a parent shape and pass the subshape and some parent gameobject data
• Parent gameobject data lands at the subshape instead, potentially parent gameobject also points now to the subshape, etc

This isn't something for Jolt v5 I suppose.