Rename "global" methods in Skeleton3D to "skeletal"

[nukulele]

Describe the project you are working on

Learning the use of Skeleton3D for figure animation.

Describe the problem or limitation you are having in your project

Learning the Skeleton3D API is made unnecessarily confusing by an odd choice of terminology.

In general, "global" is used to mean "in the global (world) coordinate system." "Global" and "world" are generally synonymous. In the Skeleton3D API, "global" is overloaded with a different meaning unique to Skeleton armatures: "in this Skeleton3D node's coordinate system." A user encountering the word "global" in the docs of Skeleton3D -- for example, running across the function "local_pose_to_global_pose()" -- has to remember that "global" doesn't mean global in the usual sense but rather something specific just for Skeleton3D.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

It would be better if some word other than "global" was used for coordinates WRT the Skeleton3D coordinate system. My suggestion is "skeletal" or maybe "armature."

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

So, for example, the method "local_pose_to_global_pose()" would become "local_pose_to_skeletal_pose()".

"world_transform_to_global_pose()" becomes "world_transform_to_skeletal_pose()" and "global_pose_to_world_transform()" becomes "skeletal_pose_to_world_transform()".

And so on.

If this enhancement will not be used often, can it be worked around with a few lines of script?

It's part of the built-in API.

Is there a reason why this should be core and not an add-on in the asset library?

It's part of the built-in API.

[Mickeon]

I have no better suggestion, but I do have to agree on limiting "global" to exclusively refer to "in the global (world) coordinate system". Feels like a necessary improvement.

Yyyeaah, this one is necessary. I am not much of a 3D guy, but if I had seen this being done to work around the poor naming I would've done it sooner.

However, there probably is a good reason as to why it's called this way. Perhaps it's standardised?

[Mickeon]

Doesn't this also mean that world_transform_to_skeletal_pose would better off be called global_transform_to_skeletal_pose?

[fire]

    void clear_bones_local_pose_override();
    Transform3D get_bone_local_pose_override(int p_bone) const;
    void set_bone_local_pose_override(int p_bone, const Transform3D &p_pose, real_t p_amount, bool p_persistent = false);

    void update_bone_rest_forward_vector(int p_bone, bool p_force_update = false);
    void update_bone_rest_forward_axis(int p_bone, bool p_force_update = false);
    Vector3 get_bone_axis_forward_vector(int p_bone);
    int get_bone_axis_forward_enum(int p_bone);

    Basis global_pose_z_forward_to_bone_forward(int p_bone_idx, Basis p_basis);

    // Modifications
#ifndef _3D_DISABLED
    Ref<SkeletonModificationStack3D> get_modification_stack();
    void set_modification_stack(Ref<SkeletonModificationStack3D> p_stack);
    void execute_modifications(real_t p_delta, int p_execution_mode);
#endif // _3D_DISABLED

Have been removed in godotengine/godot#63588

[fire]

1. Skeleton global pose means relative to the skeleton. Like to the root bone.
2. Skeleton local pose means relative to the bone
3. Node3D global is relative to the scene root.
4. Node3D local is relative to the node3d.

I'm not sure skeletal terminology will bring enlightenment.

[akien-mga]

We discussed this in a PR review meeting and couldn't reach a consensus on this proposal. We agreed that the "global" naming is not the best, but the proposed alternative is not better.

[Zireael07]

Glad I saw this before fiddling more with my skeleton /ragdoll!
I assumed, like most people probably, that blah blah global means the same thing as anywhere else, and would've had a nasty surprise.

I have no better suggestion than 'skeletal', but it definitely should not be called global

[TokageItLab]

This concept of transform is not only for Skeleton. So, if it were renamed, I would prefer the word object_space_transform or model_space_transform. However, I can compromise by keeping using the global_transform for now.