Implement physics support in the GLTF module

[aaronfranke]

Implements and closes godotengine/godot-proposals#5268

This PR implements physics support in the GLTF module. This allows importing physics objects from a GLTF file using the OMI_collider and OMI_physics_body GLTF extensions. omigroup/gltf-extensions#127 and omigroup/gltf-extensions#125

The code is designed in a modular and carefully abstracted way. There are helper classes GLTFCollider and GLTFPhysicsBody that serve as an intermediary between the imported OMI_* physics data and Godot's nodes.
The *_dictionary methods handle converting to/from the JSON Dictionary data that gets stored in the GLTF files, and the *_node methods handle converting to/from Godot nodes. GLTFDocumentExtensionPhysics is the stateless master class that manages the other two helper classes during the import and export processes.

OMI_collider is designed to be able to work independently of OMI_physics_body to allow for simpler files. This PR handles this case. If a collider is by itself, we create two nodes, a body (StaticBody3D or Area3D, depending on the collider's isTrigger flag), and a CollisionShape3D child.

Both importing and exporting GLTF files with physics is fully supported. GLTF -> Godot -> GLTF round-trip conversions should keep everything functional (even if the data is slightly different, such as Godot adding a physics body parent to GLTF files with standalone colliders). Godot -> GLTF -> Godot round-trip conversions should also keep everything functional for the data present in the standard (GLTF OMI physics won't keep track of everything Godot does).

One implementation note:

• While I was in the process of making this PR, MSFT_physics appeared as a competing standard to OMI's physics extensions. Due to the abstractions I mentioned earlier, if MSFT_physics ends up taking off as a popular standard, it should be fairly simple to modify this code to allow reading (and maybe writing) Microsoft physics by modifying the *_dictionary methods. For now, this PR only implements reading and writing OMI physics data. We can also allow reading both, so there is no risk of future breakage with merging this PR.

Here is a test project that tests most things listed above: Godot_GLTF_OMI_physics.zip

I am also interested in backporting this to Godot 3.x to help with using GLTF as an independent scene format interchangeable between different Godot versions (and also interchangeable between other engines). #76453

[fire]

I and @lyuma discussed off-thread with @aaronfranke. We are still reviewing.

[Cretezy]

Hey 👋 (original proposal author here). Sorry for delay reviewing this.

I'll start with thoughts before digging in the code:

• I'm not very familiar with glTF, and took a look at OMI_physics. Looks interesting, however as an end-user, how would this be supported? Currently, we have introp with general modeling tools (like Blender) by using name prefixes (which makes it easy to use, but is kind of a hack). Would tools like Blender need to support colliders, or a separate tool be required to create them, or would they possibly need to be made in Godot since it's the only one supported currently?
  • Sub-point: I see that Blender does support some extensions (https://docs.blender.org/manual/en/latest/addons/import_export/scene_gltf2.html#extensions), however none are currently for physics
  • I also see that Blender does have some 3rd-party collision tools such as https://blendermarket.com/products/collider-tools
• I can't find any details on MSFT_physics (search engines don't return any results). Could you provide a link? Thanks 😄
• For satisfying my proposal, I think this does a good job! Love seeming progress on this.

I think this is an important step towards user-generated model import, hopefully this goes into the engine! Thanks a lot for working on this.

[aaronfranke]

@Cretezy Thanks! I've updated the OP with a clickable link to MSFT_physics.

Would tools like Blender need to support colliders, or a separate tool be required to create them, or would they possibly need to be made in Godot since it's the only one supported currently?

For now, you can use Godot to create them. It has also been implemented in Third Room, a Unity game. Eventually it would be great to have Blender support it, it does have physics primitives available, but I am a Blender noob so unfortunately I don't have more details of how this will work in Blender.

[Cretezy]

Code tested 👍

I was also able to add one of my basic glTF models (a path for a racing game), generate the static body + collider, add a physics cube, export it, and re-import it succesfully.

Here's the model for reference: test.zip

While trying out a more complex scene, figured initial velocity and physics properties (bounce, mass) were missing, but that seems to be missing as part of the OMI_physics_body spec. It does seem that the
MSFT_physics spec has it though. This is more of a side-note again, as I think this is already great progress, and enables 3d user-generated (static) maps in Godot!

[aaronfranke]

@Cretezy Mass is supported, but more complex physics information should probably be left to another extension. At some point in the future we could see OMI_physics_material start to exist.

[fire]

We discussed in Discord and Github the last remaining changes from the OMI_physics and OMI_collider specification point of view. These have been proposed. omigroup/gltf-extensions#125

What's your take on merging as any changes will be less easy?

Also we do we want to mark the classes as experimental?

[fire]

Some things don't match in your opening post.

(GLTF OMI physics won't keep track of inertia or angular velocity etc).

Can you revise?

[aaronfranke]

What's your take on merging as any changes will be less easy?

I think it would be good to merge sometime soon. If we have to make breaking changes, there is still time to do this before Godot 4.0 is out. But we may want to first merge the PRs on OMI's end for the standards.

I think the main change remaining that was discussed is that I did not implement inertia tensors either in this PR or in the standard. I'm not familiar with this so I'd prefer if somebody else implements this. One option is to merge in the PRs without inertia tensors and then other people can make PRs that add it. A merged PR is not feature frozen.

[lyuma]

I'm pretty happy with it. there will continue to be small changes here or there but overall it seems pretty solid.

If you look at browsers for example, common practice for these sorts of spec implementation issues is to make it an opt-in feature flag as long as the spec is in draft.

So we should make a ProjectSettings property (needs to be synced to everyone working on the project) to allow glTF import and export. This would allow us to add it to 4.0 with very low risk.

[aaronfranke]

I don't think it makes sense to have as a feature flag. It's only used if people try to import/export physics with GLTF.

[fire]

See the argument against disabling by default #59675 (comment)

[fire]

TLDR; Approved after 4.x branch cut.

We believe the gltf physics changes should be merged after 4.0 is branched off master to get the full benefit of testing. I and Lyuma approve the changes. There is an alternative spec from KHR and the plan is to integrate that as it is ratified in some amount of time.

Edited:

Swapped 4.x versus 4.0.

[akien-mga]

Thanks!