Expose MeshInstance3D.get_skin_reference and add docs

4 files changed, 22 insertions, 0 deletions

diff --git a/doc/classes/MeshInstance3D.xml b/doc/classes/MeshInstance3D.xml
index f56b03bdc4..e5187cf7a1 100644
--- a/doc/classes/MeshInstance3D.xml
+++ b/doc/classes/MeshInstance3D.xml
@@ -70,6 +70,12 @@
 				Returns the value of the blend shape at the given [param blend_shape_idx]. Returns [code]0.0[/code] and produces an error if [member mesh] is [code]null[/code] or doesn't have a blend shape at that index.
 			</description>
 		</method>
+		<method name="get_skin_reference" qualifiers="const">
+			<return type="SkinReference" />
+			<description>
+				Returns the internal [SkinReference] containing the skeleton's [RID] attached to this RID. See also [method Resource.get_rid], [method SkinReference.get_skeleton], and [method RenderingServer.instance_attach_skeleton].
+			</description>
+		</method>
 		<method name="get_surface_override_material" qualifiers="const">
 			<return type="Material" />
 			<param index="0" name="surface" type="int" />
diff --git a/doc/classes/SkinReference.xml b/doc/classes/SkinReference.xml
index 466dbe2500..cb0c44cefa 100644
--- a/doc/classes/SkinReference.xml
+++ b/doc/classes/SkinReference.xml
@@ -1,8 +1,14 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="SkinReference" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		A reference-counted holder object for a skeleton RID used in the [RenderingServer].
 	</brief_description>
 	<description>
+		An internal object containing a mapping from a [Skin] used within the context of a particular [MeshInstance3D] to refer to the skeleton's [RID] in the RenderingServer.
+		See also [method MeshInstance3D.get_skin_reference] and [method RenderingServer.instance_attach_skeleton].
+		Note that despite the similar naming, the skeleton RID used in the [RenderingServer] does not have a direct one-to-one correspondence to a [Skeleton3D] node.
+		In particular, a [Skeleton3D] node with no [MeshInstance3D] children may be unknown to the [RenderingServer].
+		On the other hand, a [Skeleton3D] with multiple [MeshInstance3D] nodes which each have different [member MeshInstance3D.skin] objects may have multiple SkinReference instances (and hence, multiple skeleton [RID]s).
 	</description>
 	<tutorials>
 	</tutorials>
@@ -10,11 +16,14 @@
 		<method name="get_skeleton" qualifiers="const">
 			<return type="RID" />
 			<description>
+				Returns the [RID] owned by this SkinReference, as returned by [method RenderingServer.skeleton_create].
 			</description>
 		</method>
 		<method name="get_skin" qualifiers="const">
 			<return type="Skin" />
 			<description>
+				Returns the [Skin] connected to this SkinReference. In the case of [MeshInstance3D] with no [member MeshInstance3D.skin] assigned, this will reference an internal default [Skin] owned by that [MeshInstance3D].
+				Note that a single [Skin] may have more than one [SkinReference] in the case that it is shared by meshes across multiple [Skeleton3D] nodes.
 			</description>
 		</method>
 	</methods>
diff --git a/scene/3d/mesh_instance_3d.cpp b/scene/3d/mesh_instance_3d.cpp
index 8635240655..616fb18d53 100644
--- a/scene/3d/mesh_instance_3d.cpp
+++ b/scene/3d/mesh_instance_3d.cpp
@@ -204,6 +204,10 @@ Ref<Skin> MeshInstance3D::get_skin() const {
 	return skin;
 }
 
+Ref<SkinReference> MeshInstance3D::get_skin_reference() const {
+	return skin_ref;
+}
+
 void MeshInstance3D::set_skeleton_path(const NodePath &p_skeleton) {
 	skeleton_path = p_skeleton;
 	if (!is_inside_tree()) {
@@ -518,6 +522,7 @@ void MeshInstance3D::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("get_skeleton_path"), &MeshInstance3D::get_skeleton_path);
 	ClassDB::bind_method(D_METHOD("set_skin", "skin"), &MeshInstance3D::set_skin);
 	ClassDB::bind_method(D_METHOD("get_skin"), &MeshInstance3D::get_skin);
+	ClassDB::bind_method(D_METHOD("get_skin_reference"), &MeshInstance3D::get_skin_reference);
 
 	ClassDB::bind_method(D_METHOD("get_surface_override_material_count"), &MeshInstance3D::get_surface_override_material_count);
 	ClassDB::bind_method(D_METHOD("set_surface_override_material", "surface", "material"), &MeshInstance3D::set_surface_override_material);
diff --git a/scene/3d/mesh_instance_3d.h b/scene/3d/mesh_instance_3d.h
index add6bfe15e..d6ae1291d3 100644
--- a/scene/3d/mesh_instance_3d.h
+++ b/scene/3d/mesh_instance_3d.h
@@ -75,6 +75,8 @@ public:
 	void set_skeleton_path(const NodePath &p_skeleton);
 	NodePath get_skeleton_path();
 
+	Ref<SkinReference> get_skin_reference() const;
+
 	int get_blend_shape_count() const;
 	int find_blend_shape_by_name(const StringName &p_name);
 	float get_blend_shape_value(int p_blend_shape) const;