Merge pull request #76453 from aaronfranke/3.x-gltf-physics

[3.x] Implement physics support in the GLTF module

modules/gltf/config.py

@@ -13,11 +13,13 @@ def get_doc_classes():
         "GLTFAnimation",
         "GLTFBufferView",
         "GLTFCamera",
+        "GLTFCollider",
         "GLTFDocument",
         "GLTFDocumentExtension",
         "GLTFLight",
         "GLTFMesh",
         "GLTFNode",
+        "GLTFPhysicsBody",
         "GLTFSkeleton",
         "GLTFSkin",
         "GLTFSpecGloss",

modules/gltf/doc_classes/GLTFCollider.xml

@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="GLTFCollider" inherits="Resource" version="3.6" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../doc/class.xsd">
+	<brief_description>
+		Represents a GLTF collider.
+	</brief_description>
+	<description>
+		Represents a collider as defined by the [code]OMI_collider[/code] GLTF extension. This class is an intermediary between the GLTF data and Godot's nodes, and it's abstracted in a way that allows adding support for different GLTF physics extensions in the future.
+	</description>
+	<tutorials>
+		<link title="OMI_collider GLTF extension">https://github.com/omigroup/gltf-extensions/tree/main/extensions/2.0/OMI_collider</link>
+	</tutorials>
+	<methods>
+		<method name="to_dictionary" qualifiers="const">
+			<return type="Dictionary" />
+			<description>
+				Serializes this GLTFCollider instance into a [Dictionary].
+			</description>
+		</method>
+		<method name="to_node">
+			<return type="CollisionShape" />
+			<argument index="0" name="cache_shapes" type="bool" default="false" />
+			<description>
+				Converts this GLTFCollider instance into a Godot [CollisionShape] node.
+			</description>
+		</method>
+	</methods>
+	<members>
+		<member name="array_mesh" type="ArrayMesh" setter="set_array_mesh" getter="get_array_mesh">
+			The [ArrayMesh] resource of the collider. This is only used when the collider type is "hull" (convex hull) or "trimesh" (concave trimesh).
+		</member>
+		<member name="height" type="float" setter="set_height" getter="get_height" default="2.0">
+			The height of the collider, in meters. This is only used when the collider type is "capsule" or "cylinder". This value should not be negative, and for "capsule" it should be at least twice the radius.
+		</member>
+		<member name="is_trigger" type="bool" setter="set_is_trigger" getter="get_is_trigger" default="false">
+			If [code]true[/code], indicates that this collider is a trigger. For Godot, this means that the collider should be a child of an Area3D node.
+			This is the only variable not used in the [method to_node] method, it's intended to be used alongside when deciding where to add the generated node as a child.
+		</member>
+		<member name="mesh_index" type="int" setter="set_mesh_index" getter="get_mesh_index" default="-1">
+			The index of the collider's mesh in the GLTF file. This is only used when the collider type is "hull" (convex hull) or "trimesh" (concave trimesh).
+		</member>
+		<member name="radius" type="float" setter="set_radius" getter="get_radius" default="0.5">
+			The radius of the collider, in meters. This is only used when the collider type is "capsule", "cylinder", or "sphere". This value should not be negative.
+		</member>
+		<member name="shape_type" type="String" setter="set_shape_type" getter="get_shape_type" default="&quot;&quot;">
+			The type of shape this collider represents. Valid values are "box", "capsule", "cylinder", "sphere", "hull", and "trimesh".
+		</member>
+		<member name="size" type="Vector3" setter="set_size" getter="get_size" default="Vector3( 1, 1, 1 )">
+			The size of the collider, in meters. This is only used when the collider type is "box", and it represents the "diameter" of the box. This value should not be negative.
+		</member>
+	</members>
+	<constants>
+	</constants>
+</class>

modules/gltf/doc_classes/GLTFNode.xml

@@ -31,30 +31,43 @@
 	</methods>
 	<members>
 		<member name="camera" type="int" setter="set_camera" getter="get_camera" default="-1">
+			If this GLTF node is a camera, the index of the [GLTFCamera] in the [GLTFState] that describes the camera's properties. If -1, this node is not a camera.
 		</member>
 		<member name="children" type="PoolIntArray" setter="set_children" getter="get_children" default="PoolIntArray(  )">
+			The indices of the children nodes in the [GLTFState]. If this GLTF node has no children, this will be an empty array.
 		</member>
 		<member name="height" type="int" setter="set_height" getter="get_height" default="-1">
+			How deep into the node hierarchy this node is. A root node will have a height of 0, its children will have a height of 1, and so on. If -1, the height has not been calculated.
 		</member>
 		<member name="joint" type="bool" setter="set_joint" getter="get_joint" default="false">
+			This property is unused and does nothing.
 		</member>
 		<member name="light" type="int" setter="set_light" getter="get_light" default="-1">
+			If this GLTF node is a light, the index of the [GLTFLight] in the [GLTFState] that describes the light's properties. If -1, this node is not a light.
 		</member>
 		<member name="mesh" type="int" setter="set_mesh" getter="get_mesh" default="-1">
+			If this GLTF node is a mesh, the index of the [GLTFMesh] in the [GLTFState] that describes the mesh's properties. If -1, this node is not a mesh.
 		</member>
 		<member name="parent" type="int" setter="set_parent" getter="get_parent" default="-1">
+			The index of the parent node in the [GLTFState]. If -1, this node is a root node.
 		</member>
 		<member name="rotation" type="Quat" setter="set_rotation" getter="get_rotation" default="Quat( 0, 0, 0, 1 )">
+			The rotation of the GLTF node relative to its parent.
 		</member>
 		<member name="scale" type="Vector3" setter="set_scale" getter="get_scale" default="Vector3( 1, 1, 1 )">
+			The scale of the GLTF node relative to its parent.
 		</member>
 		<member name="skeleton" type="int" setter="set_skeleton" getter="get_skeleton" default="-1">
+			If this GLTF node has a skeleton, the index of the [GLTFSkeleton] in the [GLTFState] that describes the skeleton's properties. If -1, this node does not have a skeleton.
 		</member>
 		<member name="skin" type="int" setter="set_skin" getter="get_skin" default="-1">
+			If this GLTF node has a skin, the index of the [GLTFSkin] in the [GLTFState] that describes the skin's properties. If -1, this node does not have a skin.
 		</member>
 		<member name="translation" type="Vector3" setter="set_translation" getter="get_translation" default="Vector3( 0, 0, 0 )">
+			The position of the GLTF node relative to its parent.
 		</member>
 		<member name="xform" type="Transform" setter="set_xform" getter="get_xform" default="Transform( 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0 )">
+			The transform of the GLTF node relative to its parent. This property is usually unused since the position, rotation, and scale properties are preferred.
 		</member>
 	</members>
 	<constants>

modules/gltf/doc_classes/GLTFPhysicsBody.xml

@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="GLTFPhysicsBody" inherits="Resource" version="3.6" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../doc/class.xsd">
+	<brief_description>
+		Represents a GLTF physics body.
+	</brief_description>
+	<description>
+		Represents a physics body as defined by the [code]OMI_physics_body[/code] GLTF extension. This class is an intermediary between the GLTF data and Godot's nodes, and it's abstracted in a way that allows adding support for different GLTF physics extensions in the future.
+	</description>
+	<tutorials>
+		<link title="OMI_physics_body GLTF extension">https://github.com/omigroup/gltf-extensions/tree/main/extensions/2.0/OMI_physics_body</link>
+	</tutorials>
+	<methods>
+		<method name="to_dictionary" qualifiers="const">
+			<return type="Dictionary" />
+			<description>
+				Serializes this GLTFPhysicsBody instance into a [Dictionary].
+			</description>
+		</method>
+		<method name="to_node" qualifiers="const">
+			<return type="CollisionObject" />
+			<description>
+				Converts this GLTFPhysicsBody instance into a Godot [CollisionObject] node.
+			</description>
+		</method>
+	</methods>
+	<members>
+		<member name="angular_velocity" type="Vector3" setter="set_angular_velocity" getter="get_angular_velocity" default="Vector3( 0, 0, 0 )">
+			The angular velocity of the physics body, in radians per second. This is only used when the body type is "rigid" or "vehicle".
+		</member>
+		<member name="body_type" type="String" setter="set_body_type" getter="get_body_type" default="&quot;static&quot;">
+			The type of the body. Valid values are "static", "kinematic", "character", "rigid", "vehicle", and "trigger".
+		</member>
+		<member name="linear_velocity" type="Vector3" setter="set_linear_velocity" getter="get_linear_velocity" default="Vector3( 0, 0, 0 )">
+			The linear velocity of the physics body, in meters per second. This is only used when the body type is "rigid" or "vehicle".
+		</member>
+		<member name="mass" type="float" setter="set_mass" getter="get_mass" default="1.0">
+			The mass of the physics body, in kilograms. This is only used when the body type is "rigid" or "vehicle".
+		</member>
+	</members>
+	<constants>
+	</constants>
+</class>

modules/gltf/doc_classes/GLTFSpecGloss.xml

@@ -6,19 +6,25 @@
 		[b]Note:[/b] This class is only compiled in editor builds. Run-time glTF loading and saving is [i]not[/i] available in exported projects. References to [GLTFSpecGloss] within a script will cause an error in an exported project.
 	</description>
 	<tutorials>
+		<link title="KHR_materials_pbrSpecularGlossiness GLTF extension spec">https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Archived/KHR_materials_pbrSpecularGlossiness</link>
 	</tutorials>
 	<methods>
 	</methods>
 	<members>
 		<member name="diffuse_factor" type="Color" setter="set_diffuse_factor" getter="get_diffuse_factor" default="Color( 1, 1, 1, 1 )">
+			The reflected diffuse factor of the material.
 		</member>
 		<member name="diffuse_img" type="Image" setter="set_diffuse_img" getter="get_diffuse_img">
+			The diffuse texture.
 		</member>
 		<member name="gloss_factor" type="float" setter="set_gloss_factor" getter="get_gloss_factor" default="1.0">
+			The glossiness or smoothness of the material.
 		</member>
 		<member name="spec_gloss_img" type="Image" setter="set_spec_gloss_img" getter="get_spec_gloss_img">
+			The specular-glossiness texture.
 		</member>
 		<member name="specular_factor" type="Color" setter="set_specular_factor" getter="get_specular_factor" default="Color( 1, 1, 1, 1 )">
+			The specular RGB color of the material. The alpha channel is unused.
 		</member>
 	</members>
 	<constants>

modules/gltf/doc_classes/GLTFState.xml

@@ -1,6 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="GLTFState" inherits="Resource" version="3.6" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../doc/class.xsd">
 	<brief_description>
+		Represents all data of a GLTF file.
 	</brief_description>
 	<description>
 		[b]Note:[/b] This class is only compiled in editor builds. Run-time glTF loading and saving is [i]not[/i] available in exported projects. References to [GLTFState] within a script will cause an error in an exported project.
@@ -44,6 +45,7 @@
 		<method name="get_animations">
 			<return type="Array" />
 			<description>
+				Returns an array of all [GLTFAnimation]s in the GLTF file. When importing, these will be generated as animations in an [AnimationPlayer] node. When exporting, these will be generated from Godot [AnimationPlayer] nodes.
 			</description>
 		</method>
 		<method name="get_buffer_views">
@@ -54,6 +56,7 @@
 		<method name="get_cameras">
 			<return type="Array" />
 			<description>
+				Returns an array of all [GLTFCamera]s in the GLTF file. These are the cameras that the [member GLTFNode.camera] index refers to.
 			</description>
 		</method>
 		<method name="get_images">
@@ -64,6 +67,7 @@
 		<method name="get_lights">
 			<return type="Array" />
 			<description>
+				Returns an array of all [GLTFLight]s in the GLTF file. These are the lights that the [member GLTFNode.light] index refers to.
 			</description>
 		</method>
 		<method name="get_materials">
@@ -74,11 +78,13 @@
 		<method name="get_meshes">
 			<return type="Array" />
 			<description>
+				Returns an array of all [GLTFMesh]es in the GLTF file. These are the meshes that the [member GLTFNode.mesh] index refers to.
 			</description>
 		</method>
 		<method name="get_nodes">
 			<return type="Array" />
 			<description>
+				Returns an array of all [GLTFNode]s in the GLTF file. These are the nodes that [member GLTFNode.children] and [member root_nodes] refer to. This includes nodes that may not be generated in the Godot scene, or nodes that may generate multiple Godot scene nodes.
 			</description>
 		</method>
 		<method name="get_scene_node">
@@ -95,11 +101,13 @@
 		<method name="get_skeletons">
 			<return type="Array" />
 			<description>
+				Returns an array of all [GLTFSkeleton]s in the GLTF file. These are the skeletons that the [member GLTFNode.skeleton] index refers to.
 			</description>
 		</method>
 		<method name="get_skins">
 			<return type="Array" />
 			<description>
+				Returns an array of all [GLTFSkin]s in the GLTF file. These are the skins that the [member GLTFNode.skin] index refers to.
 			</description>
 		</method>
 		<method name="get_texture_samplers">
@@ -116,11 +124,13 @@
 		<method name="get_unique_animation_names">
 			<return type="Array" />
 			<description>
+				Returns an array of unique animation names. This is only used during the import process.
 			</description>
 		</method>
 		<method name="get_unique_names">
 			<return type="Array" />
 			<description>
+				Returns an array of unique node names. This is used in both the import process and export process.
 			</description>
 		</method>
 		<method name="set_accessors">
@@ -244,8 +254,10 @@
 		<member name="minor_version" type="int" setter="set_minor_version" getter="get_minor_version" default="0">
 		</member>
 		<member name="root_nodes" type="Array" setter="set_root_nodes" getter="get_root_nodes" default="[  ]">
+			The root nodes of the GLTF file. Typically, a GLTF file will only have one scene, and therefore one root node. However, a GLTF file may have multiple scenes and therefore multiple root nodes, which will be generated as siblings of each other and as children of the root node of the generated Godot scene.
 		</member>
 		<member name="scene_name" type="String" setter="set_scene_name" getter="get_scene_name" default="&quot;&quot;">
+			The name of the scene. When importing, if not specified, this will be the file name. When exporting, if specified, the scene name will be saved to the GLTF file.
 		</member>
 		<member name="use_named_skin_binds" type="bool" setter="set_use_named_skin_binds" getter="get_use_named_skin_binds" default="false">
 		</member>

modules/gltf/extensions/SCsub

@@ -7,3 +7,4 @@ env_gltf = env_modules.Clone()
 
 # Godot source files
 env_gltf.add_source_files(env.modules_sources, "*.cpp")
+env_gltf.add_source_files(env.modules_sources, "physics/*.cpp")